RainMaker Neo Core

The esp_rmaker_neo component: node lifecycle, event delivery and the host/local control surfaces.

Core

Header File

• components/esp_rmaker_neo/include/esp_rmaker_core.h

Flow

Header File

• components/esp_rmaker_neo/include/esp_rmaker_flow.h

Functions

esp_rmaker_error_t esp_rmaker_pre_prov_init(void)

Initialize ESP RainMaker Neo Pre-Provisioning.

This initializes components of the ESP RainMaker Neo SDK that are required before provisioning is initialized and started. Should be called as early as possible if provisioning is required.

Note

This function will be called automatically by esp_rmaker_node_init() if not done already.

Note

Calling it again after a successful call is a no-op that returns ESP_RMAKER_OK.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_pre_prov_deinit(void)

Deinitialize ESP RainMaker Neo Pre-Provisioning.

This deinitializes components of the ESP RainMaker Neo SDK that are no longer required after provisioning is initialized and started.

Note

This function will be called automatically by esp_rmaker_node_deinit() if not done already.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

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

Initialize ESP RainMaker Neo Node.

This initializes the ESP RainMaker Neo agent and creates the node. The model and firmware version for the node are set internally from the platform’s project name and version (see osal_sysinfo_get_project_name() / osal_sysinfo_get_fw_version()).

Note

This should be the first call before using any other ESP RainMaker Neo API, except esp_rmaker_pre_prov_init()/esp_rmaker_pre_prov_deinit().

Parameters:

• config – [in] Configuration to be used by the SDK. See ESP_RMAKER_DEFAULT_CONFIG.

• name – [in] Name of the node.

• type – [in] Type of the node.

Returns:

Node handle on success.

Returns:

NULL in case of failure.

esp_rmaker_error_t esp_rmaker_node_deinit(const esp_rmaker_node_t *node)

Deinitialize ESP RainMaker Neo Node.

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

Note

The SDK must not be running. If a esp_rmaker_stop() is still in flight, this call blocks until the stop completes; if the SDK is started or starting, it returns ESP_RMAKER_INVALID_STATE.

Parameters:

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

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_start(void)

Start the SDK.

This queues the start work and returns as soon as the work queue is running; the steps below then run asynchronously:

• Waits for time synchronization (blocking or decoupled, depending on the build).

• Loads the schedule and automation state from NVS.

• Waits for network connectivity, then connects to the MQTT broker.

• Subscribes to the cloud topic and fetches cloud information (group information, whether Alexa is enabled, etc.).

• Publishes the node configuration, if required.

RMAKER_EVENT_CORE_STARTED is posted once all of the above has completed.

Note

Network connectivity is not required for this call to succeed: the start work waits for it. A working connection is required for the node to come online.

Note

This function must be called after esp_rmaker_node_init().

Returns:

ESP_RMAKER_OK on success, or if the SDK is already started.

Returns:

ESP_RMAKER_INVALID_STATE if the SDK is not initialized.

Returns:

error code in case of failure.

esp_rmaker_error_t esp_rmaker_stop(void)

Stop the SDK.

Like esp_rmaker_start(), this queues the work and returns immediately. The queued work stops the pending retries, unsubscribes from all topics and disconnects from the MQTT broker.

Note

This function must be called before esp_rmaker_node_deinit().

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_INVALID_STATE if the SDK is not started.

Structures

struct esp_rmaker_config_t

Configuration for the ESP RainMaker Neo SDK.

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 Neo service

Macros

ESP_RMAKER_DEFAULT_CONFIG

Default configuration for the ESP RainMaker Neo SDK.

When CONFIG_RMNG_CUSTOM_MQTT_CLIENT_PROVIDER is set, override mqtt_setup_fn in your application code.

Node

Header File

• components/esp_rmaker_neo/include/esp_rmaker_node.h

Functions

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

Returns:

Node handle on success.

Returns:

