Basics

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

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()
     */
    app_wifi_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!!!");
        vTaskDelay(5000/portTICK_PERIOD_MS);
        abort();
    }

    /* 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: esp.param.name), 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 */
    esp_rmaker_start();

    /* 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
     */
    app_wifi_start(POP_TYPE_RANDOM);

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.