设备标准接入协议

文档目标

本文档用于描述得力云平台智能办公场景设备接入的通用标准方式、通信协议以及具体的接口定义,不涉及具体某种类型设备的业务操作协议。

适用范围

本文档用于说明得力云平台对外提供的接入方式,帮助和指导智能办公场景下设备产品固件开发人员正确接入云平台。对于本身不支持连接云平台网络的设备不在此文档讨论的范畴。

相关术语

术语 解释
智能设备 是指任何一种具有计算处理能力的设备、器械或者机器,智能设备通过网络与云平台连接,实现设备和云端软件服务的集成
云平台 各种智能设备和应用服务接入的基础服务平台,为智能设备和云端应用进行接入和数据交换提供支撑
应用服务 为智能设备提供增值服务的云端软件应用

通信协议

目前平台支持的主要设备通信方式有MQTT和HTTP两种,如果涉及安全级别要求较高的设备,可在此基础上增加SSL安全协议。考虑到平台接入的稳定性以及设备端低功耗、高网络可靠性等因素,推荐设备通过MQTT协议接入平台。

  • MQTT

得力云平台设备接入默认推荐目前物联网行业事实上的标准(OASIS)接入协议:MQTT协议,版本号3.1.1。MQTT协议是轻量级的发布和订阅(publish/subscribe)协议,其建立在TCP协议之上,对设备硬件要求低、网络可靠性要求低以及资源消耗要求低的特性为得力云平台未来广泛接入的智能设备提供很好的支持。

与HTTP协议这种请求/响应同步模式不同,发布/订阅模式解耦了发布消息的客户(发布者)与订阅消息的客户(订阅者)之间的关系,是一种异步消息通信机制,对大量并发提供了更好的支持。

MQTT数据包格式如下:

MQTT客户端连接库可参考链接

  • HTTP

对于某些不支持MQTT协议的设备,平台也提供了HTTP协议的接入支持,设备可以使用http协议来模拟MQTT对应的动作:建立连接、断开连接、推送消息到平台、接收平台的消息。具体的请求URL和参数见后续章节。

接入流程

任何一台设备在出厂后,都需要经过设备连接、接入认证以及绑定激活这三个步骤后方能正式投入使用。以MQTT接入方式为例,一旦设备激活成功,即可订阅关联的业务主题,并接受相应的发布消息。

具体说明如下:

  • 设备连接

几乎所有的智能设备都需要通过与得力E+ APP(以下简称“APP”)或者得力云平台设备网关服务器建立数据连接通道来实现命令控制和数据传输。目前,在连接方面主要分为以下几类设备:

1.  设备不连接云平台,不需要配置网络,与APP直接通信完成数据交互;
2.  设备连接云平台,但不需要或者不支持通过APP进行通信完成网络等参数配置;
3.  设备连接云平台,但需要通过与APP连接通信来完成网络等参数配置;

对于情况#1,主要是指一些小型设备,类似手环、微型打印机等。这类设备一般通过蓝牙等短距离连接通信方式与APP建立数据连接,完成设备的数据传输;

对于情况#2,主要是指一些支持有线连接或者自带配网功能的设备,类似带屏幕的考勤机等。这类设备无需与APP进行连接进行网络配置,在自行配网成功后,通过与得力云平台的设备网关交互进行数据传输;

对于情况#3,主要是指一些不支持有线且不带配网功能的设备,类似无屏幕的Wifi考勤机等。这类设备通过蓝牙、Wifi广播、声波甚至二维码拍照识别等方式与APP进行数据通信完成网络配置,在配网成功后,通过与得力云平台的设备网关交互进行数据传输;

不同设备类型,平台会通过定义不同的产品型号来进行区分。APP扫描设备二维码获取到对应产品型号,并根据不同产品型号的配置参数来区分处理,具体的设备连接配置流程和协议请参考《APP设备标准交互协议》的对应章节。

  • 接入认证

出于安全考虑,所有智能设备在连接成功后都需要第一时间进行基本的安全认证才能接入系统。不同的连接方式,其设备接入认证方式也不同。

