RainMaker Core

Core

Header File

• components/esp_rainmaker/include/esp_rmaker_core.h

Functions

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().

Note

This should be called after rainmaker has stopped.

Return

ESP_OK on success.

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

Model is set internally to the project name. This API can be used to override that name, now that a new field “project” has also been added internally to the node info.

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• node: Node handle.

• [in] model: New model string.

esp_err_t esp_rmaker_node_add_subtype(const esp_rmaker_node_t *node, const char *subtype)

Add subtype for a node

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• node: Node handle.

• [in] subtype: Subtype 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_rmaker_device_t *esp_rmaker_node_get_device_by_name(const esp_rmaker_node_t *node, const char *device_name)

Get device by name

Get handle for a device based on the name.

Return

Device handle on success.

Return

NULL in case of failure.

Parameters

• [in] node: Node handle.

• [in] device_name: Device name to search.

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.

esp_err_t esp_rmaker_device_add_subtype(const esp_rmaker_device_t *device, const char *subtype)

Add a Device subtype

This can be something like esp.subtype.rgb-light for a device of type esp.device.lightbulb. This would primarily be used by the phone apps to render different icons for the same device type.

Return

ESP_OK if the subtype was added successfully.

Return

error in case of failure.

Parameters

• [in] device: Device handle.

• [in] subtype: String describing the sub type.

esp_err_t esp_rmaker_device_add_model(const esp_rmaker_device_t *device, const char *model)

Add a Device model

This would primarily be used by the phone apps to render different icons for the same device type.

Return

ESP_OK if the model was added successfully.

Return

error in case of failure.

Parameters

• [in] device: Device handle.

• [in] model: String describing the model.

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(const esp_rmaker_param_t *param, esp_rmaker_param_val_t val)

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.

esp_err_t esp_rmaker_param_update_and_notify(const esp_rmaker_param_t *param, esp_rmaker_param_val_t val)

Update and notify a parameter

Calling this API will update the parameter and report it to ESP RainMaker cloud similar to esp_rmaker_param_update_and_report(). However, additionally, it will also trigger a notification on the phone apps (if enabled).

Alternatively, the

esp_rmaker_raise_alert() API can also be used to trigger notification on the phone apps with pre-formatted text.

Note

This should be used only when some local change requires explicit notification even when the phone app is in background, not otherwise. Eg. Alarm got triggered, temperature exceeded some threshold, etc.

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.

esp_err_t esp_rmaker_raise_alert(const char *alert_str)

Trigger an alert on the phone app

This API will trigger a notification alert on the phone apps (if enabled) using the formatted text provided. Note that this does not send a notification directly to the phone, but reports the alert to the ESP RainMaker cloud which then uses the Notification framework to send notifications to the phone apps. The value does not get stored anywhere, nor is it linked to any node parameters.

Note

This should be used only if some event requires explicitly alerting the user even when the phone app is in background, not otherwise. Eg. “Motion Detected”, “Fire alarm triggered”

Return

ESP_OK on success.

Return

error in case of failure.

Parameters

• [in] alert_str: NULL terminated pre-formatted alert string. Maximum length can be ESP_RMAKER_MAX_ALERT_LEN, excluding NULL character.

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_rmaker_param_val_t *esp_rmaker_param_get_val(esp_rmaker_param_t *param)

Get parameter value

This gives the parameter value that is stored in the RainMaker core.

Note

This does not call any explicit functions to read value from hardware/driver.

Return

Pointer to parameter value on success.

Return

NULL in case of failure.

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_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_system_service_enable(esp_rmaker_system_serv_config_t *config)

Enable System Service

This enables the ESP RainMaker standard system service which can be used for operations like reboot, factory reset and Wi-Fi reset.

Please refer the specifications for additional details.

Return

ESP_OK on success

Return

error on failure

Parameters

• [in] config: Configuration for the system service.

bool esp_rmaker_local_ctrl_service_started(void)

Check if local_ctrl service has started

Return

true if service has started

Return

false if the service has not started

esp_err_t esp_rmaker_ota_enable_default(void)

Enable Default RainMaker OTA Firmware Upgrade

