得力云开放文档中心

# 协议介绍

设备在通过设备平台接入指南接入平台成功后，为了完成设备与平台以及应用的业务通信，得力云平台定义了设备指令集，不同的指令代表不同的设备功能。

所有的指令采用统一的JSON数据格式定义，指令消息结构如下：

{
    "mid": "消息ID", 
    "from": "发送方ID",
    "to": "接收方ID",
    "time": 时间戳, 
    "action": 指令,
    "pv": "1.0",
    "data": {
        ......
    }
}
1
2
3
4
5
6
7
8
9
10
11
请求参数 格式 必传 参数说明
mid 字符串 Y 消息ID，长度不超过32位，用于唯一标示一条消息。
注意，对于一个消息上下文的请求和响应，应使用相同的mid，用于表示其关联性。
from 字符串 Y 消息的发送方ID
to 字符串 Y 消息的接受方ID
time 整型 Y 消息发送的时间戳(秒)
action 整型 Y 平台指令，不同的指令代表不同的平台业务功能
pv 字符串 N 协议版本，可选字段，默认1.0
data JSON对象 N 平台指令关联的业务数据，不同的平台指令数据结构不同

如果发送方from或接收方to是平台(非设备和应用)，请使用平台的唯一IDsystem，否则应使用设备或应用在平台注册的唯一ID。

注意

所有指令消息中值为NULL的信息，为了节省传输大小，平台会自动将其从序列化JSON字符串中去除。因此，设备在解析指令消息时，对于可选信息一定要做判空处理，避免出现NPE。
另外，协议在未来升级过程中会保持向下兼容性，但不排除增加新的字段信息，设备务必要保持向下兼容性。

目前和设备相关的指令集action设计如下：

  • 1xx指令：设备对得力云平台主动发起的请求指令；
  • 2xx指令：得力云平台对设备主动发起的请求指令；
  • 3xx指令：设备与应用之间通信的通用指令；

不同指令类型的通信流程示意如下：

uml diagram

关于指令上下文

逻辑上，为了完成同一个业务操作发送的请求和响应指令，应归属于一个指令消息上下文。

对于归属于同一个消息上下文的指令，必须使用相同的mid标识，如果请求指令超时未收到响应，在重复请求时，也应保持mid不变。

另外，如无特别说明，对于等待响应结果的指令请求而言，设备等待超时时间建议设置为60s，如果超时未收到响应，可以尝试重发直到收到响应为止。

下面会根据设备功能分别对不同的平台指令进行描述。

# 指令清单

通过以下指令清单快速检索所有开放可用的设备功能指令。

指令 指令名称 指令描述
1 请求设备激活指令 对于未激活的设备，设备向平台请求设备激活的密钥信息。
100 时间同步指令废弃 获取平台时间进行设备本地校准，也可以用于验证平台通信是否正常。
101 设备状态上报指令 将本地状态数据上报到平台。
102 设备配置查询指令 向平台主动查询设备在平台端的最新配置信息。
103 固件查询指令 向平台查询指定版本的固件信息。
104 设备主动解除绑定指令 向平台发起主动解除组织绑定。
105 设备告警上报指令 上报异常告警信息到平台。
108 设备升级进度上报指令 固件升级过程中向平台及时上报设备升级的进度变化。
109 设备数据备份指令 存储设备本地数据到云端进行备份。
110 设备数据恢复指令 将109指令保存在云端的数据恢复到设备本地。
120 文字语音转换指令 向平台请求对文字进行实时语音转换。
121 临时文件上传指令 向平台请求预签名的 OSS 地址用于上传临时文件。
200 设备远程控制 平台远程控制设备进行日志查询、重启、自检等操作。
203 设备绑定更新通知指令 向设备发送绑定状态通知消息，包括绑定和解绑。
204 设备应用关联通知指令 向设备发送设备关联应用更新通知消息。
205 用户授权登录通知指令 下发用户登录授权信息到设备。
206 固件升级指令 向设备发起实时固件升级请求。
300 设备推送消息到应用指令 设备发送消息给关联应用。
301 应用推送消息到设备指令 下发应用消息到设备。

# 指令功能

# 设备激活

  • # 功能描述

为了提高设备接入的安全性，设备在首次接入平台后，应立刻进行设备激活，更新设备接入密钥。

一旦设备完成激活，后续设备接入时，平台将仅支持通过新的设备接入密钥完成接入认证。

设备激活流程示意如下：

uml diagram

  • # 设备激活指令

对于初次接入平台还没有激活的设备，通过调用【1指令】可以从平台获取设备唯一的接入密钥进行后续激活操作。

关于设备接入密钥

设备接入密钥是设备接入安全认证的关键信息，设备激活过程中，平台会为每台设备分配一个唯一的密钥信息，该密钥与设备是一一对应的关系。

一旦设备完成激活，出于安全考虑，平台将不再支持通过本指令再次查询设备接入密钥。因此，设备务必妥善保管该密钥信息，确保不会泄漏或者丢失。

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 0,
    "action": 1
}
1
2
3
4
5
6
7