但,不论采用什么样的认证方式,设备都首先需要有一个全局唯一的ID进行标示,该设备ID由设备厂商生成,但应符合全局唯一性要求,平台建议的设备ID格式如下: {产品型号}_{厂商设备唯一SN编码}。 例如考勤机型号3960C,那么某一台设备ID则建议是3960C_1234567890

设备ID以及对应产品型号的获取,具体请参考《APP设备标准交互协议》的对应章节。

不同连接对应的接入认证方式具体说明如下:

  • MQTT接入设备

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

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

接入参数 描述
ClientID 设备唯一ID,格式:{产品型号}_{厂商设备唯一编码}
UserName 产品型号
Password MD5(ClientID + "-" + {产品型号} + "-" + {产品密钥})

其中产品密钥是由云平台注册产品型号时自动生成,并通过安全渠道提供给设备厂商。每个不同的产品型号,生成的产品密钥不同,是一一对应的关系。

  • HTTP接入设备

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

POST /api/connect/{clientId}
Headers: 
    "Content-Type: application/json"
Body:
{
    "clientId": "3T2PL_1323E322",
    "userName": "产品型号",
    "password": "MD5生成的密码"   // 生成规则参见上一个表格
    "keepAliveTime": 10           //(单位: 秒) 对应MQTT协议的KeepAliveTime设置
}

其中认证的信息内容与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"

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

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

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

GET /api/disconnect/{clientId}
Headers:
    "Authorization: DELI.eyJ0KV1...iJ9.eyJjbGll...wNH0.gh0ia8c1..Di07o3o"
    "Connection: close"

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

  • APP直连设备

对于其他不支持连接云平台的设备,由APP与设备之间根据相应的通信协议(例如蓝牙、WIFI直连等)进行接入认证,具体协议请参考《APP设备标准交互协议》的对应章节。

  • 其他说明

对于某些高安全级别的设备,平台还提供了预注册模式的认证方式。即在通过基本的设备校验之后,还需要在平台数据库中查询该设备ID是否已注册,如果没有注册,设备也会接入认证失败。

  • 绑定激活

所有直接或间接通过APP接入得力云平台的智能设备都应完成设备绑定激活才能投入使用。所谓绑定激活,就是完成设备和人员组织以及对应软件应用系统在平台的对应关联关系,一旦设备绑定,除非主动解绑,其他组织人员将无法管理该设备。

整个绑定操作由设备管理人员通过APP操作完成,绑定之前设备必须已完成了设备连接和接入认证的操作。

为了完成这一绑定流程,首先APP必须知道设备ID以及对应产品型号等关键信息。为了最大程度支持各种不同类型的智能设备,APP提供了扫描二维码获取设备信息的功能。

具体设备绑定过程中与APP的交互流程和通信协议请参考《APP设备标准交互协议》的对应章节。

  • 接收平台消息

  • MQTT接入设备

MQTT接入设备在绑定成功后,需要订阅设备产品相关的主题消息(Topic),以便平台向设备发送消息。设备在接入成功后,平台会自动会为该设备订阅一个唯一的主题$client/{clientID},用于点对点的设备通信(设备无需主动订阅)。除此之外,设备还可以按需订阅以下几个全局主题:

主题 描述
{产品类型} 一种业务类型产品的全局消息,例如所有考勤机,定义一个产品类型主题KQ
{产品类型}/{产品型号} 一种业务类型产品下某个具体产品型号的全局消息,例如考勤机的某个产品型号3960C可订阅主题KQ/3960C

除以上主题外,平台不支持设备订阅任何其他主题。

产品类型与产品型号都是由云平台生成并提供给设备生产商,生产商直接固化该信息到设备程序或配置中即可。

设备订阅了以上两个主题,则平台可以针对某种产品类型或者产品类型下的某个具体产品型号发送全局广播消息,以应对某些特殊场景的需求,例如升级通知。

设备订阅成功后,即可根据MQTT协议接口规则接收异步消息响应,具体消息响应格式将再第三章说明。

  • 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"

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

平台会按照时间顺序将最早未读取的batchSize条设备缓存消息返回给设备,实际数量可能小于batchSize。如果HTTP请求成功,则返回HTTP状态码200,同时响应结果示例如下:

