ESP RainMaker MQTT Definitions for Nodes 3.3.0-6c749d111

ESP RainMaker MQTT Definitions for Nodes 3.3.0-6c749d111_2025-07-24T12:18

The API Defintions for the Rainmaker MQTT topics for communication with RainMaker nodes.

TLS encryption with RainMaker issued X.509 certificate-based mutual authentication is required to publish and subscribe to these topics.

Command Structure

Command requests/responses use Binary TLV (Tag, Length, Value) format with these standard tags:

Tag 1: Request ID (22 bytes) - Uniquely identifies each request
Tag 2: User Role (1 byte) - 1=admin, 2=primary user, 4=secondary user
Tag 3: Status (1 byte) - 0=success, 1=failed, 2=invalid, 3=auth failure, 4=not found
Tag 5: Command (2 bytes) - See command categories below
Tag 6: Data (0-64KB) - JSON object with command-specific data

Command Categories

Standard Commands

0: Get all pending requests
1: Request param update
16: Request file upload URL
17: Get file download URL
20: Confirm file upload success

DAC Commands (Device Attestation Certificate)

201: CSR submission for DAC/Custom Data
202: Request/Response for DAC, Custom Data, or PAI certificates
203: Status update for DAC data retrieval process

Servers

mqtt://a1p72mufdu6064-ats.iot.us-east-1.amazonaws.com/mqttproduction
Security:
X509:

Operations

SEND $aws/events/presence/connected/<node_id>
[Node connection] AWS IoT Core presence events for device connections

Operation IDonPresenceConnected
Available only on servers:
- production
Accepts the following message:
connectedMessage
Message IDconnectedMessage
object
clientId
required
string
ID of the connected device

clientInitiatedDisconnect
required
boolean
Whether the disconnect was initiated by the client

eventType
required
string
Type of the event (connected/disconnected)

principalIdentifier
required
string
Principal identifier of the device. For TLS mutual authentication certificates, this is the certificate ID.

sessionIdentifier
required
string
Session identifier for the connection

timestamp
required
integer
Unix timestamp of the event

versionNumber
required
integer
Version number of the event

ipAddress
string
IP address of the connected device

Additional properties are allowed.
Examples
{ "clientId": "rainmaker-node", "clientInitiatedDisconnect": true, "eventType": "connected", "principalIdentifier": "6cf12df543fe301f65b52632c8a59b743467db17bae30ce74120663e96736ff3", "sessionIdentifier": "adecf6af-2abd-4f23-8309-cf9257de3fa0", "timestamp": 1743656583784, "versionNumber": 0, "ipAddress": "192.168.1.100" }

This example has been generated automatically.
SEND $aws/events/presence/disconnected/<node_id>
[Node connection] AWS IoT Core presence events for device disconnections

Operation IDonPresenceDisconnected
Available only on servers:
- production
Accepts the following message:
disconnectedMessage
Message IDdisconnectedMessage
object
clientId
required
string
ID of the disconnected device

clientInitiatedDisconnect
required
boolean
Whether the disconnect was initiated by the client

eventType
required
string
Type of the event (connected/disconnected)

principalIdentifier
required
string
Principal identifier of the device. For TLS mutual authentication certificates, this is the certificate ID.

sessionIdentifier
required
string
Session identifier for the connection

timestamp
required
integer
Unix timestamp of the event

versionNumber
required
integer
Version number of the event

disconnectReason
required
string
Reason for disconnection

Additional properties are allowed.
Examples
{ "clientId": "rainmaker-node", "clientInitiatedDisconnect": true, "eventType": "disconnected", "principalIdentifier": "6cf12df543fe301f65b52632c8a59b743467db17bae30ce74120663e96736ff3", "sessionIdentifier": "adecf6af-2abd-4f23-8309-cf9257de3fa0", "timestamp": 1743656583784, "versionNumber": 0, "disconnectReason": "CLIENT_INITIATED_DISCONNECT" }

This example has been generated automatically.
SEND node/<node_id>/config
[Node config] Node configuration

Note: Use Basic ingest topic $aws/rules/esp_node_config/node/<node_id>/config to save costs

Operation IDonNodeConfig
Available only on servers:
- production
Accepts the following message:
configMessage
Message IDconfigMessage
object
node_id
required
string
ID of the node

config_version
required
string
Version of the configuration

required
object
name
required
string
Name of the node

model
required
string
Model of the node

