RainMaker AT Command Set
Important
The default AT firmware does not support the AT commands listed on this page. If you need ESP32-C3 to support RainMaker commands, you have two options:
Refer to the How to Download the Latest Temporary Version of AT Firmware from GitHub documentation to download the esp32c3-rainmaker-at firmware.
Compile the ESP-AT project yourself by following the steps in Compiling the ESP-AT Project. During the third step (Install Environment), choose “PLATFORM_ESP32C3” for the “Platform name” and choose “ESP32C3_RAINMAKER” for the “Module name”.
AT+RMNODEINIT: Initialize the node.
AT+RMNODEATTR: Attributes operations.
AT+RMDEV: Device operations.
AT+RMPARAM: Device parameters operations.
AT+RMPARAMBOUNDS: Add bounds to numeric parameters.
AT+RMPARAMSTRLIST: Add a list of strings to a character parameters.
AT+RMPARAMCOUNT: Add maximum number of elements to array parameters.
AT+RMUSERMAPPING: Start user-node mapping.
AT+RMUSERUNMAPPING: Clear user-node mapping.
AT+RMPROV: Provisioning and user-node mapping.
AT+RMCONN: Connect to ESP RainMaker cloud.
AT+RMCLOSE: Actively disconnect from ESP RainMaker cloud.
AT+RMPARAMUPDATE: Update parameters.
AT+RMMODE: Set the transmission mode.
AT+RMSEND: Send data in the RainMaker Normal Transmission Mode or RainMaker Passthrough Mode.
AT+RMOTARESULT: Send the OTA result.
AT+RMOTAFETCH: Fetch OTA information.
AT+RMNODEINIT: Initialize the Node
Execute Command
Command:
AT+RMNODEINIT
Response:
OK
After the command is executed successfully, the node configuration will be saved internally in JSON format as follows.
{
"node_id":"xxxxxxxxxxxx",
"config_version":"xxxx-xx-xx",
"info":{
"name":"ESP RainMaker AT Node",
"fw_version":"xxxxxxx",
"type":"AT Node",
"model":"esp-at",
"project_name":"esp-at",
"platform":"esp32c3"
},
"devices":[
],
"services":[
{
"name":"System",
"type":"esp.service.system",
"params":[
{
"name":"Reboot",
"type":"esp.param.reboot",
"data_type":"bool",
"properties":[
"read",
"write"
]
},
{
"name":"Factory-Reset",
"type":"esp.param.factory-reset",
"data_type":"bool",
"properties":[
"read",
"write"
]
},
{
"name":"Wi-Fi-Reset",
"type":"esp.param.wifi-reset",
"data_type":"bool",
"properties":[
"read",
"write"
]
}
]
},
{
"name":"Time",
"type":"esp.service.time",
"params":[
{
"name":"TZ",
"type":"esp.param.tz",
"data_type":"string",
"properties":[
"read",
"write"
]
},
{
"name":"TZ-POSIX",
"type":"esp.param.tz_posix",
"data_type":"string",
"properties":[
"read",
"write"
]
}
]
},
{
"name":"Schedule",
"type":"esp.service.schedule",
"params":[
{
"name":"Schedules",
"type":"esp.param.schedules",
"data_type":"array",
"properties":[
"read",
"write"
],
"bounds":{
"max":10
}
}
]
}
]
}
Note
This command should be executed before any other ESP RainMaker AT commands.
This command enables the services of system management, OTA, time, and scheduling by default.
This command will first obtain the authentication information from the mass manufacturing partition
rmaker_mfg
. If the information is not found, it will search the system NVS. If it is still not found, it will perform claiming.This command will load the parameters from the mass manufacturing partition
rmaker_mfg
. If the parameters do not exist, the default configuration will be used to create a node automatically.After the command is executed successfully, the node configuration will be saved internally. There are some default key-value pairs in the node configuration.
node_id: Unique identifier derived from certificates and cannot be changed.
config_version: Temporarily no practical use. No need to change.
name: Fixed to “ESP RainMaker AT Node”.
fw_version: RainMaker AT version information.
type: Fixed to “AT Node”.
model: Fixed to “esp-at”.
project_name: Fixed to “esp-at”.
platform: Fixed to “ESP32-C3”.
services: system, OTA, time, and scheduling services.
AT+RMNODEATTR: Attributes Operations
Set Command
Command:
AT+RMNODEATTR=<"name1">,<"value1">[<"name2">,<"value2">,<"name3">,<"value3">,...,<"name8">,<"value8">]
Response:
OK
Parameters
<”name”>: node attribute key name.
<”value”>: node attribute value.
Note
Example
AT+RMNODEATTR="serial_num","123abc"
AT+RMDEV: Device Operations
Set Command
Command:
AT+RMDEV=<dev_opt>,<"unique_name">,<"device_name">,<"device_type">
Response:
OK
Parameters
<”dev_opt”>: device operations.
0: Add a device.
1: Delete a device.
<”unique_name”>: device unique name.
<”device_name”>: device name, which will be used as the default device name displayed on the app.
<”device_type”>: device type. Please refer to Devices.
Note
This command should be used before the device is connected to the RainMaker cloud (please refer to AT+RMPROV or AT+RMCONN).
Currently, only one device can be added to a node.
With the command being executed successfully, the device is added to the node configuration. The default type in the params is “esp.param.name”, the data type in the params is “string”, and the properties are “read” and “write”.
Example
AT+RMDEV=0,"Light","Light","esp.device.light"
After the command is executed successfully, the device “Light” will be added to the node configuration and saved internally in JSON format as follows (For node configuration, please refer to AT+RMNODEINIT).
{
"node_id":"xxxxxxxxxxxx",
"config_version":"xxxx-xx-xx",
"info":{
"name":"ESP RainMaker AT Node",
"fw_version":"xxxxxxx",
"type":"AT Node",
"model":"esp-at",
"project_name":"esp-at",
"platform":"esp32c3"
},
"attributes":[
{
"name":"serial_num",
"value":"123abc"
}
],
"devices":[
{
"name":"Light",
"type":"esp.device.light",
"params":[
{
"name":"Name",
"type":"esp.param.name",
"data_type":"string",
"properties":[
"read",
"write"
]
}
]
}
],
"services":[
{
"name":"System",
"type":"esp.service.system",
"params":[
{
"name":"Reboot",
"type":"esp.param.reboot",
"data_type":"bool",
"properties":[
"read",
"write"
]
},
{
"name":"Factory-Reset",
"type":"esp.param.factory-reset",
"data_type":"bool",
"properties":[
"read",
"write"
]
},
{
"name":"Wi-Fi-Reset",
"type":"esp.param.wifi-reset",
"data_type":"bool",
"properties":[
"read",
"write"
]
}
]
},
{
"name":"Time",
"type":"esp.service.time",
"params":[
{
"name":"TZ",
"type":"esp.param.tz",
"data_type":"string",
"properties":[
"read",
"write"
]
},
{
"name":"TZ-POSIX",
"type":"esp.param.tz_posix",
"data_type":"string",
"properties":[
"read",
"write"
]
}
]
},
{
"name":"Schedule",
"type":"esp.service.schedule",
"params":[
{
"name":"Schedules",
"type":"esp.param.schedules",
"data_type":"array",
"properties":[
"read",
"write"
],
"bounds":{
"max":10
}
}
]
}
]
}
AT+RMPARAM: Device Parameters Operations
Set Command
Function:
Add parameters to the device.
Command:
AT+RMPARAM=<"unique_name">,<"param_name">,<"param_type">,<data_type>,<properties>,<"ui_type">,<"def">
Response:
OK
Parameters
<”unique_name”>: device unique name.
<”param_name”>: parameter name.
<”param_type”>: parameter type. Please refer to Parameters.
<data_type>: data type.
bit 0: boolean.
bit 1: integer.
bit 2: floating-point number.
bit 3: string.
bit 4: object.
bit 5: array.
<properties>: data properties.
bit 0: read.
bit 1: write.
bit 2: time_series.
bit 3: persist.
<”ui_type”>: UI type. Please refer to UI Elements.
<”def”>: default value.
Note
This command should be used before the device is connected to the RainMaker cloud (please refer to AT+RMPROV or AT+RMCONN).
Please make sure the parameter
<def>
matches the parameter<data_type>
. AT does not check it internally.In the RainMaker Passthrough Mode, only one parameter is allowed in the device (the default parameter created by the AT+RMDEV command is not included). If there are multiple parameters, the device cannot enter the RainMaker Passthrough Mode.
Example
AT+RMPARAM="Light","Brightness","esp.param.brightness",2,3,"esp.ui.slider","50"
AT+RMPARAMBOUNDS: Add Bounds to Numeric Parameters
Set Command
Command:
AT+RMPARAMBOUNDS=<"unique_name">,<"param_name">,<"min">,<"max">,<"step">
Response:
OK
Parameters
<”unique_name”>: device unique name.
<”param_name”>: parameter name.
<”min”>: minimum value.
<”max”>: maximum value.
<”step”>: step value.
Note
This command should be used before the device is connected to the RainMaker cloud (please refer to AT+RMPROV or AT+RMCONN).
This command is only for parameter whose type is an integer or a floating-point number (please refer to the parameter
<data_type>
in the AT+RMPARAM). Please make sure the parameters<"min">
,<"max">
, and<"step">
match the parameter<data_type>
. AT does not check it internally.
Example
AT+RMPARAMBOUNDS="Switch","brightness","0","100","1"
After the command is executed successfully, the “bounds” will be added to the device “Switch” and saved internally in JSON format as follows (For node configuration, please refer to AT+RMNODEINIT).
{
"name":"Brightness",
"type":"esp.param.brightness",
"data_type":"int",
"properties":[
"read",
"write"
],
"bounds":{
"min":0,
"max":100,
"step":1
},
"ui_type":"esp.ui.slider"
}
AT+RMPARAMSTRLIST: Add a List of Strings to a Character Parameters
Set Command
Command:
AT+RMPARAMSTRLIST=<"unique_name">,<"param_name">,<"str1">[,<"str2">,<"str3">,...,<"str14">]
Response:
OK
Parameters
<”unique_name”>: device unique name.
<”param_name”>: parameter name.
<”str”>: members of a list of strings.
Note
This command should be used before the device is connected to the RainMaker cloud (please refer to AT+RMPROV or AT+RMCONN).
This command is only for parameter whose type is a string (please refer to the parameter
<data_type>
in the AT+RMPARAM). Please make sure the parameters<"str">
matches the parameter<data_type>
. AT does not check it internally.
Example
AT+RMPARAM="Light","Color","esp.param.color",4,3,"esp.ui.dropdown","white"
AT+RMPARAMSTRLIST="Light","Color","white","red","blue","yellow"
After the command is executed successfully, the “valid_strs” will be added to the device “Light” and saved internally in JSON format as follows (For node configuration, please refer to AT+RMNODEINIT).
{
"name":"Color",
"type":"esp.param.color",
"data_type":"string",
"properties":[
"read",
"write"
],
"valid_strs":[
"white",
"red",
"blue",
"yellow"
],
"ui_type":"esp.ui.dropdown"
}
AT+RMPARAMCOUNT: Add Maximum Number of Elements to Array Parameters
Parameters
<”unique_name”>: device unique name.
<”param_name”>: parameter name.
<array_count>: maximum number of elements in an array.
Note
This command should be used before the device is connected to the RainMaker cloud (please refer to AT+RMPROV or AT+RMCONN).
This command is only for parameter whose type is array (please refer to the parameter
<data_type>
in the AT+RMPARAM). Please make sure the parameters<array_count>
matches the parameter<data_type>
, AT doesn’t check internally.
Example
AT+RMPARAM="Light","Color","esp.param.color",6,3,"esp.ui.hidden",""
AT+RMPARAMCOUNT="Light","Color",5
After the command is executed successfully, the “bounds” will be added to the device “Light” and saved internally in JSON format as follows (For node configuration, please refer to AT+RMNODEINIT).
{
"name":"Color",
"type":"esp.param.color",
"data_type":"array",
"properties":[
"read",
"write"
],
"bounds":{
"max":5
},
"ui_type":"esp.ui.hidden"
}
AT+RMUSERMAPPING: Start User-Node Mapping
Set Command
Command:
AT+RMUSERMAPPING=<"user_id">,<"secret_key">
Response:
OK
If the mapping completes, the system returns:
+RMMAPPINGDONE
Parameters
<”user_id”>: user identifier.
<”secret_key”>: secret key.
AT+RMUSERUNMAPPING: Clear User-Node Mapping
AT+RMPROV: Provisioning and User-Node Mapping
Set Command
Command:
AT+RMPROV=<mode>[,<customer_id>,<device_extra_code>,<"broadcast_name">]
Response:
OK
Parameters
<mode>: mode.
0: start provisioning and user-node mapping.
1: stop provisioning.
<customer_id>: customer identifier, used to distinguish different customers. Range:[0,65535]. If you want to use the Nova Home, please contact us.
<device_extra_code>: device code, used to identify the device icon when provisioning. Range:[0,255].
<”broadcast_name”>: device name when customizing the Bluetooth broadcast. Range:[0,12]. Unit: byte.
AT+RMCONN: Connect to ESP RainMaker cloud
Set Command
Command:
AT+RMCONN=<conn_timeout>
Response:
If the device connects to the cloud successfully, the system returns:
+RMCONNECTED
OK
If the device fails to connect to the cloud, the system returns:
ERROR
Execute Command
Command:
AT+RMCONN
Response:
If the device connects to the cloud successfully, the system returns:
+RMCONNECTED
OK
If the device fails to connect to the cloud, the system returns:
ERROR
Parameters
<conn_timeout>: maximum timeout for connection. Range:[3,600]. Unit: second. Default: 15.
AT+RMCLOSE: Actively Disconnect from ESP RainMaker Cloud
Note
When the device actively calls this command to disconnect from the cloud, AT will not report the +RMDISCONNECTED message. Only when the device is passively disconnected from the cloud, AT will report the +RMDISCONNECTED message.
AT+RMPARAMUPDATE: Update Parameters
Set Command
Command:
AT+RMPARAMUPDATE=<"unique_name">,<"param_name1">,<"param_value1">[,<"param_name2">,<"param_value2">,...,<"param_name7">,<"param_value7">]
Response:
OK
Parameters
<”unique_name”>: device unique name.
<”param_name”>: parameter name.
<”param_value”>: parameter value.
Note
The parameter
<"param_value">
must match the parameter<data_type>
set in AT+RMPARAM.The command supports up to 15 parameters, namely, 1
<"unique_name">
+ 7<"param_name">
+ 7<"param_value">
.The length of the entire AT command should be less than
256
bytes. If the amount of data you want to update is relatively large, please use the AT+RMSEND command.
Example
AT+RMPARAMUPDATE="Light","Power","1"
AT+RMMODE: Set the Transmission Mode
Parameters
<mode>: transmission mode.
Note
In the RainMaker Passthrough Mode, only one parameter is allowed in the devices (the default parameter created by the AT+RMDEV command is not included). If there are multiple parameters, the device cannot enter the RainMaker Passthrough Mode.
AT+RMSEND: Send Data in the RainMaker Normal Transmission Mode or RainMaker Passthrough Mode
Set Command
Function:
Send data of specified length in the RainMaker Normal Transmission Mode.
Command:
AT+RMSEND=<"unique_name">,<"param_name">,<len>
Response:
OK
>
This response indicates that AT is ready for receiving serial data. You should enter the data, and when the data length reaches the <len> value, the system returns:
Recv <len> bytes
If not all the data has been sent out, the system finally returns:
SEND FAIL
If all the data is transmitted successfully, the system finally returns:
SEND OK
Execute Command
Function:
Enter the RainMaker Passthrough Mode.
Command:
AT+RMSEND
Response:
OK
>
or
ERROR
Enter the RainMaker Passthrough Mode. When a single packet containing +++
is received, the ESP32-C3 will exit the data sending mode under the RainMaker Passthrough Mode. Please wait for at least one second before sending the next AT command.
Parameters
<”unique_name”>: device unique name.
<”param_name”>: parameter name.
<len>: data length. The length depends on the RAM size. You can use AT+SYSRAM to query the remaining RAM size.
Note
In the RainMaker Passthrough Mode, only one parameter in the devices is allowed (the default parameter created by the AT+RMDEV command is not included). If there are multiple parameters, the device cannot enter the RainMaker Passthrough Mode.
If you want to update multiple parameters at the same time, please refer to AT+RMPARAMUPDATE command.
AT+RMOTARESULT: Send the OTA Result
Set Command
Command:
AT+RMOTARESULT=<type>,<"ota_job_id">,<result>,<"additional_info">
Response:
OK
Parameters
<type>: reserved.
<”ota_job_id”>: OTA job ID.
<result>: OTA result.
1: OTA in progress.
2: OTA succeeded.
3: OTA failed.
4: OTA delayed by the application.
5: OTA rejected due to some reason.
<”additional_info”>: Additional information for the OTA status.
Note
This command is only applicable to host MCU OTA. For ESP32-C3 Wi-Fi OTA, the system will automatically send the OTA status.
AT+RMOTAFETCH: Fetch OTA Information
Note
For host MCU OTA, ESP-AT will send the received OTA informations instantly to the host MCU in the format of
+RMFWNOTIFY:<type>,<size>,<url>,<fw_version>,<ota_job_id>
.<type>: reserved. It is always set to 0 by ESP-AT.
<size>: host MCU OTA firmware size. Unit: byte.
<url>: host MCU OTA download URI. You can use the AT+HTTPCGET command to download firmware.
<fw_version>: host MCU OTA firmware version.
<ota_job_id>: host MCU OTA job ID. You can use the AT+RMOTARESULT command to send the OTA result.
For ESP32-C3 Wi-Fi OTA, the system will automatically executes the OTA. ESP-AT will send the OTA status to the host MCU in the format of
+RMOTA:<status>
.1: OTA in progress.
2: OTA succeeded.
3: OTA failed.
4: OTA delayed by the application.
5: OTA rejected due to some reason.
Please refer to RainMaker AT OTA Guide for how to implement OTA via ESP RainMaker cloud.