{
    "code": 0, //错误码,0表示成功
    "msg": "错误描述",
    "size": 5,
    "data" : [
        {"mid":"232231", "from":"应用服务ID", "to":"设备ID", "action": 301, "data": {}},
        {"mid":"232232", "from":"system", "to":"设备ID", "action": 203, "data": {}},
        ......
    ]
}

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

HTTP响应码为406则表示请求授权信息不正确或已过期,需要重新进行http连接认证。如果HTTP响应码为200, 但是code不为0,则参见平台统一错误码

  • 设备消息发布

  • MQTT接入设备

MQTT接入设备在接入平台之后,可以根据实际业务流程向平台网关发布主题消息,设备发布主题统一定为device, 平台会订阅该消息主题,并根据接收消息的具体操作指令进行处理或者转发。

  • HTTP接入设备

HTTP接入设备可通过HTTP请求/api/push/{clientId}主动向平台发送消息,平台HTTP设备网关会同步接收该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": {...}
}

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

{
    "code": 0,  //错误码,0表示成功
    "msg": "错误描述"
}

如果HTTP响应码为406, 则表示请求授权信息不正确或已过期,需要重新进行http连接认证。如果HTTP响应码为200,则code不为0时,错误码参见平台统一错误码

平台设备接口

设备可通过平台提供的一系列接口指令与平台以及云端应用服务进行通信完成设备的相关业务操作,包括设备通用消息指令、平台通用消息指令以及设备应用交互指令三个部分。

  • 消息格式

为了便于开发和管理,平台为所有开放接口约定了统一的数据交换格式。

  • 针对MQTT接入的设备平台自定义数据格式都通过MQTT数据包的Payload消息体部分来设计。

  • 针对HTTP接入的设备平台自定义数据格式都通过HTTP的body部分来设计。

所有发送和接收到的Payload消息体都是以JSON数据格式存储的字符串,编码格式统一为UTF-8。数据格式如下:

{
    "mid": "消息ID", 
    "from": "发送者ID", 
    "to": "接收者ID", 
    "time": 操作时间(秒), 
    "action": 操作指令, 
    "data": {具体消息内容 }
}

各参数说明如下:

参数 类型 描述
mid 字符串 消息ID,用来标识一次消息请求上下文,内容由请求方自定义,建议采用类似时间戳等唯一信息,方便调试跟踪。
from 字符串 消息发布者ID。包括设备ID、应用服务ID或者平台system
to 字符串 消息接收者ID。包括设备ID、应用服务ID或者平台system
time 整型 消息发布时间,精确到秒
action 整型 消息指令。不同指令代表不同的消息操作类型
data JSON 可选,具体的请求或响应消息内容

注意:所有未标注为"可选"状态的信息都是必填的,当可选信息为空时,平台默认是不会传递的。

对于一次完整的消息请求和响应的流程,mid应相同,请求的fromto应和响应的tofrom一一对应。另外,data字段中响应部分应包含响应错误码code和错误描述信息msg等。

下面就目前开放的所有指令进行具体说明。注意,以下指令并非全部需要支持,设备应根据业务实际情况进行支持,设备厂商应告知平台可以支持的指令列表。

  • 设备通用指令

以下指令是由设备端主动向平台发起的指令集,设备通过该指令集请求平台数据或通知平台设备状态数据,该指令集所有指令action1开头。请求数据中from固定为设备ID, to固定为字符串system

请求示例如下:

{
    "mid": "消息ID",
    "from": "设备ID",
    "to": "system",
    "time": 请求时间戳,
    "action": 1xx,
    "data": {
        ......
    }
}

平台响应示例如下:

{
    "mid": "消息ID",
    "from": "system",
    "to": "设备ID",
    "time": 响应时间戳,
    "action: 1xx,
    "data": {
        "code": -1, 
        "msg": "错误描述或空", 
        ......
    }
}

其中, code表示平台响应错误码msg表示具体的错误描述,如果code等于0,msg返回空字符串。除了codemsg之外,根据协议指令不同,可能会返回更多的信息,具体见指令说明。

  • 时间同步100

设备接入成功后需要第一时间进行时间同步,以保证本地时间的准确性。为了保证时间的准确性,设备建议每天至少进行一次定时时间同步操作。

