RainMaker Neo Common

The esp_rmaker_neo_common component: shared events, credentials, the MQTT glue interface, the work queue and assorted utilities.

Common Events

Header File

Enumerations

enum esp_rmaker_common_event_t

Event loop base event.

Events posted on the RMAKER_COMMON_EVENT base.

Values:

enumerator RMAKER_COMMON_EVENT_BASE_ANY

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

enumerator RMAKER_EVENT_REBOOT

System service reboot. Event data will contain the seconds after which the system will reboot.

enumerator RMAKER_EVENT_NETWORK_RESET

System service network reset. No event data will be provided.

enumerator RMAKER_EVENT_FACTORY_RESET

System service factory reset. No event data will be provided.

enumerator RMAKER_MQTT_EVENT_CONNECTED

MQTT connected. Event data will be NULL.

enumerator RMAKER_MQTT_EVENT_DISCONNECTED

MQTT disconnected. Event data will be NULL.

enumerator RMAKER_MQTT_EVENT_PUBLISHED

MQTT message published successfully. Event data is a pointer to a osal_mqtt_event_loop_data_on_complete_t.

enumerator RMAKER_MQTT_EVENT_SUBSCRIBED

MQTT message subscribed successfully. Event data is a pointer to a osal_mqtt_event_loop_data_on_complete_t.

enumerator RMAKER_MQTT_EVENT_UNSUBSCRIBED

MQTT message unsubscribed successfully. Event data is a pointer to a osal_mqtt_event_loop_data_on_complete_t.

enumerator RMAKER_EVENT_TZ_POSIX_CHANGED

POSIX Timezone Changed. Eg. “PST8PDT,M3.2.0,M11.1.0” Event data will contain the NULL terminated POSIX timezone (string).

enumerator RMAKER_EVENT_TZ_CHANGED

Timezone Changed. Eg. “America/Los_Angeles” Note that whenever this event is received, the RMAKER_EVENT_TZ_POSIX_CHANGED event will also be received, but not necessarily vice versa. Event data will contain the NULL terminated Timezone (string).

Error Types

Header File

Macros

ESP_RMAKER_OK
ESP_RMAKER_FAIL
ESP_RMAKER_TIMEOUT
ESP_RMAKER_INVALID_STATE
ESP_RMAKER_NO_MEM
ESP_RMAKER_INVALID_ARG
ESP_RMAKER_NOT_SUPPORTED
ESP_RMAKER_NOT_FOUND
ESP_RMAKER_NOT_INITIALIZED
ESP_RMAKER_ALREADY_INITIALIZED
ESP_RMAKER_NOT_CONNECTED
ESP_RMAKER_ALREADY_CONNECTED
ESP_RMAKER_NOT_DISCONNECTED
ESP_RMAKER_ALREADY_EXISTS

Type Definitions

typedef osal_err_t esp_rmaker_error_t

ESP RainMaker Neo error type. Alias of the portable OSAL error type.

Credentials

Header File

Functions

esp_rmaker_error_t esp_rmaker_credentials_set_client_key(const uint8_t *client_key, size_t client_key_len)

Store the client private key.

Parameters:

  • client_key – [in] The key, typically PEM.

  • client_key_len – [in] Length in bytes, excluding any NUL terminator.

Returns:

ESP_RMAKER_OK on success, otherwise an error code.

esp_rmaker_error_t esp_rmaker_credentials_set_client_cert(const uint8_t *client_cert, size_t client_cert_len)

Store the client certificate.

Parameters:

  • client_cert – [in] The certificate, typically PEM.

  • client_cert_len – [in] Length in bytes, excluding any NUL terminator.

Returns:

ESP_RMAKER_OK on success, otherwise an error code.

esp_rmaker_error_t esp_rmaker_credentials_set_client_id(const char *client_id)

Store the client ID (node ID).

Parameters:

client_id – [in] The NUL-terminated client ID.

Returns:

ESP_RMAKER_OK on success, otherwise an error code.

esp_rmaker_error_t esp_rmaker_credentials_set_mqtt_host(const char *mqtt_host)

Store the MQTT host.

Parameters:

mqtt_host – [in] The NUL-terminated MQTT host.

Returns:

ESP_RMAKER_OK on success, otherwise an error code.

