# 设备和应用接入

更新日志

版本	修改日期	编辑人	备注
V1.0	2022/07/22	黄家明	init
V1.1	2022/10/17	朱嘉年、周广胜、陈勇	文档格式化重构，添加部分功能的说明和应用
v1.2	2022/10/20	张辉	添加视频/视频网关接入文档
v1.3	2022/10/20	周广胜	新增常用接口，模型上报示例
V1.4	2022/12/01	周广胜	优化模型定义章节
v1.5	2022/12/05	周广胜	整体文档格式转换

# 1. 设备接入

# 1.1. 概述

设备接入微瓴平台后，便可与微瓴平台、应用服务器之间进行通信。

如图1.1_1所示，设备接入的操作流程共分为4大步骤，分别是：

新增产品：通过产品能够方便地管理具有相同功能或特性的设备，例如指同一个型号的产品，设备就是该型号下的某个设备。
放号申请：新增产品之后，通过将该产品下的设备相关信息填写到"SN文件模板"中，微瓴平台自动审核并返回平台中登记的相关信息。
设备接入：通过运行协议接入的Demo，当中包含注册、登陆以及MQTT消息上报，之后设备便能够与微瓴平台进行通信及交互（子设备可通过填写"导入模版"文件完成接入，详细可查看 1.6子设备接入）。
导入设备：当设备完成注册登陆后，通过填写"导入模版"文件，将登陆注册后的设备导入到微瓴管理平台中，在设备管理的详情页可查看完成接入的设备。

注意：子设备由于本身不具备网络通信能力，因此它要挂载到某个网关产品（设备）下进行数据转发。在导入设备的步骤中，若导入的设备是子设备类型，需要填写它所属的网关的wId标识号（更多细节可查看 1.6子设备接入）。

Alt text

图1.1_1. 操作流程图

# 1.2. 相关术语解释

术语	说明
产品	具有相同功能或特性的一类设备，例如指同一个型号的产品，设备就是该型号下的某个设备
设备	建筑中使用到的硬件设备，比如传感器等，也可以是某个产品下的具体设备，每个设备都会有对应的设备类型
pid	产品的Product ID
wId	设备标识号。设备在微瓴平台的唯一标识。全平台通用
din	设备标识号，与wId意义相同
sn	Serial Number，设备序列号，每台设备都有一个唯一的序列号

# 1.3. 新增产品

产品指一类具有相同功能或特性的设备。微瓴平台为各类直连设备和子设备分配一个独立的 Product ID (简称 pid)。

# 1.3.1. 登录

微瓴开放平台 (opens new window)

# 1.3.2. 新增产品

1）在顶部导航栏，从开发中心>产品管理，进入到产品的列表页，单击"新增产品"。

Alt text

2）根据提示填写产品参数，然后单击下方的"确认"按钮，完成产品的创建。

Alt text

参数	描述
产品名称	为产品命名。支持中文、英文字母、数字和下划线，必须以中文、英文字母或数字开头，长度不超过20个字符
所属厂商	产品所属的厂商名称。支持中文、英文字母、数字和下划线，必须以中文、英文字母或数字开头，长度不超过20个字符
产品类型	请根据实际情况选择产品的类型。若没有合适的类型选择，可单击右侧的"导入设备类型"按钮导入自定义的设备类型。提交后不可修改，请慎重填写
心跳间隔时长	产品下的设备在心跳间隔时长内，最少要上报一次心跳消息，设备才会在线。（60/120/180/240/300s）
产品属性	直连设备：设备实现了TCP/IP协议栈，能够与微瓴平台进行通信；子设备：未实现TCP/IP协议栈，因此它需要由网关进行数据转发。提交后不可修改，请慎重填写
操作系统	产品搭载的操作系统。例如 Windows，Linux，RTOS 等
主控芯片	例如 x86。支持中英文、数字和下划线，长度不超过20个字符
联网方式	直连设备和网关设备的联网方式。例如 2G/3G/4G，Wi-Fi，蓝牙等
接入方案	请根据实际情况选择产品的接入方案。例如sdk接入，协议对接等
产品简介	尽量对该产品详细描述，以便我方工作人员对配置进行检查和审核，内容长度不超过100个字符

3）产品创建成功后，微瓴平台会自动生成产品的 ID 号（pid）。此外，您可以单击"删除"按钮删除不再使用的产品。

# 1.4. 设备放号

为了后续的设备开发工作，需要在开发中心完成生产放号流程，才能在微瓴管理平台进行导入操作。放号操作可视为创建设备。

1）在产品管理的详情页，从产品列表中选择刚刚创建的产品，单击"放号"，进入到放号的详情页。

Alt text

2）在放号的详情页中，单击"放号申请"进入到放号申请页。

Alt text

字段	描述
项目ID	联系项目负责人获取
项目名称	根据项目 ID 从服务器读取自动填充
申请原因	输入申请原因，内容长度不超过100个字符

3）项目 ID。进入微瓴管理平台 >选择项目，单击"项目信息"，从基本信息中可查看项目ID

Alt text

4）点击"下载SN文件模板"填写设备信息，从箭头指向处开始填写设备的 SN 号。

Alt text

5）单击"选择文件"，将填写好的SN文件模版进行上传。注意：如果勾选了"是否为一个SN生成私钥"，则微瓴平台会为每一台设备生成私钥，否则的话当前产品下的设备共用一个私钥。

6）单击"确定"后，放号操作自动审核。在放号申请页可查看申请列表，单击申请项右侧的"下载"按钮查看放号后的信息。