NULL in case of failure.

char *esp_rmaker_get_node_id(void)

Get the node ID (synonymous with AWS Thing Name / MQTT client ID)

This API returns the node ID (synonymous with AWS Thing Name / MQTT client ID)

Returns:

Node ID on success. If not NULL, the caller must free the returned string using free().

Returns:

NULL in case of failure.

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.

Parameters:

node – [in] Node handle.

Returns:

Pointer to the node info on success.

Returns:

NULL in case of failure.

esp_rmaker_error_t esp_rmaker_node_fill_with_info(const esp_rmaker_node_t *node, const esp_rmaker_node_info_t *info)

Populate a freshly initialised node with the supplied info.

Allocates node->info and duplicates each of the four fields (name / type / fw_version / model) from info. Reserved tags (name, type, fw_version, model) are automatically added/updated to mirror the info.

Used for child nodes created by the bridge: the caller passes a stack esp_rmaker_node_info_t describing the child. The self node is normally filled via a higher-level internal create API.

Fails with ESP_RMAKER_INVALID_STATE if the node already has info allocated (e.g., this function has already been called once for that node).

Parameters:

• node – [in] Node handle.

• info – [in] Source info struct. The struct itself is not retained.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_report_node_config(void)

Report the node configuration to the cloud (self Thing).

Builds the self-ctx slice of the node config, hashes it, and publishes setNodeConfig only if the checksum differs from the value persisted in NVS. For the per-child counterpart see esp_rmaker_report_node_config_for_child().

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

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

Parameters:

• node – [in] Node handle.

• attr_name – [in] Name of the attribute.

• val – [in] Value for the attribute.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_node_add_tag(const esp_rmaker_node_t *node, const char *tag_name, const char *tag_value)

Add a tag to a node.

Note

Tags are reported to the indexed shadow to facilitate searching.

Note

If the tag already exists, its value will be overwritten.

Note

The tag value is not reported to the cloud. If you require simultaneous adding and reporting, use esp_rmaker_node_update_tag().

Parameters:

• node – [in] Node handle.

• tag_name – [in] Name of the tag. The reserved names name, type, fw_version and model are rejected; they mirror esp_rmaker_node_info_t and are maintained by the SDK.

• tag_value – [in] Value of the tag.

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_INVALID_ARG if the tag name is reserved, or if any argument is NULL.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_node_update_tag(const esp_rmaker_node_t *node, const char *tag_name, const char *tag_value)

Update a tag of a node.

Note

Tags are reported to the indexed shadow to facilitate searching.

Note

The tag value is reported to the cloud. If the tag already exists with the same value, nothing is reported.

Parameters:

• node – [in] Node handle.

• tag_name – [in] Name of the tag. The reserved names name, type, fw_version and model are rejected; they mirror esp_rmaker_node_info_t and are maintained by the SDK.

• tag_value – [in] Value of the tag.

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_INVALID_ARG if the tag name is reserved, or if any argument is NULL.

Returns:

error in case of failure.

Structures

struct esp_rmaker_node_info_t

ESP RainMaker Neo Node information.

Public Members

char *name

Name of the Node

char *type

Type of the Node

char *fw_version

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

char *model

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

struct esp_rmaker_attr

ESP RainMaker Neo Attribute.

Public Members

char *name

Name of the Attribute

char *value

Value of the Attribute

struct esp_rmaker_attr *next

Next attribute

struct esp_rmaker_tag

ESP RainMaker Neo tag.

Public Members

char *name

Name of the tag

char *value

Value of the tag

struct esp_rmaker_tag *next

Next tag

uint8_t flags

Flags

Type Definitions

typedef struct esp_rmaker_attr esp_rmaker_attr_t

ESP RainMaker Neo attribute

typedef struct esp_rmaker_tag esp_rmaker_tag_t

ESP RainMaker Neo tag

typedef esp_rmaker_handle_t esp_rmaker_node_t

