Skip to main content


The ESP RainMaker agent is built on top of ESP-IDF and provides simple APIs to build applications based on the ESP RainMaker specification.

SDK Structure

The C API documentation can be found here.

Simple Example

To understand the ESP RainMaker firmware, let's have a look at the simple Switch example (esp-rainmaker/examples/switch/main/app_main.c). The relevant code snippet is as below

    /* Initialize Wi-Fi. Note that, this should be called before esp_rmaker_init()

/* Initialize the ESP RainMaker Agent.
* Note that this should be called after app_wifi_init() but before app_wifi_start()
* */
esp_rmaker_config_t rainmaker_cfg = {
.enable_time_sync = false,
esp_rmaker_node_t *node = esp_rmaker_node_init(&rainmaker_cfg, "ESP RainMaker Device", "Switch");
if (!node) {
ESP_LOGE(TAG, "Could not initialise node. Aborting!!!");

/* Create a Switch device.
* You can optionally use the helper API esp_rmaker_switch_device_create() to
* avoid writing code for adding the name and power parameters.
switch_device = esp_rmaker_device_create("Switch", ESP_RMAKER_DEVICE_SWITCH, NULL);

/* Add the write callback for the device. We aren't registering any read callback yet as
* it is for future use.
esp_rmaker_device_add_cb(switch_device, write_cb, NULL);

/* Add the standard name parameter (type:, which allows setting a persistent,
* user friendly custom name from the phone apps. All devices are recommended to have this
* parameter.
esp_rmaker_device_add_param(switch_device, esp_rmaker_name_param_create("name", "Switch"));

/* Add the standard power parameter (type: esp.param.power), which adds a boolean param
* with a toggle switch ui-type.
esp_rmaker_param_t *power_param = esp_rmaker_power_param_create("power", DEFAULT_POWER);
esp_rmaker_device_add_param(switch_device, power_param);

/* Assign the power parameter as the primary, so that it can be controlled from the
* home screen of the phone apps.
esp_rmaker_device_assign_primary_param(switch_device, power_param);

/* Add this switch device to the node */
esp_rmaker_node_add_device(node, switch_device);

/* Start the ESP RainMaker Agent */

/* Start Wi-Fi.
* If the node is provisioned, it will start connection attempts,
* else, it will start Wi-Fi provisioning. The function will return
* after a connection has been successfully established

The typical code for any ESP RainMaker based application is as follows:

  • Initialize Wi-Fi (app_wifi_init()), which also initializes the MAC address that will act as the unique node identifier (node_id) for ESP32-S2 self-claiming.
  • Initialize the ESP RainMaker node (esp_rmaker_node_init()) by passing it a configuration (esp_rmaker_config_t), node name and type.
  • Create a device (esp_rmaker_device_create()). The RainMaker node in itself has no specific value, unless it has a device under it. In our example, we create a device named "Switch", for which we also provide a write callback. The callback will be invoked if a write request is received for any parameter under the Switch device.
  • Add parameters and other metadata. A switch device, at the minimum, will have at least the standard power parameter. Marking some parameter as primary gives it prominence in the phone apps.
  • Add the device to the node.
  • Start the RainMaker Agent (esp_rmaker_start()). This will start the RainMaker core task which will wait for Wi-Fi, do the claiming, if required, connect to the RainMaker cloud over MQTT, report the node configuration, report the values of parameters, and then wait for commands.
  • Start Wi-Fi (app_wifi_start()). If ESP32 is already provisioned, it will join the configured Wi-Fi network. Else, it will start the Wi-Fi provisioning. Note that rainmaker should be initialized and started before this call.