RainMaker Common

Factory Storage

Functions

esp_err_t esp_rmaker_factory_init(void)

Initialize Factory NVS

This initializes the Factory NVS partition which will store data that should not be cleared even after a reset to factory.

Return

ESP_OK on success.

Return

error on failure.

void *esp_rmaker_factory_get(const char *key)

Get value from factory NVS

This will search for the specified key in the Factory NVS partition, allocate the required memory to hold it, copy the value and return the pointer to it. It is responsibility of the caller to free the memory when the value is no more required.

Return

pointer to the value on success.

Return

NULL on failure.

Parameters
  • [in] key: The key of the value to be read from factory NVS.

size_t esp_rmaker_factory_get_size(const char *key)

Get size of value from factory NVS

This will search for the specified key in the Factory NVS partition, and return the size of the value associated with the key.

Return

size of the value on success.

Return

0 on failure.

Parameters
  • [in] key: The key of the value to be read from factory NVS.

esp_err_t esp_rmaker_factory_set(const char *key, void *value, size_t len)

Set a value in factory NVS

This will write the value for the specified key into factory NVS.

Return

ESP_OK on success.

Return

error on failure.

Parameters
  • [in] key: The key for the value to be set in factory NVS.

  • [in] value: Pointer to the value.

  • [in] len: Length of the value.

Work Queue

Functions

esp_err_t esp_rmaker_work_queue_init(void)

Initializes the Work Queue

This initializes the work queue, which is basically a mechanism to run tasks in the context of a dedicated thread. You can start queueing tasks after this, but they will get executed only after calling esp_rmaker_work_queue_start().

Return

ESP_OK on success.

Return

error in case of failure.

esp_err_t esp_rmaker_work_queue_deinit(void)

De-initialize the Work Queue

This de-initializes the work queue. Note that the work queue needs to be stopped using esp_rmaker_work_queue_stop() before calling this.

Return

ESP_OK on success.

Return

error in case of failure.

esp_err_t esp_rmaker_work_queue_start(void)

Start the Work Queue

This starts the Work Queue thread which then starts executing the tasks queued.

Return

ESP_OK on success.

Return

error in case of failure.

esp_err_t esp_rmaker_work_queue_stop(void)

Stop the Work Queue

This stops a running Work Queue.

Note

The worker stack and TCB stay allocated until esp_rmaker_work_queue_deinit().

Return

ESP_OK on success.

Return

error in case of failure.

esp_err_t esp_rmaker_work_queue_add_task(esp_rmaker_work_fn_t work_fn, void *priv_data)

Queue execution of a function in the Work Queue’s context

This API queues a work function for execution in the Work Queue Task’s context.

Return

ESP_OK on success.

Return

ESP_ERR_INVALID_ARG if work_fn is NULL.

Return

error in case of failure.

Parameters
  • [in] work_fn: The Work function to be queued. Must not be NULL.

  • [in] priv_data: Private data to be passed to the work function.

esp_err_t esp_rmaker_work_queue_init_inst(esp_rmaker_work_queue_handle_t *p_handle, const esp_rmaker_work_queue_config_t *p_config)

Initialize a Work Queue instance

This initializes a Work Queue instance.

Return

ESP_OK on success.

Return

ESP_ERR_INVALID_STATE if *p_handle is not NULL.

Return

error in case of failure.

Parameters
  • [out] p_handle: The pointer to the handle for the Work Queue. Must point to NULL.

  • [in] p_config: The configuration for the Work Queue.

esp_err_t esp_rmaker_work_queue_deinit_inst(esp_rmaker_work_queue_handle_t *p_handle)

De-initialize a Work Queue instance

This de-initializes a Work Queue instance.

Note

Do not call this from a work function of the same queue.

Return

ESP_OK on success.

Return

ESP_ERR_INVALID_STATE if called from the queue’s own worker.

Return

error in case of failure.

Parameters
  • [inout] p_handle: The handle for the Work Queue. Will be set to NULL on success.

esp_err_t esp_rmaker_work_queue_start_inst(esp_rmaker_work_queue_handle_t handle)

Start a Work Queue instance

This starts a Work Queue instance.

Return

ESP_OK on success.

Return

error in case of failure.

Parameters
  • [in] handle: The handle for the Work Queue.

esp_err_t esp_rmaker_work_queue_stop_inst(esp_rmaker_work_queue_handle_t handle)

Stop a Work Queue instance

This stops a Work Queue instance.

Note

The worker stack and TCB stay allocated until esp_rmaker_work_queue_deinit_inst().

Return

ESP_OK on success.

Return

error in case of failure.

Parameters
  • [in] handle: The handle for the Work Queue.

