hedon-robotics (UGV Beast)

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.

Screencapture of the laptop control UI (make viz-bridge — see docs/HEDON_EDGE.md).

Documentation

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/GET + agent hints
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).

Getting started

git clone <this-repo-url>
cd hedon-robotics
make install
cp .env.example .env
make test

• Offline fusion + pem-core (optional): make simulation → docs/SIMULATION_RESULTS.md. With EXPERIENCE_API_URL and DRY_RUN=false, posts each step to pem-core and GETs a cloud verify summary (see below).
• Cyberwave smoke test: set CYBERWAVE_API_KEY, CYBERWAVE_TWIN_REGISTRY_ID, and usually CYBERWAVE_ENVIRONMENT_ID / CYBERWAVE_TWIN_ID in .env, then make sim-runner.
• Raspberry Pi edge: docs/SETUP.md, then make pi, make pi-models, make hedon-cw-bg (Docker) or make hedon-edge (native).
• Laptop control UI (viz-bridge): make viz-bridge — opens a browser dashboard at http://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.

pem-core (local cloud backend)

Experience logging targets pem-core when configured. This is not Supabase JWT auth — use a shared EXPERIENCE_API_KEY (same string in both repos).

1. Start pem-core: cd pem-core && make server
2. In .env:

EXPERIENCE_API_URL=http://127.0.0.1:54321/functions/v1/experiences
EXPERIENCE_API_KEY=pem-local-experience-key
DRY_RUN=false
ROBOT_ID=ugb-beast-01

3. Run make simulation — posts all scenario steps, then prints e.g. Cloud verify: N experience.record event(s) for 'ugb-beast-01'.

Endpoint	Method	Auth
/functions/v1/experiences	POST	Bearer EXPERIENCE_API_KEY + X-Experience-Schema-Version: 1
/functions/v1/experiences?robot_id=&limit=	GET	same Bearer

Leave EXPERIENCE_API_URL unset or DRY_RUN=true for stdout-only (no network). Agent hints and device x-device-token ingest are separate pem-core paths — see pem-core README.

Troubleshooting

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.
make simulation POST/GET fails	pem-core make server running; EXPERIENCE_API_KEY matches pem-core .env; not the Supabase publishable/S3 keys.