Alt text

参数	描述
SN	Serial Number，设备序列号，每台设备都有一个唯一的序列号
私钥	设备进行消息通信时所使用的私钥
共钥	设备进行消息通信时所使用的公钥

# 1.5. 设备接入demo的使用

设备是建筑中使用到的硬件设备以及传感器等，也可以是某个产品下的设备实体，每个设备在微瓴平台中使用唯一的wId号进行标识。此外，设备可以是直连微瓴平台的直连设备，也可以是代理子设备连接微瓴平台的网关。通过在开放平台新增产品且放号后，您可以在微瓴平台注册您的设备实体，通过平台分配的设备ID（wId）和密钥，在执行设备协议接入的Demo后，您的设备可以接入到微瓴平台，实现与平台的通信及交互。

接入demo和微瓴对接人处获取。

通过修改设备协议接入Demo中的配置文件，可实现设备快速接入到微瓴平台中。

# 1.5.1. 打开demo代码

打开微瓴提供的设备协议接入Demo代码。

# 1.5.2. 修改配置信息

打开src/main/resources/welink-java-sdk-new-yz.properties配置文件，将]设备相关信息填入（ip，port，pid，sn，设备私钥，服务器公钥）。

配置项	描述
ip	IoT服务的TCP协议的IP地址。填写iot.weiling.qq.com
port	IoT服务的TCP协议的端口地址。填写18831
pid	设备的pid号
sn	设备的序列码
SERVER_PUBLIC_KEY	服务器公钥
PRODUCT_PRIVATE_KEY	设备的私钥

填写说明：

>产品管理，进入到产品管理的详情页，单击产品右侧的"调试"按钮，进入到设备调试页面，单击服务器公钥右侧的"复制"复制服务器公钥。

Alt text

填写pid，sn，PRODUCT_PRIVATE_KEY配置项。单击上一步填写服务器公钥SERVER_PUBLIC_KEY配置项中的"放号"，跳转至生产放号的详情页后，单击"下载"，从下载的"已放号SN列表 (1).csv"文件中复制参数到配置文件中的对应配置项（如下图所示）。

Alt text

# 1.5.3. 注册设备到云中心

修改配置文件后运行src/main/java/com/tencent/welink/iot/IOTLogin.java，可完成设备的注册登录流程，设备注册后需要导入到项目中，赋予项目属性。

# 1.5.4. 导入设备

在设备完成注册及登陆后，从微瓴管理平台首页 > 选择项目 > 设备管理 > 导入设备进入到设备导入的详情页，随后单击"下载导入文件模版"。

Alt text

导入文件模版说明

需要注意的是：建筑、楼层、位置、具体点位编码(经纬度)、图纸编号等字段信息建议在"子设备模版"文件中进行填写。

Alt text

填写项	说明
设备名称	（非必填）可自定义设备的名称，不超过50个字符
设备类型	（非必填）辅助信息
* PID	（必填）产品ID，此字段强校验，校验不通过无法导入
* SN	（必填）设备条码，此字段强校验，校验不通过无法导入
建筑	（非必填）建筑有录入时，可下拉填写数据
楼层	（非必填）楼层有录入时，可下拉填写数据
位置	（非必填）位置数据来源于导入的"建筑平面图"图纸中的区域、房间等位置信息
具体点位编码(经纬度)	（非必填）经纬度信息
图纸编号	（非必填）图纸上的编号

注意事项

1）模板表中的PID、SN为必填项，其他为非必填。

2）设备必须通过了生产放号，并注册到平台后才能导入到指定的项目。

3）批量导入设备单次最多导入500个。

4）一个设备只能导入到一个项目中。

5）若没有空间数据可暂时不填，后续在设备管理页面进行补充。

单击中的"上传导入文件"。根据微瓴平台返回的校验结果进行相应的操作。

若不存在无效设备，单击"立即导入"即可。

Alt text

若存在无效设备，则可以单击"查看校验列表"，查看具体校验提示，根据提示修改后重新导入。

Alt text

设备接入成功后，在微瓴管理平台首页 > 选择项目 > 设备管理中可查看设备的状态是否在线。

Alt text

# 1.6. 视频软网关接入（sharp流）

# 1.6.1. 支持设备类型

海康（ipc，nvr，cvr）

说明：磁盘阵列需要对接海康系统

大华
宇视
海康平台
电信平台
其他监控平台按要求定制化

# 1.6.2 支持协议

sharp 自研协议（对接大屏和客户端）
rtmp
http-flv
https-flv
hls

# 1.6.2. 部署方式

公有云接入
私有化接入
专有云接入

Alt text

混合云接入

Alt text

# 1.6.3. 视频软网关部署

要求：

和摄像头部署在同一网络环境下（最好同一网段，至少能ping通摄像头ip）
x86机器
部署步骤如下
新版本视频网关安装部署指引 (opens new window)

# 1.7. 国标GB28181视频接入（sip网关）

# 1.7.1 集成方式

视频监控系统提供基于gb28181协议的方式与下级平台对接，并以api的形式对应用层提供视频播放能力，

其交互方式如下：

Alt text

# 1.7.2. 集成功能

1）视频推流支持最新版国标标准协议：GB28181协议；

2）支持通过上级域的方式拉流；

3）支持实时流、常用云台控制指令，包括有移动（上，下，左，右）、对焦、缩放、调光

4）支持通过open api为第三方提供 rtsp、rtmp、flv、hls等协议拉流能力

