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:
| Installer | Device CPU |
|---|---|
pv-sdk-<tag>-x86_64.sh | x86_64 |
pv-sdk-<tag>-armv8.sh | 64-bit ARM (aarch64) |
pv-sdk-<tag>-armv6.sh | 32-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:
| For | Examples (pkg-config names) | Tools in the sysroot |
|---|---|---|
| GPIO and buses | libgpiod, libiio, libusb-1.0, libsocketcan | gpiodetect, gpioset, i2cdetect, candump |
| Fieldbus | libmodbus, open62541 | |
| Networking and security | libcurl, openssl, libwebsockets, libmosquitto | |
| Cameras | libcamera, libv4l2, opencv4 | v4l2-ctl, media-ctl |
| Video processing and playback | gstreamer-1.0, gstreamer-video-1.0, gstreamer-rtsp-server-1.0 | gst-launch-1.0, gst-inspect-1.0 |
| Graphics | wayland-client, egl, glesv2, gbm, cairo | weston |
| User interfaces | Qt6Quick, gtk4, sdl2, lvgl, wpe-webkit-2.0 | cog |
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:
| Option | Same 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 NAME | PVR_APP_ADD_GROUP |
--roles "R1 R2" | PVR_APP_ADD_ROLES |
--comp lz4 | PANTAVISOR_FEATURES squash-lz4 |
-- <args> | PVR_APP_ADD_EXTRA_ARGS |
--no-var-volume | PVR_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.