This enables the default recommended RainMaker OTA Firmware Upgrade, which is “Using the Topics”, which allows performing OTA from Dashboard. This OTA can be triggered by Admin Users only. On Public RainMaker deployment, for nodes using “Self Claiming”, since there is no associated admin user, the Primary user will automatically become the admin and can perform OTA from dashboard.

Return

ESP_OK on success

Return

error on failure

esp_err_t esp_rmaker_test_cmd_resp(const void *cmd, size_t cmd_len, void *priv_data)

esp_err_t esp_rmaker_node_auth_sign_msg(const void *challenge, size_t inlen, void **response, size_t *outlen)

This API signs the challenge with RainMaker private key.

Return

ESP_OK on success. response is dynamically allocated, free the response on success.

Return

Apt error on failure.

Parameters

• [in] challenge: Pointer to the data to be signed

• [in] inlen: Length of the challenge

• [out] response: Pointer to the signature.

• [out] outlen: Length of the signature

esp_err_t esp_rmaker_local_ctrl_enable(void)

esp_err_t esp_rmaker_local_ctrl_disable(void)

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)

char *subtype

Subtype (Optional).

char **secure_boot_digest

An array of digests read from efuse. Should be freed after use

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

struct esp_rmaker_system_serv_config_t

System service configuration

Public Members

uint16_t flags

Logical OR of system service flags (SYSTEM_SERV_FLAG_REBOOT, SYSTEM_SERV_FLAG_FACTORY_RESET, SYSTEM_SERV_FLAG_WIFI_RESET) as required or SYSTEM_SERV_FLAGS_ALL.

int8_t reboot_seconds

Time in seconds after which the device should reboot. Value of zero would trigger an immediate reboot if a write is received for the Reboot parameter. Recommended value: 2

int8_t reset_seconds

Time in seconds after which the device should reset (Wi-Fi or factory). Value of zero would trigger an immediate action if a write is received for the Wi-Fi reset or Factory reset parameter. Recommended value: 2

int8_t reset_reboot_seconds

Time in seconds after which the device should reboot after it has been reset. Value of zero would mean that there won’t be any reboot after the reset. Recommended value: 2

Macros

ESP_RMAKER_CONFIG_VERSION

ESP_RMAKER_MAX_ALERT_LEN

SYSTEM_SERV_FLAG_REBOOT

System Service Reboot Flag

SYSTEM_SERV_FLAG_FACTORY_RESET

System Service Factory Reset Flag

SYSTEM_SERV_FLAG_WIFI_RESET

System Service Wi-Fi Reset Flag

SYSTEM_SERV_FLAGS_ALL

System Service All Flags

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.

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_USER_NODE_MAPPING_DONE

Node side communication for User-Node mapping done. Actual mapping state will be managed by the ESP RainMaker cloud based on the user side communication. Associated data is the NULL terminated user id.

RMAKER_EVENT_LOCAL_CTRL_STARTED

Local control started. Associated data is the NULL terminated Service Name

RMAKER_EVENT_USER_NODE_MAPPING_RESET

RMAKER_EVENT_LOCAL_CTRL_STOPPED

Local control stopped.

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)

PROP_FLAG_SIMPLE_TIME_SERIES = (1 << 4)

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_SCENE_ACTIVATE

Request received when a scene has been activated

ESP_RMAKER_REQ_SRC_SCENE_DEACTIVATE

Request received when a scene has been deactivated

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

• components/esp_rainmaker/include/esp_rmaker_user_mapping.h

Functions

esp_rmaker_user_mapping_state_t esp_rmaker_user_node_mapping_get_state(void)

Get User-Node mapping state

This returns the current user-node mapping state.

Return

user mapping state

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)

Enumerations

enum esp_rmaker_user_mapping_state_t

User-Node Mapping states

Values:

ESP_RMAKER_USER_MAPPING_RESET = 0

Mapping does not exist or is not initialized

ESP_RMAKER_USER_MAPPING_STARTED

Mapping has started

ESP_RMAKER_USER_MAPPING_REQ_SENT

Mapping request sent to cloud

ESP_RMAKER_USER_MAPPING_DONE

Mapping is done

Scheduling

Header File

• components/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.

Scenes

Header File

• components/esp_rainmaker/include/esp_rmaker_scenes.h

Functions

esp_err_t esp_rmaker_scenes_enable(void)

Enable Scenes

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

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.