请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "设备ID",
    "to": "system",
    "time": 0, 
    "action": 100
}

平台响应消息示例如下:

{
    "mid": "123456",
    "from": "system", 
    "to": "设备ID", 
    "time": 1502867044, 
    "action": 100, 
    "data": {
        "code": 0,
        "msg": ""
    }
}

响应结果中data中仅包括默认响应错误码等信息。设备可直接使用time进行本地时间同步,精确到秒。如果设备对时间精度有要求,请选择得力云的NTP服务(time.delicloud.com)或其它公共的NTP服务。

  • 设备信息更新101

建议设备信息发生变化或每次接入平台成功时主动调用101指令上报设备信息。

请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "设备ID", 
    "to": "system",
    "time": 1502867086, 
    "action": 101, 
    "data": {
        "name": "设备名称", 
        "product_version": "1.0",
        "properties": {
            "ip": "61.153.143.62", 
            "gps": "121.594077,29.852002",
            "mac": "00-01-6C-06-A6-29"
            ...
        }
    }
}

其中data部分的各参数说明如下:

参数 类型 描述
name 字符串 可选,设备名称,如果设备不支持名称设置,则置为空,不上传
product_version 字符串 设备当前固件版本号
properties JSON 可选,设备自定义参数,可根据需要补充,例如设备ip地址,gps位置、mac地址等等。如果没有,则置为空。

平台响应消息与指令100类似:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "设备ID", 
    "time": 1502867044, 
    "action": 101, 
    "data": {
        "code": 0,
        "msg": ""
    }
}
  • 设备查询102

设备可通过指令查询平台记录的设备信息。设备本地可以缓存该信息,但应设置合理的过期时间,防止信息不同步。

建议设备每天至少查询一次设备状态,如果设备断电或者断网失去了与平台的网络连接,为了避免数据不一致,应在恢复连接后立刻调用该指令从平台获取设备的最新状态信息,并做相应的同步处理。

请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "设备ID", 
    "to": "system", 
    "time": 1502867086, 
    "action": 102
}

响应消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 102, 
    "data": {
        "code": 0, 
        "msg": "", 
        "status": 1,
        "name": "设备名称",
        "organization" : {
            "org_id": "绑定组织ID", 
            "name": "组织名称", 
            "logo": "组织logo URL地址或空",
            "org_admin": {
                "user_id": "组织管理员ID", 
                "name": "姓名", 
                "empno": "工号或空", 
                "avatar": "头像URL或空"
            }
        },
        "last_access": 上次接入时间(秒), 
        "product_version": "最新固件版本号",
        "app_ids": ["绑定的应用ID"]
    }
}

其中平台响应data部分的各参数说明如下:

参数 类型 描述
status 整型 设备状态: 0锁定、1正常
name 字符串 设备名称
organization JSON 可选,设备组织信息。如果设备无组织,则为空。组织信息包括:
org_id:设备已绑定组织ID,
name:组织名称,
logo:可选,组织LOGO图片URL,
org_admin:组织管理员信息
product_version 字符串 可选,设备产品固件最新版本
last_access 整型 上次接入时间(精确到秒), 初次接入为0
app_ids 数组 设备所绑定的应用ID

注意: 如果organization信息为空或者与本地缓存的org_id信息不一致,可能是平台已解绑该设备,此时设备应及时清理所有本地业务数据,恢复出厂数据状态。如果平台更改了设备的名称name,设备也应主动更新。

另外,如果平台固件版本与本地版本不一致,设备应通过指令103主动查询平台最新固件版本信息进行升级。

  • 固件版本查询103

通过该指令,设备可以查询目前该设备当前可升级的最新固件版本信息包括固件版本号、文件下载地址等。

请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "设备ID", 
    "to": "system", 
    "time": 1502867086, 
    "action": 103
}

响应消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 103, 
    "data": {
        "code": 0, 
        "msg": "",
        "version": "1.1", 
        "upgrade_type": "force|normal",  
        "file_path": "http://file.delicloud.com/xxx.zip", 
        "checksum": "4c56ff4ce4aaf9573aa5dff913df997a"
    }
}

各响应参数说明如下:

