Device Management

Last Updated on : 2022-06-27 09:27:21download

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/devices/{deviceId}/resetGateway Remove a device.
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 10,000. 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.",
      "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",
      "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 10,000. 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"
  }
}

Remove a device

API description

Remove a specified device by device ID.

API endpoint

POST /v1.0/illumination/devices/{deviceId}/resetGateway

Request parameter

Parameter Type Type Description Required
deviceId String url The device ID. Yes
projectId String body The project 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

{
  "action": "Removed a device successfully"
  "message": "SUCCESS"
}

Sample request

{
  "projectId": "The project ID",
}

Sample response

{
  "action": "Removed a device successfully",
  "message": "SUCCESS"
}

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.