Yocto Integration

Pantavisor integrates seamlessly with the Yocto Project through the meta-pantavisor layer. This integration allows you to build containerized embedded Linux systems using Yocto’s powerful build system while leveraging Pantavisor’s container runtime capabilities.

What is Meta-Pantavisor?

Meta-pantavisor is a Yocto layer that enables building Pantavisor-based container distributions for embedded Linux products. It provides:

• Container runtime integration - Pantavisor as the init system
• BSP abstraction - Board Support Package integration
• pvroot image generation - Complete flashable images
• Multi-container deployment - Support for multiple containers
• Cross-platform support - Works with various hardware platforms

Prerequisites

Before you begin, ensure you have:

• Linux development environment (Ubuntu 20.04+ recommended)
• At least 50GB free disk space
• Internet connection for fetching layers
• Basic knowledge of Yocto Project concepts

Supported Yocto Versions

Meta-pantavisor supports:

Quick Start

Method 1: Using kas-container (Recommended)

The easiest way to get started is using the kas-container script provided by meta-pantavisor:

# Clone meta-pantavisor repository
git clone https://github.com/pantavisor/meta-pantavisor.git
cd meta-pantavisor

# Build for a supported machine
./kas-container build kas/machines/raspberrypi-armv8.yaml

Method 2: Manual Layer Integration

1. Clone meta-pantavisor and dependencies:

cd <your-yocto-project>/layers

# Clone meta-pantavisor
git clone https://github.com/pantavisor/meta-pantavisor.git
cd meta-pantavisor
git checkout scarthgap  # or kirkstone

# Clone required dependencies
cd ..
git clone https://git.openembedded.org/meta-openembedded
cd meta-openembedded
git checkout scarthgap

2. Add layers to bblayers.conf:

BBLAYERS ?= " \
    <path-to>/poky/meta \
    <path-to>/poky/meta-poky \
    <path-to>/meta-openembedded/meta-oe \
    <path-to>/meta-openembedded/meta-python \
    <path-to>/meta-openembedded/meta-networking \
    <path-to>/meta-pantavisor \
    "

3. Build the image:

source oe-init-build-env
bitbake pantavisor-remix

Layer Dependencies

Meta-pantavisor requires these base layers:

• core (poky/meta) - Base Yocto layer
• meta-oe - OpenEmbedded meta layer
• meta-python - Python recipes
• meta-networking - Networking utilities

Optional Hardware-Specific Layers

For specific hardware platforms, you may need:

Understanding pvroot Images

A pvroot image is the primary output of meta-pantavisor. It contains:

1. Pantavisor runtime - The init system and container manager
2. Initial container state (trails/0) - Factory default containers
3. BSP integration - Board-specific drivers and firmware
4. Factory packages - Recovery and reset capabilities

Image Types

Configuring Your Build

Using the Kas Menu

Meta-pantavisor provides an interactive menu for easy configuration:

./kas-container menu

The menu allows you to:

• Select build type (multiconfig, singleconfig, appengine)
• Choose Yocto version (scarthgap, kirkstone)
• Select build target (pantavisor-remix, pantavisor-bsp)
• Configure containers (enable/disable predefined containers)
• Select machine (filter by vendor)

Adding Containers

Containers are defined using PVROOT_CONTAINERS variable:

# In local.conf or kas configuration
PVROOT_CONTAINERS += " \
    pv-connman \
    pv-pvwificonnect \
    my-custom-app \
"

# Core containers (always included)
PVROOT_CONTAINERS_CORE += " \
    pantavisor-bsp \
"

Common Container Options

Creating Custom Recipes

When building your own containers for Pantavisor:

SUMMARY = "My Custom Container"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://LICENSE;md5=..."

inherit pvrexport

PVREXPORT_NAME = "my-container"
PVREXPORT_VERSION = "1.0"

SRC_URI = " \
    file://config.json \
    file://rootfs.tar.gz \
"

do_install() {
    install -d ${D}${datadir}/pantavisor/containers/my-container
    install -m 0644 ${WORKDIR}/config.json ${D}${datadir}/pantavisor/containers/my-container/
    install -m 0644 ${WORKDIR}/rootfs.tar.gz ${D}${datadir}/pantavisor/containers/my-container/
}

Key Classes and Variables

Important Classes

Key Variables

Supported Machines

Meta-pantavisor supports various hardware platforms:

ARM Platforms

• raspberrypi-armv8 - Raspberry Pi 3/4 (64-bit)
• raspberrypi-armv7 - Raspberry Pi 2/3 (32-bit)
• sunxi-orange-pi-3lts - Orange Pi 3 LTS
• sunxi-orange-pi-r1 - Orange Pi R1
• sunxi-bananapi-m2-berry - Banana Pi M2 Berry
• radxa-rock5a - Radxa ROCK 5A

NXP i.MX

• imx8qxp-b0-mek - i.MX 8QuadXPlus MEK
• colibri-imx6ull - Colibri i.MX6ULL

x86

• docker-x86_64 - Containerized builds

Build Output

After a successful build, you’ll find:

tmp/deploy/images/<machine>/
├── pantavisor-remix-<machine>.pvroot    # Flashable pvroot image
├── pantavisor-remix-<machine>.img       # Raw disk image
├── pantavisor-remix-<machine>.wic       # WIC formatted image
└── <container>-<version>.squashfs       # Individual container images

Flashing the Image

Use pvtx or dd to flash the pvroot image:

# Using pvtx
pvtx flash -i pantavisor-remix-raspberrypi-armv8.pvroot -d /dev/sdX

# Using dd (Linux)
sudo dd if=pantavisor-remix-raspberrypi-armv8.pvroot of=/dev/sdX bs=4M status=progress

Troubleshooting

Build Issues

Issue: pvr: command not found

• Ensure pvr-native is in your recipe dependencies
• Check that you’ve inherited the correct class

Issue: pvroot image missing containers

• Verify PVROOT_CONTAINERS is set correctly
• Check bitbake-layers show-recipes for container recipes

Issue: Layer dependency errors

• Check LAYERDEPENDS_meta-pantavisor in conf/layer.conf
• Ensure all required layers are in bblayers.conf

Debugging Commands

# Check layer dependencies
bitbake-layers show-layers

# Inspect task execution
bitbake -e <recipe> | less

# Check Pantavisor variables
bitbake -e <image> | grep -E "(PVROOT|PANTA|PVR)"

# Enter development shell
bitbake -c devshell <recipe>

Best Practices

1. Use kas for builds - Ensures reproducible builds
2. Version your containers - Always set PVREXPORT_VERSION
3. Sign production images - Configure PVR_SIG_KEY and PVS_VENDOR_NAME
4. Test factory reset - Include all necessary factory packages
5. Use multiconfig - Separate BSP and container builds for complex projects

Next Steps

• Build Setup - Detailed build environment setup
• Porting Guide - Add support for new hardware
• Device Setup - Flash and configure your device
• CLI Tools - Learn about pvr and other tools

Resources

• Meta-Pantavisor GitHub: https://github.com/pantavisor/meta-pantavisor
• GitHub Wiki: https://github.com/pantavisor/meta-pantavisor/wiki
• Community Forum: https://community.pantavisor.io/
• Yocto Project: https://www.yoctoproject.org/