RainMaker Neo Data Model

Devices, parameters and their values, plus the standard (cloud-recognised) device, parameter and service definitions.

Data Model

Header File

Functions

esp_rmaker_error_t esp_rmaker_node_clear_stored_values(const esp_rmaker_node_t *node)

Clear all stored values for a node and its devices.

This function clears the NVS storage for all devices attached to the node. It should be called before esp_rmaker_node_deinit() to ensure that persistent parameter values are properly cleared from storage.

Parameters:

node – [in] Node handle.

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_INVALID_ARG if node handle is NULL.

Returns:

ESP_RMAKER_FAIL if clearing stored values for any device fails.

esp_rmaker_device_t *esp_rmaker_node_get_device_by_id(const esp_rmaker_node_t *node, const char *device_id)

Get device by id.

Get handle for a device based on the id.

Parameters:

  • node – [in] Node handle.

  • device_id – [in] Device id to search.

Returns:

Device handle on success.

Returns:

NULL in case of failure.

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

Add a device to a node.

Parameters:

  • node – [in] Node handle.

  • device – [in] Device handle.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

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

Remove a device from a node.

Does not delete the device.

Parameters:

  • node – [in] Node handle.

  • device – [in] Device handle.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_device_t *esp_rmaker_device_create(const char *dev_id, 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().

Parameters:

  • dev_id – [in] The unique device id. Must not contain ‘.’, which is reserved as the data model path separator.

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

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

Returns:

Device handle on success.

Returns:

NULL in case of any error.

esp_rmaker_device_t *esp_rmaker_service_create(const char *serv_id, 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

Id of a service should not clash with id of a device.

Note

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

Parameters:

  • serv_id – [in] The unique service id. Must not contain ‘.’, which is reserved as the data model path separator.

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

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

Returns:

Device handle on success.

Returns:

NULL in case of any error.

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

Parameters:

device – [in] Device handle.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_device_clear_stored_values(const esp_rmaker_device_t *device)

Clear stored values for a device.

This function clears the NVS storage for the specified device, removing all persistent parameter values. It should be called before esp_rmaker_device_delete() to ensure that persistent parameter values are properly cleared from storage.

Parameters:

device – [in] Device handle.

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_INVALID_ARG if device handle or device id is NULL.

Returns:

ESP_RMAKER_FAIL if NVS operations fail.

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

Parameters:

  • device – [in] Device handle.

  • param – [in] Parameter handle.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_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

Parameters:

  • device – [in] Device handle.

  • attr_name – [in] Name of the attribute.

  • val – [in] Value of the attribute.

Returns:

ESP_RMAKER_OK if the attribute was added successfully.

Returns:

error in case of failure.

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

Parameters:

  • device – [in] Device handle.

  • param – [in] Parameter handle.

Returns:

ESP_RMAKER_OK if the parameter was assigned as the primary successfully.

Returns:

error in case of failure.

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

Note

A device is created with a built-in bulk write callback that fans a bulk request out to this single-parameter callback, one parameter at a time. Registering your own bulk callback with esp_rmaker_device_add_bulk_cb() replaces that default, after which the callback registered here is no longer invoked.

Parameters:

  • device – [in] Device handle.

  • write_cb – [in] Write callback. NULL clears any previously registered callback.

  • read_cb – [in] Read callback. NULL clears any previously registered callback.

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_INVALID_ARG if device is NULL.

esp_rmaker_error_t esp_rmaker_device_add_bulk_cb(const esp_rmaker_device_t *device, esp_rmaker_device_bulk_write_cb_t write_cb, esp_rmaker_device_bulk_read_cb_t read_cb)

Add bulk callbacks for a device/service.

Add bulk 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).

This is an improvement over the earlier callbacks registered using esp_rmaker_device_add_cb() so that all parameters received in a single request are passed to the callback together, instead of one by one.

Note

This replaces the default bulk callback installed at device creation, which fans requests out to the single-parameter callback of esp_rmaker_device_add_cb(). Register either one or the other, not both.

Parameters:

  • device – [in] Device handle.

  • write_cb – [in] Bulk Write callback. NULL clears any previously registered callback, including the default one.

  • read_cb – [in] Bulk Read callback. NULL clears any previously registered callback.

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_INVALID_ARG if device is NULL.

char *esp_rmaker_device_get_id(const esp_rmaker_device_t *device)

Get device id from handle.

Parameters:

device – [in] Device handle.

Returns:

NULL terminated device id string on success.

Returns:

NULL in case of failure.

void *esp_rmaker_device_get_priv_data(const esp_rmaker_device_t *device)

Get Device Private data from handle.

Parameters:

device – [in] Device handle.

Returns:

void type of pointer on success.

Returns:

NULL if no private data found.

char *esp_rmaker_device_get_type(const esp_rmaker_device_t *device)

Get device type from handle.

Parameters:

device – [in] Device handle.

Returns:

NULL terminated device type string on success.

Returns:

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

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_id() can be used to get a specific parameter, because the parameter ids in a device are unique.

Parameters:

  • device – [in] Device handle.

  • param_type – [in] Parameter type to search.

Returns:

Parameter handle on success.

Returns:

NULL in case of failure.

esp_rmaker_param_t *esp_rmaker_device_get_param_by_id(const esp_rmaker_device_t *device, const char *param_id)

Get parameter by id.

Get handle for a parameter based on the id.

Parameters:

  • device – [in] Device handle.

  • param_id – [in] Parameter id to search.

Returns:

Parameter handle on success.

Returns:

NULL in case of failure.

esp_rmaker_param_t *esp_rmaker_param_create(const char *param_id, 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 id should be unique in a given device.

Parameters:
Returns:

Parameter handle on success.

Returns:

NULL in case of failure.

esp_rmaker_error_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 Neo core does not check the bounds. It is up to the application to handle it.

Parameters:

  • param – [in] Parameter handle.

  • min – [in] Minimum allowed value.

  • max – [in] Maximum allowed value.

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

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_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 Neo documentation for supported UI Types.

Parameters:

  • param – [in] Parameter handle.

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

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_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 Neo core does not check the values. It is up to the application to handle it.

Parameters:

  • param – [in] Parameter handle.

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

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

char *esp_rmaker_param_get_id(const esp_rmaker_param_t *param)

Get parameter id from handle.

Parameters:

param – [in] Parameter handle.

Returns:

NULL terminated parameter id string on success.

Returns:

NULL in case of failure.

char *esp_rmaker_param_get_type(const esp_rmaker_param_t *param)

Get parameter type from handle.

Parameters:

param – [in] Parameter handle.

Returns:

NULL terminated parameter type string on success.

Returns:

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

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 Neo core.

Note

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

Parameters:

param – [in] Parameter handle

Returns:

Pointer to parameter value on success.

Returns:

NULL in case of failure.

esp_rmaker_error_t esp_rmaker_param_update(const esp_rmaker_param_t *param, esp_rmaker_param_val_t val)

Update a parameter.

This will update the value of a parameter with ESP RainMaker Neo core and schedule a delayed report of all changed parameters. The report will be sent after a configurable delay (CONFIG_RMAKER_STATE_REPORT_DELAY_MS). This can be used when multiple parameters need to be reported together, as multiple calls will coalesce into a single report.

Eg. If x parameters are to be reported, this API can be used for all x parameters. All parameters updated within the delay window will be included in a single report.

Alternatively, if immediate reporting is needed, use esp_rmaker_param_update_and_report().

Sample:

esp_rmaker_param_update(param1, esp_rmaker_float(10.2));
esp_rmaker_param_update(param2, esp_rmaker_int(55));
esp_rmaker_param_update(param3, esp_rmaker_int(95));
// All three parameters will be reported together after the delay

Note

If the new value equals the current value, the function returns ESP_RMAKER_OK without making any changes.

Note

If PROP_FLAG_TIME_SERIES or PROP_FLAG_TS_CUMULATIVE is set, the value will be added to the timeseries queue.

Note

The parameter value will be stored to NVS if PROP_FLAG_PERSIST is set.

Note

The function validates that the new value is within bounds (if bounds are set) and that the value type matches.

Note

Automation triggers are checked and fired if the update causes any trigger conditions to be met.

Parameters:

  • param – [in] Parameter handle.

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

Returns:

ESP_RMAKER_OK if the parameter was updated successfully, or if the value was already equal.

Returns:

ESP_RMAKER_INVALID_ARG if param is NULL, value is out of bounds, value type is invalid, or value comparison fails.

Returns:

ESP_RMAKER_FAIL if memory allocation fails (for string/object/array types).

esp_rmaker_error_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 immediately report all changed parameters to ESP RainMaker Neo cloud. This cancels any scheduled delayed reports and sends the report right away. This should be used whenever there is any local change that needs immediate reporting.

Note

This function calls esp_rmaker_param_update() internally, so all the same behaviors apply (timeseries, persistence, validation, etc.), but with immediate reporting instead of scheduled reporting.

Note

If the parameter update fails, the function returns the update error without attempting to report.

Note

If the parameter update succeeds but the report fails, the function returns the report error.

Parameters:

  • param – [in] Parameter handle.

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

Returns:

ESP_RMAKER_OK if the parameter was updated and reported successfully.

Returns:

ESP_RMAKER_INVALID_ARG if param is NULL or the update fails with INVALID_ARG.

Returns:

ESP_RMAKER_FAIL if the update fails with FAIL, or if the report fails.

esp_rmaker_error_t esp_rmaker_param_update_and_notify(const esp_rmaker_param_t *param, esp_rmaker_param_val_t val)

Update and notify a parameter.

This updates the parameter (like esp_rmaker_param_update(), so the new value is reported to ESP RainMaker Neo cloud with the next state report) and additionally triggers a notification on the phone apps (if enabled), published on the notify topic of the node owning the parameter.

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.

Warning

The notification payload currently carries no parameter identity: the cloud is told only that this node has an alert, so the phone app shows a generic “Node <node ID> has an alert”. Carrying the parameter ID/value through to the app needs a corresponding cloud-side change.

Parameters:

  • param – [in] Parameter handle.

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

Returns:

ESP_RMAKER_OK if the parameter was updated successfully. The notification is best-effort: a notify failure is logged but does not change the return value.

Returns:

error in case the parameter update itself failed.

Structures

struct esp_rmaker_write_ctx_t

Write request Context

Public Members

esp_rmaker_req_src_t src

Source of request

struct esp_rmaker_param_write_req_t

Parameter write request payload

Public Members

esp_rmaker_param_t *param

Parameter handle

esp_rmaker_param_val_t val

Value to write

struct esp_rmaker_read_ctx_t

Read request context

Public Members

esp_rmaker_req_src_t src

Source of request

Type Definitions

typedef esp_rmaker_handle_t esp_rmaker_device_t

ESP RainMaker Neo Device Handle

typedef esp_rmaker_handle_t esp_rmaker_param_t

ESP RainMaker Neo Parameter Handle

typedef esp_rmaker_error_t (*esp_rmaker_device_bulk_write_cb_t)(const esp_rmaker_device_t *device, const esp_rmaker_param_write_req_t write_req[], uint8_t count, void *priv_data, esp_rmaker_write_ctx_t *ctx)

Callback for bulk parameter value write requests.

This callback is recommended over esp_rmaker_device_write_cb_t since it gives all values of a given device together, which will help if the parameters are related to each other.

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

Param device:

[in] Device handle.

Param write_req:

[in] Array of parameter write request payloads.

Param count:

[in] Count of parameters and their values passed to this callback

Param priv_data:

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

Param ctx:

[in] Context associated with the request.

Return:

ESP_RMAKER_OK on success.

Return:

error in case of failure.

typedef esp_rmaker_error_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.

Param device:

[in] Device handle.

Param param:

[in] Parameter handle.

Param val:

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

Param priv_data:

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

Param ctx:

[in] Context associated with the request.

Return:

ESP_RMAKER_OK on success.

Return:

error in case of failure.

typedef esp_rmaker_error_t (*esp_rmaker_device_bulk_read_cb_t)(const esp_rmaker_device_t *device, const esp_rmaker_param_t *params[], uint8_t count, void *priv_data, esp_rmaker_read_ctx_t *ctx)

Callback for bulk parameter value reads.

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 may however be used in future.

Param device:

[in] Device handle.

Param params:

[in] Array of Parameter handles.

Param count:

[in] Count of parameters passed to this callback.

Param priv_data:

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

Param ctx:

[in] Context associated with the request.

Return:

ESP_RMAKER_OK on success.

Return:

error in case of failure.

typedef esp_rmaker_error_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 reads.

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 may however be used in future.

Param device:

[in] Device handle.

Param param:

[in] Parameter handle.

Param priv_data:

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

Param ctx:

[in] Context associated with the request.

Return:

ESP_RMAKER_OK on success.

Return:

error in case of failure.

Enumerations

enum esp_rmaker_param_property_flags_t

Param property flags

Values:

enumerator PROP_FLAG_READ

Parameter can be read from the cloud.

enumerator PROP_FLAG_WRITE

Parameter can be written from the cloud.

enumerator PROP_FLAG_TIME_SERIES

Parameter is a time series (not cumulative)

enumerator PROP_FLAG_TS_CUMULATIVE

Parameter is a time series (cumulative)

enumerator PROP_FLAG_INDEXED

Parameter value is also in the indexed shadow.

enumerator PROP_FLAG_PERSIST

Parameter value is persisted across reboots.

Parameter Values

Header File

Functions

esp_rmaker_param_val_t esp_rmaker_bool(bool bval)

Initialise a Boolean value.

Parameters:

bval – [in] Initialising value.

Returns:

Value structure.

esp_rmaker_param_val_t esp_rmaker_int(int ival)

Initialise an Integer value.

Parameters:

ival – [in] Initialising value.

Returns:

Value structure.

esp_rmaker_param_val_t esp_rmaker_float(float fval)

Initialise a Float value.

Parameters:

fval – [in] Initialising value.

Returns:

Value structure.

esp_rmaker_param_val_t esp_rmaker_str(const char *sval)

Initialise a String value.

Parameters:

sval – [in] Initialising value.

Returns:

Value structure.

esp_rmaker_param_val_t esp_rmaker_obj(const char *val)

Initialise a JSON object value.

Note

The object is not validated internally. It is the application’s responsibility to ensure that the object is a valid JSON object, e.g. esp_rmaker_obj(“{"name":"value"}”);

Parameters:

val – [in] Initialising value.

Returns:

Value structure.

esp_rmaker_param_val_t esp_rmaker_array(const char *val)

Initialise a JSON array value.

Note

The array is not validated internally. It is the application’s responsibility to ensure that the array is a valid JSON array, e.g. esp_rmaker_array(“[1,2,3]”);

Parameters:

val – [in] Initialising value.

Returns:

Value structure.

esp_rmaker_error_t esp_rmaker_val_compare(const esp_rmaker_param_val_t *val1, const esp_rmaker_param_val_t *val2, esp_rmaker_val_compare_t compare_type)

Compare two values.

Parameters:

  • val1 – [in] First value

  • val2 – [in] Second value

  • compare_type – [in] Type of comparison. val1 is compared to val2 based on the compare_type. e.g., GT means val1 > val2.

Returns:

ESP_RMAKER_OK if the comparison holds.

Returns:

ESP_RMAKER_INVALID_ARG if either value is NULL, the values are of different types, or the comparison type is not valid for that type (e.g. GT on a boolean).

Returns:

ESP_RMAKER_FAIL if the comparison does not hold.

esp_rmaker_error_t esp_rmaker_val_copy(const esp_rmaker_param_val_t *val, esp_rmaker_param_val_t *dest)

Copy a value. For string, object, and array types, a new copy is created and must be freed by the caller.

Parameters:

  • val – [in] Source value

  • dest – [out] Destination value

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_val_free(esp_rmaker_param_val_t *val)

Free a value. For string, object, and array types, the held string is freed.

Note

The struct itself is not modified, so val->val.s is left dangling. Types other than string, object and array hold nothing to free and the call is a no-op.

Parameters:

val – [in] Value to free

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_INVALID_ARG if val is NULL.

Unions

union esp_rmaker_val_t
#include <esp_rmaker_val.h>

RainMaker Neo Value.

Public Members

bool b

Boolean

int i

Integer

float f

Float

char *s

NULL terminated string

Structures

struct esp_rmaker_param_val_t

RainMaker Neo 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_param_bounds_t

RainMaker Neo Parameter Bounds.

Public Members

esp_rmaker_param_val_t min

Minimum value

esp_rmaker_param_val_t max

Maximum value

esp_rmaker_param_val_t step

Step value

Enumerations

enum esp_rmaker_val_type_t

RainMaker Neo Value Type.

Values:

enumerator RMAKER_VAL_TYPE_INVALID

Invalid

enumerator RMAKER_VAL_TYPE_BOOLEAN

Boolean

enumerator RMAKER_VAL_TYPE_INTEGER

Integer. Mapped to a 32 bit signed integer

enumerator RMAKER_VAL_TYPE_FLOAT

Floating point number

enumerator RMAKER_VAL_TYPE_STRING

NULL terminated string

enumerator RMAKER_VAL_TYPE_OBJECT

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

enumerator RMAKER_VAL_TYPE_ARRAY

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

enum esp_rmaker_val_compare_t

RainMaker Neo Value Comparison.

Used with esp_rmaker_val_compare(), which tests val1 <op> val2.

Values:

enumerator RMAKER_VAL_COMPARE_EQ

val1 is equal to val2

enumerator RMAKER_VAL_COMPARE_NEQ

val1 is not equal to val2

enumerator RMAKER_VAL_COMPARE_GT

val1 is greater than val2

enumerator RMAKER_VAL_COMPARE_LT

val1 is less than val2

enumerator RMAKER_VAL_COMPARE_GTE

val1 is greater than or equal to val2

enumerator RMAKER_VAL_COMPARE_LTE

val1 is less than or equal to val2

Standard Types

Header File

Macros

ESP_RMAKER_UI_TOGGLE
ESP_RMAKER_UI_SLIDER
ESP_RMAKER_UI_DROPDOWN
ESP_RMAKER_UI_TEXT
ESP_RMAKER_UI_HUE_SLIDER
ESP_RMAKER_UI_HUE_CIRCLE
ESP_RMAKER_UI_PUSHBUTTON
ESP_RMAKER_UI_TRIGGER
ESP_RMAKER_UI_HIDDEN
ESP_RMAKER_UI_QR_SCAN
ESP_RMAKER_PARAM_NAME
ESP_RMAKER_PARAM_POWER
ESP_RMAKER_PARAM_BRIGHTNESS
ESP_RMAKER_PARAM_HUE
ESP_RMAKER_PARAM_SATURATION
ESP_RMAKER_PARAM_INTENSITY
ESP_RMAKER_PARAM_CCT
ESP_RMAKER_PARAM_SPEED
ESP_RMAKER_PARAM_DIRECTION
ESP_RMAKER_PARAM_TEMPERATURE
ESP_RMAKER_PARAM_OTA_STATUS
ESP_RMAKER_PARAM_OTA_INFO
ESP_RMAKER_PARAM_OTA_URL
ESP_RMAKER_PARAM_TIMEZONE
ESP_RMAKER_PARAM_TIMEZONE_POSIX
ESP_RMAKER_PARAM_SCHEDULES
ESP_RMAKER_PARAM_SCENES
ESP_RMAKER_PARAM_REBOOT
ESP_RMAKER_PARAM_NETWORK_RESET
ESP_RMAKER_PARAM_FACTORY_RESET
ESP_RMAKER_PARAM_LOCAL_CONTROL_POP
ESP_RMAKER_PARAM_LOCAL_CONTROL_TYPE
ESP_RMAKER_PARAM_LOCAL_CONTROL_USERNAME
ESP_RMAKER_PARAM_TOGGLE
ESP_RMAKER_PARAM_RANGE
ESP_RMAKER_PARAM_MODE
ESP_RMAKER_PARAM_BLINDS_POSITION
ESP_RMAKER_PARAM_GARAGE_POSITION
ESP_RMAKER_PARAM_LIGHT_MODE
ESP_RMAKER_PARAM_AC_MODE
ESP_RMAKER_PARAM_ADD_ZIGBEE_DEVICE
ESP_RMAKER_DEVICE_SWITCH
ESP_RMAKER_DEVICE_LIGHTBULB
ESP_RMAKER_DEVICE_FAN
ESP_RMAKER_DEVICE_TEMP_SENSOR
ESP_RMAKER_DEVICE_LIGHT
ESP_RMAKER_DEVICE_OUTLET
ESP_RMAKER_DEVICE_PLUG
ESP_RMAKER_DEVICE_SOCKET
ESP_RMAKER_DEVICE_LOCK
ESP_RMAKER_DEVICE_BLINDS_INTERNAL
ESP_RMAKER_DEVICE_BLINDS_EXTERNAL
ESP_RMAKER_DEVICE_GARAGE_DOOR
ESP_RMAKER_DEVICE_GARAGE_LOCK
ESP_RMAKER_DEVICE_SPEAKER
ESP_RMAKER_DEVICE_AIR_CONDITIONER
ESP_RMAKER_DEVICE_THERMOSTAT
ESP_RMAKER_DEVICE_TV
ESP_RMAKER_DEVICE_WASHER
ESP_RMAKER_DEVICE_OTHER
ESP_RMAKER_DEVICE_ZIGBEE_GATEWAY
ESP_RMAKER_DEVICE_THREAD_BR
ESP_RMAKER_SERVICE_OTA
ESP_RMAKER_SERVICE_TIME
ESP_RMAKER_SERVICE_SCHEDULE
ESP_RMAKER_SERVICE_SCENES
ESP_RMAKER_SERVICE_SYSTEM
ESP_RMAKER_SERVICE_LOCAL_CONTROL

Standard Parameters

Header File

Functions

esp_rmaker_param_t *esp_rmaker_name_param_create(const char *param_id, const char *val)

Create standard name param.

This will create the standard name parameter. This should be added to all devices for which you want a user customisable name. The value should be same as the device id.

All standard device creation APIs will add this internally. No application registered callback will be called for this parameter, and changes will be managed internally, unless a custom bulk write callback is registered.

Parameters:

  • param_id – [in] Id of the parameter

  • val – [in] The device name

Returns:

Parameter handle on success.

Returns:

NULL in case of failures.

esp_rmaker_param_t *esp_rmaker_power_param_create(const char *param_id, bool val)

Create standard Power param.

This will create the standard power parameter.

Parameters:

  • param_id – [in] Id of the parameter

  • val – [in] Default Value of the parameter

Returns:

Parameter handle on success.

Returns:

NULL in case of failures.

esp_rmaker_param_t *esp_rmaker_brightness_param_create(const char *param_id, int val)

Create standard Brightness param.

This will create the standard brightness parameter.

Parameters:

  • param_id – [in] Id of the parameter

  • val – [in] Default Value of the parameter

Returns:

Parameter handle on success.

Returns:

NULL in case of failures.

esp_rmaker_param_t *esp_rmaker_hue_param_create(const char *param_id, int val)

Create standard Hue param.

This will create the standard hue parameter.

Parameters:

  • param_id – [in] Id of the parameter

  • val – [in] Default Value of the parameter

Returns:

Parameter handle on success.

Returns:

NULL in case of failures.

esp_rmaker_param_t *esp_rmaker_saturation_param_create(const char *param_id, int val)

Create standard Saturation param.

This will create the standard saturation parameter.

Parameters:

  • param_id – [in] Id of the parameter

  • val – [in] Default Value of the parameter

Returns:

Parameter handle on success.

Returns:

NULL in case of failures.

esp_rmaker_param_t *esp_rmaker_intensity_param_create(const char *param_id, int val)

Create standard Intensity param.

This will create the standard intensity parameter.

Parameters:

  • param_id – [in] Id of the parameter

  • val – [in] Default Value of the parameter

Returns:

Parameter handle on success.

Returns:

NULL in case of failures.

esp_rmaker_param_t *esp_rmaker_cct_param_create(const char *param_id, int val)

Create standard CCT param.

This will create the standard cct parameter.

Parameters:

  • param_id – [in] Id of the parameter

  • val – [in] Default Value of the parameter

Returns:

Parameter handle on success.

Returns:

NULL in case of failures.

esp_rmaker_param_t *esp_rmaker_light_mode_param_create(const char *param_id, esp_rmaker_light_mode_t val, bool ui_hidden)

Create standard Light Mode param.

This will create the standard light mode parameter. The parameter is bounded to the currently supported light modes:

Parameters:

  • param_id – [in] Id of the parameter

  • val – [in] Default Light Mode of the parameter

  • ui_hidden – [in] Whether to hide the UI for this parameter

Returns:

Parameter handle on success.

Returns:

NULL in case of failures.

esp_rmaker_param_t *esp_rmaker_direction_param_create(const char *param_id, int val)

Create standard Direction param.

This will create the standard direction parameter.

Parameters:

  • param_id – [in] Id of the parameter

  • val – [in] Default Value of the parameter

Returns:

Parameter handle on success.

Returns:

NULL in case of failures.

esp_rmaker_param_t *esp_rmaker_speed_param_create(const char *param_id, int val)

Create standard Speed param.

This will create the standard speed parameter.

Parameters:

  • param_id – [in] Id of the parameter

  • val – [in] Default Value of the parameter

Returns:

Parameter handle on success.

Returns:

NULL in case of failures.

esp_rmaker_param_t *esp_rmaker_temperature_param_create(const char *param_id, float val)

Create standard Temperature param.

This will create the standard temperature parameter.

Parameters:

  • param_id – [in] Id of the parameter

  • val – [in] Default Value of the parameter

Returns:

Parameter handle on success.

Returns:

NULL in case of failures.

Macros

ESP_RMAKER_DEF_NAME_PARAM_ID
ESP_RMAKER_DEF_POWER_ID
ESP_RMAKER_DEF_BRIGHTNESS_ID
ESP_RMAKER_DEF_HUE_ID
ESP_RMAKER_DEF_SATURATION_ID
ESP_RMAKER_DEF_INTENSITY_ID
ESP_RMAKER_DEF_CCT_ID
ESP_RMAKER_DEF_LIGHT_MODE_ID
ESP_RMAKER_DEF_DIRECTION_ID
ESP_RMAKER_DEF_SPEED_ID
ESP_RMAKER_DEF_TEMPERATURE_ID

Enumerations

enum esp_rmaker_light_mode_t

Light mode enumeration.

Note

These values are used to set the default light mode.

Values:

enumerator ESP_RMAKER_LIGHT_MODE_INVALID

Invalid mode.

enumerator ESP_RMAKER_LIGHT_MODE_HSV

HSV mode.

enumerator ESP_RMAKER_LIGHT_MODE_CCT

CCT mode.

enumerator ESP_RMAKER_LIGHT_MODE_MAX

Used for bounds calculation.

Standard Devices

Header File

Functions

esp_rmaker_device_t *esp_rmaker_switch_device_create(const char *dev_id, void *priv_data, bool power)

Create a standard Switch device.

This creates a Switch device with the mandatory parameters and also assigns the primary parameter. The default parameter names will be used. Refer esp_rmaker_standard_params.h for default names.

Parameters:

  • dev_id – [in] The unique device id

  • priv_data – [in] (Optional) Private data associated with the device. This should stay allocated throughout the lifetime of the device

  • power – [in] Default value of the mandatory parameter “power”

Returns:

Device handle on success.

Returns:

NULL in case of failures.

esp_rmaker_device_t *esp_rmaker_lightbulb_device_create(const char *dev_id, void *priv_data, bool power)

Create a standard Lightbulb device.

This creates a Lightbulb device with the mandatory parameters and also assigns the primary parameter. The default parameter names will be used. Refer esp_rmaker_standard_params.h for default names.

Parameters:

  • dev_id – [in] The unique device id

  • priv_data – [in] (Optional) Private data associated with the device. This should stay allocated throughout the lifetime of the device

  • power – [in] Default value of the mandatory parameter “power”

Returns:

Device handle on success.

Returns:

NULL in case of failures.

esp_rmaker_device_t *esp_rmaker_fan_device_create(const char *dev_id, void *priv_data, bool power)

Create a standard Fan device.

This creates a Fan device with the mandatory parameters and also assigns the primary parameter. The default parameter names will be used. Refer esp_rmaker_standard_params.h for default names.

Parameters:

  • dev_id – [in] The unique device id

  • priv_data – [in] (Optional) Private data associated with the device. This should stay allocated throughout the lifetime of the device

  • power – [in] Default value of the mandatory parameter “power”

Returns:

Device handle on success.

Returns:

NULL in case of failures.

esp_rmaker_device_t *esp_rmaker_temp_sensor_device_create(const char *dev_id, void *priv_data, float temperature)

Create a standard Temperature Sensor device.

This creates a Temperature Sensor device with the mandatory parameters and also assigns the primary parameter. The default parameter names will be used. Refer esp_rmaker_standard_params.h for default names.

Parameters:

  • dev_id – [in] The unique device id

  • priv_data – [in] (Optional) Private data associated with the device. This should stay allocated throughout the lifetime of the device

  • temperature – [in] Default value of the mandatory parameter “temperature”

Returns:

Device handle on success.

Returns:

NULL in case of failures.

Standard Services

Header File

Functions

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

Returns:

ESP_RMAKER_OK on success

Returns:

error on failure

esp_rmaker_error_t esp_rmaker_timezone_service_disable(void)

Disable Timezone Service.

This disables the ESP RainMaker standard timezone service.

Returns:

ESP_RMAKER_OK on success

Returns:

error on failure

esp_rmaker_error_t esp_rmaker_system_service_enable(const esp_rmaker_system_serv_config_t *config)

Enable System Service.

This enables the ESP RainMaker standard System service which exposes Reboot, Network-Reset and/or Factory-Reset params (selected via config->flags). Writing true to a param triggers the corresponding esp_rmaker_system_ctrl_* action.

Parameters:

config – [in] System service configuration. Must not be NULL and must have at least one flag set.

Returns:

ESP_RMAKER_OK on success

Returns:

error on failure

esp_rmaker_error_t esp_rmaker_system_service_disable(void)

Disable System Service.

This disables the ESP RainMaker standard System service.

Returns:

ESP_RMAKER_OK on success

Returns:

error on failure

esp_rmaker_error_t esp_rmaker_local_ctrl_set_pop(const char *pop)

Set custom PoP for Local Control Service.

This allows setting a custom Proof of Possession (PoP) for the local control service instead of the internally generated one. This is useful when you want to use the same PoP that was used for provisioning.

Note

This must be called before esp_rmaker_local_ctrl_service_enable() for it to take effect. If not called, a random PoP will be generated and stored in NVS.

Parameters:

pop – [in] NULL terminated PoP string (typically 8 characters alphanumeric). Pass NULL to clear any previously set custom PoP.

Returns:

ESP_RMAKER_OK on success

Returns:

ESP_RMAKER_INVALID_ARG if pop is empty string

Returns:

ESP_RMAKER_NO_MEM if memory allocation fails

esp_rmaker_error_t esp_rmaker_local_ctrl_service_enable(void)

Enable Local Control Service.

This enables the ESP RainMaker standard local control service, which allows users to control their device without internet connection.

Returns:

ESP_RMAKER_OK on success

Returns:

error on failure

esp_rmaker_error_t esp_rmaker_local_ctrl_service_disable(void)

Disable Local Control Service.

This disables the ESP RainMaker standard local control service.

Returns:

ESP_RMAKER_OK on success

Returns:

error on failure

esp_rmaker_error_t esp_rmaker_chal_resp_service_enable(void)

Enable the Challenge-Response endpoint.

Registers the ch_resp endpoint on the local endpoints service instance (starting the instance if needed) and reflects it in the advertised capabilities. Independent of local control: any combination of the two endpoint sets may be active.

Note

Refused (ESP_RMAKER_INVALID_STATE) while a client-issued disable is persisted; that state is cleared only by a factory reset.

Returns:

ESP_RMAKER_OK on success

Returns:

error on failure

esp_rmaker_error_t esp_rmaker_chal_resp_service_disable(void)

Disable the Challenge-Response endpoint.

Removes the ch_resp endpoint; the service instance is stopped when no endpoint set remains active.

Returns:

ESP_RMAKER_OK on success

Returns:

error on failure

bool esp_rmaker_chal_resp_service_is_enabled(void)

Check whether the Challenge-Response endpoint is enabled.

Returns:

true if the ch_resp endpoint is currently registered, false otherwise.

Structures

struct esp_rmaker_system_serv_config_t

System service configuration

Public Members

uint16_t flags

OR of esp_rmaker_system_serv_flag_t; at least one required

uint8_t reboot_seconds

Reboot delay (s); passed to esp_rmaker_system_ctrl_reboot

uint8_t reset_seconds

Network/factory reset delay (s)

int8_t reset_reboot_seconds

Reboot delay (s) after reset; negative means no reboot

esp_rmaker_system_ctrl_network_reset_fn_t network_reset_fn

Network credentials reset fn; required (non-NULL) if NETWORK_RESET or FACTORY_RESET flag is set

Macros

RMAKER_STANDARD_SERVICE_COUNT
SYSTEM_SERV_FLAGS_ALL

All System service flags.

Type Definitions

typedef esp_rmaker_error_t (*esp_rmaker_standard_service_disable_func)(void)

Standard service disable function type

Enumerations

enum esp_rmaker_system_serv_flag_t

System service flags. Selects which params the System service exposes.

Values:

enumerator SYSTEM_SERV_FLAG_REBOOT
enumerator SYSTEM_SERV_FLAG_NETWORK_RESET
enumerator SYSTEM_SERV_FLAG_FACTORY_RESET