平台收到请求后，会自动为设备分配一个唯一的接入密钥并返回如下响应结果。

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307375, 
    "action": 1, 
    "data": {
        "code": 0,
        "msg": "",
        "access_key": "U2FsdGVkX1+dDls3ALE9vAuL5gvyxXHQKRTM02UT4XCC1TuHBdb9tg=="
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
响应参数 格式 必传 参数说明
access_key 字符串 Y 设备接入密钥，将作为未来再次平台连接认证时的设备接入密钥使用，请妥善保管。

关于平台响应中的code和msg见平台错误码定义，后续不再重复阐述。

注意

设备一旦收到平台分配的设备接入密钥，应立刻断开连接，并使用新的设备接入密钥进行连接认证。平台连接认证成功后，将自动激活设备，后续该设备将不再支持使用产品密钥进行接入认证。

如果在请求过程中，因为网络或其他意外因素导致设备未收到平台的正确响应，设备应按照平台默认的响应超时策略进行重试直到获取到密钥为止。

注意，为了安全考虑，设备一旦使用新的密钥连接激活成功，则建议直接清理掉本地初始产品密钥信息，以防泄漏。

# 时间同步

  • # 功能描述

设备在接入平台之前，必须联网进行本地时间校准，确保本地时间的准确性。

  • # 时间同步指令 废弃

设备通过调用【100指令】可以获取平台时间进行本地校准。

注意

平台提供的时间同步指令功能较为简陋，无法保证设备时间的准确性，现已废弃。如无特殊原因，请设备单独通过实现NTP协议实现精确的时间同步功能。

平台推荐的NTP服务地址是: pool.ntp.org。

由于接入平台后的设备消息通信基本上都会校验时间，因此设备应当在联网成功后第一时间完成NTP时间同步，确保本地时间的准确性。

请求示例如下：

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 0,
    "action": 100
}
1
2
3
4
5
6
7

平台收到请求后，会查询本地时间（time精确到秒），并返回如下响应结果。

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307375, // 平台时间
    "action": 100, 
    "data": {
        "code": 0,
        "msg": ""
    }
}
1
2
3
4
5
6
7
8
9
10
11

注意

除了可用于同步时间外，设备还可以通过本指令的平台响应情况来判断设备与平台指令通信链路是否正常，如果设备等待平台响应超时，则可以视为平台通信链路异常。

为了减少不必要的通信，设备此时应暂停其他指令通信业务，按照平台默认的响应超时策略继续尝试100指令请求直到正常收到平台响应为止。

# 设备状态上报

  • # 功能描述

设备应在本地状态发生变化时及时上报状态信息到平台，以便于用户了解设备状态变化，进行相应的状态管理。

设备本地状态信息主要包括：网络配置、固件版本以及工作状态等等。

提示

为了确保APP端设备状态数据的实时准确性，请设备按照如下规则上报：

  1. 设备每次连接平台成功后（包括临时上下线的情况）主动上报；
  2. 设备本地状态数据发生任何变化时应主动上报；

  • # 设备状态上报指令

设备可通过调用【101指令】将设备本地状态数据上报到平台。

请求示例如下：

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 101,
    "data" : {
        "product_version": "1.0.0",
        "gps": "30.59276,114.30525",
        "mac": "00-01-6C-06-A6-29",
        "local_ip": "192.168.0.3",
        "connect_type": "wifi",
        "simulator": false,
        "status": 0,
        "status_code": "0",
        "status_msg": "正常",
        "properties": {
            "k_1": "v_1",
            "k_2": "v_2"
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
请求参数 格式 必传 参数说明
product_version 字符串 Y 设备当前固件的版本
gps 字符串 N 设备当前的GPS坐标，请返回WGS84坐标系的坐标位置。
local_ip 字符串 Y 设备局域网内的ip地址
mac 字符串 Y 设备网卡MAC地址
connect_type 字符串 Y 设备当前接入网络的方式。包括:cable、wifi、4g等
simulator 字符串 Y 是否模拟器，默认是false。
status 整型 Y 设备当前的工作状态: 0-正常；1-警告但可用；2-故障不可用；3-升级；默认是0。
status_code 字符串 N status对应的设备状态码。当status非0时返回的异常状态代码，由设备自定义。
status_msg 字符串 N status_code对应的设备状态描述
properties 字符串键值对 N 设备自定义的属性集合

平台在收到该请求后，会返回如下响应表示请求已接收。

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 101, 
    "data": {
        "code": 0,
        "msg": ""
    }
}
1
2
3
4
5
6
7
8
9
10
11

如果消息处理出现异常，会通过code和msg反馈给设备。具体错误码定义见平台错误码。

注意

  1. 为了确保平台能够收到设备的状态变更信息，如果设备在发送本指令后等待平台响应超时，设备应按照平台默认的响应超时策略继续尝试直到收到平台响应为止。
  2. 设备发送版本号字符不能超过32位。

# 设备配置查询

  • # 功能描述

平台端会对设备进行一些配置和管理，包括：设备产品配置、组织及应用配置、固件升级配置等等。通过本功能设备可以实时获取最新的平台端设备配置信息。

提示

关于组织及应用配置说明如下：

一台接入得力云平台的智能设备被用户通过E+APP添加到账户后，需要经过组织绑定、应用配置两个基础流程后方能投入使用。具体细节请参考【设备绑定激活】和【设备应用通信】的功能描述。

另外，为了确保设备本地实时保持和平台一致的配置数据，请设备按照如下规则触发查询：

  1. 设备每次连接平台成功后（包括临时上下线的情况）主动上报；
  2. 定时进行查询，定时周期至少1小时一次；

  • # 设备配置查询指令

设备可通过调用【102指令】向平台主动查询设备在平台端的最新配置信息。

请求示例：

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 102
}
1
2
3
4
5
6
7

  • # 响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 102, 
    "data": {
        "code": 0,
        "msg": "",
        "status": 1,
        "name": "3960CT测试设备",
        "icon": "http://file.delicloud.com/product/3960CT.jpg",
        "last_access": 1561391999,
        "bound": true,
        "organization": {
            "org_id": "123513772057952257",
            "name": "得力集团"
        },
        "product_version": "1.1.0",
        "app_ids": ["492731092441235453"]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
响应参数 格式 必传 参数说明
status 整型 N 已废弃字段，用于标示设备是否被禁用
name 字符串 Y 设备名称。默认是产品名称，用户可设置自定义名称
icon 字符串 Y 设备对应的产品图标URL
bound Boolean Y 是否已绑定到组织。true表示已绑定，否则未绑定
organization JSON对象 N 设备绑定的组织基本信息，如果未绑定(bound为false)则不返回。包括:
org_id: 组织ID；
name: 组织名称；
product_version 字符串 N 设备当前可升级的最新固件版本。如果没有可升级版本，则不返回。
last_access 整型 N 设备上次接入时间（精确到秒), 初次接入为0
app_ids JSON数组 Y 设备关联的应用ID列表，目前仅支持关联1个应用

