Device Management

Last Updated on : 2024-08-20 03:34:08download

This topic describes how to call the following API operations to query information about your devices.

Request method	API	Description
PUT	/v1.0/illumination/device/{deviceSaasId}/name	Modify the device name.
GET	/v1.0/illumination/devices	Get a list of devices.
GET	/v1.0/illumination/devices/{deviceSaasId}/detail	Query the details of a single device by device ID.
GET	/v1.0/illumination/devices/unassignedRoom	Get a list of unassigned devices.
GET	/v1.0/illumination/devices/roomstate/{roomId}	Query the status of devices in a room.
POST	/v1.0/illumination/device/relations/save	Assign a device to a space.

Modify a device name

API description

Modify the name of a device.

API endpoint

PUT /v1.0/illumination/device/{deviceSaasId}/name

Request parameter

Parameter name	Type	Parameter type	Description	Required
deviceSaasId	String	url	The device ID.	true
name	String	url	The device name.	true

Return parameter

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-bit timestamp.
result	Object	The returned result.

Description of result parameter

ResponseVO{}

Sample request

{
  "name": "The device name",
  "deviceSaasId": "The device ID"
}

Sample response

ResponseVO{}

Get a list of devices

API description

Get a list of device information on pages according to the specified criteria.

API endpoint

GET /v1.0/illumination/devices

Request parameter

Parameter	Type	Type	Description	Required
projectId	String	body	The project ID.	No
roomId	String	body	The room ID.	Yes
roomType	int	body	The room type.	Yes
page	int	body	The page number starting from `1`.	Yes
pageSize	int	body	The number of entries per page. Valid values: 0 to 100.	Yes
deviceStatus	String[]	body	The device status. Valid values: EXPIRING EXCEPTION ONLINE OFFLINE	No

Return parameter

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-bit timestamp.
result	Object	The returned result.

Description of result parameter

{
  "total": "int",
  "list": [
    {
      "deviceSaasId": "String // The unique ID of the commercial lighting device.",
      "deviceId": "String // The device ID. Each device ID corresponds with one hardware device. Because the device is re-bound to a new point, the device ID is not unique.",
      "deviceName": "String // The device name.",
      "deviceType": "String // The device type. For more information, see `DeviceTypeEnum`.",
      "deviceTypeValue": "int // The value of the device type. For more information, see `DeviceTypeEnum`.",
      "topCategory": "String // The major category of the product. For more information, see the type description of `ProductCategoryEnum`.",
      "devicePower": "double // The device power.",
      "deviceStatus": "The device status. Valid values: `NORMAL`, `OFFLINE`, `EXPIRING`, and `EXCEPTION`.",
      "installTime": "long // The installation time of the device.",
      "activeTime": "long // The active time of the device.",
      "productId": "String // The device category (product) ID.",
      "projectId": "String // The project ID",
      "roomId": "String // The ID of the room to which the device belongs.",
      "roomName": "String // The name of the room to which the device belongs.",
      "ownerId": "String // The ID of the home group to which the device belongs",
      "properties": [
        {
          "dpId": "Integer // The DP ID.",
          "dpCode": "String // The DP code.",
          "dpName": "String // The DP name.",
          "dpValueStd": "String // The current DP value.",
          "property": {
            "range": "String[] // The value range of the attribute."
          },
          "propertyDetail": {},
          "mode": "String // The mode such as `ro` and `rw`. This feature is added to v1.4.3.",
          "dpFrom": "String"
        }
      ],
      "masterGroupJoinStatus": "int // Indicates whether the device has joined the main group. Valid values: `0`: no. `1`: yes. `2`: a non-lighting device that has not joined the main group.",
      "currentBrightness": "int // The brightness threshold of the room to which the device belongs.",
      "supportGroup": "boolean // Check whether the device can be grouped.",
      "switchStatus": "boolean // The switch status.",
      "switchDpCode": "String // The switch DP code.",
      "colourValue": "String // The color value.",
      "brightPercentValue": "String // The brightness percentage value."
      "iconUrl": "String // The icon of a device.",
    }
  ]
}

Sample request

{
  "pageSize": "The number of items per page",
  "page": "The page number"
  "projectId": "The project ID",
  "roomId": "The room ID",
  "roomType": "The room type",
  "deviceStatus": "The device status"
}

Sample response

{
  "total": "int",
  "list": [
    {
      "deviceSaasId": "String // The unique ID of the commercial lighting device",
      "deviceId": "The device ID. Each device ID corresponds with one hardware device. Because the device is re-bound to a new point, the device ID is not unique here",
      "deviceName": "The device name",
      "deviceType": "The device type. For more information, see `DeviceTypeEnum`.",
      "deviceTypeValue": "The value of the device type. For more information, see `DeviceTypeEnum`.",
      "topCategory": "The major category of the product. For more information, see the type description of `ProductCategoryEnum`.",
      "devicePower": "The device power",
      "deviceStatus": "The device status. Valid values: `NORMAL`, `OFFLINE`, `EXPIRING`, and `EXCEPTION`.",
      "installTime": "The installation time of the device",
      "activeTime": "The active time of the device",
      "productId": "The device category (product) ID",
      "projectId": "The project ID",
      "roomId": "The ID of the room to which the device belongs",
      "roomName": "The name of the room to which the device belongs",
      "pointId": "The ID of the point where the device is located",
      "ownerId": "The ID of the home group to which the device belongs",
      "properties": [
        {
          "dpId": "The DP ID",
          "dpCode": "The DP code",
          "dpName": "The DP name",
          "dpValueStd": "The current DP value",
          "property": {
            "range": "The value range of the attribute"
          },
          "propertyDetail": {},
          "mode": "The mode such as `ro` and `rw`. This feature is added to v1.4.3.",
          "dpFrom": "String"
        }
      ],
      "masterGroupJoinStatus": "Indicates whether the device has joined the main group. Valid values: `0`: no. `1`: yes. `2`: a non-lighting device that has not joined the main group",
      "currentBrightness": "The brightness threshold of the room to which the device belongs",
      "supportGroup": "Check whether the device can be grouped",
      "switchStatus": "The switch status",
      "switchDpCode": "The switch DP code",
      "colourValue": "The color value",
      "brightPercentValue": "The brightness percentage value"
      "iconUrl": "The icon of a device",
      "pointDeviceType": "The device type on the location map",
      "switchCount": "int",
      "dpFrom": "String"
    }
  ]
}

