Command Response Usage Guide
The Command-Response framework in ESP RainMaker provides a reliable way to send data from clients (such as phone apps) to devices, serving as an alternative to the set parameters workflow. It ensures seamless device state recovery after power loss by allowing devices to query the last received command from the cloud. This framework enhances reliability, enables request execution even when devices are offline, and improves access control by recognizing user roles (admin, primary, secondary).
Usage Guide
Enable Command Response
To enable command-response in your firmware, set CONFIG_ESP_RMAKER_CMD_RESP_ENABLE=y in sdkconfig. Then, register your command using the API esp_rmaker_cmd_register().
Definitions of the API and callback prototype:
esp_err_t esp_rmaker_cmd_register(uint16_t cmd, uint8_t access, esp_rmaker_cmd_handler_t handler, bool free_on_return, void *priv);
typedef esp_err_t (*esp_rmaker_cmd_handler_t)(const void *in_data, size_t in_len, void **out_data, size_t *out_len, esp_rmaker_cmd_ctx_t *ctx, void *priv);
| Parameters | Description |
|---|---|
| cmd | Command Identifier. Custom commands should use ids beyond ESP_RMAKER_CMD_CUSTOM_START (0x1000) |
| access | User Access for the command. Can be a logical OR of the various User Role Flags like: ESP_RMAKER_USER_ROLE_SUPER_ADMIN ESP_RMAKER_USER_ROLE_PRIMARY_USER ESP_RMAKER_USER_ROLE_SECONDARY_USER |
| handler | The handler to be invoked when the given command is received. |
| free_on_return | Flag to indicate if the framework should free the output after it has been sent as response. |
| priv | Optional private data to be passed to the handler. |
The handler esp_rmaker_cmd_handler_t parameters:
| Parameters | Description |
|---|---|
| in_data | Pointer to input data. |
| in_len | Data length. |
| out_data | Pointer to output data which should be set by the handler. |
| out_len | Length of output generated. |
| ctx | Command Context. Includes command id, request id and role of the user who invoked the command. |
| priv | Private data, if specified while registering command. |
Usage Example
#define LIGHT_CMD ESP_RMAKER_CMD_CUSTOM_START /* Custom commands should start from here */
/* Callback for command */
esp_err_t led_light_cmd_handler(const void *in_data, size_t in_len, void **out_data, size_t *out_len, esp_rmaker_cmd_ctx_t *ctx, void *priv)
{
ESP_LOGI(TAG, "Got command: %.*s", in_len, (char *)in_data);
/* Sending dummy response */
static char resp_data[100];
snprintf(resp_data, sizeof(resp_data), "{\"status\":\"success\"}");
*out_data = resp_data;
*out_len = strlen(resp_data);
return ESP_OK;
}
void app_main()
{
...
/* Register a command accessible to primary and secondary users (not admin) */
esp_rmaker_cmd_register(LIGHT_CMD, ESP_RMAKER_USER_ROLE_PRIMARY_USER | ESP_RMAKER_USER_ROLE_SECONDARY_USER, led_light_cmd_handler, false, NULL);
...
}
More Info
Sample firmware usage can be found in the led_light example. See the sample command handler for a real implementation.