esp_rmaker_error_t esp_rmaker_credentials_set_random(const uint8_t *random, size_t random_len)

Store the general-purpose random bytes.

Parameters:

  • random – [in] The random bytes.

  • random_len – [in] Length of the random bytes.

Returns:

ESP_RMAKER_OK on success, otherwise an error code.

esp_rmaker_error_t esp_rmaker_credentials_erase_claim_data(void)

Erase the credentials that claiming writes, so the node claims again.

Removes the node ID, client certificate, private key and MQTT host, and nothing else. A claimed node claims again from scratch on the next boot; a node whose credentials were pre-flashed will need them re-flashed.

Returns:

ESP_RMAKER_OK on success, otherwise an error code.

esp_rmaker_error_t esp_rmaker_credentials_override(const esp_rmaker_credentials_providers_t *p_provider_overrides)

Override some/all of the credentials providers.

By default, the credentials are read from the factory partition. If provider overrides are provided, the credentials will be read from the overrides.

Parameters:

p_provider_overrides – [in] The provider overrides. You can partially override by setting the only the required provider overrides to non-NULL values.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_credentials_reset_to_default(void)

Reset the credentials to the default providers.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_credentials_get_mqtt_conn_params(osal_mqtt_conn_params_t **p_mqtt_conn_params)

Get the MQTT connection parameters.

Parameters:

p_mqtt_conn_params – [out] The MQTT connection parameters.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_credentials_free_mqtt_conn_params(osal_mqtt_conn_params_t *p_mqtt_conn_params)

Free the MQTT connection parameters.

Parameters:

p_mqtt_conn_params – [in] The MQTT connection parameters.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_credentials_get_private_key(esp_rmaker_credential_t *p_private_key)

Get the private key.

Parameters:

p_private_key – [out] The private key.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_credentials_get_thing_name(char **p_thing_name)

Get the thing name.

Parameters:

p_thing_name – [out] The thing name. Must be freed by the caller if not NULL.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_credentials_get_codesign_cert(esp_rmaker_credential_t *p_codesign_cert)

Get the codesign certificate.

Parameters:

p_codesign_cert – [out] The codesign certificate. Must be freed by the caller if not NULL.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_credentials_get_mqtt_host(char **p_mqtt_host)

Get the MQTT host.

Parameters:

p_mqtt_host – [out] The MQTT host. Must be freed by the caller on success.

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_NOT_FOUND if no MQTT host is stored.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_credentials_get_client_cert(esp_rmaker_credential_t *p_client_cert)

Get the client certificate.

Mainly useful as an “is this node provisioned with cloud credentials” check: claiming uses the presence of a certificate to decide whether it has anything to do.

Parameters:

p_client_cert – [out] The certificate. Must be freed by the caller on success with esp_rmaker_credentials_free_credential.

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_NOT_FOUND if no certificate is stored.

Returns:

error in case of failure.

esp_rmaker_error_t esp_rmaker_credentials_get_random(esp_rmaker_credential_t *p_random)

Get the random value as a hex string.

Parameters:

p_random – [out] The random value. Must be freed by the caller if not NULL.

Returns:

ESP_RMAKER_OK on success.

Returns:

error in case of failure.

Header File

Functions

void esp_rmaker_credentials_free_credential(esp_rmaker_credential_t *p_credential)

Free a credential.

Parameters:

p_credential – [in] The credential.

Structures

struct esp_rmaker_credential_t

Credentials.

struct esp_rmaker_credentials_providers_t

Set of credential providers, one per credential the SDK needs

Public Members

esp_rmaker_credentials_provider_string_t mqtt_host

MQTT host

esp_rmaker_credentials_provider_credential_t client_cert

Client certificate, only the following formats are supported:

  • PEM

  • ASN.1 DER

esp_rmaker_credentials_provider_credential_t client_key

Client key, only the following formats are supported:

  • PEM

  • ASN.1 DER

  • NIST P-256 raw 32 bytes big-endian only

esp_rmaker_credentials_provider_string_t client_id

Client ID

esp_rmaker_credentials_provider_string_t client_username

Client username

esp_rmaker_credentials_provider_string_t client_password

Client password

esp_rmaker_credentials_provider_credential_t random

Random

