RainMaker Common¶
Utilities¶
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¶
Header File¶
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.
-