Command Response Usage Guide
Firmware Usage Guide
The Command-Response framework in ESP RainMaker provides a reliable way to send data from clients (like 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
In the firmware application code, enable command-response by setting CONFIG_ESP_RMAKER_CMD_RESP_ENABLE=y in sdkconfig. Thereafter, just calling the API esp_rmaker_cmd_register() is sufficient to register a command.
Definitions of the API nd 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 has the following 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 as well as secondary user (but 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. This is the sample command handler example code, taken part from the led_light example.