Humalien Docs

Humalien is a cyborg head: 3D printed parts with a skin-like texture, driven by a natural voice conversation you can interrupt and talk over.

Doc	What's in it
architecture.md	How the brain and the node split the work, and why
voice-pipeline.md	Why the robot was answering itself, and how it's fixed
hardware.md	Pi 5, Waveshare hat, audio devices, echo cancellation
parts.md	What Humalien is made of, and what still needs buying
vision.md	USB webcam face tracking and the gaze-target contract
people.md	Recognising people, remembering them, and looking on request
running.md	Starting Humalien by hand, and on boot

The two machines

   USB webcam
        │
        ▼
┌──────────────────────────┐          ┌──────────────────────────┐
│  BRAIN                   │          │  NODE                    │
│  brain/                  │          │  node/                   │
│                          │◄────────►│                          │
│  Asus laptop → Jetson    │  ws://   │  Raspberry Pi 5          │
│  All the logic           │  :8765   │  Microphone + speaker    │
└──────────────────────────┘          └──────────────────────────┘
          │
          │ wss://
          ▼
   OpenAI Realtime API

The node is a dumb pipe. Every decision lives in the brain. That's what makes swapping the Asus for a Jetson Orin Nano a non-event.

Running it

On the Pi:

cd node
python -m pip install -r requirements.txt    # websockets only
python -m humalien_node.server

The Pi needs nothing from brain/requirements.txt — see running.md for what deliberately does not belong on it.

On the brain:

cd brain
python -m pip install -r requirements.txt
python tools/fetch_models.py    # face models, ~38 MB, once per machine
cp .env.example .env            # then fill in OPENAI_API_KEY
python humalien.py

humalien.py is the master entry point — it preflights, then supervises and reconnects. Run voice_core.py directly while developing, when you want a crash to be loud rather than retried. See running.md.

Without a Pi (testing on a laptop with headphones), run the simulator instead of the Pi node, and point HUMALIEN_PI_URL at ws://127.0.0.1:8765:

cd brain
python tools/list_audio_devices.py   # pick your real mic, not a loopback
python tools/desktop_node.py

To preview face tracking with a USB webcam, see vision.md.

Tests

cd brain
$env:PYTHONPATH = "."          # PowerShell; use export on Linux
python tests/test_audio_adapter.py     # 4 tests
python tests/test_playback.py          # 3 tests
python tests/test_gaze.py              # 11 tests
python tests/test_people.py            # 12 tests

None of them need a camera, a microphone, an API key, or the ONNX models. test_gaze.py doesn't even need OpenCV, and test_people.py runs against an in-memory database with synthetic embeddings — the matching maths is kept out of recognizer.py precisely so it stays testable without hardware.