esp_err_t esp_rmaker_work_queue_add_task_inst(esp_rmaker_work_queue_handle_t handle, esp_rmaker_work_fn_t work_fn, void *priv_data)

Queue execution of a function in the Work Queue instance’s context

This API queues a work function for execution in the Work Queue instance’s task context.

Return

ESP_OK on success.

Return

ESP_ERR_INVALID_ARG if handle or work_fn is NULL.

Return

error in case of failure.

Parameters
  • [in] handle: The handle for the Work Queue.

  • [in] work_fn: The Work function to be queued. Must not be NULL.

  • [in] priv_data: Private data to be passed to the work function.

Structures

struct esp_rmaker_work_queue_config_t

Configuration for a Work Queue instance

Note

Start from ESP_RMAKER_WORK_QUEUE_CONFIG_DEFAULT() and override fields, so new fields get defaults.

Macros

ESP_RMAKER_WORK_QUEUE_PREFER_EXT_RAM_DEFAULT

Default configuration for a Work Queue instance

Follows the sdkconfig defaults.

ESP_RMAKER_WORK_QUEUE_CONFIG_DEFAULT()

Type Definitions

typedef void (*esp_rmaker_work_fn_t)(void *priv_data)

Prototype for ESP RainMaker Work Queue Function

Parameters
  • [in] priv_data: The private data associated with the work function.

typedef struct esp_rmaker_work_queue *esp_rmaker_work_queue_handle_t

Handle for a Work Queue instance, separate from the global Work Queue

Common Events

Functions

ESP_EVENT_DECLARE_BASE(RMAKER_COMMON_EVENT)

ESP RainMaker Common Event Base

Enumerations

enum esp_rmaker_common_event_t

Values:

RMAKER_EVENT_REBOOT

Node reboot has been triggered. The associated event data is the time in seconds (type: uint8_t) after which the node will reboot. Note that this time may not be accurate as the events are received asynchronously.

RMAKER_EVENT_WIFI_RESET

Wi-Fi credentials reset. Triggered after calling esp_rmaker_wifi_reset()

RMAKER_EVENT_FACTORY_RESET

Node reset to factory defaults. Triggered after calling esp_rmaker_factory_reset()

RMAKER_MQTT_EVENT_CONNECTED

Connected to MQTT Broker

RMAKER_MQTT_EVENT_DISCONNECTED

Disconnected from MQTT Broker

RMAKER_MQTT_EVENT_PUBLISHED

MQTT message published successfully. Event data will contain the message ID (integer) of published message.

RMAKER_EVENT_TZ_POSIX_CHANGED

POSIX Timezone Changed. Associated data would be NULL terminated POSIX Timezone Eg. “PST8PDT,M3.2.0,M11.1.0”

RMAKER_EVENT_TZ_CHANGED

Timezone Changed. Associated data would be NULL terminated Timezone. Eg. “America/Los_Angeles” Note that whenever this event is received, the RMAKER_EVENT_TZ_POSIX_CHANGED event will also be received, but not necessarily vice versa.

RMAKER_MQTT_EVENT_MSG_DELETED

MQTT message deleted from the outbox if the message couldn’t have been sent and acknowledged. Event data will contain the message ID (integer) of deleted message. Valid only if CONFIG_MQTT_REPORT_DELETED_MESSAGES is enabled.

RMAKER_MQTT_EVENT_SUBSCRIBED

MQTT subscription acknowledged by the broker. Event data is the NUL-terminated topic. Also posted for every subscription re-established after a reconnect. Note: this and RMAKER_MQTT_EVENT_SUBSCRIBE_FAILED are usually posted while the MQTT task holds its API lock, so a handler must not publish or subscribe directly; defer that to a timer or the work queue.

RMAKER_MQTT_EVENT_SUBSCRIBE_FAILED

MQTT subscription rejected by the broker (SUBACK failure code, e.g. throttling) or dropped without an acknowledgement. Event data is the NUL-terminated topic. The subscription is retried internally with backoff and RMAKER_MQTT_EVENT_SUBSCRIBED follows once it succeeds.

RMAKER_MQTT_EVENT_ERROR

MQTT client reported an error. Posted only when the esp-mqtt backend is selected (CONFIG_ESP_RMAKER_LIB_ESP_MQTT).

To read event data, include “mqtt_client.h” and cast event_data to esp_mqtt_error_codes_t *. The data is a copy and is valid only for the duration of the handler.

Meaningful fields depend on error_type:

  • MQTT_ERROR_TYPE_TCP_TRANSPORT: esp_tls_last_esp_err, esp_tls_stack_err, esp_tls_cert_verify_flags, esp_transport_sock_errno

  • MQTT_ERROR_TYPE_CONNECTION_REFUSED: connect_return_code

This event can be posted on every failed reconnect attempt. Handlers should be cheap and non-blocking.