UGV Beast is a multimodal "affective" rover stack: sense (vision, audio, optional biosignals) → fusion (BehaviorEngine: profiles, hysteresis, cooldowns) → act on a Cyberwave digital twin or live hardware, with optional northbound experience logging and southbound agent hints (see docs/CLOUD_AGENT_CONTRACT.md).
Uses: Python 3.13+, uv for env/lockfile, cyberwave-python for twin I/O, a vendor-free core under src/hedon_core/ (domain, fusion, ports), and on the Pi OpenCV + ONNX models (YuNet, VAD, SER, etc.) documented in docs/HEDON_EDGE.md.
| Document | Who it is for | What it covers |
|---|---|---|
| docs/ARCHITECTURE.md | Architects / onboarding / roadmap | Repo layout, pipelines, emotional mapping, Cyberwave runner summary, local sim requirements, gaps; links to Experience client + cloud contract |
| docs/RUNNERS.md | Day-to-day dev / ops | Make targets (including viz-bridge), Pi init + rsync, offline simulation, Cyberwave runners, autonomous loop, env var table, twin troubleshooting |
| docs/SETUP.md | Pi operators | HedonExt USB, HEDON_*, Piper, mic/camera, onboard Bluetooth for Polar (disable-bt), make pi / hedon-edge |
| docs/HEDON_EDGE.md | Edge developers | Orchestrator FSM, vision (YuNet, FER), audio (VAD, SER), models, Docker deploy on Pi, Raspberry Pi Bluetooth for Polar, twin frame fallback, tick log fields; viz-bridge laptop control UI |
| docs/ROS2_IMAGE_EDGE_VISION.md | ROS + edge | Subscribing to /image_raw for edge vision |
| docs/METHODOLOGY.md | Reproducibility | Fusion formulas: agreement, profiles, hysteresis, ambiguity, suppression |
| docs/CLOUD_AGENT_CONTRACT.md | Cloud + edge | JSON Schema + HTTP for Experience POST + agent hints (hosted API outside this repo) |
| docs/SIMULATION_RESULTS.md | Offline runs | Generated by simulation.py — do not hand-edit |
Suggested reading order: this README → ARCHITECTURE → METHODOLOGY (math) or SETUP + HEDON_EDGE (Pi).
git clone <this-repo-url>
cd hedon-robotics
make install
cp .env.example .env
make test- Offline fusion report (no Cyberwave):
make simulation→ docs/SIMULATION_RESULTS.md. - Cyberwave smoke test: set
CYBERWAVE_API_KEY,CYBERWAVE_TWIN_REGISTRY_ID, and usuallyCYBERWAVE_ENVIRONMENT_ID/CYBERWAVE_TWIN_IDin.env, thenmake sim-runner. - Raspberry Pi edge: docs/SETUP.md, then
make pi,make pi-models,make hedon-cw-bg(Docker) ormake hedon-edge(native). - Laptop control UI (viz-bridge):
make viz-bridge— opens a browser dashboard athttp://127.0.0.1:8765/with Connect/Disconnect tunnel, Sync Code, Start/Stop edge, live MJPEG stream, and detection state cards. See docs/HEDON_EDGE.md.
Full Makefile reference and runner behavior: docs/RUNNERS.md or run make / make help from the repo root.
| Symptom | What to check |
|---|---|
make test / import errors |
Run make install from repo root; Python ≥ 3.13. |
| Twin errors before "Connected to twin" | Repo root + .env with valid CYBERWAVE_API_KEY, registry id, environment/twin ids — see docs/RUNNERS.md. |
| API OK but nothing moves in the portal | Viewport on same environment, sim not paused; prefer navigation.goto as motion smoke test — docs/RUNNERS.md. |
| "Loading" / wrong world | CYBERWAVE_ENVIRONMENT_ID must match the session you are watching — docs/RUNNERS.md. |
| Edge / mic / camera / models | docs/HEDON_EDGE.md, docs/SETUP.md. |
| viz-bridge: "SSH forward not active" | Click Connect in the browser UI, or run ssh -L 8090:127.0.0.1:8090 hedon-pi manually. If port 8090 is in use the UI will prompt to force-reconnect. |
| viz-bridge: stream not loading | Ensure HEDON_VIZ_ENABLED=true in .env on the Pi and the edge is running (make hedon-cw-bg). Then click Connect tunnel and check status strip. |
| Docker logs empty after edge start | Edge output goes to docker compose logs; click Tail Logs in the viz-bridge UI (calls docker compose logs --tail over SSH). |
Polar / BLE: no Bluetooth; bluetooth.service skipped |
On Raspberry Pi, dtoverlay=disable-bt in /boot/firmware/config.txt turns off onboard BT — there is no /sys/class/bluetooth. Comment out that line, reboot, then enable the stack — docs/HEDON_EDGE.md. |