Getting Started with ESP Insights in the esp-insights Project

To get started with ESP Insights in the esp-insights project, please follow the steps below:

1. Clone the latest esp-RainMaker.

Based on the previous introduction to the ESP RainMaker IoT cloud platform, pull the project code of esp-RainMaker, and esp-insights will be under the project directory esp-RainMaker/components as a submodule.

$ git clone --recursive https://github.com/espressif/esp-RainMaker.git

2. Modify CMakeLists.txt of esp-RainMaker.

Add esp-insight as a component to the esp-RainMaker project, ensuring that the functions of esp-insight can be called under the esp-RainMaker project. In the current directory of building project, modify the following command in CMakeLists.txt:

set(EXTRA_COMPONENT_DIRS ${RMAKER_PATH}/components ${RMAKER_PATH}/examples/common)

to:

set(EXTRA_COMPONENT_DIRS ${RMAKER_PATH}/components ${RMAKER_PATH}/examples/common ${RMAKER_PATH}/components/esp-insights/components)

3. Implement the features of ESP Insights.

The code for ESP Insights is already wrapped by the examples/common/app_insights component. Users only need to include app_insights.h in their code and call app_insights_enable() before calling esp_rmaker_start(). However, this component is controlled by the macro CONFIG_ESP_INSIGHTS_ENABLED, which is disabled by default. Users can enable this feature in default configuration or the image configuration interface (use the idf.py tool to open the menu menuconfig → Component config → ESP Insights → Enable ESP Insights).

4. Build and flash.

Run the following command to build and flash:

$ idf.py build flash monitor

When the build completes, the following log will be printed as an led_light-v1.0.zip will be generated in the build directory for future use.

======== 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

5. Claim for the ESP RainMaker IoT cloud platform.

As developers need the admin access for the ESP Insights cloud, claiming is thus required. For specific claiming details, please refer to Chapter 3.

6. Log in to the Dashboard of ESP RainMaker.

Once the firmware and claiming operations are all completed, the device is ready to connect to ESP RainMaker. Now, users can log in to the ESP RainMaker interface (https://dashboard.RainMaker.espressif.com/), and click the node corresponding to the device to enter its Dashboard.

7. Upload the generated zip file.

To better understand the diagnostics information, users also need to upload the previously generated zip file led_light-v1.0.zip to Firmware Images on the left navigation bar of the ESP RainMaker interface, as the zip file contains binary files, elf files, mapping files, and other useful information for analysis.

Even without changes in code, commands such as idf.py build and idf.py flash will conduct rebuilds to generate new firmware. Thus, it is important to ensure that the firmware running on the device corresponds to the zip file package uploaded to the ESP RainMaker platform. Otherwise, ESP RainMaker may report errors when processing and analysing the information reported by the device.