5）支持将下级平台设备接入微瓴，并在微瓴平台展示设备列表，统计设备心跳，维护在离线状态

6）支持基于国标协议的不间断推流，按需推流

7）支持动态端口，收流更加安全

8）支持推拉流鉴权配置

# 1.7.3. 接入要求

按照标准的gb28181协议，可以将推流协议简单的等同为：rtp协议+sip协议，其中sip协议负责为平台与平台、平台与设备、设备与平台之间建立消息通道。基于sip协议我方自研的sip服务包含有如下功能和要求：

平台级对接：作为上级，对接下级视频平台
设备对接：支持直接对接设备拉取视频流

其中作为上级，对接下级平台要求如下：

下级平台需支持设备分包下发
如果视频上公网，下级平台需要支持良好的内网穿透能力
下级平台需要支持常用的国标指令（包含但不限于）：REGISTER、invite、catalog、bye、message、RecordInfo、DeviceControl
下级平台有能力接收并处理常用的云台控制指令：移动、对焦、缩放、调光

其中对接设备对摄像头要求如下：

协议版本支持GB/T28181
支持适配sip服务器ip、端口、sip服务器Id、sip服务器域
传输协议支持tcp以及udp
支持定时发送设备心跳
支持定时向指定的sip服务器注册

# 1.7.4 设备接入流程

Alt text

在超管平台为下级平台创建产品（当作视频网关类型）
生成密钥，完成注册、放号生成sn、wId
在微瓴管理平台导入设备将下级平台当成视频网关
部署并配置video-register服务

# 1.8. 子设备接入

微瓴平台支持设备直连，也支持设备挂载在网关上，作为网关的子设备，由网关直连。对于不能进行网络通信的设备，它们需要通过网关进行数据转发。

Alt text

直连设备、网关和子设备的网络拓扑关系

# 1.8.1 新增子设备产品

通过新增产品添加子设备产品，若新增的子设备是挂载到已有的网关中，此步可忽略，可沿用同一子设备产品。

新增子设备产品同【1.3新增产品】步骤基本相同，需要注意：在新增产品中新增子设备，产品属性选择"子设备"。

Alt text

# 1.8.2 导入子设备

子设备产品表示的是一类设备的产品概念，需要使用产品ID加上设备序列号sn把设备注册到微瓴上，有两种子设备注册的方式，如下：

# 1.8.2.1. 通过微瓴平台导入：【推荐】

支持导入网关下的子设备实现批量添加操作，可以将子设备和网关设备进行关联，上传成功后，网关设备可通过获取云端子设备，将子设备注册到网关设备所属的项目中，并生成的子设备的wId。

下载添加子设备模版

从微瓴管理平台首页 > 选择项目 > 设备管理 >批量添加子设备，进入到导入子设备的详情页，单击"下载添加子设备模版"。

需要注意的是：建筑、楼层、位置、具体点位编码(经纬度)、图纸编号等字段信息建议在"子设备模版"文件中进行填写。

Alt text

子设备模版的填写

打开子设备导入模版，根据提示填写自设备信息。需要注意的是：填写`所属网关DIN`中，先加上英文输入法下的单引号 '，确保不会出现超长数字变为0的情况。

Alt text

填写项	说明
设备名称	（非必填）可自定义子设备的名称
设备类型	（非必填）辅助信息
* PID	（必填）产品ID，此字段强校验，校验不通过无法导入
* SN	（必填）设备条码，此字段强校验，校验不通过无法导入
* 所属网关DIN	（必填）子设备所属网关设备的设备标识din，din值获取方式查看
建筑	（非必填）建筑有录入时，可下拉填写数据
位置	（非必填）位置数据来源于导入的"建筑平面图"图纸中的区域、房间等位置信息
具体点位编码（经纬度）	（非必填）经纬度信息
图纸编号	（非必填）图纸上的编号
实时流来源	（非必填）子设备为摄像头设备可选实时流来源为NVR或IPC。摄像机实时视频的配置方式，摄像机设备建议必填
录像存储方式	（非必填）可选COSMTAV或NVR存储方式
RTSP URL(主码流)	（非必填）实时流协议传输协议取主码流，示例：rtsp://设备用户名:密码@设备IP地址/端口号/视频编码格式/通道号/码流类型（主码为main）/av_stream

根据实时流的实际来源填写NVR配置或IPC配置。

Alt text

注意事项：

A）模板表中的PID、SN、所属网关DIN为必填项，其他为非必填。

B）子设备所属父设备必须是网关设备。

C）一个设备只能导入到一个项目中。

wId, din的获取方式：从微瓴管理平台首页 > 选择项目 > 设备管理，进入到设备管理页面，输入网关产品的sn号，单击"查询"。从查询结果中选择网关产品，单击"详情"，在详情页中可获取设备的wId和din号。

Alt text

上传模版注册设备

单击子设备详情页中的"上传导入文件"。根据微瓴平台返回的校验结果进行相应的操作。

a) 若不存在无效设备，单击"立即导入"即可。

b) 若存在无效设备，则可以单击"查看校验列表"，查看具体校验提示，根据提示修改后重新导入。

Alt text

4）子设备在线状态检查

网关上报子设备心跳后，在平台可以看到设备的在线信息。

Alt text

子设备上报模型数据检查

子设备消息上报后，可以在子设备详情里查看设备影子。

Alt text

# 1.8.2.2. 通过设备协议注册

参考设备协议接入demo的例子，通过MQTT的方案按照特定的消息功能码datapoint=30010进行子设备的注册。

