得力云开放文档中心

# 注册产品

所有智能联网硬件设备在接入得力E+云平台之前，必须先通过设备开发者平台 (opens new window)注册对应的产品型号, 并完成基础参数的配置。包括：

  • 产品基础信息：产品ID、名称、图标以及产品介绍。其中，产品ID是产品的唯一标识，且不允许包括除数字、大写字母和连接符号(-)外的其他符号，长度不得超过16位；
  • 平台接入配置信息：发现设备方式和流程、平台接入方式和协议、设备配网方式及流程、是否支持E+APP等；
  • 产品业务属性：根据不同的产品类型可自定义；

产品注册成功后，设备开发者会获得产品IDproduct_id和接入密钥product_key等接入信息，用于后续平台接入认证使用，请务必妥善保管，不要外泄。

提示

目前开发者平台并未对外开放，请通过项目负责人联系平台运营人员完成产品注册。另外，产品接入信息包含测试和生产两套环境，开发者在研发阶段应使用测试环境的接入配置进行平台对接开发工作，设备研发完成准备发布上线时方可切换接入密钥对接到生产环境。

# 接入流程

一台智能联网设备在接入得力云平台时，需要经过设备发现、网络配置、接入认证这三步。流程示意如下：

# 设备发现

设备发现主要用于得力E+APP (opens new window)与设备进行直连通信（例如蓝牙配网）以及用户绑定设备等场景。

  • # 设备ID

设备ID是用于唯一标识一台设备的关键信息。为了方便直接识别设备对应的产品型号，平台规定了设备ID格式为: {产品ID}_{设备SN}。例如，产品ID为3960C下的设备ID可以是3960C_123456、3960C_123457......。同时，同一个产品ID下的所有设备SN必须是唯一的，以确保设备ID的全局唯一性。

注意

平台支持的最大设备ID长度是64位，且不允许包含除数字、字母以及连接字符（-）之外的其他特殊字符（产品ID和设备SN中间的下划线除外）。另外，平台不区分字母大小写，为了避免出错，请统一使用大写字母。

  • # 发现方式

目前得力E+APP仅支持通过设备二维码扫描发现设备并获取设备ID等关键信息。

设备二维码规范

为了确保所有得力生态的IOT设备都能够按照统一的规则进行识别发现，所有得力IOT设备应按照如下规则生成二维码：

  https://delicloud.com/{appType}/{appID}/d/{deviceID}/{funcType}?product={productID}&status={status}
1

其中，花括号({})部分为可变参数，其他部分是固定字符串。各参数说明如下：

参数 是否必传 参数说明
appType Y 默认操作设备的APP类型，包括：
app: 独立APP；
wxmp: 微信小程序；
appID Y 默认操作设备的APPID，可自定义，但应保证唯一
deviceID Y 设备的唯一ID。如果设备不支持通过二维码展示ID，则缺省设置为0
funcType Y 设备二维码的功能类型，包括：
activate: 设备激活码；

设备可根据使用场景进行自定义扩展。
productID Y 设备所属的产品型号ID
status N 设备连接状态，仅针对通过屏幕动态生成二维码的联网设备。包括：
-1: 未联网；
0: 接入平台成功；
1: 接入平台失败；

注意：所有参数仅支持英文、数字、连接符(-)、下划线(_)等常规字符，请勿使用任何不符合URL规范的特殊字符。

例如，一台型号为M2000DNW的打印机设备，设备ID为M2000DNW_L42118J05R，默认使用微信小程序printer进行激活绑定，则生成的设备二维码是：

https://delicloud.com/wxmp/printer/d/M2000DNW_L42118J05R/activate?product=M2000DNW

设备二维码

为了保持向下兼容，对于通过得力E+APP (opens new window)激活绑定的设备，还支持使用如下规则的二维码：

https://delicloud.com/d/{设备ID}/activate?product={产品型号}&status={状态}
https://delicloud.com?from=device&action=activate&product={产品型号}&device={设备ID}&status={状态}

# 网络配置

对于不支持有线等自配网的设备，得力E+APP提供了蓝牙以及wifi热点两种直连配网方式。

  • # 连接设备

对于蓝牙、wifi热点这样的广播设备，请统一命名设备广播名称为：

DELI_{产品ID}_{设备ID后6位}

例如，打印机产品IDproduct_id为PT的设备ID为PT12345678，则可以设置广播名称为DELI_PT_345678。

APP一旦扫描到符合该命名规范的设备，便可以直接与该设备建立通信链路以便与后续配网数据传输。

注意

如果设备ID不足6位，请左补零。另外，请尽量保证设备ID后6位具备不重复性，避免APP扫描到多台相同的热点广播名称。

  • # 蓝牙配网 推荐

