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.

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.

**Table 1** Default topics provided by IEF
Name	Type	Topic	Description
Device Twin Update	Subscribe	$hw/events/device/{device_id}/twin/update/document	This topic is used to subscribe to device twin updates. It reflects the differences before and after a device twin update.
Device Twin Delta	Subscribe	$hw/events/device/{device_id}/twin/update/delta	This topic is used to subscribe to device twin delta events. When a device twin changes, the twin properties whose actual values are different from expected values are returned.
Device Member Update	Subscribe	$hw/events/node/{node_id}/membership/updated	This topic is used to subscribe to end device binding updates.
Device Property Update	Subscribe	$hw/events/device/{device_id}/updated	This topic is used to subscribe to end device property updates.
Device Member Acquisition	Publish	$hw/events/node/{node_id}/membership/get	This topic is used to subscribe to end device bindings.
Device Member Acquisition Result	Subscribe	$hw/events/node/{node_id}/membership/get/result	This topic is used to subscribe to the result of obtaining information about end device members.
Device Twin Acquisition	Publish	$hw/events/device/{device_id}/twin/get	This topic is used to publish the request for obtaining device twins.
Device Twin Acquisition Result	Subscribe	$hw/events/device/{device_id}/twin/get/result	This topic is used to subscribe to the result of obtaining device twins.
Device Twin Modification	Publish	$hw/events/device/{device_id}/twin/update	This topic is used to publish device twin modifications.
Device Twin Modification Result	Subscribe	$hw/events/device/{device_id}/twin/update/result	This topic is used to subscribe to the result of modifying device twins.
Encryption Data Request	Publish	$hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/decrypt	This topic is used to publish the request for obtaining encryption data.
Encryption Data Acquisition	Subscribe	$hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/plaintext	This topic is used to subscribe to encryption data.
Alarm Reporting	Publish	$hw/alarm/{appname}/add	This topic is used to report alarms to AOM.
Alarm Clearance	Publish	$hw/alarm/{appname}/clear	This topic is used to clear alarms in AOM.
Custom Topics	Publish	{project_id}/nodes/{node_id}/user/{custom_topic}	Topics customized based on actual requirements. You can publish end device data to a custom topic in the MQTT broker of an edge node. IEF then forwards the device data to a DIS stream or an API Gateway address. Then, you can extract the data for processing and analysis.

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

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":""}
```

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

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

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

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

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.

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"
                }
            }
        }
    }
}

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

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

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"
            }
        }
    }
}

Parent topic: End Device Management

Previous topic: Device Twin Working Principles

Next topic: Performing Security Authentication Using Certificate