参数 类型 描述
version 字符串 设备所属产品型号最新升级版本
upgrade_type 字符串 升级类型,包括强制升级force和普通升级normal。对于强制升级,升级完成前设备不可用;否则,可按照设备自定义空闲时间进行升级
file_path 字符串 固件最新升级文件下载地址
checksum 字符串 固件升级文件的MD5完整性校验值

设备根据本地版本比较决定是否需要升级,如果需要,则通过file_path给定的路径下载文件升级。为了避免集中并发压力过大,一个产品型号所有设备不要同一时刻启动升级文件下载操作,建议在某个时间段进行随机生成一个下载启动时间,例如凌晨0点-2点,按照0-7200秒随机。文件下载成功后,应进行本地MD5校验,防止文件损坏造成设备升级失败。

另外,平台也可以主动向设备广播固件新版本变更通知, 参考固件升级通知指令202

注意,由于下载升级文件时采用的HTTP协议,为了避免网络不佳造成无法下载,建议采用HTTP通用的断点续传下载方案

  • 设备主动解绑104

对于安全性要求不高的设备类型,平台通过预授权允许其通过设备端主动完成解绑操作,解绑之后本地业务数据应清理干净。通过该指令设备可主动通知平台解除设备与用户组织的绑定关系。 请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "设备ID", 
    "to": "system", 
    "time": 1502867086, 
    "action": 104
}

响应消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "设备ID", 
    "time": 1502867044, 
    "action": 104, 
    "data": {
        "code": 0,
        "msg": ""
    }
}

为了保证设备一定解绑成功,在收到平台响应结果之前,设备应处于循环等待状态(如果超时,应重新发起解绑),不能进行其他操作。 注意,是否需要主动解绑功能,设备开发商可根据设备使用场景决定,但是需要平台对设备产品型号进行预授权。

  • 设备异常报警105

通过该指令设备可向平台主动进行设备系统级别的(非业务级别的)异常报警。平台会将设备报警消息推送给组织管理员。

请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "设备ID", 
    "to": "system", 
    "time": 1502867086, 
    "action": 105, 
    "data": {
        "level": 1,
        "code": 200,
        "msg": "警报消息"
    }
}

各请求参数说明如下:

参数 类型 描述
level 整型 报警级别,可选。可分为:低(1)、中(2)、高(3)三个级别,缺省默认为低。各级别定义说明如下:
:级别为1,异常不影响正常业务进行,但存在潜在风险;
:级别为2,异常会造成某些业务出现错误,但是无致命影响;
:级别为3,异常会严重影响用户的使用,必须尽快处理。
code 整型 报警代码,由平台和设备开发商协商决定,设备应考虑网络、固件或硬件各项指标出现异常的情况定义错误码
msg 字符串 报警描述信息,设备自定义

响应消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "设备ID", 
    "time": 1502867044, 
    "action": 105, 
    "data": {
        "code": 0,
        "msg": ""
    }
}

设备收到平台响应之后方可删除该报警信息,否则应定时重复上传报警信息,直到确认平台收到消息为止。

  • 平台通用指令

以下指令是由平台主动发起请求到设备的指令集,通过该指令集可远程控制设备以及获取设备数据。该指令集指令以2开头,消息体中from默认为system或者操作人员ID,设备响应时将该信息直接赋值给消息体的to字段即可。

  • 设备控制200

运营人员或者平台管理人员可通过该指令实现对设备进行远程自定义控制命令下发。不同的设备类型可以支持不同的远程控制命令集,但命令集的定义应与平台进行协商共同决定。该指令主要用于远程设备售后调试用。

请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "运营人员ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 200, 
    "data": {
        "cmd": "自定义命令",
        "payload": {
            // 自定义命令消息体
        }
    }
}

请求各参数说明如下:

参数 类型 描述
cmd 字符串 设备自定义控制命令,不同产品不同
payload JSON 设备自定义控制命令参数消息体,可选

设备收到命令后,应给出执行结果并返回。响应消息示例如下:

{
    "mid": "消息ID", 
    "from": "设备ID", 
    "to": "运营人员ID", 
    "time": 1502867086, 
    "action": 200, 
    "data": {
        "code": 0, 
        "msg": "",
        "cmd": "自定义命令", 
        "result": "响应结果"
    }
}

