Skip to main content
Documentation Hub

OTA Firmware Upgrade Usage Guide

Firmware Usage Guide​

about

OTA firmware upgrades is one of the most important functions of any IoT System. It helps add features and fix bugs for devices in fields. ESP RainMaker offers a rich OTA Upgrades interface with many options and flexibility.

  • To learn more about OTA firmware upgrades, please click here.
  • On the usage of how to (upload,start or monitor) OTA upgrades on dashboard, click here

Usage Guide​

Enable OTA Upgrades in the Firmware​

The recommended API to enable OTA functionality is to call this single API:

esp_rmaker_ota_enable_default();

This internally maps to "OTA Using Topics", uses the ESP x509 Certificate Bundle for server authentication and sets the default OTA callback.

info

For more details about OTA C APIs, click here

Setup OTA Upgrade Image​

Compile an OTA upgrade firmware image as you would normally do, but ensure the following:

  • The project name should be the same as that used for the firmware already flashed on the node(s).
  • The firmware version should be different than what the nodes already have. (check set(PROJECT_VER "1.0") in the example's CMakeLists.txt file)
disclaimer

If you miss out any of the above, the OTA upgrade will fail.

Bypass version & project name check (Not Recommended)

This is done in the following configuration option.
Again, this is not recommended.

CONFIG_ESP_RMAKER_SKIP_VERSION_CHECK=y
CONFIG_ESP_RMAKER_SKIP_PROJECT_NAME_CHECK=y

Auto Fetch Configuration​

  • Most of the time, it is desired that the OTA upgrades are sent to the nodes in a staggered way, so as to prevent overwhelming the server with too many image download requests at the same time.
  • Moreover, it is also possible that the node is offline when the cloud is publishing to node/<node_id>/otaurl, so alternative methods to fetch the upgrade information again are required.
  • When CONFIG_ESP_RMAKER_OTA_AUTOFETCH=y is set , the node tries to fetch the OTA upgrade periodically as per the interval specified by CONFIG_ESP_RMAKER_OTA_AUTOFETCH_PERIOD. This is accomplished by publishing the following data to node/<node_id>/otafetch:
{
    “node_id": “<node_id>",
    “fw_version": “<fw_version>"
}
tip

  • If the cloud service finds any OTA job pending for the node, it publishes it to node/<node_id>/otaurl as specified above and the job starts.

  • CONFIG_ESP_RMAKER_OTA_AUTOFETCH_PERIOD has a default value of 0, which means that the request will be sent only once, when the node connects to the cloud first time after a boot.
    Else, its range is 0 to 168 (hours).

Server Validation​

  • The OTA framework uses ESP x509 Certificate Bundle for server validation.
  • This allows it to fetch the OTA image from various different servers, including RainMaker backend (by default).
  • The OTA configuration optionally accepts a server certificate (server_cert) in case a specific server certificate is to be used, you can copy the appropriate server.crt file into your example's main/ folder and embed it into the binary by including the below line in main/CMakeLists.txt:
target_add_binary_data(${COMPONENT_TARGET} "server.crt" TEXT)

It can be accessed in your code using the following:

extern const uint8_t ota_server_cert[] asm("_binary_server_crt_start");

{
    ...
    esp_rmaker_ota_config_t ota_config = {
        .server_cert = (char *)ota_server_cert,
    };
    esp_rmaker_ota_enable(&ota_config, OTA_USING_PARAMS);
    ...
Skip server authentication (Not recommended)

If you want to skip server authentication, or use HTTP server instead of HTTPS (not recommended), please set CONFIG_OTA_ALLOW_HTTP=y in your sdkconfig.

Dashboard Usage to perform OTA​

On the usage of how to (upload,start or monitor) OTA upgrades on dashboard, click here.

On this page