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

Gateway Requesting for Adding Child Devices

Function

This API is used by a gateway to register new child devices on the platform. For details about the relationship between a gateway and its child devices, see Gateway and Child Devices.

Topic

Upstream: $oc/devices/{device_id}/sys/events/up

Parameters

Parameter

Mandatory/Optional

Type

Description

object_device_id

Optional

String

Explanation:

This parameter is not in use currently and does not need to be set.

services

Mandatory

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_request.

event_time

Optional

String

Explanation:

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

If this parameter is not carried in the reported data or is in incorrect format, the time when the platform receives the data is used.

event_id

Optional

String

Explanation:

Uniquely identifies an event. If this parameter is not carried, an event ID will be generated by the platform. An event ID is a random string of 36 characters consisting of letters, numbers, and hyphens (-).

paras

Mandatory

Object

Explanation:

Event parameters in JSON format.

paras structure

Parameter

Mandatory/Optional

Type

Description

devices

Mandatory

List<DeviceInfo>

Explanation:

List of child devices to add. Up to 50 child devices can be added at a time.

DeviceInfo structure

Parameter

Mandatory/Optional

Type

Description

parent_device_id

Optional

String

Explanation:

ID of the parent device, that is, the gateway.

node_id

Mandatory

String

Explanation:

Indicates the node ID.

device_id

Optional

String

Explanation:

Device ID, which uniquely identifies a device. If this parameter is carried, the platform will use the parameter value as the device ID. Otherwise, the platform will allocate a device ID, which is in the format of [product_id]_ [node_id].

name

Optional

String

Explanation:

Device name.

description

Optional

String

Explanation:

Device description.

product_id

Mandatory

String

Explanation:

Uniquely identifies the product associated which the device. The value is allocated by the platform after the product model is imported to the IoTDA console.

extension_info

Optional

Object

Explanation:

Indicates the device extended information, which can be customized. The maximum size of the value is 1 KB.

Example

Topic: $oc/devices/{device_id}/sys/events/up 
Data format:
{
   "object_device_id": "{object_device_id}",
   "services": [
    {
      "service_id": "$sub_device_manager",
      "event_type": "add_sub_device_request",
      "event_time": "20151212T121212Z",
      "event_id": "40cc9ab1-3579-488c-95c6-c18941c99eb4",
      "paras": {
        "devices": [
          {
            "name": "subdevice11",
            "node_id": "subdevice11",
            "product_id": "c6b39067b0325db34663d3ef421a42f6",
            "description": "subdevice11"
          },
          {
            "name": "subdevice12",
            "node_id": "subdevice12",
            "product_id": "c6b39067b0325db34663d3ef421a42f6",
            "description": "subdevice12"
          }
        ]
      }
    }
  ]
}