响应各参数说明如下:

参数 类型 描述
cmd 字符串 请求命令,与请求时一致
result 字符串 命令执行结果
  • 设备日志上传201

平台通过该指令可以控制设备进行日志上传操作,用于远程售后故障分析。日志文件上传默认采用FTP协议,设备本地存储的日志时间长度根据设备的能力决定,建议至少保留1天的日志信息。

另外,为了区分不同设备上传的日志文件,设备在上传日志文件前,应首先创建一个以设备ID命名的文件目录(如果目录已存在,则忽略),并将日志文件上传到该目录,统一管理。

请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 201, 
    "data": {
        "ftp_host": "ftp.delicloud.com", 
        "ftp_port": 21,
        "upload_path": "上传日志根目录",
        "ftp_account": "ftp账户",
        "ftp_password": "ftp密码",
        "size": 256
    }
}

请求各参数说明如下:

参数 类型 描述
ftp_host 字符串 上传FTP地址
ftp_port 整型 FTP端口,默认21
upload_path 字符串 上传日志文件的工作目录,如果为空,则为当前ftp根目录
ftp_account 字符串 ftp登录账户,如果为空,则匿名登录
ftp_password 字符串 ftp登录密码
size 整型 可选,上传日志文件长度,以kb为单位。默认为0,表示全部上传

上传成功后,设备通知平台响应消息示例如下:

{
    "mid": "消息ID", 
    "from": "设备ID", 
    "to": "system", 
    "time": 1502867086, 
    "action": 201, 
    "data": {
        "code": 0, 
        "msg": ""
    }
}

如果上传失败,应设置code201,并给出具体的错误原因。

  • 设备固件升级通知202

当平台发布了某种产品型号的固件升级版本时,平台会通过该指令广播通知所有该产品型号的设备进行升级。设备不需要对该通知类型进行实时响应

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "time": 1502867086, 
    "action": 202, 
    "data": {
        "version": "1.1"
    }
}

请求各参数说明如下:

参数 类型 描述
version 字符串 产品固件升级版本号

设备收到该通知后,如果判断版本不一致,应通过指令103查询升级版本信息,并按照随机升级时间策略进行下载升级文件。

  • 组织绑定通知203

平台通过该指令通知设备与用户组织绑定状态的更新,包括绑定通知和解绑通知两种情况。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 203, 
    "data": {
        "org_id": "组织ID", 
        "name": "组织名称", 
        "status": 0|1
    }
}

通知各参数说明如下:

参数 类型 描述
org_id 字符串 组织ID
name 字符串 组织名称
status 整型 绑定更新状态。0表示设备和用户组织已解绑,1代表设备和组织已绑定

注意,一旦设备和用户组织绑定关系发生变化,其本地缓存的历史业务数据需要及时清理。

对于平台解绑操作,设备可能不在线,为了保证解绑成功,设备再次接入平台时,必须主动清除本地业务数据。

如果设备本地并未存储历史业务数据和绑定关系信息,可直接忽略该通知。

  • 应用绑定通知204

设备一旦投入使用,默认都会通过APP安装相应的云端应用服务。平台通过该指令通知设备与云端应用的绑定状态更新,包括绑定和解绑两种通知状态。设备不需要对该通知类型进行实时响应

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 204, 
    "data": {
        "app_id": "应用服务ID", 
        "name": "服务名称", 
        "icon": "服务图标URL", 
        "status": 0|1
    }
}

通知各参数说明如下:

参数 类型 描述
app_id 字符串 设备绑定的应用服务ID
name 字符串 应用服务名称
icon 字符串 可选,应用服务图标URL,可能为空
status 整型 绑定更新状态。0表示设备和云端应用已解绑,1代表设备和云端应用已绑定

注意,后续设备与云端应用通过指令300通信时需要使用该app_id作为to字段信息发送应用消息请求。

  • 用户授权登录通知205

