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 = {
        .info = {
            .name = "My_Switch",
            .type = "Switch",
        },
        .enable_time_sync = false,
    };
    err = esp_rmaker_init(&rainmaker_cfg);
    if (err != ESP_OK) {
        ESP_LOGE(TAG, "Could not initialise ESP RainMaker Agent. Aborting");
        while (1) {
            vTaskDelay(50/portTICK_PERIOD_MS);
        }
    }

    /* Create a device and add the relevant parameters to it */
    esp_rmaker_create_device("Switch", ESP_RMAKER_DEVICE_SWITCH, switch_callback, NULL);
    esp_rmaker_device_add_name_param("Switch", "name");
    esp_rmaker_device_add_power_param("Switch", "power", DEFAULT_POWER);
    esp_rmaker_device_assign_primary_param("Switch", "power");

    /* Start the ESP RainMaker Agent */
    esp_rmaker_start();

    /* Start the 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();

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

• Initialise the Wi-Fi (app_wifi_init()), primarily to get the MAC address which will act the unique node identifier (node_id).
• Initialise the ESP RainMaker agent (esp_rmaker_init())by passing it a configuration (esp_rmaker_config_t). The configuration provides some basic information of the node, along with some other options like time sync requirement.
• Create a device (esp_rmaker_create_device()). 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 callback, which 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 atleast the standard power parameter. Marking some parameter as primary gives it prominence in the phone apps.
• 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 the Wi-Fi (app_wifi_start()). If the 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 initialised and started before this call.