# 物联云MQTT协议设备接入

# 接入流程

询问云平台管理员获取平台地址和登录账号。
登录云平台创建项目信息。
创建对应的产品和设备。
设备按照iot物联云MQTT对外通信定义文档（以下简称通讯文档）接入平台。

# 接入示例

# 创建项目

TIP

进入云平台 系统管理-项目配置 页面，点击 新增 按钮。

TIP

填写项目信息，选择项目成员后 再选择项目负责人。

# 创建产品

# step1

TIP

进入云平台 设备中心-设备管理 下的产品列表页面，点击 添加产品 ，按需选择 产品类型 。如果需要接入阿里云设备则添加阿里云产品，网关设备则添加普通网关产品，其他则选择默认产品。

TIP

添加产品页面:

# step2

TIP

添加产品成功后 点击添加点位按钮添加数据点位

# step3

TIP

测试数据点位添加完成

# 创建设备

TIP

进入云平台 设备中心-设备管理 下的 设备列表 页面，点击 添加设备。

TIP

选择上一步创建的产品，设备会自动添加产品数据点位信息。

TIP

点击 查看 按钮进入设备详情页，查看设备详细信息。

硬件版本 / 查询周期 和 心跳检测 为默认参数。

查询周期 为平台 定时 查询设备数据时间， 默认三分钟 。
平台按该参数配置时间主动查询一次设备实时数据（ allCall 总招命令）。

心跳检测 为平台判定设备离线时间， 默认五分钟 。
平台一分钟检测一次设备是否离线，按该参数配置时间再加一分钟 设备未上送任何数据 则平台认为设备离线， 会断开与设备的连接并设备修改为离线状态 。

# 模拟设备接入

# 接入步骤

询问管理员获取云平台 mqtt连接账号 和 设备通讯${AppKey} ，
本次示例${AppKey}为 accessTest 。
安装 mqtt客户端 工具，用于模拟设备收发数据。
按照通讯文档消息格式（通讯文档云平台接收设备消息格式）发送模拟数据。

# 订阅平台回复数据主题

TIP

设备需要登录后才能与云平台进行其他通讯。
根据通讯文档 云平台推送设备消息 格式定义，
订阅主题格式为 iot/tx/${AppKey}/${ID}/# ，
其中
iot/tx/ 为固定前缀，
${AppKey} 为询问管理员获取到的标识码，
${ID} 为平台设备的通讯地址，
# 代表订阅全部命令消息。
真实接入时设备需按通讯文档定义的命令做不同的处理

本次示例订阅如下主题查看平台发送给设备的数据：iot/tx/accessTest/183b6d73ecb8f4c7bfa5d987/#
接入设备时需要将accessTest和183b6d73ecb8f4c7bfa5d987替换为从管理员处获取到的${AppKey}和平台真实存在的设备通讯地址

TIP

根据通讯文档 云平台接收设备消息格式 定义，
设备推送主题格式为 iot/rx/${AppKey}/${ID}/xxx ，
其中
iot/rx/为固定前缀 ，
${AppKey}为询问管理员获取到的标识码 ，
${ID}为平台设备的通讯地址 ，
xxx代表设备上送的各种命令 。
本次示例为模拟设备 登录上线 /上送实时数据 /上传文件 三种命令，
其他剩余命令可查看通讯文档。

以下模拟发送给平台的数据需要将accessTest和183b6d73ecb8f4c7bfa5d987替换为从管理员处获取到的${AppKey}和平台真实存在的设备通讯地址

# 设备发送登录请求

# 登录步骤

设备向平台发送登录请求（ask）。
平台回复设备登录请求（req）。
设备再向平台回复登录确认（fin）。

设备向平台发送登录请求：

topic iot/rx/accessTest/183b6d73ecb8f4c7bfa5d987/login

{
 "productKey": "183b6a9fbd24d5c0",
 "deviceSecret": "a803dd00717c4ef39fd834c818bfb2e9",
 "status": "ask",
 "id": 1
}

1
2
3
4
5
6

TIP

productKey 表示产品密钥，
deviceSecret 表示设备密钥，
产品密钥和设备密钥可在 设备详情页 查看。
status 共有 ask，req，fin 三种类型，详情如下：
ask 表示设备发起登录请求， req 表示平台回复登录， fin 表示设备确认完成登录操作。
id 表示一个随机整数，设备每次登录时，随机创建。

输入主题和内容后点击 publish 按钮发送数据，
可在上一步订阅消息处收到平台回复的 req 消息， 收到req后需要再回复登录确认数据 。

客户端模拟设备发送登录请求并收到平台登录回复：

设备回复登录确认示例：

topic iot/rx/accessTest/183b6d73ecb8f4c7bfa5d987/login
{
 "status":"fin", 
 "id":3
}
1
2
3
4

