Introduction
hiot is a local-first platform for wiring physical things to software. Sensors, switches, blinds, meters, panels and remotes report to a space you control, and keep working when the network does not.
The system is deliberately small at the edge and boring in the middle: cheap microcontrollers speak a compact binary protocol, a hub bridges them onto MQTT, and a single backend owns identity, history and authorization.
Start here
If you want a device reporting in the next ten minutes, skip to the Quickstart. This page explains why the pieces are shaped the way they are, which is what makes the rest of the documentation predictable.
The shape of the system
Two paths reach the broker, and the difference matters for the rest of your design:
- Direct devices
- A device with a WiFi radio and enough flash talks MQTT itself. It holds its own credential and is addressable on its own topics.
- Bridged devices
- A device on ESP-NOW cannot speak MQTT and cannot subscribe to anything. It sends 26-byte frames to a hub, which bridges them. Anything addressed to a whole space has to be expanded by the hub, device by device.
Why that asymmetry is permanent
ESP-NOW is what makes a battery sensor viable — no association, no DHCP, no TLS handshake. The cost is that the cheapest devices are send-mostly. Every space-wide feature in the platform is designed around hub expansion rather than pretending the fleet is homogeneous.
The two planes
This is the one distinction the rest of the documentation assumes.
- Device plane. Devices and hubs are broker principals. They hold credentials, publish, subscribe, and are constrained by broker ACLs.
- Application plane. Users, apps and views are backend principals. They never hold a broker credential and never publish to a topic.
- The backend is the only thing on both. It receives an application-plane action, evaluates it, approves it, and then publishes on the device plane.
The consequence is practical: when you read about broker authorization — ACLs, per-device credentials, payload signing — that is a device-plane concern only. It never constrains what a user or a shared view can do, because those never touch the broker.
What runs where
- Local tier
- Devices, the hub, and Bluetooth LE. Direct LAN control and hub automation survive a dead uplink.
- Server tier
- Accounts, spaces and sharing, sample history, push notifications, remote access, firmware distribution. These are online by nature, not by accident.
Offline is a design property, not a fallback
A feature that needs the server is documented as needing the server. Nothing in the local tier is allowed to silently depend on the hosted backend — if it did, “the internet is down” and “the broker is unreachable” would become the same event.
Where to go next
| If you want to… | Read |
|---|---|
| Get a device reporting | Quickstart |
| Understand spaces, devices, endpoints, hubs, views | Core concepts |
| Publish or subscribe on the wire | MQTT topics |
| Write documentation like this page | Markdown reference |