Report Connection Topology Status¶

The connection topology structure and connection status can be reported from the root node through MQTT to the cloud. For more information on connection topology in IoT Hub, see Viewing the Connection Topology of Devices.

Upstream

Request TOPIC: /sys/{productKey}/{deviceKey}/connection/state/post
Reply TOPIC: /sys/{productKey}/{deviceKey}/connection/state/post_reply

Sample Request Format¶

When the root node establishes an MQTT connection or reconnects with the cloud, it will first report the device connection topology structure and connection status to IoT Hub. See the sample codes below.

Reporting Connection Topology Structure and Status¶

{
    "id":"123",
    "version":"1.0",
    "params":{
        "nodes":[
            {"name":"name3","state":1,"nodeId":"#003","assetId":"assetId3"},
            {"name":"name4","state":1,"nodeId":"#004"},
            {"name":"name5","state":1,"nodeId":"#005","assetId":"assetId5"},
            {"name":"name1","state":1,"nodeId":"#001","info":"reconnect by xxx"},
            {"name":"connection1","state":2,"nodeId":"#002","info":"no heartbeat"}
        ],
        "isFull":true,
        "relations":{
            "#004":["#005"],
            "#001":["#003","#004","#002"]
        },
        "reportTime":1612254712139
    },
    "method":"connection.state.post"
}

Reporting Disconnected/Reconnection Status¶

When root nodes are disconnected/reconnected, IoT Hub automatically detects it and sets the status of the root nodes to 2 (disconnected) or 1 (connected).

When child nodes are disconnected/reconnected, the root node needs to report the information of the specific disconnected/reconnected node for IoT Hub to update the status to 2 or 1. See the sample code below.

{
    "method":"connection.state.post",
    "id":"1",
    "params":{
        "isFull":false,
        "reportTime":1609809203312,
        "nodes":[
            {
                "nodeId":"#002",
                "assetId": "Edge1",
                "state":2,
                "info": "no heartbeat"
            }
        ]
    },
    "version":"1.0"
}

Sample Response Format¶

{
    "id":"123",
    "code":200,
    "data":{}
}

Request Parameter Description¶

Parameter	Type	Mandatory/Optional	Description
id	String	Optional	The message ID. It is a reserved parameter that is reserved for future use.
version	String	Mandatory	The version of the protocol. The current version is 1.0.
params	Object	Mandatory	The parameters used for reporting the connection topology status.
nodes	Array	Optional	Contains all the node information in the topology on the device side.
nodeId	String	Mandatory	The node identifier, which is globally unique.
assetId	String	Optional	The assetId of the device corresponding to the node. It the node does not correspond to any device, this field can be left blank.
state	Integer	Mandatory	The connection status of the node. 1: Connected 2: Disconnected 3: Unknown
info	String	Optional	Additional information on the node status, such as why the node became offline.
name	String	Optional	The node name. For device nodes, if not provided, the name of the cloud device will be used instead.
isFull	Boolean	Optional	States whether the current request contains the full connection status information. `true`: Requests for the full connection status information. `relations` must be provided. `false` (default): Does not request for the full connection status information. `relations` can be omitted.
relations	Object	If `isFull` is true, this field is mandatory, if false, this is optional.	Describes the connection information between nodes.
reportTime	Long	Optional	The time when the status was reported. If left blank, it will be set to the server’s time.
method	String	Mandatory	The request method.

Response Parameter Description¶

Parameter	Type	Mandatory/Optional	Description
code	Integer	Mandatory	The return code. “200” indicates that the requested operation is executed successfully.