hermes-bot/CONTEXT.md

Current state

Last updated 2026-10-04. HANDOFF.md is the brief; this file tracks where the work stands.

Hardware on hand

Raspberry Pi 4, BrainCraft HAT, Arducam UC-346 camera. Not yet: servos, USB-C splitter, printed enclosure, speakers. Work until those arrive is limited to what the Pi, HAT and camera can do.

Package 0a (platform proof on Ubuntu 24.04)

• Step 1 done. host/check-pi-platform.sh passes: Ubuntu's 6.8.0-1065-raspi kernel ships every driver and overlay needed (WM8960 audio, OV5647, Unicam, PWM, SPI, dwc2 gadget with NCM/ECM/ACM). The script needed a fix for uncompressed data.tar (applied to host/ and the duplicate in tools/; uncommitted).
• Step 2 in progress: flashing the SD card. Image chosen: ubuntu-24.04.5-preinstalled-server-arm64+raspi.img.xz, SHA256 b23371a5c8d02f612c26e7c18cacb81c5a48f968c7c66a2645391320aa94351e (from cdimage.ubuntu.com/releases/24.04/release/SHA256SUMS). It was downloaded to the session scratchpad under /tmp, which a reboot likely cleared; re-download and re-verify.
• The Pi is not running yet. No card has been written. straylight (NixOS; has xz, dd, udisksctl, no rpi-imager) never detected the Framework SD expansion card: no kernel event in two bays, so the flashing moves to talos, where the owner confirmed the card mounts. Continue the session there: clone the repo, read this file, re-download and re-verify the image (the copy on straylight is in its /tmp). Check talos's OS and available tools first.
• Open questions for the owner before flashing: Wi-Fi credentials or Ethernet for first boot; hostname (proposed hermes-robot); username; SSH key (default ~/.ssh/id_ed25519.pub). Plan: write the image after the owner confirms the device from lsblk, then edit cloud-init on the system-boot partition (user, key, hostname, SSH, network).
• Remaining 0a steps after boot: ROS 2 Jazzy, audio (wm8960-soundcard overlay + mixer), camera (cam -l, camera_ros), display test pattern. PWM test waits for the servos. Ask before rebooting the Pi.

Repository

Git repo initialised on main with one commit ("Initial commit"). .gitignore covers .remember/, caches, .venv/, *.orig, *.rej. The earlier zip and patch files were deleted. tools/check-pi-platform.sh duplicates host/check-pi-platform.sh and can probably go.

Security review notes (parked until the USB link is up)

An automated review of the initial commit flagged three items. All stem from the code predating the USB-gadget design (HANDOFF.md package 0b); none is exposed until the Pi runs.

• pi/robot_mcp_server.py: plain HTTP, ROBOT_MCP_BIND defaults to 0.0.0.0. Plan: default to 10.55.0.2, start after usb0.
• pi/pipewire/50-network-server.conf: TCP 4713 on all interfaces, unrestricted. Plan: keep, comment that the firewall is the protection.
• pi/nftables-robot.nft: still the Pi Zero version (single host IP, any interface). Package 0b rewrites it to accept only on the USB interface from 10.55.0.1.
• pi/install.sh permissions looked fine (/etc/robot-mcp.env is root:$USER, 640).

The owner wants to confirm the real IPs on the link before changing any of this. If the USB link doesn't work, revisit: TLS or a Tailscale-only bind for MCP and audio.