Get the details of a single device

API description

Get the details of a single device by deviceSaasId.

API endpoint

GET /v1.0/illumination/devices/{deviceSaasId}/detail

Request parameter

Parameter	Type	Type	Description	Required
deviceSaasId	String	url	The device ID.	Yes

Return parameter

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-bit timestamp.
result	Object	The returned result.

Description of result parameter

The parameters are the same as the API operation that returns the device list.

Sample request

{
  "deviceSaasId": "The device ID"
}

Sample response

The parameters are the same as the API operation that returns the device list.

Get a list of unassigned devices

API description

Query the list of devices that are not allocated space under the project.

API endpoint

GET /v1.0/illumination/devices/unassignedRoom

Request parameter

Parameter	Type	Type	Description	Required
page	int	body	The page number starting from `1`.	No
pageSize	int	body	The number of entries per page. Valid values: 1 to 100.	No
projectId	String	body	The project ID.	Yes
deviceStatus	String[]	body	The device status. Valid values: EXPIRING EXCEPTION ONLINE OFFLINE	No
deviceTypes	int[]	body	The device type. Valid values: `-1`: others `0`: smart light `1`: gateway `2`: non-smart light `3`: switch `4`: sensor	No

Return parameter

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-bit timestamp.
result	Object	The returned result.

Description of result parameter

The parameters are the same as the API operation that returns the device list.

Sample request

{
  "pageSize": "The number of items per page",
  "page": "The page number"
  "projectId": "The project ID",
  "topCategories": "The code of the list of devices based on the status (electrical products: `dgzm`, lighting products: `zm`, small home appliances: `xjd`, security sensor: `jjaf`, gateway and central control: `wgzk`, and other categories: `qt`)",
  "deviceName": "The device name",
  "roomId": "The room ID",
  "deviceStatus": "The list of devices based on the status"
}

Sample response

The parameters are the same as the API operation that returns the device list.

Query the status of devices in a room

API description

Query the status of devices in a room. This feature is added to v1.4.3.

API endpoint

GET /v1.0/illumination/devices/roomstate/{roomId}

Request parameter

Parameter	Type	Type	Description	Required
roomId	String	url	The room ID.	Yes

Return parameter

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-bit timestamp.
result	Object	The returned result.

Description of result parameter

{
  "properties": [
    {
      "dpCode": "String // The DP code.",
      "dpName": "String // The DP name.",
      "dpValueStd": "String // The current DP value.",
      "property": {
        "range": "String[] // The value range of the attribute."
      },
      "propertyDetail": {},
      "mode": "String // The mode such as `ro` and `rw`. This feature is added to v1.4.3",
      "dpFrom": "String"
    }
  ],
  "count": {
    "total": "long // The total number of devices",
    "online": "long // The number of online devices",
    "offline": "long // The number of offline devices",
    "expiring": "long // The number of the replaced alarm devices",
    "exception": "long // The number of the DP alarm devices"
  }
}

Sample request

{
  "roomId": "The room ID",
}

Sample response

{
  "properties": [
    {
      "dpCode": "The DP code",
      "dpName": "The DP name",
      "dpValueStd": "The current DP value",
      "property": {
        "range": "The value range of the attribute"
      },
      "propertyDetail": {},
      "mode": "The mode such as `ro` and `rw`. This feature is added to v1.4.3",
      "dpFrom": "String"
    }
  ],
  "count": {
    "total": "The total number of devices",
    "online": "The number of online devices",
    "offline": "The number of offline devices",
    "expiring": "The number of replaced alarm devices",
    "exception": "The number of DP alarm devices"
  }
}

Assign a device to space

API description

Assign a specified device to a specified space.

API endpoint

POST /v1.0/illumination/device/relations/save

Request parameter

Parameter name	Type	Parameter type	Description	Required
projectId	String	body	The project ID	Yes
roomId	String	body	The space ID. The value is `0` for an unassigned space.	Yes
deviceIds	List	body	The list of device IDs.	Yes

Return parameter

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-bit timestamp.
result	Object	The returned result.

Description of result parameter

{
  "expiredSeconds": "The remaining seconds before the task expires. The task will expire after this duration.",
  "taskId": "The number of device status"
}

Sample request

{
  "deviceIds": "The list of device IDs",
  "projectId": "The project ID",
  "roomId": "The space ID. The value is `0` for an unassigned space."
}

Sample response

{
  "expiredSeconds": "The remaining seconds before the task expires. The task will expire after this duration.",
  "taskId": "The number of device status"
}

Error code

The following table describes common error messages for this interface. For more errors, see Global Error Codes.

Error code	Description
500	A system error has occurred while processing your request.

Prev DocDevice Management and Control

Next DocDevice Control