RainMaker Core¶
Core¶
Header File¶
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.
Structures¶
-
struct
esp_rmaker_node_info_t
¶ ESP RainMaker Node information
-
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
-
bool
-
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
-
esp_rmaker_val_type_t
-
struct
esp_rmaker_write_ctx_t
¶ Write request Context
Public Members
-
esp_rmaker_req_src_t
src
¶ Source of request
-
esp_rmaker_req_src_t
-
struct
esp_rmaker_read_ctx_t
¶ Read request context
Public Members
-
esp_rmaker_req_src_t
src
¶ Source of request
-
esp_rmaker_req_src_t
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¶
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¶
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.
-
char *
Type Definitions¶
-
typedef struct esp_rmaker_time_config
esp_rmaker_time_config_t
¶
Scheduling¶
Header File¶
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.