platform
required
string
ESP Platform of the node

fw_version
required
string
Firmware version

type
required
string
Node type

project_name
required
string
Project name

Additional properties are allowed.
array<object>
Node attributes set by node. Espressif defined are: "cmd-resp", "admin-access", "network-id"

object
name
required
string
Attribute name

value
required
string
Attribute value

Additional properties are allowed.
required
array<object>
Devices supported by the node. For details: https://rainmaker.espressif.com/docs/standard-types#devices

object
name
required
string
Device name

type
required
string
Device type

primary
required
string
Primary parameter

array<object>
object
name
required
string
Attribute name

value
required
string
Attribute value

Additional properties are allowed.
required
array<object>
Parameters supported by the device. For details: https://rainmaker.espressif.com/docs/standard-types#parameters

object
name
required
string
Parameter name

type
required
string
Parameter type

data_type
required
string
Data type of parameter.

Allowed values:
"bool"
"int"
"float"
"string"
"array"
required
array<string>
Items:
string
Parameter properties

Allowed values:
"read"
"write"
"persist"
ui_type
string
UI type for the parameter. For details: https://rainmaker.espressif.com/docs/standard-types#ui-types

object
min
integer
Minimum value

max
integer
Maximum value

step
integer
Step value

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
array<object>
Services supported by the node. For details: https://rainmaker.espressif.com/docs/standard-types#services

object
name
required
string
Service name

type
required
string
Service type

Allowed values:
"esp.service.ota"
"esp.service.schedule"
"esp.service.time"
"esp.service.system"
"esp.service.local_control"
"esp.service.scenes"
array<object>
object
name
required
string
Attribute name

value
required
string
Attribute value

Additional properties are allowed.
required
array<object>
Parameters supported by the service. For details: https://rainmaker.espressif.com/docs/standard-types#parameters

object
name
required
string
Parameter name

type
required
string
Parameter type

data_type
required
string
Data type of parameter.

Allowed values:
"bool"
"int"
"float"
"string"
"array"
required
array<string>
Items:
string
Parameter properties

Allowed values:
"read"
"write"
"persist"
ui_type
string
UI type for the parameter. For details: https://rainmaker.espressif.com/docs/standard-types#ui-types

object
min
integer
Minimum value

max
integer
Maximum value

step
integer
Step value

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
Examples
{ "node_id": "Socfz6jwKPv8wDw4AakTts", "config_version": "2020-03-20", "info": { "name": "ESP RainMaker Multi Device", "model": "multi_device", "platform": "esp32", "fw_version": "1.0", "type": "Multi Device", "project_name": "multi_device" }, "attributes": [ { "name": "cmd-resp", "value": "1" } ], "devices": [ { "name": "Switch", "type": "esp.device.switch", "primary": "Power", "attributes": [ { "name": "Serial Number", "value": "012345" } ], "params": [ { "name": "brightness", "type": "esp.param.name", "data_type": "string", "properties": [ "read" ], "ui_type": "esp.ui.toggle", "bounds": { "min": 0, "max": 100, "step": 1 } } ] } ], "services": [ { "name": "Time", "type": "esp.service.time", "attributes": [ { "name": "deactivation_support", "value": "no" } ], "params": [ { "name": "TZ", "type": "esp.param.tz", "data_type": "string", "properties": [ "read" ], "ui_type": "esp.ui.text", "bounds": { "min": 0, "max": 10, "step": 1 } } ] } ] }

This example has been generated automatically.
SEND node/<node_id>/params/local/init
[Node params] Initial local parameters for nodes, this resets the node parameters to the provided values.

Note: Use Basic ingest topic $aws/rules/esp_init_params/node/<node_id>/params/local/init to save costs

Operation IDonNodeParamsLocalInit
Available only on servers:
- production
Accepts the following message:
paramsLocalInitMessage
Message IDparamsLocalInitMessage
object
Initial parameter values for the node

Additional properties are allowed.
Examples
{ "Light": { "brightness": 165 } }

This example has been generated automatically.
SEND node/<node_id>/user/mapping
[User node mapping] Node can request or confirm user to node mapping

Note: Use Basic ingest topic $aws/rules/esp_user_node_mapping/node/<node_id>/user/mapping to save costs

Operation IDonNodeUserMapping
Available only on servers:
- production
Accepts the following message:
userMappingMessage
Message IDuserMappingMessage
object
node_id
required
string
ID of the node

user_id
required
string
ID of the user