对于某些特殊设备,例如PPT翻页笔,需要用户授权才能够正常使用。通过该指令可实现APP进行远程授权验证并通知设备授权成功。设备不需要对该通知类型进行实时响应。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "设备ID",
    "time": 1502867086,  
    "action": 205, 
    "data": {
        "status": 0|1|2, 
        "user_id": "用户ID", 
        "name": "用户姓名", 
        "mobile": "手机号码", 
        "avatar": "用户头像URL", 
        "expire": token失效时间, 
        "token": "请求token"
    }
}

通知各参数说明如下:

参数 类型 描述
user_id 字符串 授权登录用户ID
name 字符串 用户姓名
mobile 字符串 用户手机号码
avatar 字符串 可选,用户头像URL,可为空
expire 整型 可选,授权失效截止时间,单位为秒,仅授权成功返回
token 字符串 可选,授权token,仅授权成功返回
status 整型 授权状态。0表示用户已扫码待确认状态,1则表示用户确认授权成功,其它表示授权失败
  • 设备应用交互指令

设备除了与平台之间的交互指令之外,更多的是与云端应用服务之间的消息交互。不同的设备产品类型,其交互的内容完全不同,平台仅提供指令进行消息转发,具体消息内容由应用业务类型决定。

  • 设备推送消息到应用300

所有设备发布到云端应用的消息均通过该指令来完成。平台收到该指令消息后,会进行预处理并转发到相应的云端应用。

请求消息示例如下:

{
    "mid": "消息ID",
    "from": "设备ID", 
    "to": "应用服务ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "业务操作命令", 
        "payload": {}
    }
}

请求各参数说明如下:

参数 类型 描述
cmd 字符串 应用内自定义消息命令
payload JSON 可选,自定义命令的关联参数

其中,to表示目标应用服务ID。如果设备未保存关联应用服务ID在本地,可将其置为空字符串"",平台会自动判断其应用绑定关系进行消息转发(如果设备绑定了多个应用,则会全部转发)。

平台会对消息进行验证,例如判断设备是否与应用存在绑定关系或者应用服务状态是否可用等。一旦验证失败,平台会停止消息转发并直接返回如下响应:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "设备ID", 
    "time": 1502867044, 
    "action": 300, 
    "data": {
        "cmd": "自定义请求消息命令", 
        "code": 错误码, 
        "msg": "错误描述"
    }
}

如果平台验证通过,会将消息转发给应用服务。

注意,应用服务和设备之间的交互是异步非实时的,应用服务不会通过300进行消息响应,而是通过下一节的指令301

  • 应用推送消息到设备301

所有云端应用服务发布到设备的消息在经过平台验证通过后,都会由平台通过该指令来完成消息转发到设备。

设备收到的应用服务请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "应用服务ID", 
    "to": "设备ID",     
    "time": 1502867086, 
    "action": 301, 
    "data": {
        "cmd": "自定义请求消息命令", 
        "payload": {}
    }
}

请求各参数说明与300完全一致。

设备收到消息后,如果需要返回响应,请使用指令300

接入环境

设备接入环境分测试环境和生产环节。其中默认MQTT接入点是:

测试环境:`tcp://t.device.delicloud.com:1883`
正式环境:`tcp://device.delicloud.com:1883`

如果是HTTP协议,则默认接入点是:

测试环境:`http(s)://t.device.delicloud.com`
正式环境:`http(s)://device.delicloud.com`

设备在接入平台前,应首先尝试通过以下HTTP地址动态请求可用的接入点地址:

测试环境:`http://t.endpoint.delicloud.com/mqtt.json`
正式环境:`http://endpoint.delicloud.com/mqtt.json`

请求响应结果为JSON格式,内容示例如下:

{
    "MQTT": //协议类型
    [
        "tcp://d1.delicloud.com:1883",//接入点地址1
        "tcp://d2.delicloud.com:1883"//接入点地址2
    ]
}

如果HTTP请求接入点配置失败,则采用默认的接入点地址访问平台。另外,正式环境也支持SSL加密协议,端口为8883,客户端验证服务器的CA根证书请与管理员联系获取,有能力的设备应优先使用MQTT+SSL协议,确保数据安全。

否则,应按照顺序或者随机的方式尝试连接配置的接入点列表,直到找到一个可以成功连接的接入点为止。如果所有接入点都无法访问,则应采用定时重试机制不停的尝试直到成功为止,尝试的时间间隔应不少于30秒。