Skip to main content
Version: 029-rc4

Pantavisor Starter Image

pantavisor-starter (recipes-pv/images/pantavisor-starter.bb) is the layer's top-level deployable image: a complete, bootable rootfs whose initial Pantavisor trail (/trails/0) is pre-populated with a working set of containers and the board's BSP. It is what you flash to get a device that boots Pantavisor and brings up a usable system out of the box.

inherit image pvroot-image pantavisor-docs

PVROOT_CONTAINERS_CORE ?= "pv-pvr-sdk pv-alpine-connman pvwificonnect pv-avahi"
PVROOT_IMAGE_BSP       ?= "core-image-minimal"

What "starter" means​

Unlike a plain Yocto image (a package set in a rootfs), a pvroot image is a Pantavisor state. The rootfs is the pantavisor-pvroot skeleton, and the real payload is an initial signed trail under /trails/0 assembled by mixing in container pvrexport bundles plus the BSP. The "starter" image is the opinionated default mix — enough to boot, get on the network, and be claimed/managed — as opposed to the bare pantavisor-remix which ships only the SDK container.

What it ships​

The default trail is built from two variables (see pvroot-image.bbclass):

VariableRoleDefault
PVROOT_CONTAINERS_COREContainers baked into the initial trail (pvr deploy into /trails/0)pv-pvr-sdk pv-alpine-connman pvwificonnect pv-avahi
PVROOT_CONTAINERSContainers staged as factory packages (factory-pkgs.d/), installed on first boot(none)
PVROOT_IMAGE_BSPProto rootfs the BSP's modules/firmware come fromcore-image-minimal

The core containers in the starter mix:

ContainerPurpose
pv-pvr-sdkPVR SDK / local management container
pv-alpine-connmanConnMan network backend (the WiFi/networking stack)
pvwificonnectWiFi provisioning — AP, captive portal, tethering (see pvwificonnect)
pv-avahimDNS/zeroconf service discovery

The pantavisor-bsp pvrexport (kernel, initramfs, DTBs, modules, firmware) is always mixed in, regardless of the container list — that is what makes the trail bootable on the target machine.

How the image is assembled​

The work happens in pvroot-image.bbclass's do_rootfs_pvroot task (runs after do_rootfs, before do_image):

  1. Skeleton trail — pvr checkout -c lays down the device skeleton in /trails/0, then pvr sig add / add / commit create the initial signed revision.
  2. Mix in containers — for each PVROOT_CONTAINERS_CORE entry the matching *.pvrexport.tgz from DEPLOY_DIR_IMAGE is unpacked and pvr deploy-ed into the trail. PVROOT_CONTAINERS entries are instead copied into factory-pkgs.d/ to be applied on first boot.
  3. Mix in the BSP — pantavisor-bsp-${MACHINE}.pvrexport.tgz is always deployed into the trail.
  4. Sign — the trail is signed with the developer CA (pv-developer-ca_${PVS_VENDOR_NAME}), so unsigned/tampered states are rejected at boot.
  5. Boot glue (do_rootfs_boot_scr) — boot.scr is copied to /boot, and on UBIFS machines oemEnv.txt is placed at the rootfs root (where boot.scr expects it).

Container builds depend on do_deploy; the BSP on do_compile/do_image_complete — these are wired automatically by the __anonymous hook in pvroot-image.bbclass.

Build artifacts​

After a build, in build/tmp-${codename}/deploy/images/${machine}/:

ArtifactDescription
pantavisor-starter-${machine}.wic[.bz2]Flashable disk image (partition layout from the machine's WKS file)
pantavisor-starter-${machine}.rootfs.*Rootfs tarball with the populated /trails/0
pantavisor-starter-*.docs.tar.zst / pantavisor-reference-documentation*.html.tar.zstBundled docs (from pantavisor-docs)

Building​

./kas-container build kas/build-configs/release/<machine>-scarthgap.yaml \
    --target pantavisor-starter

Because the starter aggregates the BSP and every core container, a full build also builds pantavisor-bsp, pantavisor-initramfs, and the core container recipes. See Get Started for prerequisites and the KAS workflow.

Customizing the mix​

Override the container set from a machine/distro include or local.conf — use assignment, since these are the image's content list:

# Swap the default mix for your product's containers
PVROOT_CONTAINERS_CORE = "pv-pvr-sdk pv-alpine-connman my-app-container"

# Ship an extra container as a first-boot factory package instead of in-trail
PVROOT_CONTAINERS = "my-optional-app"

Authoring a container to add here is covered in Container Development.

RecipeDescription
pantavisor-starter.bbThis image — BSP + core containers, ready to flash
pantavisor-remix.bbMinimal pvroot image: only pv-pvr-sdk, just enough to boot
pantavisor-bsp.bbBSP pvrexport (kernel + initramfs + modules + firmware); mixed into every pvroot image
pantavisor-initramfs.bbThe Pantavisor-as-init initramfs the BSP wraps
empty-image.bbEmpty proto rootfs used as a BSP modules/firmware source
pantavisor-appengineDocker-based image for local appengine testing (not a flashable device image)
pv-flash-bundle.bbFactory flash archive (UUU) wrapping this image for boards without native .wic flashing — see pv-flash-bundle