ESP RainMaker Neo Node Handle

Enumerations

enum esp_rmaker_signal_flags_t

Signal flags

Values:

enumerator RMAKER_SIGNAL_FLAG_VALUE_CHANGE

enumerator RMAKER_SIGNAL_FLAG_VALUE_NOTIFY

enumerator RMAKER_SIGNAL_FLAG_VALUE_ALL

State

Header File

• components/esp_rmaker_neo/include/esp_rmaker_state.h

Functions

const char *esp_rmaker_req_src_to_string(esp_rmaker_req_src_t src)

Convert a request source to a string.

Parameters:

src – [in] Request source.

Returns:

String representation of the request source.

esp_rmaker_error_t esp_rmaker_state_mark_for_update(esp_rmaker_state_update_id_t update_id)

Mark an update ID for update.

Evaluates any automation triggers registered for the change, adds it to the pending-report list and schedules a (delayed) report to the cloud.

Note

Ownership of update_id transfers to the SDK. The caller must not dereference or free it after this call.

Parameters:

update_id – [in] Update ID.

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_INVALID_ARG if update_id is NULL.

Returns:

error code in case of failure.

Type Definitions

typedef void *esp_rmaker_state_update_id_t

ESP RainMaker Neo Update ID.

Opaque handle identifying one pending state change (one parameter of one node). Created by the data model, not by application code.

Enumerations

enum esp_rmaker_req_src_t

Parameter read/write request source

Values:

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

enumerator ESP_RMAKER_REQ_SRC_CLOUD

Request received from cloud

enumerator ESP_RMAKER_REQ_SRC_SCHEDULE

Request received when a schedule has triggered

enumerator ESP_RMAKER_REQ_SRC_SCENE_ACTIVATE

Request received when a scene has been activated

enumerator ESP_RMAKER_REQ_SRC_SCENE_DEACTIVATE

Request received when a scene has been deactivated

enumerator ESP_RMAKER_REQ_SRC_LOCAL

Request received from a local controller

enumerator ESP_RMAKER_REQ_SRC_FIRMWARE

Request initiated from firmware/console commands

enumerator ESP_RMAKER_REQ_SRC_MAX

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

Event Loop

Header File

• components/esp_rmaker_neo/include/esp_rmaker_event_loop.h

Enumerations

enum esp_rmaker_event_t

Event loop base event.

Events posted on the RMAKER_EVENT base.

Values:

enumerator RMAKER_EVENT_BASE_ANY

Wildcard: register a handler with this id to receive every RMAKER_EVENT.

enumerator RMAKER_EVENT_INIT_DONE

Core initialized. Event data will be NULL.

enumerator RMAKER_EVENT_CORE_STARTED

Core started. Event data will be NULL.

enumerator RMAKER_EVENT_LOCAL_CTRL_STARTED

Local control started. Event data will contain the service name.

enumerator RMAKER_EVENT_LOCAL_CTRL_STOPPED

Local control stopped. No event data will be provided.

enumerator RMAKER_EVENT_BRIDGE_CHILD_ADDED

A bridged child Thing has been created on the cloud and is ready to use. Event data: esp_rmaker_event_bridge_child_added_t * (see esp_rmaker_bridge.h).

enumerator RMAKER_EVENT_BRIDGE_CHILD_REMOVED

A bridged child Thing has been removed from the cloud. Event data: esp_rmaker_event_bridge_child_removed_t *.

enumerator RMAKER_EVENT_BRIDGE_CHILD_ADD_FAILED

Add-child cloud request failed (error response or timeout). Event data: esp_rmaker_event_bridge_child_failed_t *.

enumerator RMAKER_EVENT_BRIDGE_CHILD_REMOVE_FAILED

Remove-child cloud request failed (error response or timeout). Event data: esp_rmaker_event_bridge_child_failed_t *.

