Skip to main content
Version: master

Build Containers with the SDK

The Pantavisor SDK is a cross toolchain plus pv-mkpvrexport, a tool that packs a root filesystem into a signed <name>.pvrexport.tgz, the same package a container recipe produces in a Yocto build. Use it when your application is not a Docker image and you don't want to set up a Yocto build of this layer. The same SDK also builds Pantavisor itself.

Pick the SDK for your device​

Each release publishes one installer per architecture, listed with its sha256 under sdks in releases.json from 031-rc3 on:

InstallerDevice CPU
pv-sdk-<tag>-x86_64.shx86_64
pv-sdk-<tag>-armv8.sh64-bit ARM (aarch64)
pv-sdk-<tag>-armv6.sh32-bit ARM, soft-float

The installers run on x86_64 Linux hosts. The toolchain targets musl, the C library of the Pantavisor board images.

Each sdks entry also lists what that installer ships, by recipe and version, under contents (toolchain, host tools, target libraries), with links to the full package lists under manifests. For example, to check which Qt and GStreamer an armv8 SDK carries:

curl -s https://pantavisor-ci.s3.amazonaws.com/meta-pantavisor/releases.json \
| jq '.["release-candidate"]["<tag>"].sdks[] | select(.arch == "armv8")
| .contents.toolchain, (.contents.target | with_entries(select(.key | test("qtbase|gstreamer"))))'

The armv6 SDK builds soft-float binaries. They do not load on a hard-float 32-bit board (one whose initramfs has /lib/ld-musl-armhf.so.1), which includes most armv7 boards; there is no hard-float 32-bit SDK for now.

Install​

Find and download the installer, checking its sha256. Release candidates are under release-candidate, final releases under stable:

curl -s https://pantavisor-ci.s3.amazonaws.com/meta-pantavisor/releases.json \
| jq -r '.["release-candidate"]["<tag>"].sdks[] | "\(.arch) \(.sha256) \(.url)"'
curl -fLO https://pantavisor-ci.s3.amazonaws.com/meta-pantavisor/<tag>/sdk/pv-sdk-<tag>-armv8.sh
echo "<sha256> pv-sdk-<tag>-armv8.sh" | sha256sum -c

Then install it:

sh ./pv-sdk-<tag>-armv8.sh -d ~/pv-sdk-armv8 -y
. ~/pv-sdk-armv8/environment-setup-*

Sourcing environment-setup-* puts the cross compiler ($CC, $CXX, $CONFIGURE_FLAGS, ...), pv-mkpvrexport and a host build of pvr on PATH for this shell. You don't need to install pvr separately, but it is only on PATH in a shell that sourced the script:

command -v pvr # ~/pv-sdk-armv8/sysroots/x86_64-pokysdk-linux/usr/bin/pvr
pvr --version

Build a container​

Install your application into a directory laid out like the container's root filesystem, then pack it. --base lays that directory over the SDK's base rootfs (busybox, plus the C library, libgcc and libstdc++ the toolchain links against), so a dynamically linked C or C++ binary finds its libraries:

cat > hello.c <<'EOF'
#include <stdio.h>
#include <unistd.h>
int main(void) { for (;;) { puts("hello from the container SDK"); sleep(10); } }
EOF

mkdir -p rootfs/usr/bin
$CC -o rootfs/usr/bin/hello hello.c

pv-mkpvrexport --base rootfs hello -- --config=Entrypoint=/usr/bin/hello
pvr inspect hello.pvrexport.tgz

For autotools, CMake or Meson projects, install with make DESTDIR="$PWD/rootfs" install (or the equivalent) into the same directory.

Use the SDK's libraries​

The SDK's sysroot also has libraries for most embedded applications:

