Skip to content

Use it

The bridge daemon·

ring-cli bridge: the long-running daemon that turns a ring into a tiny health device from a Mac or Pi, and the reference for every gateway port.

  • people who want vitals in tiny without a phone
  • 1 min read
  • 112 words

In 10 seconds

ring-cli bridge holds the one BLE link and posts vitals, history and memos to your tiny account from a desk machine — the reference for the phone gateways. One bridge per ring; touch ~/.tiny/ring/pause to lend the ring. ring-cli bridge -a <uuid|mac> --days 2

connect → handshake (time, app-info, auto-HR every 5 min, features, info, battery)
        → history sync (steps / sleep / HR+SpO2+temp records for --days)
        → memo sync   (0x3D count → 0x40/0x34 pull → POST /api/health/media → ring clears)
        → live listen (cmd 11 HR, 6 battery, 24 SpO2, 21 temp, 40 button, 29 steps)
        → flush every --flush-s to POST /api/health/ingest; resync every --resync-s; auto-reconnect
Behaviour worth knowing — one bridge, pause file, cradle, recording guard, fallback queue
  • One bridge only. ~/.tiny/ring/bridge.pid names the live process; a second ring-cli bridge refuses to start (two bridges = every sample posted twice — it happened). Kill the python process, not a shell wrapper.
  • Sharing the ring with another agent — do not kill the bridge. touch ~/.tiny/ring/pause → the bridge flushes and disconnects within ~1 s, then waits; rm ~/.tiny/ring/pause → it reconnects.
  • On macOS a ring bonded to this Mac is usually already connected by the system; the transport attaches to that CBPeripheral first and scans only as a fallback. Several processes can share the link — notifications fan out to every subscriber — so quick CLI reads work while the bridge runs.
  • Charging = in the cradle. While charging=1 the bridge skips day-0 sleep buckets (cradle time would become tonight's night) and debounces battery posts to one per 5 min unless the level/state changes.
  • Recording guard. Memo sync first reads 0x2F audio state and skips while any recording is in progress, so it never cuts a memo the owner is dictating. Pulled memos are written to ~/.tiny/ring/private/memos/memo-<utc>.opus before the ring is asked to delete its copy; a .posted.json marker means tiny has it (server dedupes by sha256).
  • Failed ingest posts (5xx / network) queue to a fallback jsonl; 4xx are dropped with the reason logged.

Logs: ~/.tiny/ring/bridge.err.log (human lines), ~/.tiny/ring/bridge.jsonl (every frame, hex + decoded).

Run it·

ring-cli bridge -a <uuid|mac> --days 2 --flush-s 60 --evidence ~/.tiny/ring/bridge.jsonl

Credentials: ~/.tiny/device.json ({"deviceId", "token"}, from npx tiny-tech) goes in the JSON body of both doors — no session cookie. tools/launchd-bridge.sh installs it as a macOS LaunchAgent; a systemd unit works on a Pi.