TIP

status中的 fin 表示设备确认完成登录操作，
id 根据上一步平台回复的登录信息 req 内容加1

客户端模拟设备回复登录确认：

登录完毕后可看到设备上线成功，登录成功后可模拟设备上送实时数据或其他通讯。

# 设备上送实时遥信数据

topic iot/rx/accessTest/183b6d73ecb8f4c7bfa5d987/resultYx
{
 "time":1665220112000, 
 "yxList":[
  {"id":1,"value":1}
 ]
}
1
2
3
4
5
6

TIP

time ：数据采集时间
yxList ：遥信列表
id ：对应平台 遥信类型点位数据 的编码
value ：0-关 1-开，所有只有0和1两个状态的数据可通过遥信上送

# 设备上送实时遥测数据

topic iot/rx/accessTest/183b6d73ecb8f4c7bfa5d987/resultYc
{
 "time":1665220112000, 
 "ycList":[
  {"id":2,"value":25.15}
 ]
}
1
2
3
4
5
6

TIP

time ：数据采集时间
ycList ：遥测列表
id ：对应平台 遥测类型点位数据 的编码
value ：浮点数，所有数值型的数据可通过遥测上送

# 设备上送实时参数数据

topic iot/rx/accessTest/183b6d73ecb8f4c7bfa5d987/setting
{
 "time":1665220112000, 
 "settingList":[
  {"id":3,"value":"测试"}
 ]
}
1
2
3
4
5
6

TIP

time ：数据采集时间
settingList ：参数列表
id ：对应平台 参数类型点位数据 的编码
value ：参数值，字符串类型数据可通过参数上送

若页面点位当前值不刷新，可手动切换到设备台账页面后再切换回数据点位页面，若还不刷新可查看推送报文是否正确，若报文正确平台解析数据失败可联系平台管理员排查解决。

# 设备上传文件

TIP

该模块可以进行设备上传或下载文件操作， 暂不需要上传文件可跳过此功能 。
设备可以在 收到获取文件列表命令 后回复平台文件列表，
或者 主动上传 文件列表(未收到获取文件列表命令直接上传文件列表)，
设备收到获取文件列表命令若没有需要上传的文件可不用回复平台

设备回复获取文件列表命令或主动上传文件：

topic iot/rx/accessTest/183b6d73ecb8f4c7bfa5d987/fileList
{
 "fileStep":"resultFileList",
 "fileList": [{"name":"test","docType":"log"}]
}
1
2
3
4

TIP

fileStep ：文件上传具体步骤， resultFileList ：当前步骤为设备返回文件列表
fileList ：文件列表
name ：文件名称
docType ：文件类型，目前暂定类型有：log / data / config /

设备上传文件列表后会接收到平台回复的 已准备好接收文件上传 消息：

TIP

设备需通过 http接口 上传文件到平台，接口为上一步骤返回的url，下图为postman示例
各个参数说明如下：
http://xxx/xxx ：平台回复设备的上传文件接口，需填写平台返回的url
uniqueCode ：文件唯一码
file ：需要上传的文件
deviceAddr ：设备在平台上的通讯地址
返回 code不等于200 则上传失败

下载或下发文件：

# 网关设备配置

当子设备只通过网关与平台通讯时，平台需要配置网关和子设备的关联关系

在平台创建网关设备和子设备对应的产品以及设备

TIP

网关配置：
采集时间，超时次数，物理接口，采集接口非必填
选择对应的产品，再选择产品下创建的设备，填写从机地址
从机地址不可重复，点击 保存 按钮即可保存网关与子设备关联关系

模拟测试：

子设备与网关关联后， 网关上下线会将子设备一起上下线 ，子设备不需要单独接入平台。
网关设备与终端设备登录流程相同。

网关上送子设备实时遥信数据（遥测/参数数据同理）：

topic iot/rx/accessTest/183b6d73ecb8f4c7bfa5d987/resultYc
{
 "time":1665220112000,
 "slaveDevAddr":"1843c8e95aa2d9d05ab546276",
 "ycList":[
 {"id":2,"value":66.66}
 ]
 }
}
1
2
3
4
5
6
7
8

TIP

time ：数据采集时间
slaveDevAddr ：子设备在平台上的通讯地址
ycList ：遥测列表
id ：对应平台 遥测类型点位数据 的编码
value ：浮点数，所有数值型的数据可通过遥测上送

# 注意事项

1.设备上传实时数据的time不可小于3650天前的时间戳，也不可大于当前时间戳
2.设备的报文和主题大小写敏感，需按通讯文档定义的格式发送
3.设备调试页面可查看分析设备上送的报文

# 附件

iot物联云MQTT对外通信定义文档 (opens new window)

mqtt客户端工具 (opens new window)

postman工具 (opens new window)

HTTP协议 →