ESP Insights

Insights

Functions

esp_err_t esp_insights_init(esp_insights_config_t *config)

Initialize ESP Insights.

This initializes ESP Insights with the transport (HTTPS/MQTT) as per the sdkconfig. To override the transport configuration, please use esp_insights_transport_register() and esp_insights_enable().

Return

ESP_OK on success, appropriate error code otherwise

Parameters

  • [in] config: Configuration for ESP Insights.

void esp_insights_deinit(void)

Deinitialize ESP Insights.

Disconnects the registered transport and disables ESP Insights

esp_err_t esp_insights_transport_register(esp_insights_transport_config_t *config)

Register insights transport.

This function should be used only when default transport needs to be overridden.

Note

Call esp_insights_enable() after registering your own transport to enable Insights.

Return

ESP_OK on success, appropriate error code otherwise

Parameters

void esp_insights_transport_unregister(void)

Unregister insights transport.

Note

This API does not disable Insights. Call esp_insights_disable() to turn off Insights.

esp_err_t esp_insights_send_data(void)

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.

Return

ESP_OK on success, appropriate error code otherwise

esp_err_t esp_insights_enable(esp_insights_config_t *config)

Enable ESP Insights except transport.

This API is used in conjunction with esp_insights_transport_register() to start Insights with custom transport.

Return

ESP_OK on success, appropriate error code otherwise

Parameters

  • [in] config: Configuration for ESP Insights.

void esp_insights_disable(void)

Disable ESP Insights.

This API does not unregister the transport.

Note

Call esp_insights_transport_unregister() to remove the transport.

const char *esp_insights_get_node_id(void)

Returns pointer to the NULL terminated Node ID string.

Return

Pointer to a NULL terminated Node ID string.

bool esp_insights_is_reporting_enabled(void)

Check if insights reporting is enabled.

Return

true reporting is on

Return

false reporting is off

esp_err_t esp_insights_reporting_enable()

Turn on the Insights reporting.

Return

esp_err_t ESP_OK on success, apt error otherwise

esp_err_t esp_insights_reporting_disable()

Turn off the Insights repoting.

Return

esp_err_t ESP_OK on success, apt error otherwise

Note

meta message if changed and the boot message will still be sent as this information is critical for Insights working with the cloud. You may disable insight completely using esp_insights_disable

esp_err_t esp_insights_test_cmd_handler()

Encode and parse the command directly using esp-insight’s parser.

This tests only if the parser is working as expected.

esp_err_t esp_insights_cmd_resp_enable(void)

Enable esp-insights command-response module.

This API registers esp-insights command parser which when data is received, parses it to filter out insights specific data, modifies configs accordingly, and prepares and gives response data to the module

The esp_insights_init takes care of initializing command response and enabling the same. In cases where, only esp_insights_enable is called, e.g., ESP Rainmaker’s app_insights module, user needs to call this API, before or after esp_insights_enable

Structures

struct esp_insights_config_t

ESP Insights configuration.

Public Members

uint32_t log_type

Log types to enable, bitwise OR the values from esp_diag_log_type_t

const char *node_id

Node id for insights. If NULL then insights agent uses MAC address as node id

const char *auth_key

Authentication key, valid only for https transport

bool alloc_ext_ram

Try to allocate large buffers in External RAM

struct esp_insights_transport_event_data_t

Insights transport event data.

Public Members

uint8_t *data

Data associated with the event

size_t data_len

Length of the data for the event

int msg_id

Message id

struct esp_insights_transport_config_t

Insights transport configurations.

Public Members

esp_insights_transport_init_t init

Transport init function

esp_insights_transport_deinit_t deinit

Transport deinit function

esp_insights_transport_connect_t connect

Transport connect function

esp_insights_transport_disconnect_t disconnect

Transport disconnect function

esp_insights_transport_data_send_t data_send

Function to send data

struct esp_insights_transport_config_t::[anonymous] callbacks

Insights transport callback functions

void *userdata

User data

Type Definitions

typedef esp_err_t (*esp_insights_transport_init_t)(void *userdata)

Insights transport init callback prototype.

Return

ESP_OK on success, appropriate error code otherwise.

Parameters

  • [in] userdata: User data

typedef void (*esp_insights_transport_deinit_t)(void)

Insights transport deinit callback prototype.

typedef esp_err_t (*esp_insights_transport_connect_t)(void)

Insights transport connect callback prototype.

Return

ESP_OK on success, appropriate error code otherwise.

typedef void (*esp_insights_transport_disconnect_t)(void)

Insights transport disconnect callback prototype.

typedef int (*esp_insights_transport_data_send_t)(void *data, size_t len)

Insights transport data send callback prototype.

Return

msg_id Message_id of the sent data. On failure, -1 On success, 0 if data send happens synchronously. On success, message-id(positive integer) if data send happened asynchronously.

Note

If data send happened asynchronously then appropriate events in esp_insights_event_t must be emitted.

Parameters

  • [in] data: Data to send

  • [in] len: Length of data

Enumerations

enum esp_insights_event_t

Insights events.

Transport layer emits events using default event loop, every transport event has event data of type esp_insights_transport_event_data_t;

Values:

INSIGHTS_EVENT_TRANSPORT_SEND_SUCCESS

Asynchronous data send succeded. Event data contains the msg_id of the data.

INSIGHTS_EVENT_TRANSPORT_SEND_FAILED

Asynchronous data send failed. Event data contains the msg_id of the data.

INSIGHTS_EVENT_TRANSPORT_RECV

Data received. Event data contains received data and data_len.