Getting Started

We use the kas build tool to simplify the process. It automates fetching the necessary layers and setting up the build environment based on your selections.

Step 1: Clone the Repository

First, you’ll need to clone the meta-pantavisor repository and navigate into the directory.

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

Step 2: Configure Your Build

We provide an interactive configuration menu to make setup easy. Run the following command to open it:

kas menu

This will open a terminal-based UI where you can define your build. Your choices are saved to a .config.yaml file in the root of the repository.

Quick Start: Building a Starter Image

For your first build, we recommend creating a pantavisor-starter image. This image comes pre-packaged with useful containers to get you up and running quickly.

Select the following options in the kas menu:

  • Select Build Type ➔ singleconfig

  • Select Codename to build ➔ scarthgap

  • Select Build Target ➔ pantavisor-starter

  • Filter Machines ➔ Choose the filter for your board’s manufacturer (e.g., Raspberry Pi).

  • Machine ➔ Select your specific board (e.g., raspberrypi-armv8).

  • Save & Exit.

The pantavisor-starter image includes:

  • A network container: Manages device connectivity.

  • pvwificonnect: Provides a captive portal to easily configure Wi-Fi credentials.

  • pvr-sdk: A frontend container that helps you interact with the Pantavisor services on the device.

kas menu kas menu

Detailed Configuration Options

The kas menu allows for deep customization. Here’s a breakdown of the main options available:

Build Type:

  • singleconfig: Generates a single build configuration for one target machine. Ideal for most users.

  • multiconfig: Sets up a more complex environment to build for multiple machines simultaneously.

  • Yocto Codename:

    • kirkstone or scarthgap: Choose the Yocto Project release you want to build against.

    • Build Target: This defines the type of image you will create.

  • pantavisor-bsp: Builds a minimal Board Support Package (BSP) with the Pantavisor bare-metal components. It does not include any user-space containers.

  • pantavisor-remix: Builds a BSP and allows you to select which containers to include in the final image. Choose this for custom builds.

  • pantavisor-starter: Builds a pre-configured image with a useful set of default containers, as described in the Quick Start section. Recommended for new users.

  • Containers:

    • This sub-menu is only available if you select the pantavisor-remix Build Target. Here you can choose which containers (like pv-connman, pv-pvr-sdk, etc.) to bake into your image. You can also opt to convert an existing Yocto image target (like core-image-base) into a “root container,” which is great for migrating existing projects.

  • Machine Filter & Machine:

    • First, you can filter the list of boards by manufacturer (e.g., NXP, TI, Rockchip) to make it easier to find your hardware.

    • Then, select the specific machine (board) you are targeting.

Step 3: Build the Image

Once you’ve saved your .config.yaml, you can start the build process with a single command. This will take some time, especially the first time, as it needs to download all sources and compile them. ⚙️

kas build

When the build is complete, you’ll find the deployable image and other artifacts in the build/tmp-(release_name)/deploy/images/ directory, organized by your selected machine name.

Step 4: Keeping Your Build Environment Up-to-Date

To pull the latest changes for all the Yocto layers defined in your kas configuration, you can run the following command:

kas checkout --update

This ensures you have the latest updates and patches before starting a new build.