Help Center/ IoT Device Access/ API Reference/ MQTT or MQTTS API Reference on the Device Side/ Gateway and Child Device Management/ Platform Responding to a Request for Adding Child Devices
Updated on 2024-12-02 GMT+08:00
View PDF
Share

Platform Responding to a Request for Adding Child Devices

Function

This API is used by the platform to respond to a gateway's request for adding child devices. The response is returned within 30 seconds after the platform receives the request and includes a list of child devices that are added. For details about the relationship between a gateway and its child devices, see Gateway and Child Devices.

Topic

Downstream: $oc/devices/{device_id}/sys/events/down

Parameters

Parameter

Mandatory/Optional

Type

Description

object_device_id

Optional

String

Explanation:

The value is the same as that of device_id in the topic.

services

Optional

List<ServiceEvent>

Explanation:

List of services that an event is about.

ServiceEvent structure

Parameter

Mandatory/Optional

Type

Description

service_id

Mandatory

String

Explanation:

System field.

Value range:

Fixed at $sub_device_manager.

event_type

Mandatory

String

Explanation:

System field.

Value range:

Fixed at add_sub_device_response.

event_time

Optional

String

Explanation:

Event time. UTC time format: yyyyMMdd'T'HHmmss'Z'.

event_id

Mandatory

String

Explanation:

Event ID. The value is used to associate with the corresponding event.

paras

Mandatory

Object

Explanation:

Event parameters in JSON format.

paras structure

Parameter

Mandatory/Optional

Type

Description

successful_devices

Mandatory

List<DeviceInfo>

Explanation:

Details about the child devices that are added.

failed_devices

Mandatory

List<Reason>

Explanation:

Cause for the failure to add child devices.

DeviceInfo structure

Parameter

Mandatory/Optional

Type

Description

parent_device_id

Mandatory

String

Explanation:

Parent device ID.

node_id

Mandatory

String

Explanation:

Indicates the node ID.

device_id

Mandatory

String

Explanation:

Device ID.

name

Optional

String

Explanation:

Device name.

description

Optional

String

Explanation:

Device description.

manufacturer_id

Optional

String

Explanation:

Manufacturer ID.

model

Optional

String

Explanation:

Device model.

product_id

Optional

String

Explanation:

Product ID

fw_version

Optional

String

Explanation:

Firmware version.

sw_version

Optional

String

Explanation:

Software version.

status

Optional

String

Explanation:

Indicates the device status.

Value range:

  • ONLINE: The device is online.
  • OFFLINE: The device is offline.
  • INACTIVE: The device is not activated.

extension_info

Optional

Object

Explanation:

Extended device information, which can be customized.

Reason structure

Parameter

Mandatory/Optional

Type

Description

node_id

Mandatory

String

Explanation:

The value is that of node_id of the corresponding device in the corresponding request.

product_id

Mandatory

String

Explanation:

The value is that of product_id of the corresponding device in the corresponding request.

error_code

Mandatory

String

Explanation:

Error code.

error_msg

Mandatory

String

Explanation:

Error description.

Example

Topic: $oc/devices/{device_id}/sys/events/down  
Data format:
{
  "object_device_id": "{object_device_id}",
  "services": [
    {
      "service_id": "$sub_device_manager",
      "event_type": "add_sub_device_response",
      "event_time": "20151212T121212Z",
      "event_id": "40cc9ab1-3579-488c-95c6-c18941c99eb4",
      "paras": {
          "successful_devices": [
          {
            "device_id": "c6b39067b0325db34663d3ef421a42f6_subdevice11",
            "name": "subdevice11",
            "node_id": "subdevice11",
            "product_id": "c6b39067b0325db34663d3ef421a42f6",
            "description": "subdevice11",
            "manufacturer_id": "ofo",
            "model": "twx2",
            "fw_version": null,
            "sw_version": null,
            "status": "ONLINE",
            "extension_info" : null,
            "parent_device_id" : null
          }
        ],
        "failed_devices": [
          {
            "node_id": "subdevice12",
            "product_id": "c6b39067b0325db34663d3ef421a42f6",
            "error_code": "XXX",
            "error_msg": "XXXX"
          }
        ]
 
      }
    }
  ]
}