How to build the PandA boot image

Prerequisites¶

• kas installed, or Docker / Podman available so that kas-container can pull and run the build container automatically.

• A clone of the meta-panda repository.

Build steps¶

1. Clone the repository:

   git clone https://github.com/PandABlocks/meta-panda
   cd meta-panda

2. If kas is not already installed, create a virtual environment and install it:

   python3 -m venv venv && . venv/bin/activate && pip install kas

3. Fetch the prebuilt FPGA packages and generate their recipes:

   ./fetch-fpga-ipks.py

   This downloads the panda-fpga-ipks-<tag>.tar.gz asset from the PandABlocks-FPGA release named in fpga-release.txt, unpacks the packages into ipks/, and writes a recipe for each one into recipes-panda/panda-fpga-generated/. Neither directory is tracked in git. The recipes are regenerated from scratch every run; ipks/ is only ever added to — nothing already there is removed or overwritten.

   To build against a different release, either edit fpga-release.txt or pass --release <tag>. To build against a locally built bitstream, drop its .ipk into ipks/: because existing files are never overwritten, yours is used in place of the release’s copy and survives later fetches. Add --no-download to regenerate without going to the network at all.

4. Resolve the pinned upstream releases:

   ./fetch-source-revs.py

   The recipes built from a GitHub checkout take their version and commit from a generated file rather than carrying them inline. Each upstream repository is pinned as a git tag in a top-level release file:

   Release file	Repository	Recipes
   panda-server-release.txt	PandABlocks-server	panda-server, kernel-module-panda
   panda-webcontrol-release.txt	PandABlocks-webcontrol	python3-panda-webcontrol

   This resolves each tag to a commit and writes PV and SRCREV into recipes-panda/<name>-generated/, which is not tracked in git either. The server and its driver are built from one checkout, so pinning them together is what stops them drifting apart.

   To build a different version, edit the release file, or pass a single source and --release <tag>, e.g. ./fetch-source-revs.py panda-webcontrol --release 4.0. The lookup is skipped when the generated file already pins the tag you asked for; --force resolves it again.

5. Build the image. kas-container pulls the required build container image automatically — no manual Docker setup is needed:

   export KAS_IMAGE_VERSION="4.8"
   kas-container build ./kas.yml

   To target a different machine set KAS_MACHINE, e.g.:

   KAS_MACHINE=pandabrick kas-container build ./kas.yml

   The default machine is pandabox. Output lands under build/tmp/deploy/images/<machine>. For the valid values, and which of them build without supplying your own FPGA packages, see Machine targets.

6. (Optional) Collect the output files, for example for pandabox:

   mkdir boot
   cp -Lf build/tmp/deploy/images/pandabox/fitImage-petalinux-initramfs-image-pandabox-pandabox \
       boot/image.ub
   cp -f build/tmp/deploy/images/pandabox/{rootfs.squashfs,boot.bin,boot.scr,target-defs} boot/
   zip boot-pandabox.zip boot/*

   Alternatively, the build.sh helper script runs every step above and collects everything for a specific machine in one go:

   ./build.sh <MACHINE> </path/to/workdir>

   A boot-<machine>.zip file is created in the current directory.

Output files¶

Copy these files to the SD card and insert it in the target; the system will boot normally. On the first boot of a pandabox you will be prompted for a MAC address.

To build the FPGA app that can be used to make the firmware, see Assemble blocks into an app