ecu-tests/docs/10_build_custom_image.md

Build a Custom Raspberry Pi Image with ECU Tests

This guide walks you through building your own Raspberry Pi OS image that already contains this framework, dependencies, config, and services. It uses the official pi-gen tool (used by Raspberry Pi OS) or the simpler pi-gen-lite alternatives.

Important: For full HIL on the Pi, the MUM (Melexis Universal Master) is the recommended hardware path — it's IP-reachable so the Pi only needs the Melexis Python packages (pylin, pymumclient), no native libraries. Bake those into the image's site-packages from the Melexis IDE bundle. BabyLin is deprecated; its support on ARM/Linux depends on vendor SDKs and is kept only for legacy rigs. If no .so is provided for ARM, either use the Mock or MUM interface on the Pi, or keep deprecated BabyLIN hardware tests on Windows until you can migrate.

Approach A: Using pi-gen (official)

1. Prepare a build host (Debian/Ubuntu)

   sudo apt update && sudo apt install -y git coreutils quilt parted qemu-user-static debootstrap zerofree \
     pxz zip dosfstools libcap2-bin grep rsync xz-utils file bc curl jq
   

2. Clone pi-gen

   git clone https://github.com/RPi-Distro/pi-gen.git
   cd pi-gen
   

3. Create a custom stage for ECU Tests (e.g., stage2/02-ecu-tests/):

   • 00-packages (optional OS deps like python3, libusb-1.0-0)
   • 01-run.sh to clone your repo, create venv, install deps, and set up systemd units

   Example 01-run.sh contents:

   #!/bin/bash -e
   REPO_DIR=/home/pi/ecu_tests
   sudo -u pi git clone <your-repo-url> "$REPO_DIR"
   cd "$REPO_DIR"
   sudo -u pi python3 -m venv .venv
   sudo -u pi bash -lc "source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt"
   sudo mkdir -p "$REPO_DIR/reports"
   sudo chown -R pi:pi "$REPO_DIR/reports"
   sudo install -Dm644 "$REPO_DIR/scripts/ecu-tests.service" /etc/systemd/system/ecu-tests.service
   sudo install -Dm644 "$REPO_DIR/scripts/ecu-tests.timer" /etc/systemd/system/ecu-tests.timer
   sudo systemctl enable ecu-tests.service
   sudo systemctl enable ecu-tests.timer || true
   # Optional udev rules (DEPRECATED: only needed for legacy BabyLIN hardware)
   if [ -f "$REPO_DIR/scripts/99-babylin.rules" ]; then
     sudo install -Dm644 "$REPO_DIR/scripts/99-babylin.rules" /etc/udev/rules.d/99-babylin.rules
   fi
   

4. Configure build options (config file in pi-gen root):

   IMG_NAME=ecu-tests-os
   ENABLE_SSH=1
   STAGE_LIST="stage0 stage1 stage2"  # include your custom stage2 additions
   

5. Build

   sudo ./build.sh
   

6. Flash the resulting .img to SD card with Raspberry Pi Imager or dd.

Approach B: Preseed on first boot (lighter)

• Ship a minimal Raspberry Pi OS image and a cloud-init/user-data or first-boot script that pulls your repo and runs scripts/pi_install.sh.
• Pros: Faster iteration; you control repo URL at install time.
• Cons: Requires internet on first boot.

CI Integration (optional)

• You can automate image builds with GitHub Actions or GitLab CI using a Docker runner that executes pi-gen.
• Upload the .img as a release asset or pipeline artifact.
• Optionally, bake environment-specific config/test_config.yaml or keep it external and set ECU_TESTS_CONFIG in the systemd unit.

Hardware Notes

• If using the deprecated BabyLin path (legacy rigs), ensure: .so for ARM, udev rules, and any kernel modules. New deployments should target MUM instead.
• Validate the SDK wrapper and libraries are present under /opt/ecu_tests/vendor/ (or your chosen path). Ensure .so files are on the linker path (run sudo ldconfig) and BabyLIN_library.py is importable.

Boot-time Behavior

• The ecu-tests.timer can schedule daily or hourly test runs; edit OnUnitActiveSec as needed.
• Logs are written to reports/service.log and reports/service.err on the Pi.

Security

• Consider read-only root filesystem for robustness.
• Use a dedicated user with limited privileges for test execution.
• Keep secrets (if any) injected via environment and not committed.