Basic Services

ESP RainMaker services are practical examples that integrate specific functions to facilitate secondary development and enrich the functionality of nodes. For example, the scheduling service provides devices with the offline timing/countdown function; the system service offers the remote reboot and factory reset functions; the time & time zone service enables the time zone switching function; the OTA upgrade service provides the remote update function; and the local control service allows fast, stable, and secure LAN communication. These services can be quickly implemented with simple configuration.

Time & time zone service

Fetching time is one of the most critical tasks for an IoT device after connecting to the Internet, especially when the scheduling service is enabled. In ESP RainMaker, there are two important concepts: time and time zone.

Time is typically fetched using Simple Network Time Protocol (SNTP). The ESP RainMaker SDK provides an abstraction layer over the SNTP component in ESP-IDF, making it easy for you to synchronise and check time. The code is as follows:

/*Initialise time synchronisation. This will call the SNTP component internally and set the SNTP server through sntp_server_name passed by esp_rmaker_time_config_t*/
esp_err_t esp_rmaker_time_sync_init(esp_rmaker_time_config_t *config);

//Check if time has been synchronised by comparison with the standard time 1546300800
bool esp_rmaker_time_check(void);

//Wait for time to be synchronised
esp_err_t esp_rmaker_time_wait_for_sync(uint32_t ticks_to_wait);

As countries and regions in different longitudes have different local times and time zones, the TZ environment variable and the tz_set() function are provided by ESP-IDF to set the time zone. RainMaker provides an abstraction layer over this and provides multiple ways of setting it. For example:

1. Using the C API.

   //Set time zone using the timezone region string
   esp_err_t esp_rmaker_time_set_timezone(const char *tz);
   
   //Set time zone using the POSIX format
   esp_err_t esp_rmaker_time_set_timezone_posix(const char *tz_posix);
   

2. Modifying Default Timezone in menuconfig. To use this method, you need to have some basic understanding of ESP-IDF. For more information, please refer to Chapter 4. The configuration for this method is as follows:

    (Top) → Component config → ESP RainMaker Common
       Espressif IoT Development Framework Configuration
   ...
   (Asia/Shanghai) Default Timezone
   ...
   

3. Setting time zone directly on the client side via the time zone service. To enable this service, call the following function on the device side:

   esp_err_t esp_rmaker_timezone_service_enable(void);
   

Scheduling service

The scheduling service performs periodic modifications to device parameters. For example, if you need to turn on a light at 7pm and turn it off at 11pm every day, this service can spare you from manually turning it on and off. After configured, this service runs independently on the device and does not rely on the network, which means that the device can perform the configured operation correctly even when the device is disconnected from the network. To enable this service, call the following function on the device side:

esp_err_t esp_rmaker_schedule_enable(void);

OTA upgrade service

ESP RainMaker provides the OTA upgrade service to update firmware. You only need to call a simple API to enable it. There are two methods of performing OTA upgrade.

OTA upgrade using parameters

This is the simplest way for developers to upgrade firmware OTA. You only need to upload the firmware to any secure web server and provide the URL to the node. This method can be triggered from the ESP RainMaker CLI client. The otaupgrade command in the CLI tool is used to complete the upgrade, as shown below:

esp_rmaker_ota_config_t ota_config = {
    .server_cert = ESP_RMAKER_OTA_DEFAULT_SERVER_CERT,
};
esp_rmaker_ota_enable(&ota_config, OTA_USING_PARAMS);

OTA upgrade using MQTT topics

This is a more advanced method available to admin users to upgrade firmware OTA. They need to upload the firmware to the dashboard and create a task there to enable the OTA upgrade. The device will receive the OTA upgrade URL and report the upgrade progress over MQTT. The code is as follows:

esp_rmaker_ota_config_t ota_config = {
    .server_cert = ESP_RMAKER_OTA_DEFAULT_SERVER_CERT,
};
esp_rmaker_ota_enable(&ota_config, OTA_USING_TOPICS);

Local control service

Besides remote control, ESP RainMaker also enables the client to locally control the nodes that are on the same Wi-Fi network as the client. This makes the entire process of control and response faster and more reliable. ESP-IDF provides a component called ESP Local Control, which uses mDNS-based discovery and HTTP-based control. It is now integrated into the ESP RainMaker SDK.

Local control does not require adding a service to the node configuration message. It protects data using asymmetric encryption algorithms and transmits the Proof of possession (PoP) to the app through the local control service. The smartphone app completes encryption using the PoP.

# Enable local control
CONFIG_ESP_RMAKER_LOCAL_CTRL_ENABLE=y

# Enable local control encryption
CONFIG_ESP_RMAKER_LOCAL_CTRL_SECURITY_1=y

System service

ESP RainMaker presets a set of system services for factory reset and remote reboot. Smartphone apps can use these services to erase the network configuration information on the device and unmap users from the devices. To enable this service, call the following API on the device side:

esp_err_t esp_rmaker_system_service_enable(esp_rmaker_system_serv_config_t *config)