ForExamples (pkg-config names)Tools in the sysroot
GPIO and buseslibgpiod, libiio, libusb-1.0, libsocketcangpiodetect, gpioset, i2cdetect, candump
Fieldbuslibmodbus, open62541
Networking and securitylibcurl, openssl, libwebsockets, libmosquitto
Cameraslibcamera, libv4l2, opencv4v4l2-ctl, media-ctl
Video processing and playbackgstreamer-1.0, gstreamer-video-1.0, gstreamer-rtsp-server-1.0gst-launch-1.0, gst-inspect-1.0
Graphicswayland-client, egl, glesv2, gbm, cairoweston
User interfacesQt6Quick, gtk4, sdl2, lvgl, wpe-webkit-2.0cog

The full list is in packagegroup-pv-sdk-target.bb. The sysroot also has Python 3 with modules such as numpy, pyserial, gpiod and paho-mqtt.

Compile against them with pkg-config. The base rootfs does not include them, so copy what the application needs at runtime from $SDKTARGETSYSROOT into rootfs:

mkdir -p rootfs/usr/bin rootfs/usr/lib
$CC -o rootfs/usr/bin/gpio-app gpio-app.c $(pkg-config --cflags --libs libgpiod)
cp -a "$SDKTARGETSYSROOT"/usr/lib/libgpiod.so.* rootfs/usr/lib/

GStreamer plugins are in $SDKTARGETSYSROOT/usr/lib/gstreamer-1.0, including libcamerasrc (libgstlibcamera.so) and kmssink (libgstkms.so).

The SDK decodes VP8, VP9, Theora and MJPEG in software. It has no software H.264 or H.265 decoder, so those formats need a hardware decoder on the board, through the V4L2 plugins (libgstvideo4linux2.so, libgstv4l2codecs.so). A self-built SDK can add software decoders, as described in Add commercial codecs.

pv-mkpvrexport never modifies rootfs. It copies it, adds the mountpoints LXC needs, makes every file owned by root, gives the container a persistent /var (--volume ovl:/var:permanent, as a container recipe does by default), and signs the result with the Pantacor developer keys shipped in the SDK (--keys to use your own pvs keys tarball). The options map to the files a container recipe provides:

OptionSame as, in a recipe
--args-json FILE${PN}.args.json
--config-json FILE${PN}.config.json
--services-json FILE${PN}.services.json
--network-json FILE${PN}.network.json
--mdev-json FILE / --no-mdev${PN}.mdev.json / PVRIMAGE_AUTO_MDEV = "0"
--group NAMEPVR_APP_ADD_GROUP
--roles "R1 R2"PVR_APP_ADD_ROLES
--comp lz4PANTAVISOR_FEATURES squash-lz4
-- <args>PVR_APP_ADD_EXTRA_ARGS
--no-var-volumePVR_APP_ADD_EXTRA_ARGS without its default --volume ovl:/var:permanent

pv-mkpvrexport --help lists them all. Two recipe features have no equivalent: dm-verity volumes (PVR_DM_VERITY) and the _config overlay (PV_CONFIG_OVERLAY_DIR); build such containers with the layer.

Deploy it​

Merge the export into a checkout of the device (pvr merge commits it) and post the new revision:

pvr clone http://<device-ip>:12368/cgi-bin mydevice
cd mydevice
pvr merge ../hello.pvrexport.tgz
pvr checkout
pvr post http://<device-ip>:12368

Or upload hello.pvrexport.tgz from a browser through the pvtx web UI.

For a device managed through Pantahub (pantavisor.mode is remote), clone it from Pantahub instead; pvr post then sends the revision back there:

pvr clone https://pvr.pantahub.com/<user>/<device-nick> mydevice
cd mydevice
pvr merge ../hello.pvrexport.tgz
pvr checkout
pvr post -m "add hello"

Example: read a hardware RTC​

This container reads the board's real-time clock through /dev/rtc0 and logs it next to the system time. It uses all three files most containers need: args.json (how Pantavisor runs it), config.json (entrypoint and environment) and mdev.json (which device nodes it gets). It was tested with the armv8 SDK on an Orange Pi 5B.

