Skip to content

Latest commit

 

History

History
172 lines (138 loc) · 8.39 KB

integrations.md

File metadata and controls

172 lines (138 loc) · 8.39 KB

HomeKit and MQTT reference

Setup steps live in the user guide: HomeKit and MQTT. This page keeps the protocol-level reference that changes with the code: accessory mappings, identity, topics, and environment variables.


HomeKit bridge

The Pod ships an embedded hap-nodejs bridge that publishes itself as a native HomeKit accessory over Bonjour. No Homebridge install, no Apple cloud round-trip — pairing and control happen entirely on your LAN.

graph LR
  iOS[iPhone / iPad<br/>Home app] -- HAP / mDNS --> Pod[Pod<br/>sleepypod-core<br/>:51827]
  Pod -- setPower / setTemperature --> DAC[Pod hardware]
  Pod -. occupancy / vitals .- BIO[(biometrics.db)]
Loading

The bridge is off by default — toggle it on from Settings → HomeKit. The installer's iptables rules accept HAP (tcp/51827) only from LAN address ranges; mDNS discovery (udp/5353) is accepted without a source restriction, so the bridge is discoverable but not pairable or controllable from outside the LAN.

Accessories

Each side (left, right) gets its own set; switches that act on the whole pod ship once.

Accessory Type Reads from Writes to
Bed <side> Thermostat (single setpoint) deviceStatus.<side> setTemperature / setPower
Bed <side> power Switch deviceStatus.<side>.powered setPower (preserves last setpoint)
Bed <side> occupancy OccupancySensor sleep_records (latest with leftBedAt IS NULL) —
Snooze <side> Switch snoozeManager snoozeAlarm / cancelSnooze
Prime Switch primeNotification (auto-off on completion) startPriming
Pod ambient TemperatureSensor bed_temp.ambient_temp (centidegrees → °C) —

Thermostat is HomeKit's single-setpoint primitive (the pod hardware exposes one setpoint, not a heat/cool deadband). Mode off cuts power; auto powers on at the last requested temperature. HomeKit Celsius is converted at the boundary; the in-app unit preference is unaffected.

Identity durability

The bridge's HomeKit identity (MAC-style username, pincode, setupId) is deterministically derived from a hardware-rooted seed (eMMC CID → machine-id → random fallback) via HKDF, and cached at $DATA_DIR/homekit/identity.json (where $DATA_DIR is the picker-chosen data dir — see scripts/README.md; typically /persistent/sleepypod-data/homekit/identity.json on Pod 4/5). As long as the selected seed is unchanged, a /persistent wipe or firmware reflash regenerates the same identity, so iOS still recognizes the bridge — you only re-pair, your automations and rooms stay intact. When the seed comes from machine-id (which does not survive a factory reset) or the random-dev fallback, deleting identity.json produces a new identity, and the bridge must be removed and re-added in iOS. See ADR 0020 for the full rationale, seed chain, and what the design intentionally does not protect against.

Environment variables

Headless deployments can override the auto-detected mDNS advertiser. All other config (enable/disable, pairing) lives in device_settings and is managed from the UI.

Variable Default Description
HOMEKIT_ADVERTISER auto (avahi if /run/avahi-daemon/socket exists, else ciao) mDNS advertiser; force avahi to coexist with the existing _sleepypod._tcp service file, or ciao for pods without avahi

MQTT bridge

The Pod can connect outbound to an MQTT broker you already run (typically the Mosquitto add-on that ships with Home Assistant). Off by default — opt in from Settings → MQTT in the web UI.