secret_key
required
string
Secret key for authentication which is same as the one sent by the user

reset
boolean
Whether to reset the node, this will remove all existing mappings and data of the node

timeout
integer
[ 0 .. 52560000 ]
Timeout value until which the user can confirm the mapping

Additional properties are allowed.
Examples
{ "node_id": "rainmaker-node", "user_id": "f3633ba0-3451-4996-842a-82b292b69371", "secret_key": "abcdef123456", "reset": false, "timeout": 300 }

This example has been generated automatically.
RECEIVE node/<node_id>/params/remote
[Node params] Parameter change request sent to node by cloud

Operation IDpublishNodeParamsRemote
Available only on servers:
- production
Accepts the following message:
paramsRemoteMessage
Message IDparamsRemoteMessage
object
Desired parameter change values for the node

Additional properties are allowed.
Examples
{ "Light": { "brightness": 165 } }

This example has been generated automatically.
SEND node/<node_id>/params/local
[Node params] Delta in parameters reported by nodes whenever they are changed

Note: Use Basic ingest topic $aws/rules/esp_set_params/node/<node_id>/params/local to save costs

Operation IDonNodeParamsLocal
Available only on servers:
- production
Accepts the following message:
paramsLocalMessage
Message IDparamsLocalMessage
object
Changed parameter values for the node

Additional properties are allowed.
Examples
{ "Light": { "brightness": 165 } }

This example has been generated automatically.
SEND node/<node_id>/params/local/<group_id>
[BETA] [Node params] Delta in parameters reported by nodes whenever they are changed

Note: Use Basic ingest topic $aws/rules/esp_set_group_params/node/<node_id>/params/local/<group_id> to save costs

Operation IDonNodeParamsLocalGroup
Available only on servers:
- production
Accepts the following message:
paramsLocalWildcardMessage
Message IDparamsLocalWildcardMessage
object
Changed parameter values for the node

Additional properties are allowed.
Examples
{ "Light": { "brightness": 165 } }

This example has been generated automatically.
SEND node/<node_id>/otafetch
[OTA] Nodes request for OTA firmware updates

Note: Use Basic ingest topic $aws/rules/esp_node_otafetch/node/<node_id>/otafetch to save costs

Operation IDonNodeOtaFetch
Available only on servers:
- production
Accepts the following message:
otaFetchMessage
Message IDotaFetchMessage
object
fw_version
required
string
Current firmware version of the node

network_id
string
For Thread based OTA, Network ID of the node

Additional properties are allowed.
Examples
{ "fw_version": "1.0.0", "network_id": "network-123456" }

This example has been generated automatically.
RECEIVE node/<node_id>/otaurl
[OTA] OTA update details if available sent to nodes. This is sent as a response to OTA fetch request or when a force pushed job is created.

Operation IDpublishNodeOtaUrl
Available only on servers:
- production
Accepts the following message:
otaUrlMessage
Message IDotaUrlMessage
object
url
required
string
HTTP presigned URL of the OTA firmware image binary file

stream_id
string
MQTT stream ID of the OTA firmware image binary file

file_md5
required
string
MD5 signature of the OTA binary file

file_size
required
integer
Size of the OTA binary file in bytes

ota_job_id
required
string
ID of the OTA job

fw_version
required
string
Firmware version of the OTA update

ota_available
boolean
Whether OTA is available for the node

metadata
string
Any metadata provided while creating the OTA job

Additional properties are allowed.
Examples
{ "url": "https://esp-rainmaker-ota-<Account-Id>-<Stage>.s3.<Region.amazonaws.com/users/<Admin-user-Id>/firmwareimages/<Image-Id>/<Image-Name.bin?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<>&X-Amz-Date=20240527T110857Z&X-Amz-Expires=86400&X-Amz-Security-Token=<>&X-Amz-SignedHeaders=host&X-Amz-Signature=5fb4f5ceed738e7c91ebfd7262b57562d66fb3022cb8f9576ce65c3f98f02859", "stream_id": "3Aq7BcdkX3TdoBSgPAdbTE", "file_md5": "d41d8cd98f00b204e9800998ecf8427e", "file_size": 1048576, "ota_job_id": "tyNoVBocEJ8ZQNuc9iMHZB", "fw_version": "2.0.0", "ota_available": true, "metadata": "string" }

This example has been generated automatically.
SEND node/<node_id>/otastatus
[OTA] OTA update status from nodes once they start the OTA job.