enumerator RMAKER_EVENT_BRIDGE_CHILD_GROUP_INFO_UPDATED

A bridged child’s group / subgroup info has been updated from the cloud. Event data: esp_rmaker_event_bridge_child_group_info_t *.

enumerator RMAKER_EVENT_CLAIM_STARTED

Claiming has started. Only posted when claiming is enabled and the node is not already claimed. Event data will be NULL.

enumerator RMAKER_EVENT_CLAIM_SUCCESSFUL

Claiming was successful; the certificate and node ID have been persisted. Event data will be NULL.

enumerator RMAKER_EVENT_CLAIM_FAILED

Claiming failed, or was aborted by the phone app. Event data will be NULL.

System Control

Header File

• components/esp_rmaker_neo/include/esp_rmaker_system_ctrl.h

Functions

esp_rmaker_error_t esp_rmaker_system_ctrl_reboot(uint8_t timeout_s)

Reboot the system after a given timeout.

Parameters:

timeout_s – [in] The timeout in seconds. 0 reboots immediately, from the calling context.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_system_ctrl_register_network_reset_fn(esp_rmaker_system_ctrl_network_reset_fn_t network_reset_fn)

Register a default network-credential reset function.

Once registered, esp_rmaker_system_ctrl_network_reset() and esp_rmaker_system_ctrl_factory_reset() may be called with a NULL network_reset_fn to fall back to this registered function. This lets generic callers (e.g. the serial console’s reset-network command) trigger a network reset without knowing the application-specific reset routine.

Parameters:

network_reset_fn – [in] Function to reset the network credentials. NULL clears the registration.

Returns:

ESP_RMAKER_OK on success.

esp_rmaker_error_t esp_rmaker_system_ctrl_data_reset(uint8_t reset_s, int8_t reset_reboot_s)

Reset only the RainMaker Neo data namespaces after a given timeout.

Clears the NVS namespaces owned by RainMaker Neo without erasing the entire NVS partition or touching the network credentials.

Parameters:

• reset_s – [in] The timeout in seconds to perform the data reset. 0 means perform it synchronously, with no timeout.

• reset_reboot_s – [in] The timeout in seconds to reboot the system after the data reset. 0 means reboot immediately; a negative value means do not reboot.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_system_ctrl_network_reset(uint8_t reset_s, int8_t reset_reboot_s, esp_rmaker_system_ctrl_network_reset_fn_t network_reset_fn)

Reset the network credentials after a given timeout, using the provided function.

The SDK has no notion of the underlying network (Wi-Fi, Thread, …): clearing the credentials is entirely up to network_reset_fn.

Parameters:

• reset_s – [in] The timeout in seconds to reset the network credentials. 0 means reset synchronously, with no timeout.

• reset_reboot_s – [in] The timeout in seconds to reboot the system after resetting the network credentials. 0 means reboot immediately; a negative value means do not reboot.

• network_reset_fn – [in] Function to reset the network credentials. NULL means use the function registered via esp_rmaker_system_ctrl_register_network_reset_fn().

Returns:

ESP_RMAKER_OK on success, ESP_RMAKER_INVALID_ARG if network_reset_fn is NULL and no reset function has been registered, otherwise error code.

esp_rmaker_error_t esp_rmaker_system_ctrl_factory_reset(uint8_t reset_s, int8_t reset_reboot_s, esp_rmaker_system_ctrl_network_reset_fn_t network_reset_fn)

Factory reset the system after a given timeout.

This does both of the following:

• Clears the NVS namespaces owned by RainMaker Neo, in the same way as esp_rmaker_system_ctrl_data_reset() does.

• Resets the network credentials using the provided function.

Parameters:

• reset_s – [in] The timeout in seconds to factory reset the system. 0 means reset synchronously, with no timeout.

• reset_reboot_s – [in] The timeout in seconds to reboot the system after factory reset. 0 means reboot immediately; a negative value means do not reboot.