选择好子设备接入的网关产品后，参考【1.5设备接入demo的使用】的1、2步骤，将网关产品相关信息在配置文件中填好。在随后的第3步中，网关产品上报 (opens new window)子设备注册的消息到微瓴平台。

参考网关上报子设备注册消息 (opens new window)，将设备的pid，sn填写到deviceList中。微瓴平台收到该条消息后返回功能码为30006 的子设备注册列表。

子设备注册成功，在平台侧也可以看到子设备信息：

Alt text

需要注意的是在管理平台上导入子设备或者删除子设备，网关都会接收到当前网关的子设备列表，系统需要定时拉取云上子设备列表和本地系统子设备进行比对，将设备全量注册到网关下，并且维护设备心跳，上报数据。

# 1.9. OTA更新

当前仅支持直连设备OTA更新，先查询找到想要升级的设备pid。

# 1.9.1. 固件上传

1）使用pid搜索找到直连设备产品或子设备的网关产品，选择OTA

Alt text

2）选择固件上传，此时会保存到COS服务上

Alt text

3）上传信息填写，项目ID为登录微瓴管理平台 > 项目信息 > 项目ID

Alt text

# 1.9.2. 下发固件升级信息到直连设备

登录微瓴管理平台
找到固件上传的产品pid类型下想要升级的设备，查看设备详情
点击升级，选择想要更新的版本，然后确认

Alt text

# 1.9.3. 直连设备接收OTA固件升级消息

上一步升级确认后，在直连设备侧mqtt会接收到一条datapoint功能码固定为30011的消息，需要靠此功能码来判断是否OTA更新消息，在消息里面携带了参数url，使用url进行下载文件。

消息详细请参考OPEN API > IOT通讯协议 >OTA更新接收格式 (opens new window)

# 1.9.4. 设备升级成功后上报升级结果

设备升级成功后需要给微瓴反馈一条升级结果，注意消息里面msgType=ack，seq=上一步接收升级消息里面的seq。

消息详细请参考OPEN API > IOT通讯协议 >设备升级成功后上报升级结果 (opens new window)

# 2. 应用接入

# 2.1. 概述

接入场景

需要使用微瓴的能力，调用相关API接口；
聚合统计的数据或者系统业务生产的非设备类数据需要上传到微瓴；

# 2.2. 相关术语解释

**APPID：**应用唯一标识符。每创建一个新应用，后台会为其配置一个新的应用ID，且后续不可更改。创建过的应用即使在删除后，其应用ID仍然不能被新创建的应用所占有。

**APPTicket：**应用票据，在进行鉴权时会使用到，用于登录微瓴openAPI。票据均有有效期，在票据到期前需要替换。

# 2.3. 操作步骤

# 2.3.1. 登录微瓴开放平台

登录微瓴开放平台 (opens new window)，点击开发中心：

Alt text

# 2.3.2. 新增应用

1）点击应用管理→新增应用：

Alt text

2）填写应用信息提交

**应用名称:**仅支持中文、英文大小写、数字和常用符号，必须以中文、英文或数字开头。建议您在申请的时候以中文命名，最多输入 20 字符 , 且不可修改。

应用类型: web 应用、移动应用、PC 客户端。

**应用领域:**包含智能建筑、智能家居、智慧社区、智慧园区、智慧城市、智慧零售及其他。

**应用简介:**请详细描述该应用的主要功能和使用场景，以便我方工作人员进行检查和审核。最多输入100 字符。

Alt text

# 2.3.3. 应用部署

1）回到应用管理点击部署进入部署页面：

推荐应用申请完成之后部署到微瓴沙箱进行调试项目ID：E1A864F0B77

Alt text

2）点击新增：

Alt text

3）项目ID由微瓴对接人提供，补充好信息后点击提交（其中：应用地址是管理平台跳转到该应用的地址，用于接收3个参数：projectId，login_key_type,login_key【即mvs_unified_tls_login】），消息回调地址如未用到填写应用地址即可。）

Alt text

4）部署完成之后通知微瓴对接人受理审批即可

Alt text

5）审批通过后，点击查看按钮，进入详情页面就可以获取系统对接开发所需要的：AppId，AppKey,AppTicket.

Alt text

# 2.3.4. 启用应用

登录微瓴管理平台 (opens new window)，点击应用导航栏，启动应用。

Alt text

# 2.3.5. 鉴权密钥和票据获取

1.签名机制 (opens new window)，生成sig；

2.后台方式登录接口 (opens new window)，通过该接口获取动态密钥token和物联票据iotim_ticket。

# 2.4. 常用功能

# 2.4.1. 获取设备列表

应用需要有设备权限才获取得到设备数据，需要将应用所属设备绑定到应用。

获取设备列表接口 (opens new window)

# 2.4.2. 获取设备影子

设备影子是一个用于存储设备上报状态、应用程序期望状态信息的数据模型。

设备影子数据接口 (opens new window)

# 2.4.3. 获取设备/应用实时数据

该接口不同于设备影子，该接口实时更新设备/应用实时上报的数据。

实时数据接口 (opens new window)

# 2.4.4. 获取聚合统计数据

在微瓴管理平台配置好数据指标后，可通过该接口获取统计数据。

聚合接口 (opens new window)

# 2.4.5. 获取设备/应用历史数据

历史数据接口需后台按需进行配置后才可使用

设备历史数据接口 (opens new window)

应用历史数据接口 (opens new window)

# 2.4.3. 获取空间数据

