Firmware guides
These guides take you from a fresh clone of the firmware SDK to a production-ready node: install a toolchain, build an example, provision credentials, write your own device logic, and ship OTA updates.
Everything here is task-oriented. When you need the exact wire contract instead — MQTT topic names, payload schemas, state-report semantics — go to the firmware specifications.
Start here
Pick the platform you are building for. Both use the same SDK, the same API, and the same cloud contract.
| ESP-IDF — real ESP32 hardware | POSIX — Linux/macOS host process | |
|---|---|---|
| 1. Install | Set up ESP-IDF | Set up POSIX |
| 2. Build | Configure and build | Configure and build |
| 3. Get it online | Network provisioning over BLE or SoftAP | Already on your host's network — no provisioning step |
| 4. Give it an identity | Assisted claiming does it during provisioning — nothing to flash | Factory NVS → drop nvs_persistent/ next to the binary |
| 5. Make it yours | Code basics | Code basics |
Clone the SDK, cd examples/light, and follow Configure and build. The light example is the reference implementation — it exercises the node data model, all the optional services, and OTA in about 200 lines of app_main.c.
By task
Writing firmware
| Guide | What it covers |
|---|---|
| Code basics | The shape of a RainMaker Neo application: init order, esp_rmaker_node_init(), esp_rmaker_start() |
| Data model | Nodes, devices, services, parameters, attributes, tags; standard vs custom types; property flags |
| Custom & standard types | The full type reference: devices, services, parameters, UI elements |
| Callbacks and events | Handling writes and reads, reporting state back, subscribing to the SDK event loop |
| Serial console | Built-in REPL commands for inspecting and driving a node over UART |
| Start your own project | Copying an example out of the tree and wiring the SDK into your own build |
Enabling features
| Guide | Enabled by |
|---|---|
| Feature overview | — (start here to see what is on by default) |
| Schedules and automations | Always on |
| Time and timezone | enable_time_sync + esp_rmaker_timezone_service_enable() |
| System service | esp_rmaker_system_service_enable() |
| Local control | esp_rmaker_local_ctrl_service_enable() |
| Time series data | Parameter property flags |
| OTA firmware updates | esp_rmaker_neo_ota component + esp_rmaker_ota_enable() |
| Bridge nodes | CONFIG_ESP_RMAKER_NEO_BRIDGE_ENABLE |
Device credentials and manufacturing
| Guide | Use it when |
|---|---|
| Device credentials | Understanding what a node needs before it can connect |
| Network provisioning | Wi-Fi/BLE onboarding — transports, PoP, QR codes, association |
| Assisted claiming | The default — the node gets its own credentials at first setup |
| Factory NVS | Generating and flashing credentials for one device |
| Dashboard batch flow | Creating a handful of test nodes from the Admin Dashboard |
| CLI batch flow | Scripted manufacturing runs and merged flash images |
Shipping
| Guide | Use it when |
|---|---|
| Pre-production checklist | Before you build the image that goes on real hardware |
| Tools reference | Looking for the right script under tools/ |
| Troubleshooting | A node won't connect, won't reset, or won't take an update |
How the pieces fit
The factory NVS partition holds the node's permanent identity. On ESP-IDF it is normally filled in by assisted claiming during first setup; pre-flashing it at manufacturing is the alternative. Either way it survives a factory reset. Wi-Fi credentials are written at provisioning time and are cleared by a network or factory reset. See Device credentials for the split.
Related
- Firmware SDK overview — what the SDK is, which components exist, which targets are supported
- Examples — the catalogue of buildable example projects
- Firmware specifications — the formal node behaviour and protocol contract