esp_rmaker_credentials_provider_credential_t codesign_cert

Codesign certificate, only the following formats are supported:

  • PEM

  • ASN.1 DER

Type Definitions

typedef esp_rmaker_error_t (*esp_rmaker_credentials_provider_credential_t)(esp_rmaker_credential_t *p_credential)

Provider to get a credential.

Credential contents should be dynamically allocated and freed later on with esp_rmaker_credentials_free_credential().

Param p_credential:

[out] The credentials.

Return:

ESP_RMAKER_OK on success.

Return:

error in case of failure.

typedef esp_rmaker_error_t (*esp_rmaker_credentials_provider_string_t)(char **p_str)

Provider to get a string.

String should be dynamically allocated and freed later on with free().

Param p_str:

[out] The string.

Return:

ESP_RMAKER_OK on success.

Return:

error in case of failure.

Factory Partition

Header File

Functions

esp_rmaker_error_t esp_rmaker_factory_part_init(void)

Initialize the factory partition.

Returns:

ESP_RMAKER_OK on success, otherwise an error code

esp_rmaker_error_t esp_rmaker_factory_part_deinit(void)

Deinitialize the factory partition.

Returns:

ESP_RMAKER_OK on success, otherwise an error code

MQTT Glue

Header File

Header File

Enumerations

enum mqtt_channel_main_t

Main channels for all components.

Put here so that all components that depend on this component can avoid redefining the same values.

Values:

enumerator MQTT_CHANNEL_MAIN_STATE_CHANGES
enumerator MQTT_CHANNEL_MAIN_CLOUD_MANAGER
enumerator MQTT_CHANNEL_MAIN_SHADOWS
enumerator MQTT_CHANNEL_MAIN_NOTIFY
enumerator MQTT_CHANNEL_MAIN_BRIDGE
enumerator MQTT_CHANNEL_MAIN_OTA

Runtime Gate

Header File

Functions

void esp_rmaker_runtime_gate_set_active(bool active)

Set the runtime gate active state.

Parameters:

active – [in] true when the SDK is fully started and operational; false when stopping/stopped/resetting.

bool esp_rmaker_should_do_work(void)

Query whether deferrable work should run.

Non-blocking; callable from any task or MQTT callback context.

Returns:

true if the SDK is operational and deferrable work may proceed.

Returns:

false if stopping/stopped/resetting; callers must drop the work.

Work Queue

Header File

Functions

esp_rmaker_error_t esp_rmaker_work_queue_init(void)

Initializes the Work Queue.

This initializes the work queue, which is basically a mechanism to run tasks in the context of a dedicated thread. You can start queueing tasks after this, but they will get executed only after calling esp_rmaker_work_queue_start().

Returns:

ESP_RMAKER_OK on success.

Returns:

error on failure.

esp_rmaker_error_t esp_rmaker_work_queue_deinit(void)

De-initialize the Work Queue.

This de-initializes the work queue. Note that the work queue needs to be stopped using esp_rmaker_work_queue_stop() before calling this.

Returns:

ESP_RMAKER_OK on success.

Returns:

error on failure.

esp_rmaker_error_t esp_rmaker_work_queue_start(void)

Start the Work Queue.

This starts the Work Queue thread which then starts executing the tasks queued.

Returns:

ESP_RMAKER_OK on success.

Returns:

error on failure.

esp_rmaker_error_t esp_rmaker_work_queue_stop(void)

Stop the Work Queue.

This stops a running Work Queue.

Returns:

ESP_RMAKER_OK on success.

Returns:

error on failure.

esp_rmaker_error_t esp_rmaker_work_queue_add_task(esp_rmaker_work_fn_t work_fn, void *priv_data)

Queue execution of a function in the Work Queue’s context.

This API queues a work function for execution in the Work Queue Task’s context.

Parameters:

  • work_fn – [in] The Work function to be queued.

  • priv_data – [in] Private data to be passed to the work function.

Returns:

ESP_RMAKER_OK on success.

Returns:

error on failure.

Type Definitions

typedef void (*esp_rmaker_work_fn_t)(void *priv_data)

Prototype for ESP RainMaker Neo Work Queue Function.

Param priv_data:

[in] The private data associated with the work function.

Retry / Backoff

Header File

Functions