Note: Use Basic ingest topic $aws/rules/esp_node_otastatus/node/<node_id>/otastatus to save costs

Operation IDonNodeOtaStatus
Available only on servers:
- production
Accepts the following message:
otaStatusMessage
Message IDotaStatusMessage
object
status
required
string
Status of the OTA update. Once a node reports success and rejected, the OTA is marked finished for that node.

Allowed values:
"in-progress"
"success"
"rejected"
"failed"
"delayed"
ota_job_id
required
string
ID of the OTA job

additional_info
string
Additional information about the OTA status that the node might report.

network_id
string
For Thread based OTA, Network ID of the node

Additional properties are allowed.
Examples
{ "status": "in_progress", "ota_job_id": "tyNoVBocEJ8ZQNuc9iMHZB", "additional_info": "Downloaded 50%", "network_id": "network-123456" }

This example has been generated automatically.
SEND node/<node_id>/tsdata
[Time Series Data] Time series data from nodes.

Note: Use Basic ingest topic $aws/rules/esp_ts_ingest/node/<node_id>/tsdata to save costs

Operation IDonNodeTsData
Available only on servers:
- production
Accepts the following message:
tsDataMessage
Message IDtsDataMessage
object
ts_data_version
required
string
Version of the time series data format, should be 2021-09-13

required
array<object>
Array of time series data records

object
name
required
string
Name of the time series metric

dt
required
string
Data type of the metric.

Allowed values:
"bool"
"int"
"float"
"string"
ow
boolean
Whether to overwrite existing data

required
array<object>
Array of time series metric values

object
v
required
number
Value of the parameter, Data type based on the dt field.

t
required
integer
Timestamp

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
Examples
{ "ts_data_version": "2021-09-13", "ts_data": [ { "name": "temperature", "dt": "float", "ow": false, "records": [ { "v": 25.5, "t": 1648147200 } ] } ] }

This example has been generated automatically.
SEND node/<node_id>/simple_tsdata
[Time Series Data] Simple time series data from nodes. This is a simplified version of the time series data format with lesser aggregations.

Note: Use Basic ingest topic $aws/rules/esp_simple_ts_ingest/node/<node_id>/simple_tsdata to save costs

Operation IDonNodeSimpleTsData
Available only on servers:
- production
Accepts the following message:
simpleTsDataMessage
Message IDsimpleTsDataMessage
object
name
required
string
Name of the time series metric

dt
required
string
Data type of the metric

Allowed values:
"bool"
"int"
"float"
"string"
"array"
"object"
t
required
integer
Timestamp

v
required
number
Value of the metric, Data type based on the dt field.

d
integer
Optional expiration days

Additional properties are allowed.
Examples
{ "name": "temperature", "dt": "float", "t": 1648147200, "v": 25.5, "d": 30 }

This example has been generated automatically.
SEND node/<node_id>/from-node
[Command Request Response] Command requests or responses sent from nodes to the cloud. The format is Binary of TLV (Tag, Length, Value).

Note: Use Basic ingest topic $aws/rules/esp_cmd_resp/node/<node_id>/from-node to save costs

Operation IDonNodeFromNode
Available only on servers:
- production
Accepts the following message:
fromNodeMessage
Message IDfromNodeMessage
object
1
required
string
T: 1, L: 22, V: Request ID that uniquely identifies the request

3
required
integer
T: 3, L: 1, V: Status of the request 0 for success, 1 for failed, 2 for invalid command, 3 for authorization failure, 4 for not found

Allowed values:
0
1
2
3
4
5
required
integer
T: 5, L: 2, V: Command of 2 bytes. Command Categories:

Standard Commands:

0: Get all pending requests

16: Request file upload URL

17: Get file download URL

20: Confirm file upload success

DAC Commands (Device Attestation Certificate):

201: CSR submission for DAC/Custom Data

202: Request DAC or Custom Data or PAI

203: Status update for DAC data retrieval process

6
string
T: 6, L: 0-64KB, V: Json object of command data. Examples by command type:

Standard Examples:

Param response: {"params":{"Light":{"brightness":100}},"status":"success"}

DAC Command Examples:

CSR submission (cmd 201): {"cmd":201,"data":{"csr":""}}

DAC/Custom Data request (cmd 202): {"cmd":202,"data":{"request_keys":["dac","custom_data","pai","discriminator"]}}

