plt-agent-os

Agent-OS for Raspberry Pi 5

Repository Structure

plt-agent-os/
├── layers
│   ├── meta-agentos       # BCDevices Yocto layers/customization
│   ├── meta-lts-mixins    # 
│   ├── meta-openembedded  # 
│   ├── meta-raspberrypi   # 
│   ├── meta-rauc          # 
│   └── poky               # Yocto base distribution/build system
├── Makefile
├── README.md
└── scripts
    └── kas

Prerequisites

• Linux build machine (native Linux, VM) - Yocto does not build on macOS or Windows
• Git, Make

System Packages (build)

sudo apt-get install -y make chrpath diffstat pipx
pipx install "kas==5.1"

System Packages (development/flashing)

sudo apt-get install -y bmaptool

Firmware Images

The repo builds two firmware images for the same hardware:

• AgentOS - The operating system that the device runs day-to-day. Any test agent running v2.0.0 or later can be updated via Rauc and does not require direct imaging of the SD Card. Earlier versions require reflashing the SD Card with bmaptool.
• Manufacturing Image - Programmed to an empty SD card when test agents are assembled on the manufacturing line. This image contains nothing other than some files to boot up the Test Agent hardware in a minimal shell and expose its SD card as a USB disk. The USB disk can then be flashed via the PLT. This image does not receive regular updates due to it's minimal functionality and does not need to be built on a regular basis.

Build steps

1. Clone

git clone <repo-url> plt-agent-os

2. Build

For AgentOS:

cd plt-agent-os
make

For the Manufacturing Image (one-time provisioning image):

cd plt-agent-os
KAS_YML=scripts/kas/kas-rpi-mfg-image.yml make

3. Flash

AgentOS >= v2

• Plug Agent USB type C power adapter into Test Agent and Wall Outlet
• Plug Agent USB type C data port into PC
• Plug Agent USB type A port into PC. A storage drive should appear
• Drag and drop the .raucb file to the Test Agent's storage drive
• Access the Agent's shell and type or copy/paste the following

pltagent-msc-mount && rauc install /run/pltagent/mnt/core-image-agentos-bundle-raspberrypi5.raucb

• The Test Agent will install the update payload and reboot into the new OS

AgentOS < v2 Also supported on v2 and beyond

• Power off the Test Agent
• Remove the SD Card
• Connect the SD Card to a PC
• After erasing, use bmaptool to reimage the SD Card (below)

blkdiscard <SD Card>
bmaptool copy <image file> <SD Card>

Caution/Note

Using bmaptool without erasing the SDCard first can cause failure of the Test Agent to boot. bmaptool is optimized to avoid flashing empty blocks to the file system which can cause corruption issues if a previous image was written to the SD card before updating it. Always erase the SD card before writing to it with bmaptool. blkdiscard on Linux accomplishes this.

Development and debugging

AgentOS >=v2 Agentos >=v2 initializes the Raspberry Pi 5 dedicated debug uart, which gives access to all boot diagnostics. The Raspberry Pi 5 does not contain full support for the 40 pin GPIO connector UART and a separate 3-pin adapter must be used. Consult Raspberry Pi 5 documentation for more details on the debug connector. With the debug UART, diagnostics and boot information can be captured before and after the test agent completes the boot process. This is useful for debugging issues early on in the initialization process.