graph LR
  Pod[Pod<br/>sleepypod-core] -- mqtt:// --> Broker[(MQTT broker<br/>e.g. Mosquitto)]
  Broker --> HA[Home Assistant]
  Broker --> NR[Node-RED]
  Broker --> Other[anything that<br/>speaks MQTT]
  HA -. cmd/* .-> Broker
  NR -. cmd/* .-> Broker
  Broker -. cmd/* .-> Pod
Loading

The Pod is a client, not a broker. It does not embed a broker, does not listen on 1883, and does not punch holes in the LAN-only iptables policy.

Configuration

Headless deployments can skip the UI by setting environment variables; the bridge resolves config in this order: device_settings row > env var > built-in default.

UI field Env var Default
Enable bridge MQTT_ENABLED false
Broker URL MQTT_URL (unset — bridge stays dormant)
Username MQTT_USERNAME (none)
Password MQTT_PASSWORD (none)
Topic prefix MQTT_TOPIC_PREFIX sleepypod
HA discovery MQTT_HA_DISCOVERY true
HA discovery prefix MQTT_HA_DISCOVERY_PREFIX homeassistant
TLS MQTT_TLS false
TLS allow self-signed MQTT_TLS_INSECURE false

The URL scheme decides whether the connection is encrypted: mqtts:// uses TLS, mqtt:// is plain TCP. The TLS toggle does not upgrade an mqtt:// URL; it only gates MQTT_TLS_INSECURE, which skips certificate verification when both are on.

Topics

<prefix> defaults to sleepypod. <device-id> is the slugified hostname (override with MQTT_DEVICE_ID). All state topics are retained.

Topic Direction Payload
<prefix>/<device-id>/availability pod → broker online / offline (LWT)
<prefix>/<device-id>/state/device-status pod → broker full deviceStatus JSON
<prefix>/<device-id>/state/<side>/climate pod → broker per-side temp / mode
<prefix>/<device-id>/state/water-level pod → broker low / ok / unknown
<prefix>/<device-id>/state/biometrics/<side> pod → broker latest HR / HRV / BR
<prefix>/<device-id>/state/environment/ambient pod → broker {"ts": <epoch_ms>, "temperature": <number|null>, "humidity": <number|null>} (°C, %)
<prefix>/<device-id>/state/<side>/alarm pod → broker {"ts", "nextAlarm": <ISO|null>, "time": "HH:mm", "day", "wakeWindowMinutes", "wakeWindowStart": <ISO|null>, "ringing", "snoozedUntil": <ISO|null>}
<prefix>/<device-id>/cmd/set-temperature broker → pod {"side","temperature","duration?"}
<prefix>/<device-id>/cmd/set-power broker → pod {"side","powered","temperature?"}
<prefix>/<device-id>/cmd/set-alarm broker → pod {"side","vibrationIntensity","vibrationPattern","duration"}
<prefix>/<device-id>/cmd/clear-alarm broker → pod {"side"} (stops the alarm and any snooze)
<prefix>/<device-id>/cmd/snooze-alarm broker → pod {"side","duration?"} (seconds, 60–1800)
<prefix>/<device-id>/cmd/start-priming broker → pod {}

With Home Assistant discovery on, each side also gets a Next alarm sensor (a timestamp: when that side's alarm next goes off, in the pod's timezone, unknown when none is set or the side is away) with the set time, day, wake window and snooze as attributes, and an Alarm ringing binary sensor. Use them to, say, open the blinds at the alarm or turn the lights on when it rings. The next alarm is the set time; with a wake window it can go off earlier, from wakeWindowStart. State refreshes every 30 s, so an alarm change shows up in Home Assistant within half a minute. Alarm ringing updates as soon as the alarm starts or stops.

Each side also gets Snooze alarm and Stop alarm buttons, which publish cmd/snooze-alarm and cmd/clear-alarm. A snooze works like tapping the bed: it lasts the ringing alarm's own snooze length (shortened by its snooze taper, kept within 1–30 min) and the alarm comes back with the same vibration. Put duration in the payload to snooze for a set time instead.

Commands route through the same tRPC procedures the iOS app calls, so Zod input schemas validate every payload — the bridge cannot accidentally diverge from the app's safety envelope.

Example: turn off the left side from any MQTT client

mosquitto_pub -h broker.lan \
  -t 'sleepypod/eight-pod/cmd/set-power' \
  -m '{"side":"left","powered":false}'

State mirrors back on sleepypod/eight-pod/state/left/climate within ~1 s.

See ADR 0019 for the design rationale — why client-not-broker, the credential storage decision, the tRPC dispatch model, and what's deferred until protectedProcedure lands.