ESP Insights

About

ESP Insights is a remote diagnostics solution that allows users to remotely monitor the health of Espressif devices in the field.

Developers normally prefer debugging issues by physically probing them using gdb or observing the logs. This surely helps debug issues, but there are often cases wherein issues are seen only in specific environments under specific conditions. Even things like casings and placement of the product can affect the behavior. A few examples are

  • Wi-Fi disconnections for a smart switch concealed in a wall.

  • Smart speakers crashing during some specific usage pattern.

  • Appliance frequently rebooting due to power supply issues.

Additional information about ESP Insights can be foundhere.

ESP Insights Agent API

Insights.begin

This initializes the ESP Insights agent.

boolbegin(constchar*auth_key,constchar*node_id=NULL,uint32_tlog_type=0xFFFFFFFF,boolalloc_ext_ram=false);

  • auth_key Auth key generated using Insights dashboard

  • log_type Type of logs to be captured (value can be a mask of ESP_DIAG_LOG_TYPE_ERROR, ESP_DIAG_LOG_TYPE_WARNING and ESP_DIAG_LOG_TYPE_EVENT)

This function will return

  1. true : On success

  2. false in case of failure

Insights.send

Read insights data from buffers and send it to the cloud. Call to this function is asynchronous, it may take some time to send the data.

boolsendData()

This function will return

  1. true : On success

  2. false in case of failure

Insights.end

Deinitialize ESP Insights.

voidend();

Insights.disable

Disable ESP Insights.

voiddisable();

ESP Insights Metrics API

metrics object ofInsights class expose API’s for using metrics.

Insights.metrics.addX

Register a metric of type X, where X is one of: Bool, Int, Uint, Float, String, IPv4 or MAC

booladdX(constchar*tag,constchar*key,constchar*label,constchar*path);

  • tag : Tag of metrics

  • key : Unique key for the metrics

  • label : Label for the metrics

  • path : Hierarchical path for key, must be separated by ‘.’ for more than one level

This function will return

  1. true : On success

  2. false in case of failure

Insights.metrics.remove

Unregister a diagnostics metrics

boolremove(constchar*key);

  • key : Key for the metrics

This function will return

  1. true : On success

  2. false in case of failure

Insights.metrics.removeAll

Unregister all previously registered metrics

boolremoveAll();

This function will return

  1. true : On success

  2. false in case of failure

Insights.metrics.setX

Add metrics of type X to storage, where X is one of: Bool, Int, Uint, Float, String, IPv4 or MAC

boolsetX(constchar*key,constvoidval);

  • key : Key of metrics

  • val : Value of metrics

This function will return

  1. ESP_OK : On success

  2. Error in case of failure

Insights.metrics.dumpHeap

Dumps the heap metrics and prints them to the console.This API collects and reports metrics value at any give point in time.

booldumpHeap();

This function will return

  1. true : On success

  2. false in case of failure

Insights.metrics.dumpWiFi

Dumps the Wi-Fi metrics and prints them to the console.This API can be used to collect Wi-Fi metrics at any given point in time.

booldumpWiFi();

This function will return

  1. true : On success

  2. false in case of failure

Insights.metrics.setHeapPeriod

Reset the periodic intervalBy default, heap metrics are collected every 30 seconds, this function can be used to change the interval.If the interval is set to 0, heap metrics collection disabled.

voidsetHeapPeriod(uint32_tperiod);

  • period : Period interval in seconds

Insights.metrics.setWiFiPeriod

Reset the periodic intervalBy default, Wi-Fi metrics are collected every 30 seconds, this function can be used to change the interval.If the interval is set to 0, Wi-Fi metrics collection disabled.

voidsetHeapPeriod(uint32_tperiod);

  • period : Period interval in seconds

ESP Insights Variables API

variables object ofInsights class expose API’s for using variables.

Insights.variables.addX

Register a variable of type X, where X is one of: Bool, Int, Uint, Float, String, IPv4 or MAC

booladdX(constchar*tag,constchar*key,constchar*label,constchar*path);

  • tag : Tag of variable

  • key : Unique key for the variable

  • label : Label for the variable

  • path : Hierarchical path for key, must be separated by ‘.’ for more than one level

This function will return

  1. true : On success

  2. false in case of failure

Insights.variables.remove

Unregister a diagnostics variable

boolremove(constchar*key);

  • key : Key for the variable

This function will return

  1. true : On success

  2. false in case of failure

Insights.variables.removeAll

Unregister all previously registered variables

boolunregisterAll();

This function will return

  1. true : On success

  2. false in case of failure

Insights.variables.setX

Add variable of type X to storage, where X is one of: Bool, Int, Uint, Float, String, IPv4 or MAC

boolsetX(constchar*key,constvoidval);

  • key : Key of metrics

  • val : Value of metrics

This function will return

  1. true : On success

  2. false in case of failure

Example

To get started with Insights, you can try:

#include"Insights.h"#include"WiFi.h"constcharinsights_auth_key[]="<ENTER YOUR AUTH KEY>";#define WIFI_SSID       "<ENTER YOUR SSID>"#define WIFI_PASSPHRASE "<ENTER YOUR PASSWORD>"voidsetup(){Serial.begin(115200);WiFi.mode(WIFI_STA);WiFi.begin(WIFI_SSID,WIFI_PASSPHRASE);while(WiFi.status()!=WL_CONNECTED){delay(500);Serial.print(".");}Serial.println("");Serial.println("WiFi connected");if(!Insights.begin(insights_auth_key)){return;}Serial.println("=========================================");Serial.printf("ESP Insights enabled Node ID %s\n",Insights.nodeID());Serial.println("=========================================");}voidloop(){delay(1000);}