void esp_rmaker_backoff_reset(esp_rmaker_backoff_retry_context_t *p_retry_context, uint64_t delay_ms)

Reset the backoff retry.

  • Cancels any scheduled retries.

  • Resets the delay to the initial base delay.

Parameters:

  • p_retry_context – [inout] The context for the backoff function.

  • delay_ms – [in] The delay in milliseconds.

esp_rmaker_error_t esp_rmaker_backoff_retry(esp_rmaker_backoff_retry_context_t *p_retry_context, osal_scheduler_task_t task, void *arg)

Retry a task with backoff.

The task is scheduled with the next delay with jitter.

Parameters:

  • p_retry_context – [inout] The context for the backoff function. The scheduled task handle and the current delay are updated in place.

  • task – [in] The task to schedule.

  • arg – [in] The argument to pass to the task.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_backoff_fire(esp_rmaker_backoff_retry_context_t *p_retry_context, osal_scheduler_task_t task, void *arg)

Schedule a task immediately with the current next delay (no jitter).

The delay is not incremented.

Parameters:

  • p_retry_context – [inout] The context for the backoff function. The scheduled task handle is updated in place.

  • task – [in] The task to schedule.

  • arg – [in] The argument to pass to the task.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

Structures

struct esp_rmaker_backoff_delay_context_t

Context for the backoff delay calculation.

Public Members

uint64_t current

The current delay in milliseconds. Should be set to the initial base delay.

uint64_t max

The maximum delay in milliseconds.

struct esp_rmaker_backoff_delay_context_t delay_ms

Delay in milliseconds.

The delay in milliseconds.

uint8_t exp_factor

The exponential factor to use for the backoff.

uint16_t max_jitter_ms

The maximum jitter in milliseconds.

struct esp_rmaker_backoff_delay_context_t params

Parameters for the backoff.

The parameters for the backoff.

struct esp_rmaker_backoff_retry_context_t

Context of a scheduled backoff retry

Public Members

osal_scheduler_task_handle_t handle

The handle for the scheduled task

esp_rmaker_backoff_delay_context_t delay_ctx

The backoff delay context for the retry algorithm

Macros

ESP_RMAKER_BACKOFF_DEFAULT_RETRY_CONTEXT()

Default-initialised esp_rmaker_backoff_retry_context_t compound literal.

No scheduled task, a 1 s base delay capped at 5 minutes, doubling each retry, with up to 1 s of jitter.

NVS

Header File

Functions

esp_rmaker_error_t esp_rmaker_load_nvs_handle(const char *partition_name, const char *name_space, osal_storage_handle_t *p_nvs_handle)

Load an NVS handle.

Parameters:

  • partition_name – [in] The name of the partition to load

  • name_space – [in] The namespace to load

  • p_nvs_handle – [out] The handle to the NVS partition

Returns:

ESP_RMAKER_OK on success, otherwise error code

esp_rmaker_error_t esp_rmaker_clear_nvs_namespace(const char *partition_name, const char *name_space)

Clear an NVS namespace.

Parameters:

  • partition_name – [in] The name of the partition to clear

  • name_space – [in] The namespace to clear

Returns:

ESP_RMAKER_OK on success, otherwise error code

esp_rmaker_error_t esp_rmaker_nvs_update_bool_with_handle(osal_storage_handle_t nvs_handle, const char *key, bool value)

Update a bool value in NVS with a handle.

Parameters:

  • nvs_handle – [in] The handle to the NVS partition.

  • key – [in] The key to update.

  • value – [in] The bool value to update.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_update_bool(const char *partition_name, const char *name_space, const char *key, bool value)

Update a bool value in NVS.

Parameters:

  • partition_name – [in] The name of the partition to update.

  • name_space – [in] The namespace to update.

  • key – [in] The key to update.

  • value – [in] The bool value to update.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_get_bool_with_handle(osal_storage_handle_t nvs_handle, const char *key, bool *value)

Get a bool value from NVS with a handle.

Parameters:

  • nvs_handle – [in] The handle to the NVS partition.

  • key – [in] The key to get.

  • value – [out] The bool value to get.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_get_bool(const char *partition_name, const char *name_space, const char *key, bool *value)

Get a bool value from NVS.