Status update (cmd 203): {"cmd":203,"status":"completed"}

Additional properties are allowed.
Examples
{ "1": "YHZGBT8Pxe6TJDiRKu9mGL", "3": 2, "5": 201, "6": "{\"cmd\":201,\"data\":{\"csr\":\"-----BEGIN CERTIFICATE REQUEST-----\\nMIICZjCCAU4CAQAwGTEXMBUGA1UEAwwORVNQMzJfREFDX1RFUXQMV...\\n-----END CERTIFICATE REQUEST-----\"}}" }

This example has been generated automatically.
RECEIVE node/<node_id>/to-node
[Command Request Response] Command requests sent from cloud to nodes. The format is Binary of TLV (Tag, Length, Value).

Operation IDpublishNodeToNode
Available only on servers:
- production
Accepts the following message:
toNodeMessage
Message IDtoNodeMessage
object
1
required
string
T: 1, L: 22, V: Request ID that uniquely identifies the request

2
required
integer
T: 2, L: 1, V: Role of the user who is sending command to the node. 1 for admin, 2 for primary user, 4 for secondary user

Allowed values:
1
2
4
5
required
integer
[ 0 .. 255 ]
T: 5, L: 2, V: Command of 2 bytes. Command Categories:

Standard Commands:

1: Requesting param update

DAC Commands (Device Attestation Certificate):

201: CSR submission response

202: DAC/Custom Data response

6
string
T: 6, L: 0-64KB, V: Json object of command data. Examples by command type:

Standard Examples:

Param update: {"params":{"Light":{"brightness":100}}}

DAC Command Response Examples:

CSR submission response (cmd 201): {"cmd":201,"requestID":"abc123","status":"SUCCESS","description":"Submitted CSR successfully"}

DAC/Custom Data response (cmd 202): {"cmd":202,"requestID":"def456","status":"SUCCESS","data":{"dac":"","custom_data":"","pai":""}}

Additional properties are allowed.
Examples
{ "1": "YHZGBT8Pxe6TJDiRKu9mGL", "2": 2, "5": 201, "6": "{\"cmd\":201,\"requestID\":\"abc123def456\",\"status\":\"SUCCESS\",\"description\":\"Submitted CSR successfully\"}" }

This example has been generated automatically.
SEND node/<node_id>/alert
[Alert] Channel for sending push notification alerts to associated users from nodes

Note: Use Basic ingest topic $aws/rules/esp_node_alert/node/<node_id>/alert to save costs

Operation IDonNodeAlert
Available only on servers:
- production
Accepts the following message:
nodeAlertMessage
Message IDnodeAlertMessage
object
nodeId
required
string
ID of the node sending the alert

required
object
Json or string alert message from the node

Additional properties are allowed.
Additional properties are allowed.
Examples
{ "nodeId": "rainmaker-node", "messageBody": { "message": "Alert message from the node" } }

This example has been generated automatically.

ESP RainMaker MQTT Definitions for Nodes 3.3.0-6c749d111_2025-07-24T12:18

Command Structure

Command Categories

Standard Commands

DAC Commands (Device Attestation Certificate)

Servers

Security:

Operations

SEND $aws/events/presence/connected/<node_id>

Examples

This example has been generated automatically.

SEND $aws/events/presence/disconnected/<node_id>

Examples

This example has been generated automatically.

SEND node/<node_id>/config

Examples

This example has been generated automatically.

SEND node/<node_id>/params/local/init

Examples

This example has been generated automatically.

SEND node/<node_id>/user/mapping

Examples

This example has been generated automatically.

RECEIVE node/<node_id>/params/remote

Examples

This example has been generated automatically.

SEND node/<node_id>/params/local

Examples

This example has been generated automatically.

SEND node/<node_id>/params/local/<group_id>

Examples

This example has been generated automatically.

SEND node/<node_id>/otafetch

Examples

This example has been generated automatically.

RECEIVE node/<node_id>/otaurl

Examples

This example has been generated automatically.

SEND node/<node_id>/otastatus

Examples

This example has been generated automatically.

SEND node/<node_id>/tsdata

Examples

This example has been generated automatically.

SEND node/<node_id>/simple_tsdata

Examples

This example has been generated automatically.

SEND node/<node_id>/from-node

Examples

This example has been generated automatically.

RECEIVE node/<node_id>/to-node

Examples

This example has been generated automatically.

SEND node/<node_id>/alert

Examples

This example has been generated automatically.