The application, rtc-reader.c:

#include <errno.h>
#include <fcntl.h>
#include <linux/rtc.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/ioctl.h>
#include <time.h>
#include <unistd.h>

int main(void)
{
const char *dev = getenv("RTC_DEV");
const char *interval = getenv("RTC_INTERVAL");
int secs = interval ? atoi(interval) : 10;

if (!dev)
dev = "/dev/rtc0";
if (secs <= 0)
secs = 10;

for (;;) {
struct rtc_time tm;
int fd = open(dev, O_RDONLY);

if (fd < 0) {
printf("rtc-reader: open %s: %s\n", dev, strerror(errno));
} else if (ioctl(fd, RTC_RD_TIME, &tm) < 0) {
printf("rtc-reader: RTC_RD_TIME on %s: %s\n", dev, strerror(errno));
} else {
time_t now = time(NULL);
struct tm sys;

gmtime_r(&now, &sys);
printf("rtc-reader: %s %04d-%02d-%02d %02d:%02d:%02d UTC, system %04d-%02d-%02d %02d:%02d:%02d UTC\n",
dev, tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday,
tm.tm_hour, tm.tm_min, tm.tm_sec,
sys.tm_year + 1900, sys.tm_mon + 1, sys.tm_mday,
sys.tm_hour, sys.tm_min, sys.tm_sec);
}
if (fd >= 0)
close(fd);
fflush(stdout);
sleep(secs);
}
}

It never exits: if the RTC is missing it logs the error and retries, so the container log says what is wrong instead of the container restarting.

args.json restarts only this container if it fails, counts it as up once it has started, and has Pantavisor load the rtc driver before starting it:

{
"PV_RESTART_POLICY": "container",
"PV_STATUS_GOAL": "STARTED",
"PV_DRIVERS_REQUIRED": [
"rtc"
]
}

config.json sets the entrypoint and the environment the application reads:

{
"Entrypoint": ["/usr/bin/rtc-reader"],
"Env": [
"RTC_DEV=/dev/rtc0",
"RTC_INTERVAL=10"
],
"WorkingDir": "/"
}

mdev.json gives the container the RTC, read-only, plus the basic nodes (busybox mdev rules: <regex> <uid>:<gid> <mode>):

{
"rules": [
"rtc[0-9]* 0:0 444",
"null 0:0 666",
"zero 0:0 666",
"u?random 0:0 444"
]
}

Build and pack it:

. ~/pv-sdk-armv8/environment-setup-*
mkdir -p rootfs/usr/bin
$CC -Wall -Werror -o rootfs/usr/bin/rtc-reader rtc-reader.c
pv-mkpvrexport --base \
--args-json args.json \
--config-json config.json \
--mdev-json mdev.json \
rootfs pv-rtc

Deploy pv-rtc.pvrexport.tgz as in Deploy it. The container's console log (source /lxc/console.log, platform pv-rtc in the device's Pantahub logs) then shows:

rtc-reader: /dev/rtc0 2026-10-14 21:35:31 UTC, system 2026-10-14 21:35:30 UTC

The RTC driver​

PV_DRIVERS_REQUIRED names a driver alias from the BSP's bsp/drivers.json. Pantavisor loads the alias's modules before starting the container. If the board's RTC driver is built into the kernel, drop PV_DRIVERS_REQUIRED from args.json. If it is a module, the BSP must define the alias, e.g. for the Orange Pi 5B's HYM8563:

{
"#spec": "driver-aliases@1",
"all": {
"rtc": [
"rtc_hym8563"
]
}
}

In a BSP built with this layer, set it in the machine configuration; pantavisor-bsp merges it into bsp/drivers.json:

PV_BSP_DRIVERS = '{"all": {"rtc": ["rtc_hym8563"]}}'

If the driver is not loaded, the container still starts and logs open /dev/rtc0: No such file or directory.