Skip to content

PIPELINE.md

Latest commit

 

History

History
150 lines (99 loc) · 3.87 KB

PIPELINE.md

File metadata and controls

150 lines (99 loc) · 3.87 KB
Raw

AMS Firmware Pipeline — Setup & Runbook

Hands-off build → flash → verify pipeline for the AMS flight logger. Konrad pushes to main; the device gets reflashed and the result appears as a Paperclip comment.

Quick Start (manual run)

# Full pipeline: compile → upload → smoke test
make pipeline

# Compile only (no device needed)
make build

# Override board or port
make pipeline ENV=t-a7670g-r2-debug PORT=/dev/ttyACM0

Host Setup

1. Install PlatformIO

pip3 install platformio pyserial

PlatformIO caches the ESP32 toolchain on first build (~400 MB). Pre-warm it:

make build

2. Serial port permissions

Add your user (or the CI runner user) to the dialout group so it can access USB serial:

sudo usermod -a -G dialout $USER
# Log out and back in, or: newgrp dialout

3. Connect the device

Plug the board into USB. Verify it appears:

ls /dev/ttyUSB* /dev/ttyACM*
# e.g. /dev/ttyUSB0

GitHub Actions CI (automatic, on main push)

One-time setup

  1. Register a self-hosted runner on the always-on host:

    • GitHub → repo → Settings → Actions → Runners → "New self-hosted runner"
    • Follow the install instructions; add label ams-device during setup

  2. Add GitHub secrets (repo → Settings → Secrets → Actions):

    Secret Value
    PAPERCLIP_API_KEY Agent JWT (from Paperclip agent settings)
    PAPERCLIP_API_URL http://localhost:3100
    PAPERCLIP_AMS87_ISSUE_ID UUID of the active tracking issue

  3. Push to main — the workflow triggers automatically.

Manual trigger

GitHub → Actions → "Firmware pipeline" → "Run workflow"
Optionally specify a different PlatformIO environment or serial port.

Pipeline stages

Stage Tool Failure exit
Compile python3 -m platformio run -e <env> Exit 1
Upload platformio run --target upload --upload-port <port> Exit 2
Smoke test pipeline/smoke_test.py Exit 3

Smoke test assertions

Run against the *-debug build (includes SIMULATE_GPS + SIMULATE_IMU):

Check What is verified
Startup banner AMS Flight Logger in first 5 s
NMEA sentence $GPRMC or $GPGGA within 30 s (echoed by debug build)
Non-zero IMU rms>0.001g in status line
State prefix [GROUND] (or other state) in status line

Run manually:

make smoke PORT=/dev/ttyUSB0

PlatformIO environments

Env Board Notes
t-sim7000g T-SIM7000G (Cat-M1) Production build
t-sim7000g-debug T-SIM7000G GPS+IMU simulated; echoes NMEA to serial
t-a7670g-r2 T-A7670G R2 (Cat-1 + L76K) Production build
t-a7670g-r2-debug T-A7670G R2 GPS+IMU simulated; echoes NMEA to serial

Default pipeline environment: t-sim7000g-debug.
To target production firmware against live GPS/IMU, pass ENV=t-sim7000g.
Note: smoke test NMEA assertion requires a debug build or a live GPS lock.

Result reporting

After each run, pipeline/post_result.sh posts a comment to the Paperclip issue with pass/fail status and the last 20 lines of pipeline/last_run.log.

Requires PAPERCLIP_API_KEY and PAPERCLIP_API_URL set in environment.

Troubleshooting

no USB serial port found
→ Device not plugged in, or kernel module not loaded. Run dmesg | tail -20 after plugging in.

Permission denied: /dev/ttyUSB0
→ Add user to dialout group (see Host Setup above).

Upload fails with esptool.py: error: argument --port
→ Port auto-detection failed; pass --port /dev/ttyUSBx explicitly.

Smoke test: NMEA not seen within 30 s
→ Check you're using a *-debug build. Production builds do not echo raw NMEA.

Smoke test: no startup banner within 5 s
→ Board didn't reset after upload; power-cycle and re-run make smoke.