# 2.4.3.1. 获取建筑点位信息（level6）

建筑列表接口 (opens new window)

可获取当前项目下所有建筑列表---楼栋名称、楼栋wid、位置等信息。

一般用于获取楼栋wid，用于其他接口传参

# 2.4.3.2. 获取楼层点位信息（level7）

建筑详情接口 (opens new window)

可获取当前项目下所查建筑（根据所传建筑wid）的详情信息---楼层列表、楼层wid、位置等信息

一般用于获取楼层wid，用于其他接口传参

# 2.4.3.3. 获取房间点位信息（level8）

查询地理对象接口 (opens new window)

可获取当前项目下所查某建筑，某楼层（根据所传建筑wid）下的房间信息

level传8

poiCode传m

一般用于获取房间wid，用于查询该房间下的设备点位列表信息

# 2.4.3.4. 获取设备点位信息（level9）

查询地理对象接口 (opens new window)

可获取当前项目下所查某建筑，某楼层，某房间，任意地理纬度（根据所传建筑wid）的设备点位列表信息

level传9

poiCode根据设备类型来传，如果想返回全量数据可以传w

一般用于获取设备点位

# 3. 设备/应用交互

# 3.1. 对象模型-定义对象的数据上报标准

对象模型（ObjectModel）是对事物对象的数字化描述，事物对象包含物理空间中的实体对象，如工厂、楼宇、传感器、甚至人，以及虚拟对象，如应用系统、服务等；对象模型以 JSON格式的形式，定义了对象的描述（Profile）、属性（Properties）、事件（Events）和服务（Services）四个维度。

功能类型	作用	说明
描述 (Profile)	定义模型具体信息	对于所有数据，profile中包含poiCode；对于设备数据，profile中包含productID (选填)，对于应用数据， profile 中包含 applicationId (选填)。
属性 (Properties)	定义设备/应用基础数据项，状态等字段。如：设备-灯具开关状态，色温，颜色灯字段。应用-租赁系统的房间信息、租赁状态、租赁用户、租赁时间等业务信息	属性支持多级嵌套格式。
事件 (Events)	定义设备/应用产生的通知事件或告警事件。告警事件如：设备-门禁，非法闯入事件。应用-停车场应用，道闸故障事件。通知事件如：设备-门禁，人员通行事件。应用-停车场应用，车辆通行事件。	1. 一个事件可携带若干属性，其属性数据同样支持多级嵌套格式；2. 事件 type 属性可以为 notify/alarm/dismiss 三种情况，分别表示通知/告警/取消告警三种事件。
服务 (Services)	定义设备/应用具体有什么控制项。如：设备-灯具开关，颜色等控制项，定义在服务的输入参数中。应用-访客系统，访客预约，预约取消等接口定义，参数定义在服务的输入参数中。	一个服务包含若干输入参数（inputData）和输出参数（outputData），输入参数和输出参数同样支持多级嵌套格式。

# 3.1.1. 对象模型示例：

例如用对象模型表示一个电灯

# 3.1.1.1. 描述 (Profile)

数据的身份证，每条属性值包含以下Key

Key	说明
modelID	对象模型的标识号。
productID	项目ID号。
applicationID	应用 ID 号。
poiCode	分类编码，区分不同类型的对象模型。

Json中如下所示

"profile": {
  "modelId": 123,
  "productID": "12345678",
  "applicationId": "2424",
  "poiCode": "w24242"
}

1
2
3
4
5
6

# 3.1.1.2. 属性(Properties)

对象模型中可以有多个属性值，每条属性值包含以下Key

Key	说明
id	该条属性的id号。
name	该条属性的名称。
desc	该条属性的详细描述。
required	该条属性是否必须，true / false。
mode	该条属性的读写属性，r / rw。
define	属性值的类型，可为：bool(布尔型)、enum(枚举型)、int(32位整型)、long(64位长整型)、float(单精度浮点型)、double(双精度浮点型)、string(字符串)、struct(对象)、array(数组)。

例如电灯有开关和颜色属性，那么Json中如下所示（关于define更多描述可查看下面Json中的desc）：

"properties": [
  {
    "id": "light_switch",
    "name": "电灯开关",
    "desc": "控制电灯开灭(此处示例用于展示 bool 布尔值类型的属性，只能使用 true/false/0/1 这四个可选值；define 中的 mapping 展示了不同可选值所对应的语义化解释)",
    "required": true,
    "mode": "rw",
    "define": {
      "type": "bool",
      "mapping": {
        "0": "关",
        "1": "开",
        "false": "关",
        "true": "开"
      }
    }
  },
  {
    "id": "color",
    "name": "颜色",
    "required": false,
    "desc": "灯光颜色(此处示例用于展示 enum 枚举类型的属性；define 中的 mapping 展示了不同枚举值所对应的语义化解释)",
    "mode": "rw",
    "define": {
      "type": "enum",
      "mapping": {
        "Green": "绿色",
        "Blue": "蓝色",
        "Red": "红色"
      }
    }
  }
]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 3.1.1.3. 事件(Events)

可以定义包含多个事件，但是数据上报时一个模型只允许上报一个事件，每个事件包含以下Key

Key	说明
id	该事件的id号。
name	该事件的名称。
desc	该事件的详细描述。
type	该事件的类型，notify / alarm / dismiss。
required	该事件是否必须，true / false。
properties	该事件中包含的属性组，与前面的Properties (opens new window)定义类似。

下面的Json定义了三个事件类型，如下所示：

