Firmware Specification

The complete behavioural specification for ESP RainMaker Neo node firmware: what the node does at each stage of its life, the payloads it exchanges with the cloud, and how it recovers when things go wrong.

For setup, building, and factory provisioning, see the firmware guides. For the C API, see C API Reference.

Core Functionality

  • Initialization and Startup Sequence – component initialization order, prerequisites, failure points, and the overall firmware flow sequence diagram. Start here to understand how the node boots and initializes.

  • Node Configuration – node configuration payload format, including device and service definitions, parameters, attributes and metadata.

  • State Management – incoming state modifications (parameter updates from cloud/apps), outgoing state reporting (shadow updates), online/offline state management, named and indexed shadows, and shadow migration on group changes.

  • Timeseries Data Collection – timeseries data collection (publishing timestamped parameter values) and direct notifications from node to cloud.

  • Network Provisioning – network provisioning and user-node association: the provisioning sequence, the challenge-response endpoint, and protobuf message formats.

  • Local Control Endpoint Protocol – the wire protocol for the local control and challenge-response endpoints served over protocomm.

  • Time Synchronization – NTP/SNTP setup, which services require synchronised time, and failure handling.

  • Error Handling and Recovery Strategies – the general error handling approach, retry strategies for MQTT, shadows and events, and the error recovery flows.

Subsystems

  • Networking – MQTT topics, connection lifecycle and the event-based cloud communication protocol.

  • Services – built-in services (schedules, automation triggers) and optional ones (timezone, system control, local HTTP API).

  • OTA – OTA job document format and status-details reporting.