# Home Bus

## Purpose

The `home` bus exposes room-centric and user-facing telemetry, state, and control topics for the living environment.

Typical systems connected to this bus include:

- environmental sensors
- lighting and switches
- motion/contact/presence sensors
- thermostats and climate devices
- smart sockets for on/off control semantics

The `home` bus models living-space behavior, not electrical topology.

This document defines the `home`-specific topic grammar and semantic ownership.

Shared rules for payload profiles, metadata, time semantics, quality, and operational topics are defined in `mqtt_contract.md`.


## Scope and Ownership

The `home` bus owns room and automation semantics.

The `energy` bus owns electrical accounting semantics.

Examples:

- `vad/home/living-room/power/tv/value` is room control state
- `vad/home/living-room/power/tv/set` is room control command
- `vad/energy/load/living-room-entertainment/active_power/value` is electrical telemetry

Rule:

- publish user-oriented control/state on `home`
- publish electrical measurement and accounting on `energy`


## Normative Topic Contract (v1)

All home topics MUST follow:

`<site>/home/<location>/<capability>/<device_id>/<stream>`

Where:

- `<site>`: deployment/site id, for example `vad`
- `<location>`: normalized area identifier in kebab-case
- `<capability>`: semantic capability in snake_case
- `<device_id>`: stable device/entity identifier in kebab-case
- `<stream>`: one of `value`, `last`, `set`, `meta`, `availability`

Examples:

- `vad/home/bedroom/temperature/bedroom-sensor/value`
- `vad/home/living-room/motion/radar-south/value`
- `vad/home/kitchen/light/ceiling-switch/value`
- `vad/home/living-room/power/tv/set`


## Canonical Identity Model

The `home` bus is built around stable room semantics.

Rules:

- `<location>` MUST describe the living-space area, not the vendor room name if the two differ
- `<device_id>` MUST identify the logical endpoint exposed to consumers
- one physical device MAY publish multiple capabilities under the same `<device_id>`
- replacing a physical Zigbee sensor SHOULD keep the same canonical `<device_id>` when the logical endpoint remains the same

Examples:

- `bedroom-sensor` is a logical endpoint
- `0x00158d0008aa1111` is a vendor identity and belongs in `meta.source_ref`, not in the topic path

This keeps HomeKit, historian, and automations insulated from vendor identity churn.


## Stream Semantics

- `value`: live semantic sample, whether measurement, held state, or transition notification
- `last`: retained last-known timestamped sample for startup/bootstrap decisions
- `set`: command/request topic for controllable capabilities
- `meta`: static or slowly-changing metadata
- `availability`: online/offline state

Rules:

- adapters SHOULD emit live hot-path data only on `value`
- adapters SHOULD deduplicate repeated `value` samples when the semantic value did not change
- adapters SHOULD publish retained `last` for the latest known timestamped sample
- legacy `state` and `event` topics SHOULD be treated as compatibility-only during migration

Command safety:

- `set` MUST NOT be retained
- stateful devices SHOULD acknowledge commands via `value`
- payload profile and time semantics follow `mqtt_contract.md`


## Payload Contract

To keep Node-RED flows efficient, two payload profiles are allowed.

### Profile A: Hot Path Scalar (recommended)

For frequent updates, payload SHOULD be scalar.

Examples:

- `vad/home/bedroom/temperature/bedroom-sensor/value` -> `23.6`
- `vad/home/living-room/motion/radar-south/value` -> `true`

Metadata is published separately on retained `meta`.

Example:

- Topic: `vad/home/bedroom/temperature/bedroom-sensor/meta`
- Payload:

```json
{
  "unit": "C",
  "source": "zigbee_adapter",
  "precision": 0.1
}
```

### Profile B: Envelope JSON (optional)

For streams that need inline quality/timestamp:

```json
{
  "value": 23.6,
  "unit": "C",
  "observed_at": "2026-03-08T10:15:12Z",
  "quality": "good"
}
```

Recommendation:

- prefer Profile A on high-frequency paths
- use Profile B where source quality/time must travel with each sample
- if exact source timestamp must be preserved, use Profile B
- use `last` with Profile B and `observed_at` when control consumers need a startup sample with freshness information
- do not repeat metadata or adapter internals in `value` payloads
- keep Profile B envelopes small and canonical


## Capability Catalog (initial)

Environmental capabilities:

- `temperature`
- `humidity`
- `pressure`
- `illuminance`
- `co2`
- `voc`
- `pm25`
- `pm10`

Presence and safety capabilities:

- `motion`
- `presence`
- `contact`
- `water_leak`
- `smoke`
- `gas`
- `tamper`

Control and user-facing capabilities:

- `light`
- `power`
- `lock`
- `cover_position`
- `thermostat_mode`
- `target_temperature`
- `fan_mode`
- `button`

Device health capabilities that are still user-relevant:

- `battery`
- `battery_low`

Rules:

- use `power` on `home` only for control semantics
- use electrical telemetry such as `active_power` and cumulative counters such as `energy_total` on `energy`
- radio diagnostics such as `linkquality` SHOULD NOT go on `home` by default
- `presence` SHOULD normally be a higher-level derived state, not a raw single-device detection
- raw mmWave detection, including Zigbee `presence` with `fading_time=0`, SHOULD be published as `motion`


## MQTT Delivery Policy

Default policy:

- `value`: QoS 1, retain false
- `last`: QoS 1, retain true
- `set`: QoS 1, retain false
- `meta`: QoS 1, retain true
- `availability`: QoS 1, retain true (LWT preferred)

Cold-start rule:

- control consumers such as thermostats SHOULD subscribe to retained `last` to obtain the latest known sample at startup
- `last` SHOULD include `observed_at` so staleness can be evaluated immediately after subscribe
- consumers MAY unsubscribe from `last` after bootstrap and continue consuming lightweight live updates on `value`
- consumers that depend on deterministic retained bootstrap SHOULD use a dedicated MQTT client session instead of sharing the same broker config with unrelated subscribers

If uncertain, choose QoS 1.


## Node-RED Implementation Optimizations

Translation is done in Node-RED, so the contract is optimized for low processing overhead.

Guidelines:

- keep topic shape stable to simplify wildcard routing and switch nodes
- avoid unnecessary JSON parse/build in high-rate pipelines
- publish device metadata on retained `meta` to avoid payload repetition
- publish canonical MQTT-ready messages as early as possible after normalization
- emit MQTT-ready messages only at the publish boundary
- do not carry adapter-internal normalization structures on forwarded `msg` objects
- discard temporary normalization fields before publish
- keep `value` streams extremely lightweight
- centralize mapping rules (location, capability, device_id) in reusable subflows
- keep one ingress subflow per protocol and one normalization subflow shared by all
- avoid broad `#` subscriptions in hot paths

Suggested Node-RED subscriptions:

- `+/home/+/+/+/value`
- `+/home/+/+/+/last`
- `+/home/+/+/+/set`


## Interaction with Other Buses

Cross-bus correlations are implemented by consumers, not by changing bus semantics.

Examples:

- combine `home` presence with `energy` load telemetry for occupancy-aware energy decisions
- combine `home` climate data with `network` device state for diagnostics


## Historian Relationship

The `home` bus is a major historian source.

For ingestion worker compatibility, each message should map to:

- `metric_name`
- `device_id`
- `value`
- `observed_at`

`device_id` recommendation:

- `<location>.<device_id>`

Historian defaults:

- `value` streams SHOULD be ingested by default
- `last` streams SHOULD NOT be ingested as normal telemetry samples
- `meta.historian.mode` SHOULD describe whether a `value` stream represents `sample`, `state`, or `event` semantics
- when Profile A scalar is used, `observed_at` will usually fall back to ingestion time
- string enum states are semantically valid, but the current PostgreSQL ingestion API directly supports only numeric and boolean samples

Example:

- Topic: `vad/home/bedroom/temperature/bedroom-sensor/value`
- `metric_name = temperature`
- `device_id = bedroom.bedroom-sensor`

Zigbee2MQTT projection examples:

- `zigbee2mqtt/bedroom_sensor.temperature` -> `vad/home/bedroom/temperature/bedroom-sensor/value`
- `zigbee2mqtt/front_door_contact.contact` -> `vad/home/entrance/contact/front-door/value`
- `zigbee2mqtt/bedside_remote.action` -> `vad/home/bedroom/button/bedside-remote/value`


## Relationship with HomeKit

The `home` bus is a primary source for HomeKit adapters.

HomeKit integration remains a consumer layer concern:

- Device -> Protocol Adapter -> MQTT Bus -> HomeKit Adapter -> HomeKit

The `home` bus contract SHOULD remain independent from HomeKit-specific modeling constraints.


## Design Principles

- keep room-centric semantics explicit and stable
- separate control semantics (`home`) from electrical accounting (`energy`)
- optimize for deterministic, low-cost Node-RED translation
- keep topic grammar strict and payload overhead low
- keep canonical IDs independent from vendor identifiers