Node - Cloud Communication

All the communication between the node and cloud happens over secure MQTT.

Security

TLS

The communication between the node and the cloud is secured using TLS. It uses X.509 certificate-based mutual authentication. The client key is generated on the node itself. It then generates a Certificate Signing Request (CSR) which is signed by a CA and given back to the node as a client certificate during the "Claiming" process.

MQTT Policies

The MQTT Policy specifies that a node can establish a connection only if the client ID matches the node ID. Moreover, the node is only allowed to subscribe and publish topics with the prefix node/<node_id>/.

Node Configuration

All the information pertaining to a node, like the node ID, attributes, devices, params, etc. is combined into an object called the node configuration. It is the first thing that is reported to ESP RainMaker Cloud as the node boots up. The same is reported as is to the clients like phone apps and CLI. The clients can parse and use it anyhow they want. You can add and edit this as per your requirements and handle it appropriately in your clients.

Below is the node configuration that the ESP RainMaker firmware and phone apps currently use.

Note: Entries in bold are mandatory. The strings in the parentheses indicate the corresponding key in the JSON representation and the data type.

• Node ID (node_id, String)
• Config Version (config_version, String)
• Information (info, Object)
  • Name (name, String)
  • FW Version (fw_version, String)
  • Type (type, String)
• Node Attributes (attributes, Array of Objects)
  • Name (name, String)
  • Value (value, String)
• Devices (devices, Array of objects)
  • Name (name, String)
  • Type (type, String)
  • Primary (primary, String)
  • Device Attributes (attributes, Array of Objects)
    • Name (name, String)
    • Value (value, String)
  • Params (params, Array of objects)
    • Name (name, String)
    • Data Type (data_type, String)
    • Type (type, String)
    • Properties (properties, Array of Strings)
    • UI Type (ui_type, String)
    • Bounds (bounds, Object)
      • Minimum (min, Number)
      • Maximum (max, Number)
      • Step (step, Number)

MQTT

• Topic node/<node_id>/config
• Operation: PUBLISH
• Data: Node configuration JSON object described below
• Eg. Sample node configuration

Node Parameters

All parameter changes are managed through specific node parameter topics.

Initial Reporting

MQTT

• Topic node/<node_id>/params/local/init
• Operation: PUBLISH
• Data: {"<device-name">:{"<param-name>":<value>,...},...}
• Example:

{
    "Lightbulb": {
        "name": "Bedroom Light",
        "power": true,
        "brightness": 55
    }
}

Initial reporting is done every time the node boots up. Values of all the parameters of all the devices are reported in this.

Subsequent Reporting

MQTT

• Topic node/<node_id>/params/local
• Operation: PUBLISH
• Data: {"<device-name">:{"<param-name>":<value>,...},...}
• Example

{
    "Lightbulb": {
        "brightness": 75
    }
}

Any subsequent changes on the node, either due to remote control or a local change, are reported on this topic. Only the parameter that has changed is required in the payload.

Remote Control

MQTT

• Topic node/<node_id>/params/remote
• Operation: SUBSCRIBE
• Data: {"<device-name">:{"<param-name>":<value>,...},...}
• Example

{
    "Lightbulb": {
        "brightness": 100
    }
}

A node must always stay subscribed to this topic, listening for updates triggered by the clients like phone apps or CLI. Any change in parameter values as per the updates must be reported back using the "Subsequent Reporting".

User-Node Mapping

Before the devices under a node can be monitored and controlled remotely, the node should be first mapped to a user so that only that specific user can have permission to access it. This happens in the background during the Wi-Fi provisioning stage. The node sends its node_id to the client and the client sends the user_id and secret_key to the node for mapping. Once connected to the RainMaker Cloud, the node sends the mapping request. Please check here for a detailed workflow.

MQTT

• Topic node/<node_id>/user/mapping
• Operation: PUBLISH
• Data: {"node_id":"<node_id>","user_id":"<user_id>","secret_key": "<secret_key>"}
• Example

{
    "node_id": "112233AABBCC",
    "user_id": "02e95749-8d9d-4b8e-972c-43325ad27c63",
    "secret_key": "9140ef1d-72be-48d5-a6a1-455a27d77dee"
}

Time Series Data

Full featured time series data

This is for reporting values that require complete time stamped history and operations to find min, max, average, etc. in a given time window.

Check this time series document for details.

Simple Time Series Data

This is for reporting values that require complete time stamped history, but without any additional operations.

Check this time series document for details.

Appendix: Sample Node Configuration

Here is a node configuration sample with two devices.

{
    "node_id": "5d898491-a498-48ec-9476-a4e23519fe31",
    "config_version": "2019-02-27",
    "info": {
        "name": "My_Bridge",
        "fw_version": "1.0",
        "type": "Bridge"
    },
    "attributes": [{
        "name": "serial_num",
        "value": "123abc"
    }, {
        "name": "model",
        "value": "myBridge-2019"
    }],
    "devices": [{
        "name": "Switch",
        "primary": "power",
        "params": [{
            "name": "name",
            "type": "esp.param.name",
            "data_type": "string",
            "properties": ["read", "write"]
        }, {
            "name": "power",
            "data_type": "bool",
            "properties": ["read", "write", "time_series"],
            "ui_type": "esp.ui.toggle"
        }]
    }, {
        "name": "Light",
        "type": "esp.device.lightbulb",
        "attributes": [{
            "name": "serial_number",
            "value": "012345"
        }, {
            "name": "mac",
            "value": "xx:yy:zz:aa:bb:cc"
        }],
        "primary": "power",
        "params": [{
            "name": "name",
            "type": "esp.param.name",
            "data_type": "string",
            "properties": ["read", "write"]
        }, {
            "name": "power",
            "data_type": "bool",
            "properties": ["read", "write", "time_series"],
            "ui_type": "esp.ui.toggle"
        }, {
            "name": "brightness",
            "data_type": "int",
            "properties": ["read", "write"],
            "bounds": {
                "min": 0,
                "max": 100
            },
            "ui_type": "esp.ui.slider"
        }]
    }]
}