Parameters:

  • partition_name – [in] The name of the partition to get.

  • name_space – [in] The namespace to get.

  • key – [in] The key to get.

  • value – [out] The bool value to get.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_update_u16_with_handle(osal_storage_handle_t nvs_handle, const char *key, uint16_t value)

Update a uint16_t value in NVS with a handle.

Parameters:

  • nvs_handle – [in] The handle to the NVS partition.

  • key – [in] The key to update.

  • value – [in] The uint16_t value to update.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_update_u16(const char *partition_name, const char *name_space, const char *key, uint16_t value)

Update a uint16_t value in NVS.

Parameters:

  • partition_name – [in] The name of the partition to update.

  • name_space – [in] The namespace to update.

  • key – [in] The key to update.

  • value – [in] The uint16_t value to update.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_get_u16_with_handle(osal_storage_handle_t nvs_handle, const char *key, uint16_t *value)

Get a uint16_t value from NVS with a handle.

Parameters:

  • nvs_handle – [in] The handle to the NVS partition.

  • key – [in] The key to get.

  • value – [out] The uint16_t value to get.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_get_u16(const char *partition_name, const char *name_space, const char *key, uint16_t *value)

Get a uint16_t value from NVS.

Parameters:

  • partition_name – [in] The name of the partition to get.

  • name_space – [in] The namespace to get.

  • key – [in] The key to get.

  • value – [out] The uint16_t value to get.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_update_int_with_handle(osal_storage_handle_t nvs_handle, const char *key, int value)

Update an int value in NVS with a handle.

Parameters:

  • nvs_handle – [in] The handle to the NVS partition.

  • key – [in] The key to update.

  • value – [in] The int value to update.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_update_int(const char *partition_name, const char *name_space, const char *key, int value)

Update an int value in NVS.

Parameters:

  • partition_name – [in] The name of the partition to update.

  • name_space – [in] The namespace to update.

  • key – [in] The key to update.

  • value – [in] The int value to update.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_get_int_with_handle(osal_storage_handle_t nvs_handle, const char *key, int *value)

Get an int value from NVS with a handle.

Parameters:

  • nvs_handle – [in] The handle to the NVS partition.

  • key – [in] The key to get.

  • value – [out] The int value to get.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_get_int(const char *partition_name, const char *name_space, const char *key, int *value)

Get an int value from NVS.

Parameters:

  • partition_name – [in] The name of the partition to get.

  • name_space – [in] The namespace to get.

  • key – [in] The key to get.

  • value – [out] The int value to get.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

int esp_rmaker_nvs_get_int_default_with_handle(osal_storage_handle_t nvs_handle, const char *key, int default_value)

Get an int value from NVS with a default value with a handle.

Parameters:

  • nvs_handle – [in] The handle to the NVS partition.

  • key – [in] The key to get.

  • default_value – [in] The default value to return if the key is not found or if nvs_handle/key is NULL.

Returns:

The int value, or the default value if not found, if nvs_handle/key is NULL, or if NVS get fails.

int esp_rmaker_nvs_get_int_default(const char *partition_name, const char *name_space, const char *key, int default_value)

Get an int value from NVS with a default value.

Parameters:

  • partition_name – [in] The name of the partition to get.

  • name_space – [in] The namespace to get.

  • key – [in] The key to get.

  • default_value – [in] The default value to return if the key is not found.

Returns:

The int value, or the default value if not found.

esp_rmaker_error_t esp_rmaker_nvs_update_string_with_handle(osal_storage_handle_t nvs_handle, const char *key, const char *value)

Update a string value in NVS with a handle.

Parameters:

  • nvs_handle – [in] The handle to the NVS partition.

  • key – [in] The key to update.

  • value – [in] The string value to update.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_update_string(const char *partition_name, const char *name_space, const char *key, const char *value)

Update a string value in NVS.

Parameters:

  • partition_name – [in] The name of the partition to update.

  • name_space – [in] The namespace to update.

  • key – [in] The key to update.

  • value – [in] The string value to update.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

char *esp_rmaker_nvs_get_string_with_handle(osal_storage_handle_t nvs_handle, const char *key)

Get a string value from NVS with a handle.

Note

If not NULL, the caller must free the returned string.

Parameters:

  • nvs_handle – [in] The handle to the NVS partition.

  • key – [in] The key to get.

