# Hermes robot

Desk robot giving Hermes Agent (on a NixOS or Omarchy host) a camera, microphones, speakers, a
pan/tilt head and an oscilloscope-style face. Hardware: Raspberry Pi 4, Adafruit BrainCraft HAT,
Arducam UC-346 (OV5647), two MG90S servos on GPIO12/13. Software: ROS 2 Jazzy on Ubuntu 24.04 on
the Pi; on the hosts, ROS runs only in podman containers.

**Start with `CONTEXT.md`**: where the work really stands, what is verified, the owner's decisions, and
what is open. `HANDOFF.md` is the original implementation brief (hardware facts, work packages,
acceptance checks); it has drifted, so read its status banner first.

- `pi/` and `ros/` run on the robot; `host/` runs on the owner's machines. `CONTEXT.md` tracks where
  the work stands; `HANDOFF.md` is the original brief and has drifted (ROS stays on the Pi, and
  `hermes_mcp` is the only bridge out; see `CONTEXT.md`).
- The platform is proven (`host/check-pi-platform.sh` passes and the Pi runs everything); `CONTEXT.md` says what is open.
- `docs/face-prototype.html` is the reference for the face renderer; port it, don't ship it.
- `enclosure/` holds the OpenSCAD model and STLs. It was built from estimates; refine it from the
  owner's caliper measurements and test prints before anyone prints the large parts.
- `README.md` is the guide for this build; keep it a guide for a person, and keep `CONTEXT.md` honest.
- The MCP server uses the MCP Python SDK 2.x (`mcp.server.mcpserver.MCPServer`), not 1.x `FastMCP`.
- Ask before rebooting the Pi, upgrading or holding kernel packages, or opening network ports.