注意

为了确保设备能够获取到平台端的最新设备信息，如果设备在发送本指令后等待平台响应超时，设备应按照平台默认的响应超时策略继续尝试直到收到平台响应为止。

设备的绑定状态是否要切换，以102指令响应为准。

# 设备绑定激活

  • # 功能描述

一台接入得力云平台的智能设备在正式投入使用之前，需要完成如下初始化流程：

也就是说，设备必须绑定到一个组织并指定了关联的应用才算是正式激活成功，可以投入使用。具体操作流程参考得力E+帮助文档 (opens new window)。

另外，与绑定激活对应的就是解绑，当设备所有者不再使用设备或者转让给别人使用时，可以解除设备绑定。解除绑定后，设备将恢复成未激活状态，可重新绑定新的用户和组织。

一台设备同一时刻只能绑定一个用户组织。

注意

如果设备被解除了绑定，那么原绑定组织在该设备上发生的历史数据应该被清理掉。但是，为了确保原组织未上传到平台的重要业务数据不会丢失（例如考勤机的离线打卡记录），在设备被解绑后，一定要主动检查本地是否存在某些未上传到平台的重要业务数据，并在上传完成后再做清理。

  • # 设备绑定更新通知指令

当设备在平台端的组织绑定关系发生变化时，平台会通过【203指令】向设备发送绑定状态通知消息，包括绑定和解绑。

请求示例如下：

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 203,
    "data": {
        "org_id": "411549919082446848",
        "name": "测试组织",
        "status": 0
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
请求参数 格式 必传 参数说明
org_id 字符串 Y 设备关联的组织ID
name 字符串 Y 组织名称
status 整型 Y 绑定状态。0-已解绑，1-已绑定

设备收到消息后，应在同一个上下文回复确认消息，明确告知平台已收到通知。

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 203
}
1
2
3
4
5
6
7

注意

考虑到消息传递顺序的不确定性，请设备收到203指令通知后，通过【设备配置查询指令】 102 主动查询最新的组织绑定信息bound和organization。

指令调用流程示意如下：

uml diagram

关于解绑和绑定具体内容

设备在收到203通知后，应在同一上下文立即回复203响应，并且发起【设备配置查询指令】 102 请求，收到102响应后请按照如下规则处理请求：

  1. 设备当前未绑定，收到102响应里返回bound为false，organization为空，要立即刷新设备绑定二维码。
  2. 设备当前未绑定，收到102响应里返回bound为true，organization不为空，则要处理绑定。
  3. 设备当前已绑定，收到102响应里返回bound为false，organization为空，则要处理解绑。然后刷新设备绑定二维码。
  4. 设备当前已绑定，收到102响应里返回bound为true，organization不为空，且组织ID相同，则忽略。
  5. 设备当前已绑定，收到102响应里返回bound为true，organization不为空，且组织ID不相同，则要处理先解绑并再次绑定。

  • # 设备主动解除绑定指令（禁用）

通过【104指令】设备可向平台发起主动解除组织绑定的请求，请求成功后，平台会解除设备和当前组织的绑定关系，设备恢复为未激活的状态。

警告

解除绑定成功后，平台会自动清理设备在绑定组织的关联数据，且该操作不可逆。
由于该操作不涉及平台鉴权，存在一定的危险性，该指令仅因为兼容早期设备保留，请勿使用。

请求示例如下：

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 104,
    "data": {
        "org_id": "325584307028705280"
    }
}
1
2
3
4
5
6
7
8
9
10
请求参数 格式 必传 参数说明
org_id 字符串 Y 当前绑定的组织ID

平台在收到该请求后，会返回如下响应表示请求已接收。

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 104, 
    "data": {
        "code": 0,
        "msg": ""
    }
}
1
2
3
4
5
6
7
8
9
10
11

如果消息处理出现异常，会通过code和msg反馈给设备。具体错误码定义见平台错误码。

注意

平台返回的104指令响应仅表示请求是否被接收成功，并不代表平台已完成了设备和组织的解绑，请以平台【设备绑定更新通知指令】响应结果为准。

# 设备应用通信

  • # 功能描述

得力云平台作为平台方，并不会直接实现特定业务场景的业务功能，而是通过分别与设备和应用进行对接，建立设备与应用之间的通信通道来支持设备与应用在平台完成业务交互。

我们在设备绑定激活功能描述中已经对此进行了简单阐述，其中【配置设备关联的应用】环节就是这一过程。

设备与应用通信建立流程示意如下：

uml diagram

一旦用户在平台端完成了设备与应用的关联配置，设备与应用就可以使用平台的消息指令通道进行相互通信。

  • # 设备应用关联通知指令

设备在初始化流程中一旦设置了关联的应用，平台就会通过【204指令】下发设备关联应用的通知消息。

