Skip to main content

ESP Insights (Beta)

ESP Insights is a remote diagnostics solution that allows users to remotely monitor the health of ESP devices in the field. ESP Insights is now available in all ESP RainMaker examples.

Enabling ESP Insights​

Update esp-rainmaker​

Before you go further, please ensure that your esp-rainmaker repository is up to date by executing the below commands:

cd /path/to/esp-rainmaker
git pull origin master
git submodule update --init --recursive

This will pull in the esp-insights submodule under esp-rainmaker/components and also set up all the default examples with appropriate support for ESP Insights. If you only want to try the default examples, you may skip the next two sections about CMakeLists.txt.

Edit CMakeLists.txt​

For pulling in the ESP Insights functionality in your existing projects, include the components under esp-rainmaker/components/esp-insights/components. Search for the following line in your CMakeLists.txt file:

set(EXTRA_COMPONENT_DIRS ${CMAKE_CURRENT_LIST_DIR}/../../components ${CMAKE_CURRENT_LIST_DIR}/../common)

Then replace it with the following line:

set(EXTRA_COMPONENT_DIRS ${CMAKE_CURRENT_LIST_DIR}/../../components ${CMAKE_CURRENT_LIST_DIR}/../common ${CMAKE_CURRENT_LIST_DIR}/../../components/esp-insights/components)

A better option is to just refer to the new CMakeLists.txt file from any of the examples and copy appropriate sections into your file.

Enable ESP Insights​

The code related to ESP Insights is abstracted by the examples/common/app_insights component and is disabled by default. To enable ESP Insights, use idf.py menuconfig and select Component config > ESP Insights > Enable ESP Insights to set CONFIG_ESP_INSIGHTS_ENABLED=y.

Include app_insights.h in your project's code and add the following line before esp_rmaker_start():

app_insights_enable();

The above line is already included in all ESP RainMaker examples, so you only have to enable CONFIG_ESP_INSIGHTS_ENABLED.

Build and Flash Your Project​

Follow the regular process to build and flash your project.

idf.py build flash monitor

Notice that you will see such extra lines in your build log:

===================== Generating insights firmware package build/led_light-v1.0.zip ======================
led_light-v1.0
led_light-v1.0/led_light.bin
led_light-v1.0/sdkconfig
led_light-v1.0/partition_table
led_light-v1.0/partition_table/partition-table.bin
led_light-v1.0/bootloader
led_light-v1.0/bootloader/bootloader.bin
led_light-v1.0/partitions.csv
led_light-v1.0/project_build_config.json
led_light-v1.0/led_light.map
led_light-v1.0/led_light.elf
led_light-v1.0/project_description.json

The zip file generated under build/, i.e., build/led_light-v1.0.zip in the above code, will be required later.

Claiming​

ESP RainMaker users must be aware of the concept of claiming. There are three Claiming Services:

  1. Self Claiming
  2. Host Driven Claiming
  3. Assisted Claiming

To get access to ESP Insights, the admin access to the nodes is required. Therefore, you will have to use either Host Driven Claiming or Assisted Claiming. Even for ESP32-S2, which uses Self Claiming by default, you will need to use Host Driven Claiming to get the admin access.

Checking ESP Insights​

Once the firmware is ready and the claiming is completed, use your project as normal. Visit the ESP RainMaker Dashboard, log in using the credentials used for the claiming, search for your node ID, and check your ESP Insights.

Here is a sample of how ESP Insights shows up on the dashboard:

Upload Firmware Package​

To get better insights into the diagnostics information, you also need to upload the firmware package, which consists of the binary, elf, map files, and other information useful for analysis. Please upload the package named <project_name>-<fw_version>.zip, which you can find in the build/ folder of your project by navigating to the Firmware Images section of the dashboard.

Commands such as idf.py build and idf.py flash rebuild the firmware even if there is no change in the code, which causes changes to the firmware package. Please make sure that the binary file flashed on your board and the firmware package uploaded on the dashboard are in sync.

Further Reading​

Please refer to the ESP Insights documentation for more information. If you want to use ESP Insights for commercial products, please contact us.