"events": [
    {
      "id": "status_report",
      "name": "DeviceStatus",
      "desc": "Report the device status (此处示例用于展示通知的事件，等同于微瓴的业务通知)",
      "type": "notify",
      "required": true,
      "properties": [
        {
          "id": "status",
          "name": "running_state",
          "desc": "Report current device running state",
          "define": {
            "type": "bool",
            "mapping": {
              "0": "normal",
              "1": "fault"
            }
          }
        },
        {
          "id": "message",
          "name": "Message",
          "desc": "Some extra message",
          "define": {
            "type": "string",
            "min": "1",
            "max": "64"
          }
        }
      ]
    },
    {
      "id": "low_voltage",
      "name": "LowVoltage",
      "desc": "Alert for device voltage is low (此处示例用于展示告警事件，等同于微瓴的告警；当 type 为 alarm 时，会多一个 defaultAlarmLevel 元数据，如果 properties 中不存在 alarmLevel 属性，则使用此元数据值作为默认的告警级别；微瓴告警级别为 1~5)",
      "type": "alarm",
      "defaultAlarmLevel": 3,
      "required": false,
      "properties": [
        {
          "id": "voltage",
          "name": "Voltage",
          "desc": "Current voltage",
          "define": {
            "type": "float",
            "unit": "V",
            "step": "1",
            "min": "0.0",
            "max": "24.0"
          }
        }
      ]
    },
    {
      "id": "dismiss_low_voltage_alarm",
      "name": "DismissLowVoltageAlarm",
      "desc": "Dismiss/Cancel alarm (此处示例用于展示消除告警事件，在 alarm 事件发生之后，用于消除告警)",
      "type": "dismiss",
      "required": false,
      "properties": [
        {
          "id": "name",
          "name": "Name",
          "desc": "Name like: memory,tf card, censors ...",
          "define": {
            "type": "string",
            "min": "1",
            "max": "64"
          }
        },
        {
          "id": "error_code",
          "name": "Error_Code",
          "desc": "Error code for fault",
          "define": {
            "type": "int",
            "unit": "",
            "step": "1",
            "min": "0",
            "max": "2000"
          }
        }
      ]
    }
  ]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

# 3.1.1.4 服务 (Events)

可以包含多个服务，每个服务包含以下Key

Key	说明
id	该服务的id号。
name	该服务的名称。
desc	该服务的详细描述。
required	该服务是否是标准功能的必选服务，true / false。
callType	该事件的调用方式，async(异步调用)，sync(同步调用)。目前所有 services 暂只支持 async 异步调用，同时暂无 outputData",
inputData	该服务的传入参数。
outputData	调用该服务返回的参数。
method	该服务服务对应的方法名称(根据id生成)。

以下Json给出了定义一个service的示例：

"services": [
    {
      "id": "switch",
      "name": "服务名称",
      "desc": "服务描述",
      "required": "是否是标准功能的必选服务",
      "callType": "async(异步调用)，sync(同步调用)； 目前所有 services 暂只支持 async 异步调用，同时暂无 outputData",
      "inputData": [
        {
          "id": "入参唯一标识符",
          "name": "入参名称",
          "define": {
            "type": "int",
            "unit": "",
            "step": "1",
            "min": "0",
            "max": "2000"
          }
        }
      ],
      "outputData": [
        {
          "id": "出参唯一标识符",
          "name": "出参名称",
          "define": {
            "type": "int",
            "unit": "",
            "step": "1",
            "min": "0",
            "max": "2000"
          }
        }
      ],
      "method": "服务对应的方法名称(根据id生成)"
    }
  ]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

注：关于对象模型更详细的描述可查看 OpenApi中的微瓴对象模型规范 (opens new window)。

# 3.2. 新增对象模型

管理平台支持用户自定义项目的标准对象模型，同时支持用户复用已公开的对象模型。

# 3.2.1. 登录管理平台

# 3.2.2. 定义模型

1）从微瓴管理平台首页 > 选择项目 > 数据服务 >项目标准对象模型，进入到项目标准对象模型的详情页，单击"新增项目自定义模型"。

Alt text

2）在弹出的"新增项目自定义模型"窗口中填写相关信息。

Alt text

3.1）自定义：若模型定义中选择自定义，可以输入关键字并选择设备的所属类型，随后填入模型名称，单击"确定"完成模型的创建。

3.2）引用公开模型：则需要输入要引用的模型对应的modelID，引用公开的模型后，用户可使用公开的模型来上报数据（引用的公开模型无法修改定义模型功能属性）。

4）进入到刚刚创建的"项目标准对象模型"详情页中，单击"修改定义模型"进入到模型功能定义的详情页。

Alt text

# 3.2.2.1. 属性

填写属性名称和ID，选择对应的数据类型以及对应的数据范围，读写类型即用户使用此属性，是允许读和写，还是只允许读。可自定义添加多个属性字段。

Alt text

示例：

名称：设备状态

ID：devSta

数据类型：枚举型，0/关，1/开

读写类型：读写

Alt text

# 3.2.2.2. 服务

服务是指对象的可服务功能，比如设备“灯”的开。就是开灯服务。可以定义该服务的输入与输出参数。来设置服务功能。如果设备控制项有多种，在输入参数中定义多个控制字段即可。

Alt text

示例：

名称：控制

ID：control

输入参数：

名称：开关

ID：switch

类型：枚举型，0/关，1/开

输出参数：

名称：ack

ID：success

类型：布尔型，0/失败，1/成功

Alt text

# 3.2.2.3. 事件

