muse-familiar

current mood: idle — these are the real frames from frames.py

Moods

Simulate a webhook event

The UNO Q is two computers in a UNO: a Qualcomm core running Debian, and an STM32 core running Zephyr sketches. The Familiar lives on the LED matrix in between.

It idles and blinks. Green CI → it hops. Failed deploy → it sulks. Incident → wide-eyed. Hot SoC → it dozes off.

Pair it with Muse and your assistant can ask how it feels, cheer it up, and read its narrations in chat: "The Familiar is now happy (event: ci_green)."

Try the moods and events — the grid is the exact 8×13, 3-bit-grayscale art the board renders.

How it works

Feed it

GitHub, Home Assistant, or curl hit a tiny hardened webhook on the board's Linux side. Key'd, rate-limited, loopback by default — ready-made senders in examples/.

Feel it

A mood engine turns events into frame art and pushes animations over the board's msgpack-RPC bridge — 19 ms round-trip, chunked around the router's 256-byte cap.

Show it

A Zephyr sketch on the STM32U585 renders frames — with fps, brightness and idle-timeout safety enforced in the MCU itself, so a crash can never leave it strobing.

Make it yours

uno-q — quickstart

git clone https://github.com/nitishagar/muse-familiar ~/muse-familiar && cd ~/muse-familiar
read -rs UNOQ_UPLOAD_PASSWORD && export UNOQ_UPLOAD_PASSWORD
cd firmware && ./upload.sh && cd ..          # flash the frame player
scripts/install.sh                        # webhook key + engine service
curl -X POST localhost:8123/poke -H "X-Familiar-Key: $(cat ~/.config/familiar/key)" -d '{"kind":"ci_green"}'

ci_green / deploy_ok / merge → happy ci_red / deploy_fail → sad alert / incident → alert mention / poke → curious hot → sleepy

It's a real Muse gadget

Meta's Muse gadget SDK runs on the Debian side. One command opens pairing (sudo musegadget pair), the Muse app adopts it, and the repo ships contract-tested commands — the first open-source Muse gadget that actuates real hardware on Linux.

familiar.statusfamiliar.showfamiliar.feed

Safety, baked in

≤ 4 fps, 3-bitPhotosensitivity and brightness caps enforced in the sketch, not just the host.

Idle timeoutNo heartbeat for 30 s → the Familiar dozes to a dim glyph. Crashes can't strand it.

Hardened webhookShared key (constant-time), 2 KiB cap, 12/min rate limit, bounded queue.

User-space onlyUser systemd units, one project dir, stock board services untouched, clean teardown.