RainMaker Common¶

Utilities¶

Header File¶

components/rmaker_common/include/esp_rmaker_utils.h

Functions¶

esp_err_t esp_rmaker_reboot(int8_t seconds)¶

Reboot the device after a delay

This API just starts a reboot timer and returns immediately. The actual reboot is trigerred asynchronously in the timer callback. This is useful if you want to reboot after a delay, to allow other tasks to finish their operations (Eg. MQTT publish to indicate OTA success). The RMAKER_EVENT_REBOOT event is triggered when the reboot timer is started.

Return

ESP_OK on success.

Return

error on failure.

Parameters

[in] seconds: Time in seconds after which the device should reboot.

esp_err_t esp_rmaker_wifi_reset(int8_t reset_seconds, int8_t reboot_seconds)¶

Reset Wi-Fi credentials and (optionally) reboot

This will reset just the Wi-Fi credentials and (optionally) trigger a reboot. This is useful when you want to keep all the entries in NVS memory intact, but just change the Wi-Fi credentials. The RMAKER_EVENT_WIFI_RESET event is triggered when this API is called. The actual reset will happen after a delay if reset_seconds is not zero.

Note

This reset and reboot operations will happen asynchronously depending on the values passed to the API.

Return

ESP_OK on success.

Return

error on failure.

Parameters

[in] reset_seconds: Time in seconds after which the reset should get triggered. This will help other modules take some actions before the device actually resets. If set to zero, the operation would be performed immediately.
[in] reboot_seconds: Time in seconds after which the device should reboot. If set to negative value, the device will not reboot at all.

esp_err_t esp_rmaker_factory_reset(int8_t reset_seconds, int8_t reboot_seconds)¶

Reset to factory defaults and reboot

This will clear entire NVS partition and (optionally) trigger a reboot. The RMAKER_EVENT_FACTORY_RESET event is triggered when this API is called. The actual reset will happen after a delay if reset_seconds is not zero.

Note

This reset and reboot operations will happen asynchronously depending on the values passed to the API.

Return

ESP_OK on success.

Return

error on failure.

Parameters

[in] reset_seconds: Time in seconds after which the reset should get triggered. This will help other modules take some actions before the device actually resets. If set to zero, the operation would be performed immediately.
[in] reboot_seconds: Time in seconds after which the device should reboot. If set to negative value, the device will not reboot at all.

esp_err_t esp_rmaker_time_sync_init(esp_rmaker_time_config_t *config)¶

Initialize time synchronization

This API initializes SNTP for time synchronization.

Return

ESP_OK on success

Return

error on failure

Parameters

[in] config: Configuration to be used for SNTP time synchronization. The default configuration is used if NULL is passed.

bool esp_rmaker_time_check(void)¶

Check if current time is updated

This API checks if the current system time is updated against the reference time of 1-Jan-2019.

Return: true if time is updated
Return: false if time is not updated

esp_err_t esp_rmaker_time_wait_for_sync(uint32_t ticks_to_wait)¶

Wait for time synchronization

This API waits for the system time to be updated against the reference time of 1-Jan-2019. This is a blocking call.

Return

ESP_OK on success

Return

error on failure

Parameters

[in] ticks_to_wait: Number of ticks to wait for time synchronization. Accepted values: 0 to portMAX_DELAY.

esp_err_t esp_rmaker_time_set_timezone_posix(const char *tz_posix)¶

Set POSIX timezone

Set the timezone (TZ environment variable) as per the POSIX format specified in the GNU libc documentation. Eg. For China: “CST-8” For US Pacific Time (including daylight saving information): “PST8PDT,M3.2.0,M11.1.0”

Return

ESP_OK on success

Return

error on failure

Parameters

[in] tz_posix: NULL terminated TZ POSIX string

esp_err_t esp_rmaker_time_set_timezone(const char *tz)¶

Set timezone location string

Set the timezone as a user friendly location string. Check here for a list of valid values.

Eg. For China: “Asia/Shanghai” For US Pacific Time: “America/Los_Angeles”

Note

Setting timezone using this API internally also sets the POSIX timezone string.

Return

ESP_OK on success

Return

error on failure

Parameters

[in] tz: NULL terminated Timezone location string

char *esp_rmaker_time_get_timezone_posix(void)¶

Get the current POSIX timezone

This fetches the current timezone in POSIX format, read from NVS.

Return: Pointer to a NULL terminated POSIX timezone string on success. Freeing this is the responsibility of the caller.
Return: NULL on failure.

char *esp_rmaker_time_get_timezone(void)¶

Get the current timezone

This fetches the current timezone in POSIX format, read from NVS.

Return: Pointer to a NULL terminated timezone string on success. Freeing this is the responsibility of the caller.
Return: NULL on failure.

esp_err_t esp_rmaker_get_local_time_str(char *buf, size_t buf_len)¶

Get printable local time string

Get a printable local time string, with information of timezone and Daylight Saving. Eg. “Tue Sep 1 09:04:38 2020 -0400[EDT], DST: Yes” “Tue Sep 1 21:04:04 2020 +0800[CST], DST: No”

Return

ESP_OK on success

Return

error on failure

Parameters

[out] buf: Pointer to a pre-allocated buffer into which the time string will be populated.
[in] buf_len: Length of the above buffer.

Structures¶

struct esp_rmaker_time_config¶

Public Members

char *sntp_server_name¶: If not specified, then ‘CONFIG_ESP_RMAKER_SNTP_SERVER_NAME’ is used as the SNTP server.

sntp_sync_time_cb_t sync_time_cb¶: Optional callback to invoke, whenever time is synchronised. This will be called periodically as per the SNTP polling interval (which is 60min by default). If kept NULL, the default callback will be invoked, which will just print the current local time.

Macros¶

MEM_ALLOC_EXTRAM(size)¶

MEM_CALLOC_EXTRAM(num, size)¶

MEM_REALLOC_EXTRAM(ptr, size)¶

Type Definitions¶

typedef struct esp_rmaker_time_config esp_rmaker_time_config_t¶

Factory Storage¶

Header File¶

components/rmaker_common/include/esp_rmaker_factory.h

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] data: Pointer to the value.
[in] len: Length of the value.

Work Queue¶

Header File¶

components/rmaker_common/include/esp_rmaker_work_queue.h

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.

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

error in case of failure.

Parameters

[in] work_fn: The Work function to be queued.
[in] priv_data: Private data to be passed to the work function.

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.

Common Events¶

Header File¶

components/rmaker_common/include/esp_rmaker_common_events.h

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.