填写事件名称和ID，新增对应的事件上报参数，再选择事件的类型即可。

Alt text

示例：

名称：设备故障

ID：devFault

输出参数：

时间戳，long类型，事件发生时间戳

事件类型，枚举型，0/告警，1/通知，2/消警

描述，string类型，告警描述

告警等级，int类型，1-通知类警告, 2-轻警告:48小时内处理, 3-中级警告:12小时内处理, 4-严重警告:2小时内处理, 5-致命警告:需要立即处理

事件类型：告警

# 3.3. 设备/应用上报对象模型数据概念

设备/应用根据平台标准或项目自定义的对象模型，上报属性或事件数据给到平台；

1）上报属性（设备运行参数，状态数据等，属性字段放在properties里面）：

上报属性参数：

key	说明	是否必传	层级
reportTs	上报时间戳，毫秒级	是	第一层级
profile	概述对象	是	第一层级
poiCode	分类编码	是	profile
modelId	模型ID	是	profile
productId	产品ID	否	profile
applicationId	appID	否	profile
properties	属性对象，设备/应用属性字段在properties中自定义添加	是	第一层级
light_switch	示例属性字段，用户自定义	是	properties
events	事件对象	是	第一层级

示例：

{
    "reportTs":1572702827618,
    "profile":{
        "productId":"1000001",
        "poiCode":"w0301013",
        "modelId":"123"
    },
    "properties":{
        "light_switch":false,
        "color":"red",
        "brightness":51
    },
    "events":{

    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

2）上报事件（告警/通知/消警）：

key	数据类型	说明	是否必传	层级
reportTs	long	上报时间戳，毫秒级	是	第一层级
profile	struct	概述对象	是	第一层级
appType	string	告警/通知事件父类型，例如安防监控-security_monitoring	是	profile
poiCode	string	分类编码	是	profile
modelId	int	模型ID	是	profile
properties	struct	属性对象，设备/应用属性字段在properties中自定义添加	是	第一层级
events	struct	事件对象	是	第一层级
eventName	string	告警/通知事件子类型，例如安防监控下的非法入侵-invade	是	events
eventType	int	0:告警，1:通知，2:消警	是	eventName
eventTs	long	事件发生时间戳，毫秒级	是	eventName
describe	string	事件描述	是	eventName
image	struct	告警事件/通知事件图片，图片需要自行上传到cos，获取到fileId，参考文档上传图片 (opens new window)，字段拼装参考示例	否	eventName
data	string	fileId	否	image
type	int	固定传4	否	image
videoId	string	告警事件/通知事件视频，同样传fileId，方式同image，字段拼装参考示例	否	eventName

目前已有告警类型可以参考文档事件类型 (opens new window)

上报安防告警示例：

{
    "reportTs":1572702827618,
    "profile":{
        "appType":"security_monitoring",//事件父类型
        "poiCode":"w0301013",
        "modelId":"123"
    },
    "properties":{
        "light_switch":false,
        "color":"red",
        "brightness":51
    },
    "events":{
        "invade":{//eventName事件子类型
            "eventType":0,//0：告警，1:通知，2:消警
            "eventTs":"xxxxxxxxxx",//事件发生时间（毫秒级时间戳）
            "describe":"xxxxx",//告警描述
            "image": {//没有告警图片可不传
    		    "data": "8bb1230b-78bb-4635-991b-9746dda24a9e",//图片文件，fileId
               "type": 4//固定为4
        	},
        	"videoId":"8bdsa0b-72bb-4f35-931b-97dsas4a9e"//没有视频文件可不传，视频文件，fileId
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

备注：eventName里面可以按照需求在模型里面自定义增加字段，上报后数据体现在接收到的消息里的extend字段里。

注意：reportTs，profile，properties，events字段都需要带上，即使没内容也需要带上空对象。

# 3.3.1. 设备上报对象模型

# 3.3.1.1. 模型数据上报

将上述的对象模型数据通过MQTT消息进行上报，上报模型数据（红色字体）如下，value里面是模型数据，value外面是设备消息固定消息字段id：

{
    "timeStamp":1600312947899,
    "random":"bUT4gtw1jAdwFZWW",
    "datapoint":30001,
    "wId":"cae629a1-befc-4084-b8a6-043855e58a3a",
    "msgType":"report",
    "value":"{
        \"reportTs\": 1572702827618,
        \"profile\": {
            \"productId\":\"1000001\",
            \"poiCode\": \"w0301013\",
            \"modelId\": \"123\",
            \"appType\": \"fire_protecting\"
        },
        \"properties\": {
            \"light_switch\": false,
            \"color\": \"red\",
            \"brightness\": 51 
        },
        \"events\": {
            \"fire_alarm\": {
            \"eventType\": 0,
            \"eventTs\": xxxxxxxxxx,
            \"describe\": \"xxxxx\"
            }
        }
    }",
    "seq":212321
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

MQTT消息中各个字段的说明如下：

key	数据类型	说明	是否必传
wId	string	设备唯一标识	是
subwId	string	子设备唯一标识，非必填	是
msgType	string	report：主动发送，ack：查询返回	是
seq	num	消息序号	是
random	string	随机数	是
timeStamp	long	时间戳，单位：毫秒	是
datapoint	num	功能码，如datapoint为30001的消息只能用来上报直连设备心跳	是
value	struct	除了OpenApi中微瓴IOT基础协议(3.1 – 3.11) (opens new window)可自定义填充消息，其他设备数据需要严格按照微瓴对象模型上报。	是

将内容填充到各个字段后，使用MQTT将模型数据进行上报，上报方式查看OpenApi文档中的微瓴IOT基础协议 (opens new window)。

# 3.3.1.2 应用接收设备上报的数据

1）通过调用API接口，openAPI文档 > 数字空间 > 动态数据 >4.1获取设备或者应用模块对象状态数据接口，根据接口入参poiCode（表示取分类编码一类的数据）或者标识（din或wId，表示取单条数据）。

2）通过wss订阅的方式，openAPI文档 > 数字空间 > 实时消息订阅 >3.订阅实时消息及获取，此方式仅适用于模型里仅上报事件events数据，一级主题为模型profile里的appType，二级主题为模型events里的事件对象名，即订阅的完整主题为：fire_protecting/fire_alarm。

3）通过回调接口的方式，应用部署接入时填入回调地址，即为回调接口，当设备上报数据后，如果设备绑定到了应用，上报的消息会自动发送到回调接口上，即接收的数据参考：在openAPI文档> 应用API > 9.7应用接收消息格式（来源设备）

# 3.3.2. 应用上报对象模型

# 3.3.2.1 模型数据上报

将上述的对象模型数据通过应用上报，通过openAPI文档 > 应用API > 9.5消息推送接口 (opens new window)，参数中，message_type=1000500，content对象为上报模型数据如下，content里面是模型数据，content外面是应用消息固定字段id：

{
    "message_type":1000500,
    "content":{
        "reportTs":1572702827618,
        "profile":{
            "productId":"1000001",
            "poiCode":"w0301013",
            "modelId":"123"
        },
        "properties":{
            "light_switch":false,
            "color":"red",
            "brightness":51
        },
        "events":{
            "fire_alarm":{
                "eventType":0,
                "eventTs":"xxxxxx",
                "describe":"xxxxx"
            }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 3.3.2.2. 应用接收应用上报的数据

# 3.4. 应用与设备交互

Alt text

应用系统根据平台标准或项目自定义的对象模型，调用某对象的服务，实际设备控制或应用功能调用；通过 OpenApi /common/msg/send (opens new window)接口发送消息给设备，接口参数如下：

字段名称	数据类型	说明	是否必传
token	String	鉴权参数：登录获取的动态密钥	是
iotim_ticket	String	权参数：登录获取的物联票据	是
wId	String	设备的唯一标识	是
datapoint	Long	自定义功能码	是
cmd	String	下控设备的消息内容,需UrlEncode编码（用模型中services定义的内容来下控，也可以自定义消息下控）	是

控制示例： cmd 填写的参数内容示例如下：

{
    "profile":{
        "poiCode":"w242400",
        "modelId":"123"
    },
    "services":{
        "switch":{ // 此处，switch 对应于 service 定义的 id，其值包含哪些属性由模型中定义的 inputData决定
            "action":"lightOn",
            "color":"red"
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# 3.5应用与应用交互

Alt text

场景：A应用发送消息B应用请求人员列表，B应用给A应用返回人员列表

# 3.5.1. A应用发送消息

1）openAPI文档 > 应用API > 9.5消息推送接口 (opens new window)，发送请求人员列表数据

请求参数中message_type的使用

message_type	说明
1000200	发送文本消息至其他应用系统
1000201	发送 Json 消息至其他应用系统

其他参数

请求参数	参数类型	参数说明
to_appid	String	目标appid，即B应用的appid
msg_attribute	String	消息属性。ack：根据请求返回消息，active: 主动发起，此处使用active
msg_id	Integer	当消息属性为ack时，必填，此处不填
content	String	消息内容，想要发送的数据，例如对象模型数据，此处为请求人员列表，消息自定义
message_type	Integer	1000201

2）调用了消息推送接口后会同步返回消息发送结果，取返回参数中的seq值，进行存储，作用于A回调接口接收数据时，需要进行seq的匹配，形成一次完整的请求返回链路。

注意：如果仅是发送消息，不需要B应用返回结果时，则A应用无需保存seq，也无需进行这两个步骤【3.5.3 B应用发送消息】【3.5.4 A应用接收消息】，此时B接收到A应用的请求后，关注完成自身业务即可。

# 3.5.2. B应用接收消息

1）通过回调接口的方式接收请求人员列表消息，在文档应用接入 > 2.3.3应用部署，此步骤上填写的回调地址即为回调接口，应用A发送的数据将会在此接口上接收。

2）接收的数据参考 openAPI文档 > 应用API > 9.6应用接收消息格式（来源应用） (opens new window)

# 3.5.3. B应用发送消息

【3.5.2 B应用接收消息】接收到请求，根据需求拿到A应用需求数据后，需要调用 openAPI文档 > 应用API > 9.5消息推送接口 (opens new window)，发送人员列表数据给到A应用，注意参数的使用

请求参数	参数类型	参数说明
to_appid	String	目标appid，即A应用的appid
msg_attribute	String	值为ack，即表示反馈数据给A应用
msg_id	Integer	此处需要从回调接口上取到seq进行填充，即和A应用发送消息同步返回的seq值相等
content	String	人员列表数据
message_type	number	1000201

# 3.5.4. A应用接收消息

A应用接收人员列表数据，此处接收数据同【3.5.2 B应用接收消息】方式一样，注意的是，需要取到消息中的seq和【3.5.1 A应用发送消息】同步返回数据中的seq（即已经进行存储的seq）进行匹配，如两seq相同则表示一次完整的链路。

IOT通讯协议 →