RainMaker Core

Core

Header File

• esp_rainmaker/include/esp_rmaker_core.h

Functions

ESP_EVENT_DECLARE_BASE(RMAKER_EVENT)

ESP RainMaker Event Base

const char *esp_rmaker_device_cb_src_to_str(esp_rmaker_req_src_t src)

Convert device callback source to string

Device read/write callback can be via different sources. This is a helper API to give the source in string format for printing.

Example Usage:

   static esp_err_t write_cb(const esp_rmaker_device_t *device, const esp_rmaker_param_t *param,
   const esp_rmaker_param_val_t val, void *priv_data, esp_rmaker_write_ctx_t *ctx)
{
    if (ctx) {
        ESP_LOGI(TAG, "Received write request via : %s", esp_rmaker_device_cb_src_to_str(ctx->src));
    }

Return

NULL terminated source string on success

Return

NULL on failure

Parameters

• [in] src: The src field as received in the callback context.

esp_rmaker_param_val_t esp_rmaker_bool(bool bval)

Initialise a Boolean value

Return

Value structure.

Parameters

• [in] bval: Initialising value.

esp_rmaker_param_val_t esp_rmaker_int(int ival)

Initialise an Integer value

Return

Value structure.

Parameters

• [in] ival: Initialising value.

esp_rmaker_param_val_t esp_rmaker_float(float fval)

Initialise a Float value

Return

Value structure.

Parameters

• [in] fval: Initialising value.

esp_rmaker_param_val_t esp_rmaker_str(const char *sval)

Initialise a String value

Return

Value structure.

Parameters

• [in] sval: Initialising value.

esp_rmaker_param_val_t esp_rmaker_obj(const char *val)

Initialise a json object value

param[in] val initialising value

Note

the object will not be validated internally. it is the application’s responsibility to ensure that the object is a valid json object. eg. esp_rmaker_obj(“{“name”:”value”}”);

return value structure

esp_rmaker_param_val_t esp_rmaker_array(const char *val)

Initialise a json array value

param[in] val initialising value

Note

the array will not be validated internally. it is the application’s responsibility to ensure that the array is a valid json array. eg. esp_rmaker_array(“[1,2,3]”);

return value structure

esp_rmaker_node_t *esp_rmaker_node_init(const esp_rmaker_config_t *config, const char *name, const char *type)

Initialize ESP RainMaker Node

This initializes the ESP RainMaker agent and creates the node. The model and firmware version for the node are set internally as per the project name and version. These can be overridden (but not recommended) using the esp_rmaker_node_add_fw_version() and esp_rmaker_node_add_model() APIs.

Note

This should be the first call before using any other ESP RainMaker API.

Return

Node handle on success.

Return

NULL in case of failure.

Parameters

• [in] config: Configuration to be used by the ESP RainMaker.

• [in] name: Name of the node.

• [in] type: Type of the node.

esp_err_t esp_rmaker_start(void)

Start ESP RainMaker Agent

This call starts the actual ESP RainMaker thread. This should preferably be called after a successful Wi-Fi connection in order to avoid unnecessary failures.

Return

ESP_OK on success.

Return

error in case of failure.

esp_err_t esp_rmaker_stop(void)

Stop ESP RainMaker Agent

This call stops the ESP RainMaker Agent instance started earlier by esp_rmaker_start().

Return

ESP_OK on success.

Return

error in case of failure.

esp_err_t esp_rmaker_node_deinit(const esp_rmaker_node_t *node)

Deinitialize ESP RainMaker Node

This API deinitializes the ESP RainMaker agent and the node created using esp_rmaker_node_init().

ESP_OK on success.

Note

This should be called after rainmaker has stopped.

Return

error in case of failure.

Parameters

• [in] node: Node Handle returned by esp_rmaker_node_init().

const esp_rmaker_node_t *esp_rmaker_get_node(void)

Get a handle to the Node

This API returns handle to a node created using esp_rmaker_node_init().

Return

Node handle on success.

Return

NULL in case of failure.

char *esp_rmaker_get_node_id(void)

Get Node Id

Returns pointer to the NULL terminated Node ID string.

Return

Pointer to a NULL terminated Node ID string.

esp_rmaker_node_info_t *esp_rmaker_node_get_info(const esp_rmaker_node_t *node)

Get Node Info

Returns pointer to the node info as configured during initialisation.

Return

Pointer to the node info on success.

Return

NULL in case of failure.

Parameters

• node: Node handle.

esp_err_t esp_rmaker_node_add_attribute(const esp_rmaker_node_t *node, const char *attr_name, const char *val)

Add Node attribute

Adds a new attribute as the metadata for the node. For the sake of simplicity, only string values are allowed.

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• node: Node handle.

• [in] attr_name: Name of the attribute.

• [in] val: Value for the attribute.

esp_err_t esp_rmaker_node_add_fw_version(const esp_rmaker_node_t *node, const char *fw_version)

Add FW version for a node (Not recommended)

FW version is set internally to the project version. This API can be used to override that version.

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• node: Node handle.

• [in] fw_version: New firmware version.

esp_err_t esp_rmaker_node_add_model(const esp_rmaker_node_t *node, const char *model)

Add model for a node (Not recommended)

Model is set internally to the project name. This API can be used to override that name.

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• node: Node handle.

• [in] model: New model string.

esp_rmaker_device_t *esp_rmaker_device_create(const char *dev_name, const char *type, void *priv_data)

Create a Device

This API will create a virtual “Device”. This could be something like a Switch, Lightbulb, etc.

Note

The device created needs to be added to a node using esp_rmaker_node_add_device().

Return

Device handle on success.

Return

NULL in case of any error.

Parameters

• [in] dev_name: The unique device name.

• [in] type: Optional device type. Can be kept NULL.

• [in] priv_data: (Optional) Private data associated with the device. This will be passed to callbacks. It should stay allocated throughout the lifetime of the device.

esp_rmaker_device_t *esp_rmaker_service_create(const char *serv_name, const char *type, void *priv_data)

Create a Service

This API will create a “Service”. It is exactly same like a device in terms of structure and so, all APIs for device are also valid for a service. A service could be something like OTA, diagnostics, etc.

Note

Name of a service should not clash with name of a device.

Note

The service created needs to be added to a node using esp_rmaker_node_add_device().

Return

Device handle on success.

Return

NULL in case of any error.

Parameters

• [in] serv_name: The unique service name.

• [in] type: Optional service type. Can be kept NULL.

• [in] priv_data: (Optional) Private data associated with the service. This will be passed to callbacks. It should stay allocated throughout the lifetime of the device.

esp_err_t esp_rmaker_device_delete(const esp_rmaker_device_t *device)

Delete a Device/Service

This API will delete a device created using esp_rmaker_device_create().

Note

The device should first be removed from the node using esp_rmaker_node_remove_device() before deleting.

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• [in] device: Device handle.

esp_err_t esp_rmaker_device_add_cb(const esp_rmaker_device_t *device, esp_rmaker_device_write_cb_t write_cb, esp_rmaker_device_read_cb_t read_cb)

Add callbacks for a device/service

Add read/write callbacks for a device that will be invoked as per requests received from the cloud (or other paths as may be added in future).

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• [in] device: Device handle.

• [in] write_cb: Write callback.

• [in] read_cb: Read callback.

esp_err_t esp_rmaker_node_add_device(const esp_rmaker_node_t *node, const esp_rmaker_device_t *device)

Add a device to a node

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• [in] node: Node handle.

• [in] device: Device handle.

esp_err_t esp_rmaker_node_remove_device(const esp_rmaker_node_t *node, const esp_rmaker_device_t *device)

Remove a device from a node

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• [in] node: Node handle.

• [in] device: Device handle.

esp_err_t esp_rmaker_device_add_attribute(const esp_rmaker_device_t *device, const char *attr_name, const char *val)

Add a Device attribute

Note

Device attributes are reported only once after a boot-up as part of the node configuration. Eg. Serial Number

Return

ESP_OK if the attribute was added successfully.

Return

error in case of failure.

Parameters

• [in] device: Device handle.

• [in] attr_name: Name of the attribute.

• [in] val: Value of the attribute.

char *esp_rmaker_device_get_name(const esp_rmaker_device_t *device)

Get device name from handle

Return

NULL terminated device name string on success.

Return

NULL in case of failure.

Parameters

• [in] device: Device handle.

char *esp_rmaker_device_get_type(const esp_rmaker_device_t *device)

Get device type from handle

Return

NULL terminated device type string on success.

Return

NULL in case of failure, or if the type wasn’t provided while creating the device.

Parameters

• [in] device: Device handle.

esp_err_t esp_rmaker_device_add_param(const esp_rmaker_device_t *device, const esp_rmaker_param_t *param)

Add a parameter to a device/service

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• [in] device: Device handle.

• [in] param: Parameter handle.

esp_rmaker_param_t *esp_rmaker_device_get_param_by_type(const esp_rmaker_device_t *device, const char *param_type)

Get parameter by type

Get handle for a parameter based on the type.

Note

If there are multiple parameters with the same type, this will return the first one. The API esp_rmaker_device_get_param_by_name() can be used to get a specific parameter, because the parameter names in a device are unique.

Return

Parameter handle on success.

Return

NULL in case of failure.

Parameters

• [in] device: Device handle.

• [in] param_type: Parameter type to search.

esp_rmaker_param_t *esp_rmaker_device_get_param_by_name(const esp_rmaker_device_t *device, const char *param_name)

Get parameter by name

Get handle for a parameter based on the name.

Return

Parameter handle on success.

Return

NULL in case of failure.

Parameters

• [in] device: Device handle.

• [in] param_name: Parameter name to search.

esp_err_t esp_rmaker_device_assign_primary_param(const esp_rmaker_device_t *device, const esp_rmaker_param_t *param)

Assign a primary parameter

Assign a parameter (already added using esp_rmaker_device_add_param()) as a primary parameter, which can be used by clients (phone apps specifically) to give prominence to it.

Return

ESP_OK if the parameter was assigned as the primary successfully.

Return

error in case of failure.

Parameters

• [in] device: Device handle.

• [in] param: Parameter handle.

esp_rmaker_param_t *esp_rmaker_param_create(const char *param_name, const char *type, esp_rmaker_param_val_t val, uint8_t properties)

Create a Parameter

Parameter can be something like Temperature, Outlet state, Lightbulb brightness, etc.

Any changes should be reported using the esp_rmaker_param_update_and_report() API. Any remote changes will be reported to the application via the device callback, if registered.

Note

The parameter created needs to be added to a device using esp_rmaker_device_add_param(). Parameter name should be unique in a given device.

Return

Parameter handle on success.

Return

NULL in case of failure.

Parameters

• [in] param_name: Name of the parameter. a*

• [in] type: Optional parameter type. Can be kept NULL.

• [in] val: Value of the parameter. This also specifies the type that will be assigned to this parameter. You can use esp_rmaker_bool(), esp_rmaker_int(), esp_rmaker_float() or esp_rmaker_str() functions as the argument here. Eg, esp_rmaker_bool(true).

• [in] properties: Properties of the parameter, which will be a logical OR of flags in esp_param_property_flags_t.

esp_err_t esp_rmaker_param_add_ui_type(const esp_rmaker_param_t *param, const char *ui_type)

Add a UI Type to a parameter

This will be used by the Phone apps (or other clients) to render appropriate UI for the given parameter. Please refer the RainMaker documetation for supported UI Types.

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• [in] param: Parameter handle.

• [in] ui_type: String describing the UI Type.

esp_err_t esp_rmaker_param_add_bounds(const esp_rmaker_param_t *param, esp_rmaker_param_val_t min, esp_rmaker_param_val_t max, esp_rmaker_param_val_t step)

Add bounds for an integer/float parameter

This can be used to add bounds (min/max values) for a given integer parameter. Eg. brightness will have bounds as 0 and 100 if it is a percentage. Eg. esp_rmaker_param_add_bounds(brightness_param, esp_rmaker_int(0), esp_rmaker_int(100), esp_rmaker_int(5));

Note

The RainMaker core does not check the bounds. It is upto the application to handle it.

Return

ESP_OK on success. return error in case of failure.

Parameters

• [in] param: Parameter handle.

• [in] min: Minimum allowed value.

• [in] max: Maximum allowed value.

• [in] step: Minimum stepping (set to 0 if no specific value is desired).

esp_err_t esp_rmaker_param_add_valid_str_list(const esp_rmaker_param_t *param, const char *strs[], uint8_t count)

Add a list of valid strings for a string parameter

This can be used to add a list of valid strings for a given string parameter.

Eg. static const char *valid_strs[] = {“None”,”Yes”,”No”,”Can’t Say”}; esp_rmaker_param_add_valid_str_list(param, valid_strs, 4);

Note

The RainMaker core does not check the values. It is upto the application to handle it.

Return

ESP_OK on success. return error in case of failure.

Parameters

• [in] param: Parameter handle.

• [in] strs: Pointer to an array of strings. Note that this memory should stay allocated throughout the lifetime of this parameter.

• [in] count: Number of strings in the above array.

esp_err_t esp_rmaker_param_add_array_max_count(const esp_rmaker_param_t *param, int count)

Add max count for an array parameter

This can be used to put a limit on the maximum number of elements in an array.

Note

The RainMaker core does not check the values. It is upto the application to handle it.

Return

ESP_OK on success. return error in case of failure.

Parameters

• [in] param: Parameter handle.

• [in] count: Max number of elements allowed in the array.

esp_err_t esp_rmaker_param_update_and_report(const esp_rmaker_param_t *param, esp_rmaker_param_val_t val)

Update and report a parameter

Calling this API will update the parameter and report it to ESP RainMaker cloud. This should be used whenever there is any local change.

Return

ESP_OK if the parameter was updated successfully.

Return

error in case of failure.

Parameters

• [in] param: Parameter handle.

• [in] val: New value of the parameter.

char *esp_rmaker_param_get_name(const esp_rmaker_param_t *param)

Get parameter name from handle

Return

NULL terminated parameter name string on success.

Return

NULL in case of failure.

Parameters

• [in] param: Parameter handle.

char *esp_rmaker_param_get_type(const esp_rmaker_param_t *param)

Get parameter type from handle

Return

NULL terminated parameter type string on success.

Return

NULL in case of failure, or if the type wasn’t provided while creating the parameter.

Parameters

• [in] param: Parameter handle.

esp_err_t esp_rmaker_report_node_details(void)

Report the node details to the cloud

This API reports node details i.e. the node configuration and values of all the parameters to the ESP RainMaker cloud. Eg. If a new device is created (with some parameters and attributes), then this API should be called after that to send the node details to the cloud again and the changes to be reflected in the clients (like phone apps).

Note

Please use this API only if you need to create or delete devices after esp_rmaker_start() has already been called, for use cases like bridges or hubs.

Return

ESP_OK if the node details are successfully queued to be published.

Return

error in case of failure.

esp_err_t esp_rmaker_queue_work(esp_rmaker_work_fn_t work_fn, void *priv_data)

Queue execution of a function in ESP RainMaker’s context

This API queues a work function for execution in the ESP RainMaker 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.

Unions

union esp_rmaker_val_t

#include <esp_rmaker_core.h>

ESP RainMaker Value

Public Members

bool b

Boolean

int i

Integer

float f

Float

char *s

NULL terminated string

Structures

struct esp_rmaker_node_info_t

ESP RainMaker Node information

Public Members

char *name

Name of the Node

char *type

Type of the Node

char *fw_version

Firmware Version (Optional). If not set, PROJECT_VER is used as default (recommended)

char *model

Model (Optional). If not set, PROJECT_NAME is used as default (recommended)

struct esp_rmaker_config_t

ESP RainMaker Configuration

Public Members

bool enable_time_sync

Enable Time Sync Setting this true will enable SNTP and fetch the current time before attempting to connect to the ESP RainMaker service

struct esp_rmaker_param_val_t

ESP RainMaker Parameter Value

Public Members

esp_rmaker_val_type_t type

Type of Value

esp_rmaker_val_t val

Actual value. Depends on the type

struct esp_rmaker_write_ctx_t

Write request Context

Public Members

esp_rmaker_req_src_t src

Source of request

struct esp_rmaker_read_ctx_t

Read request context

Public Members

esp_rmaker_req_src_t src

Source of request

Macros

ESP_RMAKER_CONFIG_VERSION

MAX_VERSION_STRING_LEN

Type Definitions

typedef size_t esp_rmaker_handle_t

Generic ESP RainMaker handle

typedef esp_rmaker_handle_t esp_rmaker_node_t

ESP RainMaker Node Handle

typedef esp_rmaker_handle_t esp_rmaker_device_t

ESP RainMaker Device Handle

typedef esp_rmaker_handle_t esp_rmaker_param_t

ESP RainMaker Parameter Handle

typedef esp_err_t (*esp_rmaker_device_write_cb_t)(const esp_rmaker_device_t *device, const esp_rmaker_param_t *param, const esp_rmaker_param_val_t val, void *priv_data, esp_rmaker_write_ctx_t *ctx)

Callback for parameter value write requests.

The callback should call the esp_rmaker_param_update_and_report() API if the new value is to be set and reported back.

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• [in] device: Device handle.

• [in] param: Parameter handle.

• [in] param: Pointer to esp_rmaker_param_val_t. Use appropriate elements as per the value type.

• [in] priv_data: Pointer to the private data paassed while creating the device.

• [in] ctx: Context associated with the request.

typedef esp_err_t (*esp_rmaker_device_read_cb_t)(const esp_rmaker_device_t *device, const esp_rmaker_param_t *param, void *priv_data, esp_rmaker_read_ctx_t *ctx)

Callback for parameter value changes

The callback should call the esp_rmaker_param_update_and_report() API if the new value is to be set and reported back.

Note

Currently, the read callback never gets invoked as the communication between clients (mobile phones, CLI, etc.) and node is asynchronous. So, the read request does not reach the node. This callback will however be used in future.

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• [in] device: Device handle.

• [in] param: Parameter handle.

• [in] priv_data: Pointer to the private data passed while creating the device.

• [in] ctx: Context associated with the request.

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.

Enumerations

enum esp_rmaker_event_t

ESP RainMaker Events

Values:

RMAKER_EVENT_INIT_DONE = 1

RainMaker Core Initialisation Done

RMAKER_EVENT_CLAIM_STARTED

Self Claiming Started

RMAKER_EVENT_CLAIM_SUCCESSFUL

Self Claiming was Successful

RMAKER_EVENT_CLAIM_FAILED

Self Claiming Failed

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_EVENT_MQTT_CONNECTED

Connected to MQTT Broker

RMAKER_EVENT_MQTT_DISCONNECTED

Disconnected from MQTT Broker

RMAKER_EVENT_MQTT_PUBLISHED

MQTT message published successfully

enum esp_rmaker_val_type_t

ESP RainMaker Parameter Value type

Values:

RMAKER_VAL_TYPE_INVALID = 0

Invalid

RMAKER_VAL_TYPE_BOOLEAN

Boolean

RMAKER_VAL_TYPE_INTEGER

Integer. Mapped to a 32 bit signed integer

RMAKER_VAL_TYPE_FLOAT

Floating point number

RMAKER_VAL_TYPE_STRING

NULL terminated string

RMAKER_VAL_TYPE_OBJECT

NULL terminated JSON Object string Eg. {“name”:”value”}

RMAKER_VAL_TYPE_ARRAY

NULL terminated JSON Array string Eg. [1,2,3]

enum esp_param_property_flags_t

Param property flags

Values:

PROP_FLAG_WRITE = (1 << 0)

PROP_FLAG_READ = (1 << 1)

PROP_FLAG_TIME_SERIES = (1 << 2)

PROP_FLAG_PERSIST = (1 << 3)

enum esp_rmaker_req_src_t

Parameter read/write request source

Values:

ESP_RMAKER_REQ_SRC_INIT

Request triggered in the init sequence i.e. when a value is found in persistent memory for parameters with PROP_FLAG_PERSIST.

ESP_RMAKER_REQ_SRC_CLOUD

Request received from cloud

ESP_RMAKER_REQ_SRC_SCHEDULE

Request received when a schedule has triggered

ESP_RMAKER_REQ_SRC_LOCAL

Request received from a local controller

ESP_RMAKER_REQ_SRC_MAX

This will always be the last value. Any value equal to or greater than this should be considered invalid.

User Mapping

Header File

• esp_rainmaker/include/esp_rmaker_user_mapping.h

Functions

esp_err_t esp_rmaker_user_mapping_endpoint_create(void)

Create User Mapping Endpoint

This will create a custom provisioning endpoint for user-node mapping. This should be called after wifi_prov_mgr_init() but before wifi_prov_mgr_start_provisioning()

Return

ESP_OK on success

Return

error on failure

esp_err_t esp_rmaker_user_mapping_endpoint_register(void)

Register User Mapping Endpoint

This will register the callback for the custom provisioning endpoint for user-node mapping which was created with esp_rmaker_user_mapping_endpoint_create(). This should be called immediately after wifi_prov_mgr_start_provisioning().

Return

ESP_OK on success

Return

error on failure

esp_err_t esp_rmaker_start_user_node_mapping(char *user_id, char *secret_key)

Add User-Node mapping

This call will start the user-node mapping workflow on the node. This is automatically called if you have used esp_rmaker_user_mapping_endpoint_register(). Use this API only if you want to trigger the user-node mapping after the Wi-Fi provisioning has already been done.

Return

ESP_OK if the workflow was successfully triggered. This does not guarantee success of the actual mapping. The mapping status needs to be checked separately by the clients.

Return

error on failure.

Parameters

• [in] user_id: The User identifier received from the client (Phone app/CLI)

• [in] secret_key: The Secret key received from the client (Phone app/CLI)

Utilities

Header File

• esp_rainmaker/include/esp_rmaker_utils.h

Functions

esp_err_t esp_rmaker_reboot(uint8_t seconds)

Reboot the chip 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 chip should reboot.

esp_err_t esp_rmaker_wifi_reset(uint8_t seconds)

Reset Wi-Fi credentials and reboot

This will reset just the Wi-Fi credentials and 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 after the reset.

Note

This function internally calls esp_rmaker_reboot() and returns immediately. The reboot happens asynchronously.

Return

ESP_OK on success.

Return

error on failure.

Parameters

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

esp_err_t esp_rmaker_factory_reset(uint8_t seconds)

Reset to factory defaults and reboot

This will clear entire NVS partition and trigger a reboot. The RMAKER_EVENT_FACTORY_RESET event is triggered after the reset.

Note

This function internally calls esp_rmaker_reboot() and returns. The reboot happens asynchronously.

Return

ESP_OK on success.

Return

error on failure.

Parameters

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

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

esp_err_t esp_rmaker_timezone_service_enable(void)

Enable Timezone Service

This enables the ESP RainMaker standard timezone service which can be used to set timezone, either in POSIX or location string format. Please refer the specifications for additional details.

Return

ESP_OK on success

Return

error 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.

Type Definitions

typedef struct esp_rmaker_time_config esp_rmaker_time_config_t

Scheduling

Header File

• esp_rainmaker/include/esp_rmaker_schedule.h

Functions

esp_err_t esp_rmaker_schedule_enable(void)

Enable Schedules

This API enables the scheduling service for the node. For more information, check here

It is recommended to set the timezone while using schedules. Check here for more information on timezones

Note

This API should be called after esp_rmaker_node_init() but before esp_rmaker_start().

Return

ESP_OK on success.

Return

error in case of failure.