Migrating Device Data to the Cloud

MQTT Broker

End devices can communicate with IEF using the MQTT protocol. You can also control end devices through pub/sub messaging.

An edge node has a built-in MQTT broker. The built-in MQTT broker uses port 8883 to communicate with end devices. End devices can communicate with the built-in MQTT broker only after they pass security authentication. For details, see Performing Security Authentication Using Certificate.

Edge nodes also support external MQTT brokers. You can install an MQTT broker (for example, Mosquitto, an open-source MQTT broker) on an edge node. Then devices can communicate with the edge node over port 1883.

NOTE:

If an external MQTT broker is used, ensure that the communication port of the external MQTT broker is available.

MQTT Topics

The MQTT broker forwards messages between end devices and edge nodes to enable the end devices to communicate with the nodes and IEF. By default, the MQTT broker provides message topics described in Table 1. Device status can be reported and controlled through pub/sub messaging.

After an application is compiled, you can deploy the application to an edge node through IEF. For details, see Containerized Application Management.

The following describes how to obtain end device data at the edge, receive control messages from the cloud, and report end device data to the cloud. For details about the sample code for MQTT to send and receive messages, see Go-Language Code Sample and Java-Language Code Sample.

Obtaining End Devices Associated with an Edge Node

1. Send a request to the topic Device Member Acquisition.

   Topic: $hw/events/node/{node_id}/membership/get

   Payload: {"event_id": "Custom ID"}

   For example:

   $hw/events/node/{node_id}/membership/get
   
   {"event_id":""}

2. Subscribe to the topic Device Member Acquisition Result.

   Topic: $hw/events/node/{node_id}/membership/get/result

   The following is an example of the returned result:

   {
       "event_id": "",
       "timestamp": 1554986455386,
       "devices": [
           {
               "id": "2144773f-13f1-43f5-af07-51991d4fd064",
               "name": "equipmentA",
               "state": "unknown",
               "attributes": {
                   "name": {
                       "value": "a",
                       "optional": true,
                       "metadata": {
                           "type": "string"
                       }
                   }
               }
           }
       ]
   }

Obtaining Device Twins

1. Send a request to the topic used to Device Twin Acquisition.

   Topic: $hw/events/device/{device_id}/twin/get

   Payload: {"event_id": "Custom ID"}

2. Subscribe to the topic Device Twin Acquisition Result.

   Topic: $hw/events/device/{device_id}/twin/get/result

   The following is an example of the returned result:

   {
       "event_id": "",
       "timestamp": 1554988425592,
       "twin": {
           "humidity": {
               "expected": {
                   "value": "0",
                   "metadata": {
                       "timestamp": 1554988419529
                   }
               },
               "optional": true,
               "metadata": {
                   "type": "int"
               }
           },
           "temperature": {
               "expected": {
                   "value": "0",
                   "metadata": {
                       "timestamp": 1554988419529
                   }
               },
               "optional": true,
               "metadata": {
                   "type": "int"
               }
           }
       }
   }

Listening to Device Twin Events

After Obtaining End Devices Associated with an Edge Node and Obtaining Device Twins are performed, the ID of the end device bound to the node is obtained. Then, the events of the end device can be listened to.

Update the device twin by setting the expected value in the cloud to control the end device.

For example, a device has two twin properties: humidity and temperature.

Figure 1 Twin properties

Change the value of twin property humidity on the Device Twins tab page from 9 to 10. After the twin property is changed, the device receives the following two events:

• Device twin change event: includes the twin information before and after the change.
• Device twin delta event: includes the device twin details and the delta information about the inconsistency between the expected and actual values of twin properties.

The device can receive the two events only after it has subscribed to the two topics.

1. Subscribe to the topic Device Twin Update.

   Topic: $hw/events/device/{device_id}/twin/update/document

   The update message received at the edge is as follows:

   {
       "event_id": "0f921313-4074-46a2-96f6-aac610721059",
       "timestamp": 1555313685831,
       "twin": {
           "humidity": {
               "last": {
                   "expected": {
                       "value": "9",
                       "metadata": {
                           "timestamp": 1555313665978
                       }
                   },
                   "optional": true,
                   "metadata": {
                       "type": "int"
                   }
               },
               "current": {
                   "expected": {
                       "value": "10",
                       "metadata": {
                           "timestamp": 1555313685831
                       }
                   },
                   "optional": true,
                   "metadata": {
                       "type": "int"
                   }
               }
           },
           "temperature": {
               "last": {
                   "expected": {
                       "value": "0",
                       "metadata": {
                           "timestamp": 1555313665978
                       }
                   },
                   "actual": {
                       "value": "2",
                       "metadata": {
                           "timestamp": 1555299457284
                       }
                   },
                   "optional": true,
                   "metadata": {
                       "type": "int"
                   }
               },
               "current": {
                   "expected": {
                       "value": "0",
                       "metadata": {
                           "timestamp": 1555313685831
                       }
                   },
                   "actual": {
                       "value": "2",
                       "metadata": {
                           "timestamp": 1555299457284
                       }
                   },
                   "optional": true,
                   "metadata": {
                       "type": "int"
                   }
               }
           }
       }
   }

2. Subscribe to the topic Device Twin Delta.

   Topic: $hw/events/device/{device_id}/twin/update/delta

   The update message received at the edge is as follows:

   {
       "event_id": "60fb5baf-d4ad-47b0-a21e-8b57b52d0978",
       "timestamp": 1555313685837,
       "twin": {
           "humidity": {
               "expected": {
                   "value": "10",
                   "metadata": {
                       "timestamp": 1555313685831
                   }
               },
               "optional": true,
               "metadata": {
                   "type": "int"
               }
           },
           "temperature": {
               "expected": {
                   "value": "0",
                   "metadata": {
                       "timestamp": 1555313685831
                   }
               },
               "actual": {
                   "value": "2",
                   "metadata": {
                       "timestamp": 1555299457284
                   }
               },
               "optional": true,
               "metadata": {
                   "type": "int"
               }
           }
       },
       "delta": {
           "humidity": "10",
           "temperature": "0"
       }
   }

Reporting Actual Values of Device Properties

1. Publish a twin update event for an end device.

   Topic: $hw/events/device/{device_id}/twin/update

   Payload: {"event_id":"", "timestamp":0, "twin":{"Property":{"actual":{"value":"Actual value"}}}}

   For example:

   {
       "event_id": "",
       "timestamp": 0,
       "twin": {
           "temperature": {
               "actual": {
                   "value": "2"
               }
           }
       }
   }

   After the event is published, you can find that the actual value of the device twin has changed in the cloud, as shown in Figure 2.

   Figure 2 Updated twin properties
   

2. Subscribe to the topic Device Twin Modification Result at the edge. The edge node then can receive the result of the device twin update event.

   Topic: $hw/events/device/{device_id}/twin/update/result

   The update result is as follows:

   {
       "event_id": "",
       "timestamp": 1554992093859,
       "twin": {
           "temperature": {
               "actual": {
                   "value": "2",
                   "metadata": {
                       "timestamp": 1554992093859
                   }
               },
               "optional": true,
               "metadata": {
                   "type": "int"
               }
           }
       }
   }