Firmware SDK overview
The RainMaker Neo firmware SDK (esp-rainmaker-neo-firmware) is the C library you embed in device firmware to talk to a RainMaker Neo deployment. It is consumed as an ESP-IDF component — that is the platform products ship on. The same tree also builds as a POSIX CMake library with the same API, data model, and MQTT contract, currently intended for testing and development without hardware: the exact application code that runs on ESP32 silicon runs as a Linux/macOS host process.
New here? Go to the firmware guides and pick your platform.
What it does for you
The SDK owns everything between your application logic and AWS IoT Core:
- Connectivity — MQTT over mutual TLS to AWS IoT Core, with reconnect, subscription state, retry and backoff.
- Data model — nodes, devices, services, parameters, attributes, and tags, plus the standard
esp.*types the phone apps and voice assistants understand. - State — coalesced parameter reporting, shadow updates, online/offline tracking, and NVS persistence for parameters that need it.
- Schedules and automation triggers — evaluated on the node, so they keep working when the internet does not. No enable call needed.
- Identity — assisted claiming at first setup (the default on ESP-IDF), pre-flashed factory NVS credentials, or a pluggable provider if your credentials live somewhere else.
- OTA — AWS IoT Jobs over MQTT file streams, with resume, signature verification, and rollback diagnostics.
- Optional services — timezone, system control (reboot / network reset / factory reset), local HTTP control, on-network challenge-response, and a serial console.
What you write is the part that is actually yours: hardware drivers, the parameter callbacks that drive them, and the shape of your device.
Supported platforms
| ESP-IDF | POSIX | |
|---|---|---|
| Intended for | Production firmware | Testing and development without hardware |
| Runs on | ESP32 silicon | Linux, macOS host process |
| Consumed as | ESP-IDF component | CMake library (add_subdirectory + target_link_libraries) |
| Targets / releases | esp32, esp32c2, esp32c3, esp32c5, esp32c6, esp32s3 on ESP-IDF v6.0.2 or later | Native toolchain, CMake 3.16+ |
| Network provisioning | Wi-Fi (BLE or SoftAP) | Not applicable — already networked |
| OTA | Real partitions and bootloader | Mock bootloader with ota_0 / ota_1 files |
| Setup guide | Set up ESP-IDF | Set up POSIX |
POSIX is not a simulator in the sense of a stub — the core, data model, MQTT, shadows, services, and OTA state machine are all the real implementations. Only the hardware (LED, button, radio) and provisioning are stubbed. It is what the SDK's own integration tests run against.
Architecture
| Component | Purpose |
|---|---|
esp_rmaker_neo | The core: node and data model, public API, services (schedules, automation, timezone, system, local control), bridge, challenge-response, console |
esp_rmaker_neo_common | Shared machinery: credentials providers, work queue, MQTT channel glue, crypto and conversion helpers, error types, public event definitions |
esp_rmaker_neo_ota | Optional OTA support over AWS IoT Jobs plus MQTT file streams |
osal | The platform abstraction layer — one component with an osal_* API and per-area ESP-IDF and POSIX implementations: tasks, storage, JSON, time sync, network status, discovery, HTTP, console, MQTT, OTA, serial I/O |
The osal layer is why the same app_main.c compiles for both platforms. Your application code does not include platform headers or use OS #ifdef.
Where to start
| You want to | Go to |
|---|---|
| Get something running | Firmware guides |
| Understand an application's structure | Code basics |
| Define your device | Data model |
| See what features exist | Feature overview |
| Give devices an identity | Device credentials |
| Ship | Pre-production checklist |
| Know the exact wire format | Firmware specifications |