ESP RAINMAKER

ESP RAINMAKER

  • Smart Home
  • Docs
  • API
  • Help
  • Blog
  • GitHub

›Develop Firmware

Get Started

  • Get Started

Develop Firmware

  • Basics
  • Standard Types

Specifications

  • Concepts
  • Node - Cloud communication
  • Client - Cloud communication
  • User - Node Mapping
  • Claiming
  • User Roles

Services

  • OTA FW Upgrades
  • Time Service
  • Scheduling
  • Local Control Service
  • Scenes
  • System Service

CLI

  • Setup
  • Usage

3rd Party Integrations

  • 3rd Party Integrations

Other Features

  • Node Sharing
  • Local Control
  • ESP Insights (Beta)

What's Next?

  • What's Next?

Documentation Feedback

  • Documentation Feedback

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.

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

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

  • Initialise the Wi-Fi (app_wifi_init()), which also initialises the MAC address which will act as the unique node identifier (node_id) for ESP32-S2 self claiming.
  • Initialise 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, 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.
  • 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 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.
← Get StartedStandard Types →
  • Simple Example
Copyright © 2022 Espressif SystemsPrivacy PolicyTerms of UseCookie Policy