RIoT2 is a generic, self-hosted platform for running Internet of Things scenarios, from a smart home to a lab full of sensors. Devices talk over MQTT, a central orchestrator owns configuration and state, Elsa 3 workflows provide automation, and a web UI, a mobile app, Matter controllers (Apple Home, Google Home, Amazon Alexa) and Grafana show and control it all.
- Nodes connect to the MQTT bus and host devices: sensors, actuators and integrations, loaded as plugins. A node runs as a Docker container (also on a Raspberry Pi) or as firmware on ESP32 devices with a screen.
- Devices publish reports (for example "temperature is 21.5") and receive commands (for example "turn the lamp on").
- The orchestrator is the hub. It stores every node's configuration, tracks state and history, routes commands, and forwards reports to Elsa for automation.
- Connectors bridge the bus to external systems, such as InfluxDB for Grafana dashboards.
- RIoT2 is designed for an isolated, single-user network: it is simple to run, and it has no login. See security.
More detail: architecture overview.
On one Docker host with Docker Compose:
git clone --depth 1 https://github.com/Revolutionized-IoT2/.github.git riot2
cd riot2/deploy
cp .env.example .env # set RIOT2_HOST, RIOT2_MQTT_PASSWORD and ELSA_IDENTITY_SIGNING_KEY
docker compose up -d --waitThen open http://<host>/. This starts the MQTT broker, orchestrator, Elsa and the UI; add a node
with --profile node.
- Getting started: the same install step by step, with the node and its device plugins.
- Configure your first node: a guided tour of the UI.
- Deployment variations: Raspberry Pi and ESP32 nodes, InfluxDB/Grafana, the mobile app and Matter.
Already running RIoT2? Read upgrading before you pull new images. When you update a node, update the node image before you install the new plugin zip.
| Repository | Description |
|---|---|
| RIoT2.Core | Shared library with the common data model, MQTT conventions, and services used by every other component. |
| RIoT2.Net.Orchestrator | The central hub: tracks nodes, forwards reports to Elsa, and coordinates the system over MQTT. |
| RIoT2.Net.Node | The agent that runs on IoT hardware/hubs and dynamically loads device plugins. |
| RIoT2.Net.Devices | The default device plugin catalog for the Node (webhooks, MQTT, Netatmo, Philips Hue, Firebase messaging, electricity price, and more). |
| RIoT2.Net.RasPi.Devices | A device plugin catalog for Raspberry Pi hardware, covering GPIO, I2C, Bluetooth, serial, and Z-Wave devices. |
| RIoT2.Ard.M5Core2.Node | ESP32 firmware turning an M5Stack Core2 into a touchscreen RIoT2 node (lights, scenes, sensors). |
| RIoT2.Ard.M5Dial.Node | ESP32 firmware turning an M5Stack M5Dial into a rotary-dial RIoT2 node. |
| RIoT2.Ard.Shared | Shared Wi-Fi/MQTT/provisioning/OTA firmware library used by both M5 node firmwares. |
| RIoT2.Ard.WiegandI2C | An ATtiny85 sketch that decodes Wiegand RFID/badge readers and exposes the code over I2C. |
| RIoT2.UI | The web dashboard for monitoring devices, configuring nodes, and opening Elsa Studio. |
| RIoT2.Mobile | A .NET MAUI mobile app that displays the dashboard and receives Firebase push notifications. |
| RIoT2.Matter | A managed .NET implementation of the Matter smart-home protocol, for interop with controllers like Apple Home and Google Home. |
| RIoT2.Elsa | Elsa 3 workflow engine and Studio, providing automation for RIoT2. |
| RIoT2.Connector.InfluxDB | Bridges the MQTT bus into InfluxDB for Grafana visualization. |
| RIoT2.Tests | Unit and reliability test suite for RIoT2.Core, the Orchestrator and the InfluxDB connector. |
| Looking for | Go to |
|---|---|
| Guides (install, configure, operate) | docs/guides |
| Architecture and design decisions | overview, ADRs |
| MQTT, HTTP/gRPC, variables, configuration format | docs/contracts |
| What's planned | Roadmap, delivery increments, backlog, target architecture |
| Everything | Documentation index |
- Each repository has a README.md for people and an AGENTS.md for AI coding agents.
- The workspace-wide guide for agents is AGENTS.md.
- Platform contracts change additively, and they are documented in docs/contracts in the same change.