Returns:

The string value, or NULL if not found, if nvs_handle/key is NULL, if NVS get fails, or if memory allocation fails.

char *esp_rmaker_nvs_get_string(const char *partition_name, const char *name_space, const char *key)

Get a string value from NVS.

Parameters:

  • partition_name – [in] The name of the partition to get.

  • name_space – [in] The namespace to get.

  • key – [in] The key to get.

Returns:

The string value, or NULL if not found. If not NULL, the caller must free the data.

uint8_t *esp_rmaker_nvs_get_binary_with_handle(osal_storage_handle_t nvs_handle, const char *key, size_t *data_len)

Get a binary value from NVS with a handle.

Note

This will always allocate an extra byte for the NULL terminator, but returns the length of the actual data.

Parameters:

  • nvs_handle – [in] The handle to the NVS partition.

  • key – [in] The key to get.

  • data_len – [out] The length of the data read.

Returns:

The binary value, or NULL if not found. If not NULL, the caller must free the data.

uint8_t *esp_rmaker_nvs_get_binary(const char *partition_name, const char *name_space, const char *key, size_t *data_len)

Get a binary value from NVS.

Note

This will always allocate an extra byte for the NULL terminator, but returns the length of the actual data.

Parameters:

  • partition_name – [in] The name of the partition to get.

  • name_space – [in] The namespace to get.

  • key – [in] The key to get.

  • data_len – [out] The length of the data read.

Returns:

The binary value, or NULL if not found. If not NULL, the caller must free the data.

esp_rmaker_error_t esp_rmaker_nvs_update_binary_with_handle(osal_storage_handle_t nvs_handle, const char *key, const void *data, size_t data_len)

Update a binary value in NVS with a handle.

Unlike esp_rmaker_nvs_update_string this stores exactly data_len bytes verbatim, so the value may contain embedded NULs. Pairs with esp_rmaker_nvs_get_binary_with_handle. A zero-length blob is allowed (data may be NULL only when data_len is 0).

Parameters:

  • nvs_handle – [in] The handle to the NVS partition.

  • key – [in] The key to update.

  • data – [in] Pointer to the binary data.

  • data_len – [in] Length of the binary data.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

esp_rmaker_error_t esp_rmaker_nvs_update_binary(const char *partition_name, const char *name_space, const char *key, const void *data, size_t data_len)

Update a binary value in NVS.

Parameters:

  • partition_name – [in] The name of the partition to update.

  • name_space – [in] The namespace to update.

  • key – [in] The key to update.

  • data – [in] Pointer to the binary data.

  • data_len – [in] Length of the binary data.

Returns:

ESP_RMAKER_OK on success, otherwise error code.

Header File

Macros

RMAKER_NVS_PART_NAME

Crypto

Header File

Functions

bool esp_rmaker_crypto_is_key_supported_tls(const uint8_t *private_key, size_t private_key_len)

Check if the key is supported for encryption.

Parameters:

  • private_key – [in] The private key

  • private_key_len – [in] The length of the private key

Returns:

True if the key is supported, false otherwise

esp_rmaker_error_t esp_rmaker_crypto_gen_key_pem(esp_rmaker_crypto_key_type_t key_type, uint8_t **key_pem, size_t *key_pem_len)

Generate a new private key and return it PEM-encoded.

The key is generated via PSA and then serialised to PEM, so the result is usable anywhere a PEM private key is expected (TLS, esp_rmaker_crypto_sign_data, esp_rmaker_crypto_gen_csr_pem).

Note

This is slow. RSA-2048 generation in particular can take tens of seconds on ESP32, so call it from a task with a low priority and a large stack.

Parameters:

  • key_type – [in] The type of key to generate.

  • key_pem – [out] The PEM-encoded private key, NUL-terminated. Must be freed by the caller.

  • key_pem_len – [out] Length of the PEM buffer including the NUL terminator, matching the convention used by the factory-partition credential getters.

Returns:

ESP_RMAKER_OK on success, ESP_RMAKER_INVALID_ARG on invalid args, ESP_RMAKER_NO_MEM on allocation failure, ESP_RMAKER_FAIL otherwise.

