Command Response
The Command-Response framework in ESP RainMaker is an alternative to the set parameters workflow to send data from clients (like phone apps) to devices. It can be used by admin as well as end users.
Use Case
In an ESP RainMaker setup, Command Response can be used as a fail-safe mechanism for handling device state recovery after an intermittent power loss. For example, imagine a smart light controlled via ESP RainMaker. Normally, it operates based on real-time cloud commands. However, if the device experiences a power outage and restarts, it might lose its last known state. By implementing Command Response, the device can query the cloud for the last received command upon reboot, ensuring it restores the correct light settings (e.g., brightness and color) instead of defaulting to an off state. This ensures seamless operation and prevents unexpected behavior after power interruptions.
Some advantages of using this framework
- Get status of any request reliably
- Allow setting a validity for the request so that a request can be triggered even when a device is offline
- Provide better access control since the node knows the role of the user who triggered the command (admin, primary, secondary)
The diagram below explains how command - response works.
Client side
Client to cloud communication uses REST APIs with JSON Payload. To invoke a command, a POST API is invoked with this payload:
JSON Payload (Click to view)
{
"node_ids": [
"6jyMKuFuAq3xxxxxxxxyBQ"
],
"cmd": 1,
"data": {
"brightness": 10
},
"timeout": 30
}
- node_ids: List of node ids to which the command is to be sent.
- cmd: The command id.
- data: The data payload for the command.
- timeout: The timeout (in seconds) for which the command is valid.
For passing binary data to the nodes, send it as a base64 string.
Add is_based64 as an additional key. E.g.
JSON Payload (Click to view)
: {
"node_ids": [
"6jyMKuFuAq3xxxxxxxxyBQ"
],
"cmd": 1,
"data": "YWJjZAo="
"timeout": 30,
"is_base64": true
}
The cloud backend assigns a request id for this and responds with the following:
JSON Payload (Click to view)
{
"request_id": "6jyMKuFxxxxxxxxStTKyBQ",
"status": "success"
}
The client can then query for the status of this request using the GET API, passing the above request id as a query paramter. Here are the following status:
| Status |
|---|
| requested |
| in_progress |
| success |
| timed_out |
| failure |
For success and failure, the corresponding response value will also be returned.
Device side
Device to cloud communication uses TLV8, which is a variant of TLV encoding with 8bit length field. This allows flexibility in communication, as the application data can be JSON, XML, binary or any other convenient format.
Types
| Type | Macro in code | Description | Length |
|---|---|---|---|
| 1 | ESP_RMAKER_TLV_TYPE_REQ_ID | Request Id | Variable length string, max 32 characters |
| 2 | ESP_RMAKER_TLV_TYPE_USER_ROLE | User Role | 1 byte |
| 3 | ESP_RMAKER_TLV_TYPE_STATUS | Status | 1 byte |
| 4 | ESP_RMAKER_TLV_TYPE_TIMESTAMP | Timestamp | TBD (Unused) |
| 5 | ESP_RMAKER_TLV_TYPE_CMD | Command | 2 bytes (little endian) |
| 6 | ESP_RMAKER_TLV_TYPE_DATA | Data | Variable length |
Roles
These are mapped to bits
| Value | Macro in code | Description |
|---|---|---|
| 1 | ESP_RMAKER_USER_ROLE_SUPER_ADMIN | Super admin |
| 2 | ESP_RMAKER_USER_ROLE_PRIMARY_USER | Primary End User |
| 4 | ESP_RMAKER_USER_ROLE_SECONDARY_USER | Secondary End User |
Values for status
| Value | Macro in Code | Description |
|---|---|---|
| 0 | ESP_RMAKER_CMD_STATUS_SUCCESS | Success |
| 1 | ESP_RMAKER_CMD_STATUS_FAILED | Generic Failure |
| 2 | ESP_RMAKER_CMD_STATUS_CMD_INVALID | Invalid Command |
| 3 | ESP_RMAKER_CMD_STATUS_AUTH_FAIL | Authentication Failed |
| 4 | ESP_RMAKER_CMD_STATUS_NOT_FOUND | Command not found |
Usage Guide
Firmware
This usage guide would mainly cover the firmware side to enable and use command response.
On the usage of command response on firmware, click here.
Test Command Response Feature with RainMaker CLI
- To test out command response on RainMaker cli, click here
More info about API
REST API usage information can be found in the Swagger documentation.