蓝牙配网相对其他配网方式而言操作更为简便可靠，是我们推荐的配网方式。具体配网通信过程，请阅读设备标准蓝牙通信协议的相关章节。

  • # wifi热点配网

对于通过wifi热点配网设备，需要在wifi设备上启动web服务器，服务器的固定IP地址是: 10.192.168.1。得力E+APP连接热点成功后，会通过该IP地址发起HTTP请求，传递配网信息。

wifi热点配网的标准流程如下：

  1. APP通过接口请求设备搜索周边的所有wifi热点列表，并返回APP；
  2. APP从设备搜索到的wifi列表中选择需要配置的热点；
  3. APP输入wifi密码信息，并通过HTTP接口写入设备；
  4. 设备退出热点模式，与APP断开连接，并连接配置的wifi热点；
  5. 设备通过广播通知APP配网结果，这一步与蓝牙配网一致。

其中，第1步请求设备搜索周边wifi列表的接口定义如下：

  • 接口URL: http://10.192.168.1/wifi/list
  • 请求类型： POST
  • 请求参数： 无

HTTP响应消息体结果如下：

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "ssid":"DELI",
            "anthenc":"WPA2-PSK-AES", // 注意，这里的key有拼写错误，为了兼容暂不调整！！！
            "quality":"-70"
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11

响应结果包括设备扫描到的所有可用wifi热点列表，每个wifi热点的参数说明如下：

响应参数 类型 说明
ssid 字符串 wifi热点ID
anthenc 字符串 AP的加密模式。
-设备未加密
none
-设备加密,以设备的加密类型为准。可参考
WEP64 ;
WEP128;
WPA-PSK-TKIP;
WPA-PSK-AES;
WPA2-PSK-TKIP;
WPA2-PSK-AES
quality 字符串 信号强度

第3步向设备写入配网信息的接口定义如下：

  • 请求URL: http://10.192.168.1/wifi/setting
  • 请求类型: POST
  • 请求参数: (入参格式：application/json)
{
    "ssid":"DELI",
    "authenc":"WPA2-PSK-AES",
    "key":"12345678"
}
1
2
3
4
5
请求参数 类型 说明
ssid 字符串 wifi热点ID
authenc 字符串 AP的加密模式，以设备的加密类型为准
key 字符串 wifi密码

HTTP响应消息体结果如下：

{
    "code":"0",
    "msg":""
}
1
2
3
4

# 平台连接认证

设备在联网配置成功后，应主动发起对平台的连接请求。目前平台设备网关支持通过MQTT和HTTP两种通信协议加上SSL安全加密协议接入。

提示

MQTT是一种简单、稳定、开放、轻量级易于实现的消息协议，在物联网的应用下的信息采集，工业控制，智能家居等方面具有广泛的适用性，得力E+平台强烈推荐设备使用该协议。

注意，如果您的设备不支持互联网接入，而是采用蓝牙直连的方式接入，则请点击阅读【设备标准蓝牙通信协议】的相关章节。

接入地址如下：

接入环境 接入地址
测试环境 MQTT协议：
tcp://s-device.delicloud.com:8883；

HTTP协议：
https://s-device.delicloud.com
生产环境 MQTT协议：
tcp://device.delicloud.com:8883；

HTTP协议：
https://device.delicloud.com

注意

平台系统提供了两套环境用于系统对接。在开发阶段请设备连接测试环境进行开发调试，只有在测试验收通过后方可切换到生产环境。请特别注意，测试环境和生产环境出于安全考虑，不仅接入地址不同，产品接入配置参数也不同，不要写错了😄。

另外，我们强烈要求设备使用TLS安全协议去连接平台，避免数据传输过程中的安全性风险。如果在TLS握手过程中验证服务器证书失败，可以检查下设备本地是否注册了根证书 DigiCert-Global-Root-CA.cer (opens new window), 同时请确保接入前通过NTP服务完成【时间同步】，避免本地时间错误导致无法验证服务器证书。

  • # MQTT连接

对于采用MQTT协议接入云平台的设备，可直接使用协议自带的接入认证方式完成认证即可，认证通过即可保持长连接与平台进行通信。

目前平台支持的MQTT协议版本是v3.1.1 (opens new window)。

其中认证需要的基础信息说明如下:

接入参数 描述
ClientID 设备ID，格式：{产品ID}_{设备唯一序列号}，需要具备全局唯一性。
另外平台要求设备「唯一序列号」不允许包含除数字、字母以及连接字符（-）之外的其他特殊字符
UserName 产品ID
Password MD5(设备ID + "-" + {产品ID} + "-" + {设备接入密钥})。例如:
设备ID: 3960C_123456，产品ID: 3960C，设备接入密钥: A2qN4lwf4vMIyWPamjTy1NtR，则计算密码结果为：
MD5 ("3960C_123456-3960C-A2qN4lwf4vMIyWPamjTy1NtR") = 78229e56f40ca02e6fdd80f6f846d8b2