esp_rmaker_error_t esp_rmaker_crypto_gen_csr_pem(const uint8_t *key_pem, size_t key_pem_len, const char *common_name, uint8_t **csr_pem, size_t *csr_pem_len)

Generate a PEM-encoded Certificate Signing Request for the given private key.

The CSR is signed with SHA-256 and carries a single subject attribute, CN=<common_name>.

Note

Generating a CSR needs a sizeable stack; do not call this from a thread with a small one (e.g. a protocomm endpoint handler).

Parameters:

  • key_pem – [in] PEM-encoded private key. key_pem_len must include the NUL terminator, as produced by esp_rmaker_crypto_gen_key_pem and by the factory-partition credential getters.

  • key_pem_len – [in] Length of key_pem including the NUL terminator.

  • common_name – [in] The Common Name to put in the CSR subject.

  • csr_pem – [out] The PEM-encoded CSR, NUL-terminated. Must be freed by the caller.

  • csr_pem_len – [out] Length of the CSR buffer including the NUL terminator.

Returns:

ESP_RMAKER_OK on success, ESP_RMAKER_INVALID_ARG on invalid args, ESP_RMAKER_NO_MEM on allocation failure, ESP_RMAKER_FAIL otherwise.

esp_rmaker_error_t esp_rmaker_crypto_get_key_type(const uint8_t *private_key, size_t private_key_len, esp_rmaker_crypto_key_type_t *p_key_type)

Determine the type of a private key.

Parameters:

  • private_key – [in] PEM- or DER-encoded private key. For PEM, private_key_len must include the NUL terminator.

  • private_key_len – [in] The length of the private key.

  • p_key_type – [out] The detected key type. Set to RMAKER_CRYPTO_KEY_TYPE_UNKNOWN if the key parses but is not one of the supported types.

Returns:

ESP_RMAKER_OK on success, ESP_RMAKER_INVALID_ARG on invalid args, ESP_RMAKER_INVALID_STATE if the key could not be parsed.

size_t esp_rmaker_crypto_csr_pem_max_len(esp_rmaker_crypto_key_type_t key_type)

Upper bound on the PEM CSR a given key type produces.

Includes the NUL and room for JSON newline escaping, so one buffer of this size holds the CSR both as written and as escaped. See RMAKER_CRYPTO_CSR_PEM_LEN_ECDSA_P256 and friends for where the numbers come from.

Parameters:

key_type – [in] The key type the CSR will be signed with.

Returns:

The buffer size to use, or RMAKER_CRYPTO_CSR_PEM_LEN_MAX for a key type this module does not recognise &#8212; a bound has to be returned either way, and the generator fails cleanly if even that is too small.

esp_rmaker_error_t esp_rmaker_crypto_gen_sha256(const uint8_t *data, size_t data_len, uint8_t hash[RMAKER_CRYPTO_SHA256_HASH_LEN])

Generate a SHA-256 hash of the given data.

Parameters:

  • data – [in] The data to hash.

  • data_len – [in] The length of the data to hash.

  • hash – [out] The hash to store the result in. Must be pre-allocated.

Returns:

ESP_RMAKER_OK on success, ESP_RMAKER_INVALID_ARG if the data is NULL, error code otherwise.

esp_rmaker_error_t esp_rmaker_crypto_sign_data(const uint8_t *private_key, size_t private_key_len, const uint8_t *data, size_t data_len, uint8_t **signature, size_t *signature_len)

Sign data using the given PEM-encoded private key (supports RSA and EC).

The data is hashed with SHA-256 and the resulting digest is signed using the algorithm appropriate for the key type. The signature format depends on the key:

  • RSA: raw signature, length equals the key size in bytes

  • EC (e.g., P-256): ASN.1 DER-encoded ECDSA signature (variable length)

Parameters:

  • private_key – [in] PEM-encoded private key string (null-terminated).

  • private_key_len – [in] Length of the private key in bytes.

  • data – [in] Data to sign.

  • data_len – [in] Length of the data to sign in bytes.

  • signature – [out] Pointer to the output buffer for the signature. The caller is responsible for freeing the buffer if not NULL.

  • signature_len – [out] On success, number of bytes written to signature.

Returns:

ESP_RMAKER_OK on success, ESP_RMAKER_INVALID_ARG on invalid args, ESP_RMAKER_FAIL otherwise.