提示

【203指令】和【204指令】通知都是在设备绑定初始化过程中由平台发送到设备端。
设备收到【204指令】后，也应该按照【203指令】相同方式进行处理：即通过【设备配置查询指令】主动查询下设备最新关联的应用配置信息app_ids。

请求示例如下：

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 204,
    "data": {
        "app_id": "411549919082446848",
        "name": "测试应用",
        "icon": "http://file.delicloud.com/testapp.jpg",
        "status": 0
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
请求参数 格式 必传 参数说明
app_id 字符串 Y 设备关联的应用ID
name 字符串 N 应用名称，仅在绑定时返回
icon 字符串 N 应用图标URL，仅在绑定时返回
status 整型 Y 绑定状态。0-已解绑，1-已绑定

设备收到消息后，应在同一个上下文回复确认消息，明确告知平台已收到通知。

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 204
}
1
2
3
4
5
6
7

  • # 设备推送消息到应用指令

所有从设备端发送到应用的请求或响应消息都通过【300指令】完成，平台收到该指令请求后会自动转发推送给应用系统进行处理。

提示

所有发送给应用的指令消息，应设置正确的目标应用IDto，否则会被平台拒收。应用ID可通过【设备配置查询指令】响应结果中app_ids获取。

如果设备本地未能存储目标应用ID，也可以设置为空字符串，交由平台自动判断（1对1关联时支持）。

另外，为了进一步区分不同业务场景下的业务指令，平台针对【300指令】额外定义了cmd和paylod消息字段用于自定义扩展。