• network_reset_fn – [in] Function to reset the network credentials. NULL means use the function registered via esp_rmaker_system_ctrl_register_network_reset_fn().

Returns:

ESP_RMAKER_OK on success, ESP_RMAKER_INVALID_ARG if network_reset_fn is NULL and no reset function has been registered, otherwise error code.

Type Definitions

typedef esp_rmaker_error_t (*esp_rmaker_system_ctrl_network_reset_fn_t)(void)

Function to reset the network credentials.

Console

Header File

• components/esp_rmaker_neo/include/esp_rmaker_console.h

Functions

esp_rmaker_error_t esp_rmaker_console_init(void)

Initialize the RainMaker Neo serial console.

Sets up the serial console (REPL) and registers both the common commands (from the rmaker_console component) and the RainMaker Neo SDK built-in commands (e.g. get-node-id, node-info). This is the single entry point an application needs; call it early in app_main()/main().

Works identically on ESP-IDF and POSIX: on ESP-IDF the console is backed by the IDF esp_console component, on POSIX by the esp_console-posix shim (a stdin REPL).

This entry point is always linkable. When the console is disabled (CONFIG_RMNG_CONSOLE_ENABLED=n) it logs a warning and returns ESP_RMAKER_OK without starting anything, so callers need not guard the call.

Note

If the application initializes the console itself, call esp_rmaker_register_commands() instead to register only the RainMaker Neo built-in commands. Unlike this function, esp_rmaker_register_commands() is only available when CONFIG_RMNG_CONSOLE_ENABLED=y.

Returns:

ESP_RMAKER_OK on success, or an error code on failure.

Credentials Access

Header File

• components/esp_rmaker_neo/include/esp_rmaker_credentials_access.h

Functions

esp_rmaker_error_t esp_rmaker_credentials_provider_override(const esp_rmaker_credentials_providers_t *p_credentials_providers)

Override some/all of the credentials providers. By default, the credentials are read from the factory partition.

Note

This function should be called before ANY initialization functions are called for the overrides to take effect:

• esp_rmaker_pre_prov_init()

• esp_rmaker_node_init()

Parameters:

p_credentials_providers – [in] The credentials providers. Set a provider to NULL to use the default credentials provider for that provider.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

Local Configuration Targets

Header File

• components/esp_rmaker_neo/include/esp_rmaker_local_config_targets.h

Structures

struct esp_rmaker_local_config_binary_t

Bounds of a binary blob embedded in the firmware image

Public Members

const uint8_t *start

First byte of the blob

const uint8_t *end

One past the last byte of the blob

Version

esp_rmaker_version.h gives an application the SDK version it is building against. It is on the esp_rmaker_neo include path but is not in the repository: CMake renders it into the build tree from components/esp_rmaker_neo/include/versioning/esp_rmaker_version.h.in, using the numbers in components/esp_rmaker_neo/versioning.cmake.

Macro	Meaning
ESP_RMAKER_VERSION_MAJOR	Major version, an integer.
ESP_RMAKER_VERSION_MINOR	Minor version, an integer.
ESP_RMAKER_VERSION_PATCH	Patch version, an integer.
ESP_RMAKER_VERSION_TYPE	Build-type suffix. Empty when HEAD is tagged for exactly this version; otherwise -<git short SHA>. A * is appended when the worktree is dirty.
ESP_RMAKER_VERSION_STR	The four above joined as "<major>.<minor>.<patch><type>", e.g. "0.8.0" for a release build or "0.8.0-0ccdca3*" from a dirty working tree. esp_rmaker_node_init() logs this at startup.

Because the header is generated, it carries no Doxygen documentation of its own. Version-gate on the integers rather than parsing the string:

#if ESP_RMAKER_VERSION_MAJOR > 0 || ESP_RMAKER_VERSION_MINOR >= 3
/* API added in 0.3 */
#endif