home/v1 topics: full list

home/v1 is the base prefix of the topics devices use to talk to the server. The contract is defined once in code (bridge/protocol.mjs) and mirrored everywhere else — in the panel, in the simulator, in the checks. The prefix is changed with the BASE_TOPIC variable. Every device is described by three things: state, command and event.

State topics

• <base>/state/solar, …/battery, …/grid, …/load, …/boiler, …/heatpump, …/weather, …/alarm, …/mode — the state of the home's global subsystems.
• <base>/state/room/<id> — a room; …/light/<id> — lighting; …/zone/<id> — a climate or watering zone; …/door/<id> — a door or access point; …/camera/<id> — a camera; …/cover/<id> — a blind.
• <base>/state/switch/<id> — a smart plug with {on, power?, energyToday?}. The appliance behind it requires the energy permission, because it can be a 1.5 kW convector; criticality is given only through critical in the device registry.
• <base>/state/vacuum/<id> — a robot vacuum with {state, battery, fan, room?, program?}.
• <base>/state/safety/<id> — hazard sensors with {name?, kind, state, room?, battery?, lastTestAt?}.
• <base>/state/device/<id> — device presence: available or the failure message (LWT) that produces "offline".
• <base>/state/mode — the global home mode (off/home/away), retained so that every new client sees it immediately.

Events and commands

• <base>/event — an event with the fields ts, kind, deviceId, message. The server's event log is generated from it.
• <base>/cmd/<type> — the command arguments heading to the devices.

The commands the kiosk sends: light.set, light.all, room.set, room.all, zone.set, zone.all, door.set, door.all, alarm.set, cover.set, cover.position, cover.stop, cover.autoshade, safety.test, safety.mute, switch.set, boiler.set, heatpump.set, scene.run, home.mode.set and telemetry.debug (simulation only). Of these, home.mode.set never reaches the devices — the server takes it on itself, and scene.run unfolds into its actions on the server, each one passing the permission check.

How a message is read

Parsing is tolerant of the real chaos on a network: a number sent as "3.3" is accepted, a Buffer is decoded, double-encoded JSON is unwrapped, and the shape is validated against the definition. An unreliable row is not counted as zero — it simply stays out of the numbers you see on the screen.

What a driver has to honour

Publish your device state into the matching state/… topic and accept commands on cmd/<type>. For vendors with no reverse path a read-only mode already exists: the device is shown, but commands are not promised. Adding a new device needs no change to the screens — telemetry with an unknown id creates its own record.

What is not ready yet

• A real broker. The connection code exists, but the mqtt package is not in the dependencies and has not been tested against a broker; today the path is walked by the built-in simulator, which speaks the same topics. For your own broker set MQTT_URL (for example mqtt://192.168.1.20:1883) plus MQTT_USER / MQTT_PASS, and SIMULATE=1 brings the simulator back even when MQTT_URL is set.
• The translation from Zigbee, Modbus, KNX and ONVIF into these topics — that is the job of the missing drivers (support level by transport).
• Access outside the local network: the contract is a LAN contract, with no cloud bridge.

The two things that already work are the contract and the panel: the panel shows these same topics so you do not have to look for documentation elsewhere, and the simulation already runs over the same path, which is why the rules, the log and the permissions are tested against the contract. Details of how the screen connects to the server are in the architecture.