请求示例如下：

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "411549919082446848",
    "time": 1555307375, 
    "action": 300,
    "data": {
        "cmd": "checkin",
        "payload": {
            "users":[
                {
                    "user_id":"450940540930752512",
                    "check_type":"fp",
                    "check_time":1557211726
                }
            ]
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
请求参数 格式 必传 参数说明
cmd 字符串 Y 设备发起的自定义业务请求命令
payload JSON对象 N 具体的业务请求数据。根据cmd的不同结构不同，由具体的业务协议定义

如果应用需要响应，请在同一个消息上下文使用应用推送消息到设备指令返回。

  • # 应用推送消息到设备指令

平台定义了【301指令】专门用于转发来自应用端的设备相关消息，其消息格式与设备推送消息到应用指令基本一致。

请求示例如下：

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 301,
    "data": {
        "cmd": "checkin",
        "payload": {
            
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
请求参数 格式 必传 参数说明
cmd 字符串 Y 应用下发到设备的自定义业务指令
payload JSON对象 N 具体的业务请求数据。根据cmd的不同结构不同，由具体的业务协议定义

如果设备需要响应，请在同一个消息上下文使用设备推送消息到应用指令返回。

# 设备固件升级

  • # 功能描述

如果某个型号的设备固件程序因为功能更新或者bug修正需要进行升级，平台支持通过管理平台发布新的固件通知设备进行OTA升级。

提示

固件升级的设备范围由平台根据升级策略来决定，设备不需要实现。也就是说，设备如果能够收到固件升级通知或能够主动查询到可升级的固件版本，意味着设备可以进行升级。

目前平台支持两种模式的固件升级：自动升级和手动升级。分别介绍如下：

  • # 自动升级

对于使用自动升级模式的设备，升级过程中无用户确认过程，设备需要定时检测是否有可升级的固件版本。一旦发现有新版本，即可自动启动固件升级流程。

对于自动升级的情况下，为了确保设备最终会升级成功，即便升级失败（包括主动取消），后续设备也应按照合适的策略再次触发升级。但考虑到不停的循环升级会导致设备不可用，升级失败后再次触发的时间间隔不要低于1小时。

自动升级流程示意如下:

uml diagram

关于固件下载

为了避免大量设备在同一时间下载固件造成网络堵塞，请使用自动升级模式的设备不要在固定时间点同时进行固件下载，可以考虑在一个时间范围进行随机启动下载😄。

  • # 手动升级

对于使用用户手动升级模式的设备，仅当设备收到来自用户确认升级的指令后，方可启动固件升级流程。

对于手动升级的情况下，一旦升级失败（包括主动取消）且重试次数耗尽，升级流程应自动终止，直到用户再次发起升级流程。

手动升级流程示意如下:

uml diagram

提示

为了提高升级效率，不论是哪种升级模式，设备都应该提前在后台对固件文件进行下载（不影响用户使用的前提下），避免因为固件下载时间不确定导致的升级风险和体验性问题。

  • # 固件查询指令

设备可通过【103指令】向平台查询指定版本的固件信息。如果请求中未包含查询版本信息，则默认查询设备最新可升级固件版本的信息。

请求示例如下：

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 103,
    "data": {
        "version": "1.1.0"
    }
}
1
2
3
4
5
6
7
8
9
10
请求参数 格式 必传 参数说明
version 字符串 N 当前查询的固件版本号，如果未输入，则默认查询最新设备可升级的固件版本信息

平台收到请求后会返回如下响应。如果查询固件不存在，data内的固件信息不存在，设备要做好判空。

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 103, 
    "data": {
        "code": 0,
        "msg": "",
        "version": "1.1.0",
        "upgrade_type": "force",
        "file_path": "http://file.delicloud.com/xxx.zip",
        "checksum": "4c56ff4ce4aaf9573aa5dff913df997a",
        "size": 1231,
        "update_time": 1555307488,
        "description": "解决了设备xx指令响应不正确的问题"
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
响应参数 格式 必传 参数说明
version 字符串 Y 设备当前可升级的最新固件版本。
upgrade_type 字符串 Y 升级方式。保留字段，暂时未实现，可忽略
file_path 字符串 Y 固件文件的http下载地址
checksum 字符串 Y 固件的MD5值，用于下载后文件完整性校验。
size 整型 Y 文件的尺寸大小，单位是字节。
update_time 整型 Y 发布时间戳（精确到秒）
description 字符串 N 固件发布说明

注意

当设备查询到新的固件并下载完成后，请务必通过checksum校验下载文件的完整性。

为了尽可能提高升级的成功率，不论是下载过程中失败或者是校验文件失败，设备都应进行一定次数的重试，重试次数不要低于3次。

  • # 固件升级指令

对于用户手动升级的场景，用户一旦确认对指定设备进行升级，平台会通过【206指令】向设备发起实时固件升级请求。设备收到请求后，应主动调用固件查询指令查询升级固件版本信息，并启动本地升级流程。

请求示例如下：

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 206,
    "data": {
        "version": "1.1.0"
    }
}
1
2
3
4
5
6
7
8
9
10
请求参数 格式 必传 参数说明
version 字符串 Y 通知设备升级的最新固件版本

设备收到消息后，应在同一个上下文回复确认消息，明确告知平台已收到通知。

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 206
}
1
2
3
4
5
6
7

  • # 设备升级进度上报指令

设备进入升级状态后，可通过【108指令】向平台及时上报设备升级的进度变化。

请求示例如下：

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 108,
    "data": {
        "version":"1.1.0",
        "step": 0,
        "status": 0,
        "progress": 80,
        "error": ""
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
请求参数 格式 必传 参数说明
version 字符串 Y 当前设备升级的版本号
step 整型 Y 升级阶段。包括：0-等待用户确认，1-下载固件；2-本地升级。
其中，状态0是可选状态，仅在设备支持用户二次确认时使用
status 整型 Y 升级状态。0-执行中；1-执行成功；2-执行失败；3-主动取消；
progress 整型 N 升级进度[0～100]。对于支持进度显示的设备，可在升级过程中返回升级进度百分值
error 字符串 N 执行失败的错误消息。该信息仅在升级失败时返回

关于上报升级进度

设备在启动升级流程后，请按照如下规则上报进度：

  1. 如果需要在设备端进行用户确认，返回step为0，status为0，progress为0。

    • 如果用户确认执行，返回step为0，status为1；
    • 如果用户确认不执行，返回step为0，status为3；
    • 如果等待用户确认超时（建议等待时间不低于60s），返回step为0，status为2，error返回确认超时；

  2. 如果固件进入下载阶段，返回step为1，status为0，progress为0。

    • 下载过程中，返回step为1，status为0，然后通过progress上报下载完成进度（0～100）；
    • 如果下载失败，返回step为1，status为2，error返回具体失败原因；
    • 如果下载完成但本地文件校验失败，返回step为1，status为2，error返回文件校验失败；
    • 如果下载过程中，用户主动取消下载（必须设备支持），返回step为1，status为3；
    • 如果下载完成且本地文件校验通过，返回step为1，status为1，progress为100；

  3. 如果开始启动本地升级（固件已下载完毕），返回step为2，status为0，progress为0。

    • 如果设备支持升级进度上报，返回step为2，status为0，然后通过progress返回升级完成进度（0～100）；
    • 如果升级过程因为异常出现失败，返回step为2，status为2，error返回具体失败原因。如果升级失败后重试，那么状态也应重置；
    • 如果升级过程中，用户主动取消升级，返回step为2，status为3；
    • 如果升级已完成，返回step为2，status为1，progress为100；

另外，为了避免上报过于频繁，设备应控制上报频率，例如2s/次，或根据进度变化进行上报。

平台在收到该请求后，会返回如下响应表示请求已接收。

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 108, 
    "data": {
        "code": 0,
        "msg": ""
    }
}
1
2
3
4
5
6
7
8
9
10
11

如果消息处理出现异常，会通过code和msg反馈给设备。具体错误码定义见平台错误码。

# 设备告警上报售后指令

  • # 功能描述

为了帮助售后人员在客户设备出现故障时，能够及时远程发现问题，设备应实现本功能在出现运行告警或故障时及时上报告警信息。

注意

请设备开发者仅在设备出现运行异常时上报关键错误信息，不要将所有错误日志都上报上来，造成上报数据量过多的问题。

另外，该功能上报结果不会直接显示在UI上，如果设备工作状态出现用户需要关注的异常，请使用【设备状态上报指令】。

  • # 设备告警上报指令

设备可以通过【105指令】上报异常告警信息，用于平台监控设备的运行状态。

请求示例如下：

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 105,
    "data": {
        "code": 100,
        "msg": "设备网络状况较差，丢包率50%",
        "severity": "0"
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
请求参数 格式 必传 参数说明
code 整型 Y 自定义异常告警代码
msg 字符串 Y 自定义异常告警消息。请返回详细的异常告警原因，用于售后服务定位
severity 整型 N 严重级别, 缺省是0。包括：
0：一般。指一些轻微的或不影响设备正常使用的故障或异常，例如设备温度过高，网络抖动等;
1：严重，指那些影响设备正常使用，可能需要通过售后维修或升级来解决的故障或异常，例如程序运行错误、功能异常、硬件故障等等；

平台在收到该请求后，会返回如下响应表示请求已接收。

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 105, 
    "data": {
        "code": 0,
        "msg": ""
    }
}
1
2
3
4
5
6
7
8
9
10
11

如果消息处理出现异常，会通过code和msg反馈给设备。具体错误码定义见平台错误码。

# 设备远程控制售后指令

  • # 功能描述

为了帮助售后人员能够在设备出现故障时，远程协助客户实时定位并恢复故障，平台提供了【200指令】用于远程控制设备，通过不同的cmd和payload可以实现不同的控制功能。

  • # 日志查询指令

通过本指令平台可以远程读取设备本地日志，用于故障分析。

请求示例如下：

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 200,
    "data": {
        "cmd": "log",
        "payload": {
            "day": "2019-10-14",
            "time_begin": "08:00",
            "time_end": "13:50"
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

其中cmd等于log表示日志查询指令。

请求参数 格式 必传 参数说明
cmd 字符串 Y 设备远程控制命令，固定为log
payload JSON对象 N 命令对应的消息体，不同的命令消息体不同
day 字符串 Y 请求的日志日期，精确到天，格式：yyyy-MM-dd
time_begin 字符串 Y 查询的开始时间，精确到分钟，格式为HH:mm
time_end 字符串 Y 查询的结束时间，精确到分钟，格式为HH:mm

设备收到请求后，应查找本地日志文件并响应如下：

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 200, 
    "data": {
        "cmd": "log", 
        "payload": {
            "day": "2019-10-14",
            "logs": "http://file.delicloud.com/fde4dd7e06a31b907f00181710623636" //也可以直接传递日志字符串
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
响应参数 格式 必传 参数说明
cmd 字符串 Y 固定为log
payload JSON对象 Y 响应结果消息体
day 字符串 Y 与请求日志日期一致
logs 字符串 Y 日志文件下载地址或日志内容字符串。
1. 如果选择上传日志文件（推荐），请通过平台提供的文件上传接口 (opens new window)实现文件上传并上报文件URL，日志文件过期时间固定设置为604800000。
2.如果选择直接返回日志文件内容，为了避免指令消息体过大造成上传失败，请将日志拆分为多次响应返回，每一次返回日志长度不超过256KB；

注意：如果查找时间范围的日志不存在，请返回空字符串。如果不支持精确时间范围筛选，请返回全天的日志文件。

  • # 设备重启指令

通过本指令平台可强制要求设备重启。一般用于设备死机或者异常运行状态下的售后恢复使用。

请求示例如下：

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 200,
    "data": {
        "cmd": "reboot"
    }
}
1
2
3
4
5
6
7
8
9
10

其中，cmd等于reboot表示设备重启指令。

请求参数 格式 必传 参数说明
cmd 字符串 Y 设备远程控制命令，固定为reboot

设备收到消息后，应在同一个上下文回复确认消息，明确告知平台已收到通知，然后重启设备。

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 200, 
    "data": {
        "cmd": "reboot" 
    }
}
1
2
3
4
5
6
7
8
9
10

  • # 设备自检指令

对于拥有自检功能的设备，通过本命令平台可要求设备进入自检模式，并向平台反馈健康自检结果。

请求示例如下：

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 200,
    "data": {
        "cmd": "health"
    }
}
1
2
3
4
5
6
7
8
9
10

其中，cmd等于health表示设备自检指令。

请求参数 格式 必传 参数说明
cmd 字符串 Y 设备远程控制命令，固定为health

设备收到请求后应进入自检模式，并返回如下自检结果到平台。

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 200, 
    "data": {
        "cmd": "health",
        "payload": {
            "passed": true,
            "details": "ok" 
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
响应参数 格式 必传 参数说明
cmd 字符串 Y 固定为health
payload JSON对象 Y 响应结果消息体
passed Boolean Y 是否自检通过。true表示通过，false表示不通过
details 字符串 N 自检详情。不同设备可根据实际自检项目返回检查明细结果

# 设备数据备份

对于一些容量较小的设备，平台提供了一定的云端存储空间，用于设备临时存储一些本地重要的业务数据，一般用于设备重置等功能场景。

注意

每台设备在云端可存储的数据空间有限，如果超出限额，请求将会失败。具体配额根据产品类型由管理员配置，默认1M，可根据需要申请调整。

  • # 设备数据备份指令

通过调用【109指令】设备可以存储一些本地数据到云端进行备份。

请求示例如下：

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 109,
    "data": {
        "key": "checkin-data-20190701",
        "value": "...",
        "expire": -1
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
请求参数 格式 必传 参数说明
key 字符串 Y 需要存储的数据唯一键，不同的数据应该使用不同键，否则会被覆盖
value 字符串 Y 需要存储的数据值。如果是其他格式的数据，请先做转换。单个值的长度不要超过256k。如果将value设置为空，则视为删除操作
expire 整型 N 过期时间（秒）。缺省是-1，表示永不过期。数据如果过期，会被平台自动清理

平台收到请求后会实时进行存储，并返回存储响应结果如下：

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 109, 
    "data": {
        "code": 0,
        "msg": ""
    }
}
1
2
3
4
5
6
7
8
9
10
11

除通用的平台错误码外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
120 存储空间超出限额 设备存储数据超出平台配额上限

  • # 设备数据恢复指令

对于通过设备数据备份指令保存在云端的设备数据，可以通过【110指令】读取并进行恢复。

请求示例如下：

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 110,
    "data": {
        "key": "checkin-data-20190701"
    }
}
1
2
3
4
5
6
7
8
9
10
请求参数 格式 必传 参数说明
key 字符串 Y 数据KEY，与指令109上传的key保持一致

平台收到请求后会查询key对应的数据，并在同一消息上下文返回如下响应：

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 110, 
    "data": {
        "code": 0,
        "msg": "",
        "value": "..."
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
响应参数 格式 必传 参数说明
value 字符串 N 数据字符串。与指令109上传的value一致。如果key不存在，value则返回空

# 设备临时文件管理

  • # 功能描述

部分设备有上传临时文件的需求，但无法安全持有静态密钥，针对这种场景，平台提供了临时文件上传和下载的功能。

注意

  • 目前仅对 MQTTS 协议的设备开放临时文件上传功能。
  • 对应产品型号需实现 1 指令。
  • 当前指令旨在为设备上传文件到应用提供临时存储空间，文件存储时间和空间均有限制。请不要将其作为长期存储使用。

整个文件管理流程示意如下:

uml diagram

  • # 临时文件上传指令

设备产生文件后，计算文件的长度和MD5，使用【121指令】将信息发送到平台，平台会返回临时文件上传地址和文件ID。

请求示例如下：

{
   "mid": "1",
   "from": "3960CT_1A45678910",
   "to": "system",
   "time": 1555307375,
   "action": 121,
   "data" : {
      "size": 1024,
      "md5sum": ""
   }
}
1
2
3
4
5
6
7
8
9
10
11
请求参数 格式 必传 参数说明
size 整数 Y 文件大小，单位为字节
md5sum 字符串 Y 文件内容计算出 md5 字节数组后，使用 base64 编码字符串

响应示例如下:

{
   "mid": "1", 
   "from": "system", 
   "to": "3960CT_1A45678910", 
   "time": 1555307375, 
   "action": 121, 
   "data": {
      "code": 0, 
      "msg": "", 
      "file_id": "1234567890abcdef", 
      "url": "https://xxxx.delicloud.com/3960CT/3960CT_1A45678910/f817419d-557a-11f0-957b-564d56b23e5d?Expires=1751268308&OSSAccessKeyId=xxxxxxxxxxxxxxxxxxxxxxxxxxxx&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&security-token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "expires_in_seconds": 3600
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
响应参数 格式 必传 参数说明
file_id 字符串 Y 文件 ID，应用可通过此 ID 查询文件
url 字符串 Y 预签名 URL，设备通过该 URL 上传文件（字符串长度不少于 2k）
filename 字符串 Y 文件名
expires_in_seconds 整数 Y 预签名 URL 的有效期，单位为秒

设备使用预签的 URL，向文件服务器通过 PUT 请求上传文件，上传成功后，设备应该将 file_id 通过平台上报给对应云应用。

云应用需要文件时，应该使用云应用接口按需获取文件的临时下载地址。

注意

预签名 URL 有效期极短，仅提供给云应用使用。

应用不应该分发该 URL 给其他用户或设备。

注意

预签名 URL 仅支持 HTTPS 协议。

注意

每个请求中都需要包含如下 Header，每个 Header 必须有且仅有一个 值：

  • Content-Type
  • Content-Length
  • Content-MD5
  • Content-Type 当前固定为 application/octet-stream。
  • 请注意，你需要手动的添加 Content-MD5 Header。

不要对十六进制字符串做 Base64，要对原始的 MD5 二进制字节摘要 做 Base64

请求示例：

# curl 会为带 -d（--data-binary） 的请求自动添加合适的 Content-Length
curl -X PUT "https://xxxx.delicloud.com/3960CT/3960CT_1A45678910/f817419d-557a-11f0-957b-564d56b23e5d?Expires=1751268308&OSSAccessKeyId=xxxxxxxxxxxxxxxxxxxxxxxxxxxx&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&security-token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/octet-stream" \
-H "Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==" \
--data-binary "@/path/to/example.txt"
1
2
3
4
5

注意

HTTP 状态码为 200 时，表示上传成功，客户端请勿对响应体进行处理。

如果上传失败，请检查 Content-Length、Content-MD5 是否正确，网络连接是否正常。

# 用户授权登录

  • # 功能描述

对于某些对使用者身份有验证需求的设备，平台提供了在设备端进行用户授权登录的功能。用户通过得力E+ APP扫描设备授权登录二维码，完成用户授权登录并返回授权信息到设备端。

整个登录授权操作流程示意如下：

uml diagram

其中，支持的设备授权登录二维码的格式如下所示：

https://delicloud.com?from=device&action=login&product={产品型号}&device={设备ID}
https://delicloud.com/d/{设备ID}/login?product={产品型号}     // 推荐

  • # 用户授权登录通知指令

用户设备登录授权成功后，平台会通过【205指令】将用户授权信息下发给设备。

请求示例如下：

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 205,
    "data": {
        "user_id": "534417825331150848", 
        "org_id": "385097921973977088",
        "name": "测试用户", 
        "mobile": "13801234567", 
        "avatar": "http://file.delicloud.com/avatar/534417825331150848.jpg", 
        "expire": 1555381099, 
        "token": "9e0968df5433e10c709eab51ed6231c6",
        "status": 0
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
请求参数 格式 必传 参数说明
user_id 字符串 Y 授权登录用户ID
org_id 字符串 Y 授权用户当前默认选择的组织ID
name 字符串 Y 授权登录用户姓名
mobile 字符串 Y 授权登录用户手机账户
avatar 字符串 N 授权登录用户的头像URL
expire 整型 N 授权Token的过期时间戳(秒)，仅在授权成功返回
token 字符串 N 授权的Token，仅在授权成功返回
status 整型 Y 授权状态。0-用户已扫码待确认状态，1-则表示用户确认授权成功，2-表示授权失败。

提示

为了更好的用户扫码体验，我们将授权登录状态status分为了两个阶段: 扫码和授权，具体见得力E+帮助文档 (opens new window)。

设备收到消息后，应在同一个上下文回复确认消息，明确告知平台已收到通知。

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 205
}
1
2
3
4
5
6
7

# 其他特殊功能

  • # 功能描述

对于某些特殊功能需求场景，平台定义了一些额外的辅助功能指令。具体介绍如下：

  • # 文字语音转换指令

对于一些需要支持播报文字语音的设备，平台支持设备通过【120指令】向平台请求对文字进行实时语音转换。

请求示例如下：

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 120,
    "data": {
        "source_txt": "小明",
        "accept_type": "audio/mp3"
    }
}
1
2
3
4
5
6
7
8
9
10
11
请求参数 格式 必传 参数说明
source_txt 字符串 Y 待转换的原始文本，UTF-8编码，不允许超过64个汉字
accept_type 字符串 N 期待响应的格式，暂时只支持 "audio/mp3"，非必要字段

平台收到请求后，会对文字进行实时转换，并返回如下语音转换结果。

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375,
    "action": 120,
    "data": {
        "code": 0,
        "msg": "",
        "source_txt": "小明",
        "content_type": "audio/mp3",
        "url": "http://xxxx/yy"
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
响应参数 格式 必传 参数说明
source_txt 字符串 Y 待转换的原始文本
content_type 字符串 Y 语音媒体类型
url 字符串 Y 语音文件url，设备可通过该url下载转换后的语音文件

注意

对于已经转化成功的文字语音，请设备在本地进行存储，避免频繁的提交转换。
另外，如果因为网络等原因导致无法正常下载语音文件，可以按照一定的策略进行重试（例如语音播放之前检查并再次触发下载），但不要影响设备除语音播放外其他功能的正常使用。

# 平台错误码

设备请求发送成功后（主要针对1xx指令），平台会在响应结果data中返回错误码code和错误描述msg。如果平台处理正常，则code返回0，否则返回具体的错误代码和错误描述。

平台可能返回的通用错误代码如下：

错误代码 错误消息 错误原因 处理建议
101 设备已激活 设备已完成激活，不可重复激活 该错误一般发生在研发阶段激活后再次请求设备激活指令，请检查程序逻辑是否正确
104 请求已过期 请求时间time不正确，未与平台完成时间同步 应主动发起时间同步重新校准时间
105 请求已被封禁 设备行为异常，平台已禁止设备访问 设备应通过UI或者其他交互手段提示用户设备已被封禁。处于该状态的设备应停止响应和发起任何指令，但可以通过100指令定时检查是否有解封
106 不支持的操作指令 平台禁止设备使用该指令action 该错误一般发生在研发阶段，请联系产品管理人员检查产品指令配置
108 服务器繁忙 平台内部运行错误 该错误一般是由于平台服务能力不稳定造成的偶发性问题，设备收到该错误码可以视为平台响应出错，此时应主动重新发起请求。另外一种可能性是，设备发送了错误格式的指令导致平台处理异常，这种情况一般发生在研发阶段，请设备开发人员检查指令的正确性，如果确认没问题请联系平台管理人员协助检查

个别指令特定的错误代码单独在指令响应中说明。

注意

针对平台错误代码，请设备开发商严格按照平台的处理建议进行处理，不要擅自自定义处理办法，以免影响用户的操作体验。

如果设备接收到了一些未知的错误代码（协议未定义处理建议），设备应直接忽略，并根据业务场景需要重新发起请求。

# 调试工具

为了简化设备指令的调试过程，平台提供了专用的协议调试工具，该工具支持对调试设备的日志监控、消息发送/接收控制等功能。

目前该工具仅支持通过MQTT协议接入的设备，接入地址如下：

tcp://s-devicedebug.delicloud.com:1883

提示

为了简化调试难度，调试工具不使用SSL加密连接，也不对用户名、密码进行验证，设备也不需要在得力E+APP进行绑定激活。

另外，如果设备接入遇到了问题，可以考虑先使用标准的MQTT客户端工具 (opens new window)尝试下。

接入成功后，可通过控制台 (opens new window)对设备消息进行日志监控和消息接收/发送管理。

访问后，在左侧设备菜单找到你正在调试的设备，点击选择即可进入设备调试界面，示例如下：

设备调试界面

在设备调试界面会自动显示设备与平台之间的所有事件消息，包括连接、断开、主题订阅、心跳、发送消息和接收消息等。

注意

请特别注意确认选择的设备SN与调试设备一致，如果选择错误，可以重新选择切换。

默认情况下，调试工具不会拦截所有设备发送和接收的消息，但调试人员可以通过顶部【自动收发消息】开关对其进行控制，一旦关闭该开关，所有设备相关的指令消息都会在调试器被拦截，不会自动回复。

此时，调试人员可以在操作列点击【编辑】按钮对消息进行编辑，然后通过点击底部【发送】按钮将消息发出。

设备消息发送控制

另外，调试人员也可以通过点击右侧顶部【向设备发送消息】按钮，主动向设备发送自定义指令消息。

通过人为控制和改变设备的指令消息，可以模拟不同场景下的消息请求和响应，便于检查设备固件程序逻辑是否正确。

# 变更记录

变更时间 协议版本 变更人 变更内容
2021/8/1 v1.1 徐超国 按照设备功能重新进行了文档编排，补充了部分相关的协议内容
2023/2/23 v1.2 徐超国 关于指令请求响应超时重发增加mid保持不变的要求，另外针对平台故障期间回复延迟问题，修改了响应超时的等待时间策略
2023/5/5 v1.3 徐超国 105指令增加severity字段，用于平台进一步细分处理设备异常告警信息。
上次更新: 7/25/2025, 2:14:23 PM