注意：在设备首次接入时，设备应使用产品密钥作为初始接入密钥，一旦完成设备激活，则后续设备接入时应更改为使用激活过程中获得的设备接入密钥。
Keep Alive 心跳时间，请设置在30s~60s范围
Clean Session 客户端和服务器不保存会话，请设置为true

注意

如果因为某些原因（例如网络连接异常、服务器断开等）设备与平台的连接异常断开了，设备应定时尝试重新建立连接，直到接入平台成功为止，间隔时间建议控制在3s～5s。

  • # HTTP连接

对于采用HTTP协议接入云平台的设备，可通过/api/connect/{ClientID}请求完成连接认证。请求示例如下：

POST /api/connect/{clientId}
Headers: 
    "Content-Type: application/json"
Body:
{
    "clientId": "3960C_123456",
    "userName": "3960C",
    "password": "78229e56f40ca02e6fdd80f6f846d8b2",
    "keepAliveTime": 30
}
1
2
3
4
5
6
7
8
9
10

其中认证的信息内容与MQTT协议认证内容完全一致。

认证通过后，HTTP设备网关会同步返回认证结果信息。 如果认证通过，则返回http状态码200并在HTTP头部携带授权信息Authorization，后续设备所有的http请求都需要在头部携带该Authorization信息。响应示例如下：

HTTP/1.1 200
Headers:
    "Authorization: DELI.eyJ0KV1...iJ9.eyJjbGll...wNH0.gh0ia8c1..Di07o3o"
    "Content-Length: 0"
    "Date: Wed, 11 Jul 2018 09:45:44 GMT"
1
2
3
4
5

如果认证失败，则返回406，后续任意api如果返回406都是认证失败，需要重新发起连接。响应结果如下：

HTTP/1.1 406
Content-Length: 0
Date: Wed, 11 Jul 2018 09:45:44 GMT
1
2
3

如果HTTP接入设备主动离线，应调用/api/disconnect/{clientId}接口通知平台设备离线，离线后设备连接时获得的授权信息将自动失效。请求示例如下：

GET /api/disconnect/{ClientID}
Headers:
    "Authorization: DELI.eyJ0KV1...iJ9.eyJjbGll...wNH0.gh0ia8c1..Di07o3o"
    "Connection: close"
1
2
3
4

注意，除了主动离线请求外，如果平台检测到多个心跳周期内没有收到设备的http请求，那么设备授权信息同样会自动失效。

# 消息通信

一旦完成设备接入认证，设备就可以通过建立的连接通道与平台交换消息完成业务通信。根据接入方式不同，其发送和接收消息的流程和API略有不同。

# MQTT消息

MQTT协议采用订阅-发布模型进行消息异步发送和接收处理。因此，在MQTT连接建立成功后，设备需要主动订阅如下主题，以便于接收来自平台/应用端的设备消息:

主题 QoS级别 描述
$client/{ClientID} 0 用于接收指定发送给该设备的消息，例如：设备ID为3960C_123456的设备，应订阅主题: $client/3960C_123456。

接收消息示例如下：

Topic: $client/3960C_XCG001 QoS: 0