esp_rmaker_error_t esp_rmaker_crypto_esp_key_bin_to_der(const uint8_t *key, size_t key_len, uint8_t **der, size_t *der_len)

Convert an ESP binary key to a DER key.

The key is expected to be in this format:

  • ECDSA, NIST P-256

  • Exactly 32 bytes long

  • Big-endian raw integer format

Parameters:

  • key – [in] The binary key

  • key_len – [in] The length of the binary key

  • der – [out] The DER key. Must be freed by the caller.

  • der_len – [out] The length of the DER key

Returns:

ESP_RMAKER_OK on success, ESP_RMAKER_INVALID_ARG on invalid args, ESP_RMAKER_FAIL otherwise.

Macros

RMAKER_CRYPTO_CSR_PEM_LEN_ECDSA_P256
RMAKER_CRYPTO_CSR_PEM_LEN_RSA_2048
RMAKER_CRYPTO_CSR_PEM_LEN_MAX

Fallback for a key whose type is not in esp_rmaker_crypto_key_type_t. Sized for RSA-3072 (1257 raw, 1278 escaped), the next size up that a pre-flashed key might plausibly be.

RMAKER_CRYPTO_SHA256_HASH_LEN

Enumerations

enum esp_rmaker_crypto_key_type_t

Private key type.

Used both to request a key type from esp_rmaker_crypto_gen_key_pem and to report the type of an existing key from esp_rmaker_crypto_get_key_type.

Note

Not an exhaustive list of usable key types, only of the ones generated and detected here. Extend it if more types need to be detected.

Values:

enumerator RMAKER_CRYPTO_KEY_TYPE_UNKNOWN

Unrecognised or unsupported key type.

enumerator RMAKER_CRYPTO_KEY_TYPE_ECDSA_P256

ECDSA, NIST P-256 (secp256r1).

enumerator RMAKER_CRYPTO_KEY_TYPE_RSA_2048

RSA, 2048-bit.

Conversion Helpers

Header File

Functions

char *esp_rmaker_convert_bytes_to_base64(const uint8_t *bytes, size_t bytes_len, size_t *base64_str_len)

Convert bytes to a base64 string.

Note

The caller is responsible for freeing the base64 string using free().

Parameters:

  • bytes – [in] The bytes to convert.

  • bytes_len – [in] The length of the bytes to convert.

  • base64_str_len – [out] The length of the base64 string to store the result in.

Returns:

The base64 string on success, NULL otherwise.

uint8_t *esp_rmaker_convert_base64_to_bytes(const char *base64_str, size_t base64_str_len, size_t *bytes_len)

Convert a base64 string to bytes.

Note

The caller is responsible for freeing the bytes using free().

Parameters:

  • base64_str – [in] The base64 string to convert.

  • base64_str_len – [in] The length of the base64 string to convert, excluding the null terminator.

  • bytes_len – [out] The length of the bytes to store the result in.

Returns:

The bytes on success, NULL otherwise.

Header File

Functions

esp_rmaker_error_t esp_rmaker_convert_bytes_to_hex(const uint8_t *bytes, size_t bytes_len, char *hex_str, size_t hex_str_size)

Convert bytes to a hex string.

Parameters:

  • bytes – [in] The bytes to convert.

  • bytes_len – [in] The length of the bytes to convert.

  • hex_str – [out] The hex string to store the result in.

  • hex_str_size – [in] The size of the hex string to store the result in.

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_INVALID_ARG if bytes or hex_str is NULL, or hex_str_size is smaller than bytes_len * 2 + 1.

esp_rmaker_error_t esp_rmaker_convert_hex_to_bytes(const char *hex_str, size_t hex_str_len, uint8_t *bytes, size_t bytes_size)

Convert a hex string to bytes.

Parameters:

  • hex_str – [in] The hex string to convert.

  • hex_str_len – [in] The length of the hex string to convert, excluding the null terminator.

  • bytes – [out] The bytes to store the result in.

  • bytes_size – [in] The size of the bytes to store the result in.

Returns:

ESP_RMAKER_OK on success.

Returns:

ESP_RMAKER_INVALID_ARG if hex_str or bytes is NULL, bytes_size is too small, or hex_str is not valid hex.