MQTT protocol
MQTT for the smart home: one contract, many devices and no cloud
Anything that speaks home/v1 is already inside the system.
What is ready in the contract, what is missing for a real broker, and how your own device connects.
In short
MQTT is a light publish and subscribe protocol: the device publishes its state into a topic, the server records it and applies the rules. HoumeOS describes its house with the home/v1 contract — state, commands and events for every device. The panel and the simulation already speak it; the broker with the real devices is still to come.
Why MQTT is the language of the house
MQTT is old, small and clear: there is a broker, there are topics, everyone publishes and everyone listens. It does not ask for a cloud account, it does not hold sessions, and it does not make a device depend on the app of its manufacturer. For us it is not only a transport but a contract: whoever keeps it enters the same screen, with the same rights and the same history.
- Publishing and listening on topics, with no direct link between devices
- Retained messages: a new client sees the last state immediately
- Every programming language has an MQTT client — a driver is a small part
The home/v1 contract
The contract is defined in code and describes a device as three things: state, command and event. The state topics carry the presence and the description of the device, the mode topic carries the global mode of the house, and commands and events have their own path. The integration panel shows the same contract, so you are not left hunting for documentation.
What works today
The simulation travels the same path as real devices, which is why the interface, the rules and the journal have already been tested against the contract. The kiosk talks to the server over HTTP and an SSE stream with an access token, and every command passes the rights, the confirmation for critical actions and the audit. That is the real data path today — without an outside broker.
What is still to come: the broker with real devices
The code for connecting a real broker exists, but the MQTT package is not in the project dependencies and has not been tested with a broker. The next step is a broker in the local network, optionally with TLS, then device discovery and the first integrations. Until that is done we do not say "connect your MQTT device today".
How your own device connects
From the device side only the contract is asked for: publish state on the device topic and accept commands from it. For manufacturers without a return path there is a read-only mode — the device is shown, but commands are not promised. There is a simulation mode without hardware and a tested core, so a driver can be developed without a site.
What works today and what is coming
We do not present upcoming work as available. This list matches the roadmap.
Works today
- The home/v1 contract: state, commands and events, defined in code
- An integration panel that shows the contract and the topics
- A simulation that speaks over the same path and tests the rules with it
- The HTTP+SSE facade to the kiosk with token, rights, confirmations and audit
Coming soon
- The MQTT package in the dependencies and a broker in the local network
- A test with a real broker: the device changes state, and a stopped broker gives a status and an alert
Later
- Device discovery in the network and TLS on request
- OCPP for external chargers and HTTPS remote access
Frequently asked questions
Is there a ready MQTT broker in HoumeOS?
It is not ready. The description is: the home/v1 topics, the shape of state and commands, and the panel that shows the contract. The broker that real devices would publish to is the next step. Today the same contract is used by the simulation, so the interface and the rules are already tested against it.
What is the difference between HTTP+SSE and MQTT?
They sit in two different places. MQTT is the internal language between devices and the server; HTTP and the SSE stream are the facade through which the kiosk reads state and sends commands. The kiosk does not need an MQTT client, and devices do not need a browser — that is why the two are separated.
What does a topic look like?
Along the device topic: the state topic carries the presence and the description of the device, the command topic carries the requested action, and the event topic carries the changes the system notes. The global mode of the house has its own topic with a retained message, so every new client sees it immediately.
Can I send commands from the outside?
Today you talk to the server from the outside, not to a broker: commands go through the HTTP facade with an access token, pass the rights and the confirmation for critical actions, and leave a trace in the journal. When the real broker is ready, the same path can be used by external MQTT clients as well.
How are the topics kept safe?
Everything stays inside the local network: the server address is static and lives in the settings, access is by token, and user rights and the PIN code are verified on the server. With a real broker TLS is planned as an option — not as a mandatory barrier, but as a possibility for larger installations.
We show the system on a live screen
The demo starts from your question: which devices, which protocols, which scenarios.