{
    "mid": "16264061991891",
    "from": "system",
    "to": "3960C_123456",
    "time": 1626406199,
    "action": 100,
    "data": {
        "code": 0,
        "msg": ""
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13

注意

除上述主题外，设备不可以在未授权的情况下尝试订阅其他任何主题，否则会被平台视为非法设备而强制踢出！

如果设备需要向平台或应用发送消息，请固定发送到主题device，QoS级别请设置为0即可。

提示

MQTT中的QoS等级是用于保证消息稳定传输的机制，通过设置Qos级别大于0可以确保消息能够送达平台设备网关。

但是，由于设备与应用间的通信链路较长，单纯通过Qos无法保障消息的确定送达。所以对于要求消息必须送达的应用场景，设备应按照应用协议要求主动进行消息重发，不可以简单通过调整Qos级别来实现。

示例如下：

Topic: device QoS: 0

{
    "mid": "16264061991891", 
    "from": "3960C_123456",
    "to": "system",
    "time": 0, 
    "action": 100
}
1
2
3
4
5
6
7
8
9

更多关于设备消息结构体的描述，请参考设备平台指令集。

# HTTP消息

HTTP协议属于单向半双工通信协议，服务器无法主动向设备发送消息，因此平台采用了设备定时轮询的方式来获取平台设备消息。
设备通过HTTP请求/api/pull/{clientId}向平台定时拉取发送给设备的缓存消息列表，拉取消息的频率与连接时设置的KeepAliveTime必须保持一致。

请求示例如下：

GET /api/pull/{clientId}?batchSize=10
Headers:
    "Accept": "application/json"
    "Content-Type": "application/json"
    "Authorization: DELI.eyJ0KV1...iJ9.eyJjbGll...wNH0.gh0ia8c1..Di07o3o"
1
2
3
4
5

其中，batchSize是指本次拉取消息的最大条目数(可选参数)。如果不提供，则默认为1，仅拉取1条。

提示

平台会按照时间顺序将最早未读取的batchSize条设备缓存消息返回给设备，实际数量可能小于batchSize。

如果HTTP请求成功，则返回HTTP状态码200，同时响应结果示例如下：

{
    "code": 0,
    "msg": "错误描述",
    "size": 5,
    "data" : [
        {"mid":"232231", "from":"应用服务ID", "to":"设备ID", "action": 301, "data": {}},
        {"mid":"232232", "from":"system", "to":"设备ID", "action": 203, "data": {}},
        // ......
    ]
}
1
2
3
4
5
6
7
8
9
10

其中，size表示本次返回的消息总条数，data表示返回的消息数组。

提示

如果HTTP响应码为406则表示请求授权信息不正确或已过期，需要重新进行http连接认证。另外，如果HTTP响应码为200， 但是code不为0，也视为接收消息失败。

设备可通过HTTP请求/api/push/{clientId}主动向平台发送消息，平台设备网关会同步接收该HTTP请求，并根据接收消息的具体操作指令进行处理或转发。

请求示例如下：

POST /api/push/{clientId}
Headers:
    "Accept": "application/json"
    "Content-Type": "application/json"
    "Authorization: DELI.eyJ0KV1...iJ9.eyJjbGll...wNH0.gh0ia8c1..Di07o3o"
Body:
{
    "mid": "17232432412",
    "from": "3986X_12344",
    "to": "232432423",
    "action": 300,
    "time": 123456,
    "data": {...}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

如果HTTP请求成功，则返回HTTP状态码200，同时响应结果示例如下：

{
    "code": 0,  //错误码，0表示成功
    "msg": "错误描述"
}
1
2
3
4

提示

如果HTTP响应码为406则表示请求授权信息不正确或已过期，需要重新进行http连接认证。另外，如果HTTP响应码为200， 但是code不为0，也视为发送消息失败。

# 设备日志

当设备需要异地存储日志时，可以将日志发布到设备网关中，平台会自动将已发布的设备日志存储到日志管理设施中。

需要查看设备日志，请联系平台客服。
日志可以按型号，设备sn，时间等维度检索，具体使用参考日志查看页面文档。

注意

  1. 单条日志内容不要超过 4KB，超过部分会被截断；
  2. 单个设备的发布频率不要超过 20 条/秒，超过频次的日志会被丢弃。
  3. 单个设备一天内发送的日志条数不能超过 10000 条，超过此限制的日志会被丢弃；次日00:00分重置计数为0；
  4. 日志内容建议是标准 json 格式，非json格式不利于次级索引
  5. 日志内容必须是UTF-8编码，不能出现 \0 字符，否则可能会出现乱码、被截断或无法收集。

# MQTT协议设备

发布日志到主题 log/{model}/{sn} ，QoS级别可以是0或者1。

例如:

Publish  topic: log/M2000DNS/M2000DNS_100TEST
Payload:
{
    "id": "12222",
    "step_type": "print_task_add_cnt",
    "step_num": 3,
    "data": {
        "task_id": "1111111"
    }
}
1
2
3
4
5
6
7
8
9
10

# HTTP协议设备

通过HTTP协议，POST请求/api/v2.0/log/{model}/{sn}向平台发送日志。

例如:

POST /api/v2.0/log/M2000DNS/M2000DNS_100TEST
Headers:
    "Content-Type": "application/json"
    "Authorization: DELI.eyJ0KV1...iJ9.eyJjbGll...wNH0.gh0ia8c1..Di07o3o"
Body:
{
    "id": "12222",
    "step_type": "print_task_add_cnt",
    "step_num": 3,
    "data": {
        "task_id": "1111111"
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# 变更记录

变更时间 协议版本 变更人 变更内容
2021/8/1 v1.1 徐超国 按照设备接入流程重新进行了文档编排，移除了部分已作废的协议内容
2021/9/16 v1.1 徐超国 增加设备私有化部署相关的协议内容，从综合签到协议迁移过来，作为通用设备私有化部署协议
2025/7/15 v1.1 兰欢 补充设备私有化部署配置下发说明，增加设备参数查询协议
2025/7/31 v1.1 兰欢 迁移私有化部署文档，如有需要请联系得力工作人员
上次更新: 7/30/2025, 9:44:52 AM

设备平台指令集