1 Star 0 Fork 0

JohnnyM / Pictures

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
该仓库未声明开源许可证文件(LICENSE),使用请关注具体项目描述及其代码上游依赖。
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README

设备接入

一、序言

1 什么是千方物联网平台

千方物联网平台为交通行业开发者/交通行业厂商提供了完整的设备连接和管理服务,可支持各种类型的连接方式,每一类具有相同功能定义的物联网设备以产品为单位进行管理。从“设备状态”、“设备描述”、“属性”、“服务”、“事件”五个维度,对产品的设备模型进行定义,实现设备与应用的快速集成,赋能各类交通应用场景,实现从连接到服务的智能升级。

2 设备接入流程

  • 标准协议接入:设备按照物联网平台提供的协议标准开发通信协议,实现设备接入功能。

image-20201203181148179

  • 协议适配接入:为兼容非物联网设备,可提供协议适配服务。根据双方协商的协议对接方式,为设备开发协议适配器。

基于千方物联网的接入能力,可实现产品与应用系统的快速集成,产品开发的主要流程如下:

image-20201203181911512

3 设备模型

image-20201203182419380

设备模型指将实体的设备虚拟化、数字化,并在云端为其构建数据模型。设备模型是例如传感器、车载装置、摄像头等直接或间接接入云端的数字化表示,从属性、服务和事件三个维度,分别描述了该实体是什么、能做什么、可以对外提供哪些信息。同时,通过设备状态、设备描述两个维度,对设备的状态、业务相关内容进行描述,描述了实体当前状态怎么样、布设于物理世界的什么位置、外部参数等信息。其中,设备状态,用于标注未激活、在线、离线、启用、禁用;设备描述用于标注设备标识、设备相关扩展描述信息(与业务相关)。

1.4 名词解释

功能类型 说明
属性 一般用于描述设备运行时的状态 属性支持GET和SET请求方式。可通过千方行业云平台发起对属性的读取和设置请求
服务 设备可被外部调用的能力或方法 可设置输入参数和输出参数。服务可通过一条指令实现复杂的业务逻辑
事件 设备运行时的事件。 事件一般包含需要被外部获取和/或处理的业务数据,可包含多个输出参数。例如,设备发生故障或告警的信息,超过设定值的温度等

二、产品开发

1 创建产品

1.1 概述

产品指的是具有相同功能或特征的一类设备的集合,产品下的设备将自动继承其所属产品的品牌、名称、型号、功能(属性、服务、事件)等信息。您可以将开发好的产品发布到物联网平台中的交通产品库中,适用方可以在产品下添加若干设备,并集成到项目中进行设备管理。 本文档将为您介绍交通产品库、产品创建、产品基本信息编辑、产品详情查看、删除产品等功能的使用。

1.2 交通产品库

交通产品库中,将以列表形式显示您创建的产品,包括产品的名称、产品标识(ProductKey)、产品厂商/型号、产品创建时间、节点类型、产品发布状态(开发中/已发布)、产品概述以及操作项。

如果您尚未创建任何产品,将提示您首先创建产品。

image-20201204092911512

1.3 产品注册

点击交通产品库页面的“产品注册”,开始创建一款新的产品。在“产品注册”页面中填写产品的基本信息。

  • 产品名称:填写产品名称,用于在交通产品库中标识产品;
  • 产品型号:填写产品的型号;
  • 功能类别(产品分类):选择产品的所属分类,如:视频检测器、线圈检测器等;
  • 产品类型(功能类别):选择产品应用的细分领域,列表分为两个层级,如:智能交通管理-交通采集与发布;高速/公路智能交通 - 监控系统;
  • 厂商名称:填写产品的生产厂商名称;
  • 产品简介:填写产品简介,用于描述产品的相关介绍;
  • 节点类型:选择产品节点类别,直连设备(直接连接平台的单点设别)、网关设备(支持子设备管理的网关型产品)、网关子设备、虚拟设备(通过传统边缘或平台边缘接入的产品);
  • 接入方式:设备入网的主要通讯方式,如果设备有多种入网方式,选择最主要的一种方式即可;
  • 数据协议:物联网平台可提供各种类型的数据协议,选择产品匹配的数据协议。支持的数据协议包括:标准数据协议(物联网平台提供的标准接入方式,不需要额外开发协议适配器)、HTTP(提供“服务端”、“客户端”接入选项)、TCP(提供“服务端”、“客户端”接入选项)、UDP(提供“服务端”、“客户端”接入选项)、SNMP(提供“服务端”、“客户端”接入选项)、透传;
  • 认证方式:选择产品的安全认证方式。

image-20201204093431747

填写完成产品的基本信息后,点击“保存”,产品创建成功,可在交通产品库中看到此款产品,产品状态为“开发中”。产品创建完成后,系统将自动颁发产品的唯一标识"ProductKey"。

1.4 删除产品

在交通产品库中页面,选择要删除的产品,点击“删除”按钮,在弹窗中,确认是否要删除该产品,点击“确定”后即可删除该产品,产品删除后将不可再恢复,请谨慎操作

image-20201204134814327

**注意:**仅可以对开发中且没有添加任何设备的产品进行删除操作,如果产品在开发中,但已经添加了测试设备,您需要先删除所有的测试设备再删除该产品,如果该产品已经发布,您将无法再删除。

2 产品详情

产品创建完成后,在交通产品库的产品列表中,点击“查看详情”按钮,进入该产品的详情页面。

image-20201204131443788

2.1 产品信息

产品的基本信息包括在创建产品时填写的信息,以及 系统为该产品颁发的全局唯一标识(ProductKey)。产品详情页面提供产品的能力定义、协议适配和产品调试等功能。

image-20201204131545996

2.2 编辑产品信息

在产品详情页面中,点击产品信息旁的“编辑”按钮,可在弹窗中修改产品信息。

image-20201204131935456

在产品详情页面中,点击技术参数旁的“编辑”按钮,可在弹窗中修改技术参数信息。

image-20201204134018853

**注意:**编辑产品信息对开发中且设备数量为0的产品开放,如果该产品已发布或已经添加设备,意味着产品已经进入正式投入使用,产品的所有信息将冻结。

3 能力定义

3.1 概述

物联网将物理世界的万物接入网络并通过整合各类服务实现智能化,“设备”作为网络中的基础节点和触手,既是交通信息的采集者,也是服务的提供者和承载者。因此,我们首先需要对“设备”能做什么,能提供什么样的服务进行描述,这就需要开发者从产品层面进行功能建模,定义产品的“属性”、“服务”和“事件”。通过功能建模将各类设备统一抽象为云端的资源,并对外暴露相应的接口,以满足不同场景下不同系统的调用和快速集成。

3.2 设备模型

设备模型从属性、服务和事件三个维度,分别描述了该实体是什么、能做什么、可以对外提供哪些信息。同时,通过设备状态、设备描述两个维度,对设备的状态、业务相关内容进行描述,描述了实体当前状态怎么样、布设于物理世界的什么位置、外部参数等信息。千方物联网平台通过定义的统一的功能建模方法来描述设备,称之为 DSL(即 Device Specification Language)。

image-20201204180626887

设备模型将产品功能类型分为三类:属性、服务和事件。

功能类型 说明
属性 一般用于描述设备运行时的状态 属性支持GET和SET请求方式。可通过千方行业云平台发起对属性的读取和设置请求。
服务 设备可被外部调用的能力或方法 可设置输入参数和输出参数。服务可通过一条指令实现复杂的业务逻辑。
事件 设备运行时的事件。 事件一般包含需要被外部获取和/或处理的业务数据,可包含多个输出参数。例如,设备发生故障或告警的信息,超过设定值的温度等。

3.3 功能定义

此界面可对产品的能力进行查看。点击"编辑"按钮,进入编辑页面,可对产品对应的设备模型进行编辑。

image-20201204182512132

可以根据实际需要,自定义的添加各类功能。点击列表上方的“新增”按钮,在弹窗中创建产品的自定义功能,支持分别创建属性、服务和事件。

image-20201204182703618

添加属性

自定义属性的数据类型包括:int、long、float、double、enum、bool、text、date、struct、array。

同时为其设置取值范围、步长、单位以及读写类型。

image-20201204182832772

添加服务

服务支持添加输入参数和输出参数,点击“新增参数”,在弹窗中添加服务的输入/输出参数。

注意:

事件的输入参数:可以选择将产品下的某个属性直接作为参数,也可以完全自定义一个新的参数。

事件的输出参数:可以选择将当前已有的属性直接作为参数上报,也可以完全自定义各一个参数。

image-20201204183041873

添加事件

事件分为三种类型:“信息”、“告警”和“故障”,“信息”是设备上报的一般性通知或事件,如完成某项任务等,“告警”和“故障”是设备运行过程中主动上报的突发或异常情况,优先级更高。事件由设备主动上报,设备可以携带该事件的相关参数进行输出,例如:设备上报了“高温”告警事件,事件可同时上报设备的当前温度。

image-20201207092018351

注意:

事件的输入参数:添加事件的输出参数时可以选择将当前已有的属性直接作为参数上报,也可以完全自定义各一个参数。

image-20201207114509193

添加事件的输出参数时可以选择将当前已有的属性直接作为参数上报,也可以完全自定义各一个参数。

4 产品发布

产品发布,即代表该产品完成了设备模型的配置工作,可以进入调试阶段。因此,会在该款产品下添加相关测试设备。产品发布后,您将无法再:

  • 编辑产品的信息;
  • 删除产品;
  • 编辑产品的功能定义;
  • 编辑产品的扩展信息;

5 数据流转

5.1 概述

对于采用物联网平台标准协议进行接入的设备,可直接参考mqtt协议对接文档完成设备端的开发和接入。

对于采用其他协议上报数据的设备,需为接入设备开发专用的协议适配器。

5.2 数据解析流程

image-20201207131547416

6 设备调试

6.1 概述

千方物联网平台提供了便捷的在线调试工具。测试工具包括"设备在线调试"和"设备仿真调试"

在开发过程中,可以选择已上线的设备进行在线调试,也可以选择未上线的测试设备进行仿真调试。调试的功能包括:查看设备上报的数据、设置某条属性的值、调用设备服务、获取设备事件等。

调试过程中,可以通过"日志服务"页面查看到调试的结果。

6.2 设备调试功能

在“产品详情”页面点击“产品调试”,或在“设备运维”的"在线调试"页面,选择需要进行调试的设备。

进行产品调试之前,需要先为产品注册至少 一个设备。

image-20201207142438743

如果产品下已经注册设备,则可直接进行产品调试。

image-20201207145955992

页面左侧为产品调试的功能区域,可对调试的内容、调试的方式等内容进行设置。

页面右侧为产品调试的日志展示区域,默认将实时刷新设备端与平台端之间的上、下行数据,包括:设备上线、激活、数据上报、云端下发等日志。日志默认被设置为自动刷新,可在调试过程中随时查看设备的状态,也可以改为手动刷新,以根据需要随时获取设备调试日志。点击“清屏”将清除日志区域中的日志信息。

6.3 设备在线调试

属性调试

点击"属性调试"按钮,对产品的属性进行调试。属性支持“读写”或“只读”两种模式,当选择方法为“获取”,点击“发送指令”,将触发一个 Get 请求下发到设备端,设备在接收到请求后,上报属性数值。

image-20201207151356000

当选择的方法为"设置"时,在功能区域的文本编辑框内以JSON 格式编写将要下发的指令,点击“发送指令”后,物联网平台端将下发Set指令到设备端,设备执行该指令,并且在日志区域显示本次下发的调试日志。

image-20201207152313092

在下发设备属性值时需保证设置的数值与能力定义时定义的数据类型保持一致,否则下发后右侧日志区域会提示相应的错误代码,错误代码的具体定义,请查看《设备模型DSL数据校验错误码》。

服务调试

点击"服务调用"按钮后,通过下拉菜单选择要调试的服务,下方编辑区域中将自动显示出该服务所定义的入参和出参,基于此可以构造一个服务的调用,向设备传入指定参数。

image-20201207175317548

6.4 设备仿真调试

平台根据设备模型建立设备的仿真模型,可以通过仿真模型对设备进行仿真调试。

设备仿真调试可以提供设备在线调试的基础,还可提供"属性上报"和"事件上报"功能,系统可根据页面内设置的内容,按照策略推送属性和/或事件信息。

属性上报/事件上报

点击"属性上报"或"事件上报"按钮,左侧调试功能区域的下方会根据设备模型,自动加载可上报的属性名称或时间名称,可根据字段的类型,为其设置上报内容。

根据调试需要,选择信息的推送方式:

推送:仿真设备根据设置的内容,推送一次数据。

image-20201207180405286

策略推送:以设置好的时间间隔和推送设置的次数,推送预定次数。时间间隔单位为秒。

image-20201207180450734

三、设备管理

1 设备管理

1.1 概述

产品发布后,您可以在“设备管理”页面查看到已发布产品的所有设备,支持按照产品筛选设备列表显示内容。可以通过"添加设备"或"批量添加",将设备添加千方至物联网平台,设备上线后即可通过物联网平台了解设备的运行状态和相关日志。

image-20201208103724833

1.2 查看设备

进入页面时将默认显示全部产品下的所有设备,您可以点击“全部产品”下拉菜单,选择要管理的产品,页面将显示该产品的设备统计概览和设备列表。

image-20201208104315112

1.3 统计概览

统计概览将对指定产品下的相关设备数进行统计,包括通过产品筛选后所对应的接入设备总数量、已激活设备数量、当前在线的设备数量以及当前离线的设备数量。

image-20201208104737737

1.4 设备列表

设备列表可展示已添加的所有设备信息,可以点击"查看详情",进入设备详情页面,查看设备更加详细的设备信息、运行状态及日志等内容。在搜索框内,可输入设备的设备名称或设备ID进行模糊搜索。

image-20201208104920674

1.5 删除设备

如需删除某一设备时,点击该设备所属行的“删除”按钮,且在二次确认后即可删除设备。

删除设备的操作一旦确认后将不可恢复,可能导致上层应用调用时查询出错,您可能需要重新添加设备并重新进行相关配置。

image-20201208105211258

2 新增设备

2.1 概述

产品发布后,即可开始在该产品下添加设备。设备的添加方式支持手工对单一设备进行添加录入和通过模版文件批量添加。

2.2 手工逐一添加

点击"添加设备"按钮,通过弹窗录入所要添加的设备的相关信息。

  • 产品名称(必选):

    通过下拉菜单,选择状态为“已发布”的产品名称,如没有所需产品,需要需要到“产品管理-交通产品库”中添加;

  • 设备出厂ID(必选):

    设备出厂ID为设备在出厂时,厂商为设备设置的标识符(deviceKey);

  • 设备名称(必选):

    设备名称用于在平台上显示的名称(deivce name),方便对产品特征进行识别,例如:京哈高速K0+400摄像头。除此之外,平台还会自动为设备生成一组全平台唯一标识(device ID)。

  • 备注(可选):

    用于对设备信息进行备注。

image-20201208112032656

2.3 模版批量添加(暂不支持)

暂缓

3 设备详情

3.1 概述

设备详情页包含该设备的详情信息、运行状态、设备端与平台端的上下行日志以及设备调试。可在“设备列表”页面选择一个设备,并点击后方的“查看详情”按钮,进入设备对应的设备详情页面。

针对于节点类型为网关节点的设备,在设备详情页面中还可对网关下所属的子设备进行增、删、改、查等操作。

3.2 设备基本信息

在点击"设备详情"按钮,并进入设备详情页后,首先展示该设备的基本信息,自上而下依次包括设备基础信息、设备信息、状态参数、安装配置四部分内容。

image-20201208114557038

3.3 能力中心

设备的能力中心页面,通过卡片和列表的形式对设备的实时状态、事件进行展示。

实时状态页面会根据设备所属的设备模型中定义的属性,生成相应的展示项,并显示设备运行过程中上报的最新属性值。 可以通过“实时刷新”按钮,切换刷新方式,当选择实时刷新时,平台将以固定的时间间隔自动实时请求设备的属性值并进行显示。

image-20201208132305261

3.4 事件管理

事件管理页面对设备上报的事件进行展示。可过事件类型对列表中展示的内容进行筛选。

默认显示最近1小时的事件记录,也可以通过时间范围选项,选择所要展示时间范围内的上报记录。

image-20201208115326848

3.5 服务调用

服务调用页面,对平台端调用设备端的服务内容进行展示。

默认显示最近1小时的服务调用记录,也可以通过时间范围选项,选择所要展示时间范围内的上报记录。

image-20201208115434917

3.6 设备日志

设备日志页面显示设备端与平台端的上下行日志信息,以及设备主动上报的设备运行日志。

平台调用日志

支持通过日志状态(成功、失败)和时间范围对显示的日志内容进行筛选。默认显示最近1小时的日志信息,也可以通过时间范围选择工具,选择其他时间范围

image-20201208120558191

设备运行日志

支持通过时间范围对显示的日志内容进行筛选。默认显示最近1小时的日志信息,也可以通过时间范围选择工具,选择其他时间范围。

注意:设备运行日志的数据实时性,根据设备上报的周期而定,有可能存在数据更新不及时的问题。

image-20201208120639522

3.7 子设备管理

当当前设备的节点类型为网关节点,则可对网关和网关子设备的拓扑关系进行管理。子设备管理页面将显示当前网关设备下所属的网关子设备的设备列表,并可对子设备进行增、删、改、查等操作。

在网关子设备的设备列表当中,可直接查看网关子设备的基本信息。选择指定的网关子设备,点击“查看详情”按钮,可以进入该网关子设备的设备详情页面,点击“删除”按钮,从当前网关设备中删除该网关子设备。

image-20201208134924161

网关设备在被创建出的时候,设备列表中不存在子设备,网关子设备需要手动添加。

点击"添加子设备"按钮,通过弹出的对话框,选择需要添加至网关设备下的网关子产品名称和设备名称。

image-20201208135456048

注意:网关子设备只能唯一被添加至一个网关设备下面。

四、开发资源文档

1 MQTT协议对接文档

1.1 broker

a)address: 172.20.60.21/22

b)Port: 1883

c)Node: 2

1.2 topic作用域

第一级:企业标识/设备来源

第二级:业务大类(物模型/设备影子/设备注册/设备升级/)

第三级:产品ID productID

第四级:设备ID deviceID

第五级:物模型标识

第六级:操作类型(事件/服务/属性)

第七级:动作(set/get)

操作者 操作 功能 Topic 操作 操作者
设备端 发布 属性上报 /ctfo/sys/${PI}/${DI}/model/event/properties/report 订阅 设备接入
设备端 订阅 云端响应设备 /ctfo/sys/${PI}/${DI}/model/event/properties/report/reply 发布 设备接入
设备端 发布 事件上报 /ctfo/sys/${PI}/${DI}/model/event/${dsl.event.identifier}/report 订阅 设备接入
设备端 订阅 云端响应设备 /ctfo/sys/${PI}/${DI}/model/event/${dsl.event.identifier}/report/reply 发布 设备接入
设备端 订阅 属性设置 /ctfo/sys/${PI}/${DI}/model/service/properties/set 发布 设备接入
设备端 订阅 属性获取 /ctfo/sys/${PI}/${DI}/model/service/properties/get[o1] 发布 设备接入
设备端 发布 设备响应云端 /ctfo/sys/${PI}/${DI}/model/service/properties/get/reply 订阅 设备接入
设备端 订阅 服务调用 /ctfo/sys/${PI}/${DI}/model/service/${dsl.service.identifier} 发布 设备接入
设备端 发布 设备响应云端 /ctfo/sys/${PI}/${DI}/model/service/${dsl.service.identifier}/reply 订阅 设备接入
设备端 发布 设备注册 /ctfo/sys/${PI}/${DI}/model/register 订阅 设备接入
设备端 订阅 云端响应设备 /ctfo/sys/${PI}/${DI}/model/register/reply 发布 设备接入
设备端 发布 设备取消注册 /ctfo/sys/${PI}/${DI}/model/unregister 订阅 设备接入
设备端 订阅 云端响应设备 /ctfo/sys/${PI}/${DI}/model/unregister/reply 发布 设备接入
设备端 发布 设备在线 /ctfo/sys/${PI}/${DI}/model/online 订阅 设备接入

1.3 设备属性上报

数据格式:

{
	"productKey":"a1DCgqFRQDq", 
	"deviceId":"DeviceId03", 
	"deviceKey":"设备出厂唯一标识",
    "identifier":"post",
    "params":{
        "LightErrorEnable": 1,
        "LightVolt": 2,
        "GeoLocation":{
            "altitude":7777,
            "CoordinateSystem":1,
            "latitude":36,
            "longitude":126
        }
    },
    "time":1599645880187
}

参数说明:

参数 类型 说明
productKey String 设备所属产品的唯一标识
deviceId String 设备唯一ID
deviceKey String 设备出厂唯一标识,即设备出厂id
identifier String post,此处是固定的,post代表属性上报
pararms Object 设备属性数据
power String 属性名称。产品所具有的属性名称请参见产品的TSL描述 tsl.property.identifier
position String 属性名称。产品所具有的属性名称请参见产品的TSL描述 tsl.property.identifier
value 根据TSL定义 属性值
time Long 属性值产生时间,如果设备没有上报数据,默认采用在云端生成的时间。

1.4 设备事件上报

{ 
	"productKey":"a1DCgqFRQDq",
	"deviceId":"DeviceId03", 
	"deviceKey":"设备出厂唯一标识",
    "identifier":"${tsl.event.identifer}",
    "params":{
        "LightErrorEnable": 1,
        "LightVolt": 2,
        "GeoLocation":{
            "altitude":7777,
            "CoordinateSystem":1,
            "latitude":36,
            "longitude":126
        }
    },
    "time":1599645880187
}

参数说明:

参数 类型 说明
productKey String 设备所属产品的唯一标识
deviceId String 设备唯一ID
deviceKey String 设备出厂唯一标识,即设备出厂id
identifier String ${tsl.event.identifier}
params Object 设备事件发生时的ouptdata
power String 属性名称。产品所具有的属性名称请参见产品的TSL描述 tsl.event.outputData.identifier
position String 属性名称。产品所具有的属性名称请参见产品的TSL描述 tsl.event.outputData.identifier
value 根据TSL定义 属性值
time Long 事件发生时间,如果设备没有上报数据,默认采用在云端生成的时间。

1.5 设备属性设置

{
    "productKey":"al12355****",
	"deviceId":"deviceId03",
	"deviceKey":"设备出厂唯一标识",
    "pararms":{
        "Power":"on",
        "Position":{
            "latitude":39.9,
            "longitude":116.38
        } 
    },
    “time": 1510799670074
}

参数说明:

参数 类型 说明
productKey String 设备所属产品的唯一标识
deviceId String 设备唯一ID
deviceKey String 设备出厂唯一标识,即设备出厂id
pararms Object 设置属性的参数
power Object 属性名称,参考TSL tsl.property.identifier
position Object 属性名称,参考TSL tsl.property.identifier
time Long 指令下发时间

1.6 设备服务调用

{ 
    "productKey":"X5eCzh6****", 
	"deviceId":"5gJtxDVeGAkaEztpisjX",
	"deviceKey":"设备出厂唯一标识",
	"identifier":"${tsl.service.identifier}", 
    "params":{ 
        "Power":"on" 
    }, 
    "time":1510799670074 
}

服务调用参数说明

参数 类型 说明
productKey String 设备所属产品的唯一标识
deviceId String 设备唯一ID
deviceKey String 设备出厂唯一标识,即设备出厂id
identifier String 服务标识符,参见${tsl.service.identifier}
params Object 服务调用的入参
power Object 参数名称,参考TSL tsl.service.inputData.identifier
time Long 服务调用时间

服务调用响应

{ 
    "productKey":"X5eCzh6****", 
	"deviceId":"5gJtxDVeGAkaEztpisjX",
	"deviceKey":"设备出厂唯一标识",
	"identifier":"${tsl.service.identifier}", 
    "params":{ 
        "outputdata":"on" 
    }, 
    "time":1510799670074 
}

返回的数据内容参考TSL中服务的outputData。

服务响应参数说明

参数 类型 说明
productKey String 设备所属产品的唯一标识
deviceId String 设备唯一ID
deviceKey String 设备出厂唯一标识,即设备出厂id
identifier String 服务标识符,参见${tsl.service.identifier}
params Object 服务调用的出参
outputdata Object 参数名称,参考TSL tsl.service.outputData.identifier
time Long 服务调用的响应时间

1.7 设备属性获取

{
	"productKey":"X5eCzh6****", 
	"deviceId":"5gJtxDVeGAkaEztpisjX",
	"deviceKey":"设备出厂唯一标识",
	"identifier":"get",
	"params": [
		"LightErrorEnable",
		"LightVolt",
		"DrainVoltage"
		.....
    ]
}

参数说明

参数 类型 说明
productKey String 设备所属产品的唯一标识
deviceId String 设备唯一ID
deviceKey String 设备出厂唯一标识,即设备出厂id
identifier String get,属性获取时服务的identifier为get
params Array,数组 需要获取的属性的identifier
LightErrorEnable String 参数名称,参考TSL tsl.property
LightVolt String 参数名称,参考TSL tsl.property
DrainVoltage String 参数名称,参考TSL tsl.property
time Long 属性获取时间

属性获取响应

{
	"productKey":"X5eCzh6****", 
	"deviceId":"5gJtxDVeGAkaEztpisjX",
	"deviceKey":"设备出厂唯一标识",
    "params": {
		"LightErrorEnable":1,
        "LightVolt":3,
        "DrainVoltage":{
            "altitude":7777,
            "CoordinateSystem":1,
            "latitude":36,
            "longitude":126
        }
    }      
}

参数说明

参数 类型 说明
productKey String 设备所属产品的唯一标识
deviceId String 设备唯一ID
deviceKey String 设备出厂唯一标识,即设备出厂id
identifier String get,属性获取时服务的identifier为get
params Object 属性获取时设备响应的数据
LightErrorEnable String 参数名称,参考TSL tsl.property
LightVolt String 参数名称,参考TSL tsl.property
DrainVoltage String 参数名称,参考TSL tsl.property
time Long 设备响应时间

1.8 设备在线状态

{
	"productKey":"X5eCzh6****", 
	"deviceId":"5gJtxDVeGAkaEztpisjX",
	"deviceKey":"设备出厂唯一标识",
    "params":{ 
        "onlineStatus":0 
    }, 
    "time":1510799670074 
}

参数说明

参数 类型 说明
productKey String 设备所属产品的唯一标识
deviceId String 设备名称
deviceKey String 设备出厂唯一标识,即设备出厂id
params Object 上报状态的内容
onlineStatus int 设备在线状态 0:离线 1:在线
time Long 上报时间

1.9 响应

a)成功
{
	"code":200,
    "data":{
    },
    "message":"success",
    "success":true
}
b)失败
{
    "code":1205,
    "data":{
        "productKey":"1205:productKey not exist"
    },
    "message":"fail",
    "success":false
}
{
    "code":1207,
    "data":"payload must be json format",
    "message":"fail",
    "success":false
}

更多错误状态码,请参考”设备模型DSL数据校验错误码”

2 设备模型DSL数据校验错误码

2.1 验证成功

{
    "code":200,
    "data":{
    
    },
    "message":"success",
    "success":true
}

2.2验证productKey

{
    "code":1205,
    "data":{
        "productKey":"1205:productKey not exist"
    },
    "message":"fail",
    "success":false
}

2.3验证deviceId

{
    "code":1206,
    "data":{
        "deviceId":"1206:deviceId not exist"
    },
    "message":"fail",
    "success":false
}

2.4 验证json格式正确性

{
    "code":1207,
    "data":"payload must be json format",
    "message":"fail",
    "success":false
}

2.5 验证属性是否存在

{
    "code":1304,
    "data":{
        "DrainV3232332oltage":"1304: tsl parse: params not exist"
    },
    "message":"fail",
    "success":false
}

2.6 验证属性的值

a)int类型

1.验证是否为int型

{
    "code":1306,
    "data":{
        "TiltThreshold":"1306:tsl parse: data type is not int -> TiltThreshold"
    },
    "message":"fail",
    "success":false
}

2.验证数值范围

{
    "code":1306,
    "data":{
        "TiltThreshold":"1306:tsl parse: int value is bigger than max 90 -> TiltThreshold"
    },
    "message":"fail",
    "success":false
}
b)float类型

1.验证是否为float型

{
    "code":1307,
    "data":{
        "LightCurrent":"1307:tsl parse: data type is not float -> LightCurrent"
    },
    "message":"fail",
    "success":false
}

2.验证数值范围

{
    "code":1307,
    "data":{
        "LightVolt":"1307:tsl parse: float value is bigger than max 4 -> LightVolt"
    },
    "message":"fail",
    "success":false
}
c)boolean类型

1.验证是否为boolean类型

{
    "code":1308,
    "data":{
        "OverVoltEnable":"1308:tsl parse: value of bool type must be int -> OverVoltEnable"
    },
    "message":"fail",
    "success":false
}

2.验证boolean类型值得正确性

{
    "code":1308,
    "data":{
        "OverTiltEnable":"1308:tsl parse: bool specs error -> OverTiltEnable"
    },
    "message":"fail",
    "success":false
}
d)enum类型

1.验证数据类型正确性

{
    "code":1309,
    "data":{
        "test_enum":"1309:tsl parse: value of enum type must be int -> test_enum"
    },
    "message":"fail",
    "success":false
}

2.验证枚举类型值的正确性

{
    "code":1309,
    "data":{
        "test_enum":"1309:tsl parse: enum specs error -> test_enum"
    },
    "message":"fail",
    "success":false
}
e)**text(String)**类型

1.验证数据类型正确性

{
    "code":1310,
    "data":{
        "test_text":"1310:tsl parse: data type is not string -> test_text"
    },
    "message":"fail",
    "success":false
}

2.验证数据类型值的正确性

{
    "code":1310,
    "data":{
        "test_text":"1310:tsl parse: string length bigger than max length 10 -> test_text"
    },
    "message":"fail",
    "success":false
}
f)array类型

1.params对应的值是否为数组,即格式的验证

{
    "code":1301,
    "data":{
        "test_array01":"1301:tsl parse: params format must be JSONObject/JSONArray -> test_array01"
    },
    "message":"fail",
    "success":false
}

2.验证数组的长度是否合法

{
    "code":1324,
    "data":{
        "test_array01":"1324:tsl parse: array size is bigger than max size 6 -> test_array01"
    },
    "message":"fail",
    "success":false
}

3.验证每一个参数和参数的值

{
    "code":1306,
    "data":{
        "test_array01":"1306:tsl parse: data type is not int -> test_array01"
    },
    "message":"fail",
    "success":false
}
g)double类型

1.验证数据类型正确性

{
    "code":1322,
    "data":{
        "test_double":"1322:tsl parse: data type is not double -> test_double"
    },
    "message":"fail",
    "success":false
}

2.验证数据类型值的正确性

h)struct类型

1.验证数据类型正确性

{
    "code":1312,
    "data":{
        "GeoLocation":"1312:tsl parse: struct param size error -> GeoLocation"
    },
    "message":"fail",
    "success":false
}

2.验证数据类型值的正确性

{
    "code":1304,
    "data":{
        "GeoLocation":"1304:tsl parse: field longit33333ude not exist in struct GeoLocation"
    },
    "message":"fail",
    "success":false
}

3.参数属性值得合法性

{
    "code":1322,
    "data":{
        "GeoLocation":"1322:tsl parse: double value is bigger than max 180 -> longitude"
    },
    "message":"fail",
    "success":false
}
{
    "code":1309,
    "data":{
        "GeoLocation":"1309:tsl parse: enum specs error -> CoordinateSystem"
    },
    "message":"fail",
    "success":false
}
i)date(string类型的UTC时间戳毫秒)
{
    "code":1311,
    "data":{
        "test_date":"1311:tsl parse: date type must be a string of long(UTC ms) -> test_date"
    },
    "message":"fail",
    "success":false
}

2.7 错误码

code 说明
1205 productKey不存在
1206 deviceId不存在
1207 json格式错误
1301 属性值(value)类型错误
1304 属性名(identifier)不存在
1306 int类型数据异常
1307 Float类型数据异常
1308 Boolean类型数据异常
1309 enum类型数据异常
1310 text类型数据异常
1311 Date类型数据异常
1312 struct类型数据异常
1322 Double类型数据异常
1324 Array类型数据异常

3 DSL字段描述说明

设备模型指将实体的设备虚拟化、数字化,并在云端为其构建数据模型。从属性、服务和事件三个维度,分别描述了该实体是什么、能做什么、可以对外提供哪些信息。同时,通过设备状态、设备描述两个维度,对设备的状态、业务相关内容进行描述,描述了实体当前状态怎么样、布设于物理世界的什么位置、外部参数等信息。其中,设备状态,用于标注未激活、在线、离线、启用、禁用;设备描述用于标注设备标识、设备相关扩展描述信息(与业务相关)。

功能定义完成后,物联网平台将自动生成 JSON 格式的DSL,以下是一个完整的DSL 的示例。

{
    "schema":"https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json",
    "profile":{
        "productKey":"a1CYhCg3ij0"
    },
    "properties":[
        {
            "identifier":"prop01",
            "name":"prop01",
            "accessMode":"rw",
            "desc":"自定义属性",
            "required":false,
            "dataType":{
                "type":"text",
                "specs":{
                    "length":"2048"
                }
            }
        }
    ],
    "events":[
        {
            "identifier":"post",
            "name":"post",
            "type":"info",
            "required":true,
            "desc":"属性上报",
            "method":"thing.event.property.post",
            "outputData":[
                {
                    "identifier":"prop01",
                    "name":"prop01",
                    "dataType":{
                        "type":"text",
                        "specs":{
                            "length":"2048"
                        }
                    }
                }
            ]
        },
        {
            "identifier":"event01",
            "name":"event-01",
            "type":"error",
            "required":false,
            "desc":"测试事件",
            "method":"thing.event.event01.post",
            "outputData":[
                {
                    "identifier":"event_param",
                    "name":"event_param",
                    "dataType":{
                        "type":"enum",
                        "specs":{
                            "10000":"描述00",
                            "10001":"描述01"
                        }
                    }
                }
            ]
        }
    ],
    "services":[
        {
            "identifier":"set",
            "name":"set",
            "required":true,
            "callType":"async",
            "desc":"属性设置",
            "method":"thing.service.property.set",
            "inputData":[
                {
                    "identifier":"prop01",
                    "name":"prop01",
                    "dataType":{
                        "type":"text",
                        "specs":{
                            "length":"2048"
                        }
                    }
                }
            ],
            "outputData":[
            ]
        },
        {
            "identifier":"get",
            "name":"get",
            "required":true,
            "callType":"async",
            "desc":"属性获取",
            "method":"thing.service.property.get",
            "inputData":[
                "prop01"
            ],
            "outputData":[
                {
                    "identifier":"prop01",
                    "name":"prop01",
                    "dataType":{
                        "type":"text",
                        "specs":{
                            "length":"2048"
                        }
                    }
                }
            ]
        },
        {
            "identifier":"servic01",
            "name":"servic01",
            "required":false,
            "callType":"async",
            "desc":"自定义属性",
            "method":"thing.service.servic01",
            "inputData":[
                {
                    "identifier":"param1",
                    "name":"参数01",
                    "dataType":{
                        "type":"int",
                        "specs":{
                            "min":"1",
                            "max":"10",
                            "step":"1"
                        }
                    }
                }
            ],
            "outputData":[
                {
                    "identifier":"outparam",
                    "name":"outparam",
                    "dataType":{
                        "type":"text",
                        "specs":{
                            "length":"2048"
                        }
                    }
                }
            ]
        }
    ]
}

第三方行业应用侧开发API

一、序言

为了降低应用的开发难度,提升应用侧的开发效率,设备管理平台向应用侧开放API接口,应用侧可以使用API快速集成设备管理平台,实现设备注册、设备获取、属性获取、属性设置、服务调用,运行状态,事件获取等功能。

image-20201207182441306

二、接口说明

API分组 使用说明
产品管理 获取设备管理平台的产品详细信息
设备管理 获取设备管理平台的设备详细信息
分组管理 获取设备管理平台的设备分组信息
设备模型管理 获取产品下的设备模型信息,即设备的能力定义信息
设备模型使用API 对设备的操作,主要包括对设备的服务调用,属性设备,获取设备主动上报的数据信息
设备影子
固件升级

三、产品管理

查询产品列表

3.1 接口说明

调用该接口可以获得当前设备管理平台已经创建的产品列表信息,支持分页查询和条件查询。

3.2 URI

请求方发 POST
URI /product/queryProductPage
传输协议 HTTP
consumes JSON

3.3 请求参数

参数名称 说明 请求类型 必填 类型 schema
authentication 认证方式 body false string
categoryId 产品类别,多个类型以英文半角逗号分隔 body false string
createTime 创建时间 body false date-time
dataProtocol 数据协议 body false string
featureType 功能类型 body false string
introduce 产品简介 body false string
model 产品型号 body false string
networkingType 接入方式 body false string
nodeType 节点类型 body false string
pageNo 请求页码-默认1,从1开始 body true int32
pageSize 每页条数-默认20,最大100 body true int32
productKey 产品key body false string
productName 产品名称 body false string
status 产品状态 body false int32
updateTime 修改时间 body false date-time
vendorId 厂商Id body false string

3.4 返回数据

参数名称 说明 类型 schema
code string
data PageInfo«ProductVO» PageInfo«ProductVO»
data 分页结果数据列表 array ProductVO
authentication 认证方式 string
categoryId 产品类别 string
createTime 创建时间 date-time
dataProtocol 数据协议 string
deviceNum 设备数量 int32
extra 扩展字段 object
featureType 功能类型 string
introduce 产品简介 string
model 产品型号 string
networkingType 接入方式 string
nodeType 节点类型 string
parentNode 父级节点 string
productKey 产品唯一标识 string
productLabel 产品标签 string
productName 产品名称 string
status 产品状态 int32
updateTime 更新时间 date-time
vendorId 厂商Id string
empty boolean
total 数据总条数 int64
message string
success boolean

3.5 示例

请求示例:

{
    "pageNo": 1,
    "pageSize": 10
}

响应示例:

{
    "code": "9999",
    "message": "操作成功",
    "data": {
        "total": 22,
        "data": [
            {
                "productKey": "5110498557035520",
                "productName": "ECU",
                "model": "ECU1234",
                "featureType": "margin",
                "categoryId": "5081047559341056",
                "vendorId": "102",
                "introduce": "123",
                "nodeType": "gateway",
                "networkingType": "ethernet",
                "dataProtocol": "mqtt",
                "authentication": "no_authorization",
                "status": 1,
                "deviceNum": 0,
                "createTime": "2020-09-22 14:10:53",
                "updateTime": "2020-09-22 06:10:52",
                "productLabel": null,
                "extra": {
                    "vendorName": "千方集团",
                    "nodeType": "网关设备"
                },
                "parentNode": null
            },
            {
                "productKey": "5110245780882432",
                "productName": "AAA",
                "model": "AAA",
                "featureType": "enforce",
                "categoryId": "5081047559341056",
                "vendorId": "101",
                "introduce": "aaa",
                "nodeType": "direct",
                "networkingType": "cellular",
                "dataProtocol": "standard",
                "authentication": "device_secret",
                "status": 0,
                "deviceNum": 0,
                "createTime": "2020-09-22 09:53:44",
                "updateTime": "2020-09-22 01:54:34",
                "productLabel": null,
                "extra": {
                    "vendorName": "千方科技",
                    "nodeType": "直连设备"
                },
                "parentNode": null
            }
        ],
        "empty": false
    },
    "success": true
}

四、设备管理

4.1 查询设备列表

4.1.1 接口说明

调用此接口返回设备详细信息。

4.1.2 URI

请求方发 POST
URI /device/queryDevicePage
传输协议 HTTP
consumes JSON

4.1.3 请求参数

参数名称 说明 请求类型 必填 类型
devicePageQuery devicePageQuery body true 设备查询列表
pageNo 请求页码-默认1,从1开始 body true int32
pageSize 每页条数-默认20,最大100 body true int32
productKey 产品唯一标识 body false string
deviceKey 设备编号 body false string
deviceType 设备编号 body fasle string

4.1.4 返回数据

参数名称 说明 类型 schema
code string
data PageInfo«DeviceVO» PageInfo«DeviceVO»
data 分页结果数据列表 array DeviceVO
activeTime 激活时间 date-time
activeYn int32
childDeviceNum 子设备数量 int32
createTime 添加时间 date-time
deviceId 设备唯一标识 string
deviceName 设备名称 string
deviceOperater 设备运营商 string
extra 扩展字段格式:{"dataProtocol":"标准数据协议","featureType":"功能类型","model":"产品型号","nodeType":"节点类型","networkingType":"接入方式","category":"产品类型","productName":"产品名称","vendor":"供应商"} object
firmwareVersion 固件版本 number
id id int64
inspectionCycle 巡检周期 number
ip IP地址 string
lastOnlineTime 最后一次上线时间 date-time
lifeCycle 使用寿命 number
logReportYn 本地日志是否上报 1-上报 0-不上报 int32
macAddr MAC地址 string
networkingType 网络类型 string
nickName 备注名称 string
onlineYn 设备状态 1-在线 0-离线 int32
parentDeviceId 父设备id string
position 安装位置 string
productKey 产品唯一标识 string
projectName 项目名称 string
startUseTime 启用时间 date-time
status 启用状态 0-禁用 1-启用 2-删除 int32
usedDay 已使用天数 int32
empty boolean
total 数据总条数 int64
message string
success boolean

4.1.5 示例

请求示例:

{
    "pageNo": 1,
    "pageSize": 1,
    "productKey": "5100649308652544"
}

响应示例:

{
    "code": "9999",
    "message": "操作成功",
    "data": {
        "total": 12,
        "data": [
            {
                "id": null,
                "deviceId": "5111900933800960",
                "deviceName": "test1357",
                "nickName": "test1357",
                "productKey": "5100649308652544",
                "onlineYn": null,
                "parentDeviceId": null,
                "lastOnlineTime": null,
                "activeYn": 1,
                "activeTime": null,
                "startUseTime": null,
                "logReportYn": 1,
                "ip": null,
                "macAddr": null,
                "firmwareVersion": null,
                "inspectionCycle": null,
                "position": null,
                "lifeCycle": null,
                "projectName": null,
                "status": 1,
                "childDeviceNum": 0,
                "extra": {
                    "dataProtocol": "标准数据协议",
                    "featureType": "执法设备",
                    "model": "e33333",
                    "nodeType": "直连设备",
                    "category": "交通采集与发布",
                    "networkingType": "蜂窝网络(2G/3G/4G)",
                    "productName": "正式演示",
                    "authentication": "无认证"
                },
                "createTime": "2020-09-23 05:57:26",
                "usedDay": 0,
                "networkingType": null,
                "deviceOperater": ""
            }
        ],
        "empty": false
    },
    "success": true
}

4.2 查询子设备列表

4.2.1 接口说明

调用此接口返回子设备的列表和设备的详细信息

4.2.2 URI

请求方发 POST
URI /device/queryChildDevicePage
传输协议 HTTP
consumes JSON

4.2.3 请求参数

参数名称 说明 请求类型 必填 类型
deviceId 父设备Id body true string
pageNo 请求页码-默认1,从1开始 body true int32
pageSize 每页条数-默认20,最大100 body true int32

4.2.4 返回数据

参数名称 说明 类型 schema
code string
data PageInfo«DeviceVO» PageInfo«DeviceVO»
data 分页结果数据列表 array DeviceVO
activeTime 激活时间 date-time
activeYn int32
childDeviceNum 子设备数量 int32
createTime 添加时间 date-time
deviceId 设备唯一标识 string
deviceName 设备名称 string
deviceOperater 设备运营商 string
extra 扩展字段格式:{"dataProtocol":"标准数据协议","featureType":"功能类型","model":"产品型号","nodeType":"节点类型","networkingType":"接入方式","category":"产品类型","productName":"产品名称","vendor":"供应商"} object
firmwareVersion 固件版本 number
id id int64
inspectionCycle 巡检周期 number
ip IP地址 string
lastOnlineTime 最后一次上线时间 date-time
lifeCycle 使用寿命 number
logReportYn 本地日志是否上报 1-上报 0-不上报 int32
macAddr MAC地址 string
networkingType 网络类型 string
nickName 备注名称 string
onlineYn 设备状态 1-在线 0-离线 int32
parentDeviceId 父设备id string
position 安装位置 string
productKey 产品唯一标识 string
projectName 项目名称 string
startUseTime 启用时间 date-time
status 启用状态 0-禁用 1-启用 2-删除 int32
usedDay 已使用天数 int32
empty boolean
total 数据总条数 int64
message string
success boolean

4.2.5 示例

请求示例:

{
    "deviceId": "DeviceName03",
    "pageNo": 1,
    "pageSize": 5
}

响应示例:

{
    "code": "9999",
    "message": "操作成功",
    "data": {
        "total": 2,
        "data": [
            {
                "id": null,
                "deviceId": "5086186976478208",
                "deviceName": "设备名称2",
                "nickName": "备注名称2",
                "productKey": "5080829127197696",
                "onlineYn": null,
                "parentDeviceId": "DeviceName03",
                "lastOnlineTime": null,
                "activeYn": 0,
                "activeTime": null,
                "startUseTime": "2020-09-14 19:22:45",
                "logReportYn": 0,
                "ip": null,
                "macAddr": null,
                "firmwareVersion": null,
                "inspectionCycle": null,
                "position": null,
                "lifeCycle": null,
                "projectName": null,
                "status": 0,
                "childDeviceNum": null,
                "extra": {
                    "dataProtocol": "",
                    "vendor": "",
                    "featureType": "",
                    "model": "ctfo-2000",
                    "nodeType": "",
                    "networkingType": "",
                    "category": "",
                    "productName": "测试",
                    "authentication": ""
                },
                "createTime": "2020-09-10 00:09:42",
                "usedDay": null,
                "networkingType": null,
                "deviceOperater": null
            },
            {
                "id": null,
                "deviceId": "5099270851347456",
                "deviceName": "设备名称test1",
                "nickName": "备注名称test1",
                "productKey": "2020083101",
                "onlineYn": null,
                "parentDeviceId": "DeviceName03",
                "lastOnlineTime": null,
                "activeYn": 0,
                "activeTime": null,
                "startUseTime": null,
                "logReportYn": 0,
                "ip": null,
                "macAddr": null,
                "firmwareVersion": null,
                "inspectionCycle": null,
                "position": null,
                "lifeCycle": null,
                "projectName": null,
                "status": 0,
                "childDeviceNum": null,
                "extra": {
                    "dataProtocol": "标准数据协议",
                    "vendor": "",
                    "featureType": "执法设备",
                    "model": "测试产品2020-08-31",
                    "nodeType": "网关子设备",
                    "networkingType": "蜂窝网络(2G/3G/4G)",
                    "category": "交通采集与发布,交通信号控制",
                    "productName": "测试产品2020-08-32",
                    "authentication": ""
                },
                "createTime": "2020-09-14 07:49:27",
                "usedDay": 0,
                "networkingType": null,
                "deviceOperater": "103"
            }
        ],
        "empty": false
    },
    "success": true
}

4.3 根据设备编号查询设备列表

4.3.1 接口说明

调用此接口返回设备详细信息。

4.3.2 URI

请求方发 POST
URI /device/queryDeviceByDeviceKeys
传输协议 HTTP
consumes JSON

4.3.3 请求参数

参数名称 说明 请求类型 必填 类型
deviceKeyListQuery deviceKeyListQuery body true 设备查询列表
deviceKyeList 设备编号 body true Array

4.3.4 返回数据

参数名称 说明 类型 schema
code string
data 结果数据列表 array DeviceVO
activeTime 激活时间 date-time
activeYn int32
childDeviceNum 子设备数量 int32
createTime 添加时间 date-time
deviceId 设备唯一标识 string
deviceName 设备名称 string
deviceOperater 设备运营商 string
extra 扩展字段格式:{"dataProtocol":"标准数据协议","featureType":"功能类型","model":"产品型号","nodeType":"节点类型","networkingType":"接入方式","category":"产品类型","productName":"产品名称","vendor":"供应商"} object
firmwareVersion 固件版本 number
id id int64
inspectionCycle 巡检周期 number
ip IP地址 string
lastOnlineTime 最后一次上线时间 date-time
lifeCycle 使用寿命 number
logReportYn 本地日志是否上报 1-上报 0-不上报 int32
macAddr MAC地址 string
networkingType 网络类型 string
nickName 备注名称 string
onlineYn 设备状态 1-在线 0-离线 int32
parentDeviceId 父设备id string
position 安装位置 string
productKey 产品唯一标识 string
projectName 项目名称 string
startUseTime 启用时间 date-time
status 启用状态 0-禁用 1-启用 2-删除 int32
usedDay 已使用天数 int32
empty boolean
total 数据总条数 int64
message string
success boolean

4.3.5 示例

请求示例:

{
    "pageNo": 1,
    "pageSize": 1,
    "productKey": "5100649308652544"
}

响应示例:

{
    "code": "200",
    "message": "操作成功",
    "data": [
        {
            "id": 1302935204903850129,
            "deviceId": "5150104736351232",
            "deviceName": "设备1020",
            "deviceType": "1",
            "nickName": "测试",
            "productKey": "5150085184865280",
            "onlineYn": 1,
            "parentDeviceId": "5150235051181056",
            "lastOnlineTime": null,
            "activeYn": 1,
            "activeTime": null,
            "startUseTime": "2020-10-21 14:10:06",
            "logReportYn": 1,
            "ip": null,
            "macAddr": null,
            "firmwareVersion": null,
            "inspectionCycle": 3,
            "position": "12,23",
            "lifeCycle": 5.00,
            "projectName": null,
            "status": 1,
            "childDeviceNum": null,
            "extra": {
                "dataProtocol": "MQTT",
                "featureType": "执法设备",
                "model": "3232",
                "nodeType": "直连设备",
                "category": "交通采集与发布",
                "networkingType": "蜂窝网络(2G/3G/4G)",
                "productName": "王鑫测试1020",
                "authentication": "无认证"
            },
            "createTime": "2020-10-20 05:45:21",
            "updateTime": "2020-11-27 08:43:18",
            "usedDay": 0,
            "networkType": "cellular",
            "deviceOperater": "china_mobile",
            "deviceKey": "21121221",
            "model": null,
            "vendorName": null,
            "edgeAccessIp": null,
            "edgeAccessPort": null,
            "operator": null
        }
    ],
    "success": true
}

五、设备模型管理

5.1 查询指定产品的设备模型的历史版本

5.1.1 接口说明

调用此接口查询指定产品的设备模型历史版本。

5.1.2 URI

请求方发 GET
URI /tsl/queryTslVersion
传输协议 HTTP

5.1.3 请求参数

参数名称 说明 请求类型 必填 类型
productKey 产品唯一表示productKey Query True String

5.1.4 返回数据

参数名称 说明 类型 schema
code string
data array 设备模型历史版本
createTime date-time
desc string
launchTime date-time
productKey 产品唯一标识 string
status 1 int32
updateTime date-time
version 版本号 string
message string
success boolean

5.1.5 示例

请求示例:

响应示例:

{
    "code": "9999",
    "message": "操作成功",
    "data": [
        {
            "productKey": "2020083101",
            "version": "100",
            "status": 0,
            "launchTime": "2020-09-09 19:16:20",
            "desc": "version demo1",
            "createTime": "2020-09-07 19:06:05",
            "updateTime": null
        },
        {
            "productKey": "2020083101",
            "version": "101",
            "status": 0,
            "launchTime": "2020-09-09 19:16:21",
            "desc": "version demo1",
            "createTime": "2020-09-09 10:29:09",
            "updateTime": null
        },
        {
            "productKey": "2020083101",
            "version": "102",
            "status": 0,
            "launchTime": "2020-09-09 19:16:24",
            "desc": "version demo1",
            "createTime": "2020-09-09 10:29:09",
            "updateTime": null
        },
        {
            "productKey": "2020083101",
            "version": "20200906094519037",
            "status": 0,
            "launchTime": null,
            "desc": null,
            "createTime": "2020-09-06 09:45:19",
            "updateTime": "2020-09-06 09:45:19"
        },
        {
            "productKey": "2020083101",
            "version": "20200911114653520",
            "status": 1,
            "launchTime": null,
            "desc": null,
            "createTime": "2020-09-11 11:46:54",
            "updateTime": "2020-09-11 11:46:54"
        },
        {
            "productKey": "2020083101",
            "version": "20200911114723513",
            "status": 0,
            "launchTime": null,
            "desc": null,
            "createTime": "2020-09-11 11:47:24",
            "updateTime": "2020-09-11 11:47:24"
        }
    ],
    "success": true
}

5.2 查询指定产品的已发布设备模型中功能定义详情

5.2.1 接口说明

调用此接口查询指定产品的设备模型的功能定义详情。

5.2.2 URI

请求方发 GET
URI /tsl/queryTsl
传输协议 HTTP

5.2.3 请求参数

参数名称 说明 请求类型 必填 类型
productKey 产品唯一标识productKey query true string
tslType 设备模型类型 property-属性,event-时间,service-服务 query false string

5.2.4 返回数据

参数名称 说明 类型 schema
code string
data array 产品设备模型功能定义
accessMode 读写类型 string
callType string
createTime date-time
custom 是否自定义 int32
dataType 数据类型 string
desc string
draftYn int32
eventType string
identifier 标识符 string
inputData string
name 功能名称 string
outputData string
productKey 产品Key string
required int32
status int32
tslId 唯一标识 int64
tslType 功能类别 string
updateTime date-time
version string
message string
success boolean

5.2.5 示例

请求示例:

参考postman  

响应示例:

{
    "code": "9999",
    "message": "操作成功",
    "data": [
        {
            "tslId": 5094785662010368,
            "identifier": "bsf4",
            "productKey": "2020083101",
            "name": "功能名称4",
            "tslType": "property",
            "accessMode": "rw",
            "dataType": "{\"specs\":{\"length\":\"2048\"},\"type\":\"text\"}",
            "custom": 1,
            "required": 0,
            "desc": "描述",
            "method": "",
            "eventType": null,
            "callType": null,
            "inputData": null,
            "outputData": null,
            "status": 1,
            "createTime": "2020-09-10 03:19:51",
            "updateTime": "2020-09-10 23:04:15",
            "draftYn": 0,
            "version": "20200911114653520"
        },
        {
            "tslId": 5094785662059520,
            "identifier": "bsf5",
            "productKey": "2020083101",
            "name": "功能名称5",
            "tslType": "property",
            "accessMode": "rw",
            "dataType": "{\"specs\":{},\"type\":\"date\"}",
            "custom": 1,
            "required": 0,
            "desc": "描述",
            "method": "",
            "eventType": null,
            "callType": null,
            "inputData": null,
            "outputData": null,
            "status": 1,
            "createTime": "2020-09-10 03:20:02",
            "updateTime": "2020-09-10 23:04:15",
            "draftYn": 0,
            "version": "20200911114653520"
        },
        {
            "tslId": 5094785662157824,
            "identifier": "bsf6",
            "productKey": "2020083101",
            "name": "功能名称6",
            "tslType": "property",
            "accessMode": "rw",
            "dataType": "{\"specs\":{\"item\":{\"type\":\"int32\"},\"size\":\"10\"},\"type\":\"array\"}",
            "custom": 1,
            "required": 0,
            "desc": "描述",
            "method": "",
            "eventType": null,
            "callType": null,
            "inputData": null,
            "outputData": null,
            "status": 1,
            "createTime": "2020-09-10 03:20:31",
            "updateTime": "2020-09-10 23:04:15",
            "draftYn": 0,
            "version": "20200911114653520"
        },
        {
            "tslId": 5094785662206976,
            "identifier": "bsf7",
            "productKey": "2020083101",
            "name": "功能名称7",
            "tslType": "property",
            "accessMode": "rw",
            "dataType": "{\"specs\":[{\"identifier\":\"struct1\",\"name\":\"struct1\",\"required\":false,\"dataType\":{\"type\":\"text\",\"specs\":{\"length\":\"2048\"}}},{\"identifier\":\"struct2\",\"name\":\"struct2\",\"required\":false,\"dataType\":{\"type\":\"bool\",\"specs\":{\"0\":\"关\",\"1\":\"开\"}}}],\"type\":\"struct\"}",
            "custom": 1,
            "required": 0,
            "desc": "描述",
            "method": "",
            "eventType": null,
            "callType": null,
            "inputData": null,
            "outputData": null,
            "status": 1,
            "createTime": "2020-09-10 04:34:25",
            "updateTime": "2020-09-10 23:04:15",
            "draftYn": 0,
            "version": "20200911114653520"
        }
    ],
    "success": true
}

六、设备模型使用

6.1 设置设备的属性

6.1.1 接口说明

调用该接口为指定的设备设置属性值,因为下发属性设置命令和设备收到并执行命令是异步的,所以调用该接口时,返回的成功结果只是表示下发属性设置的请求成功,并不代表设备端收到命令并执行成功。

6.1.2 URI

请求方发 POST
URI /device/service/invoke
传输协议 HTTP
consumes JSON

6.1.3 请求参数

参数 类型 说明
productKey String 设备所属产品的唯一标识
deviceId String 设唯一ID
Identifier String 固定值”set”
params Object 设置属性的参数
power Object 属性名称,参考DSL dsl.property.identifier
position Object 属性名称,参考DSL dsl.property.identifier
time Long 指令下发时间

6.1.4 返回数据

参数 类型 说明
code String 200,表示成功,其他参见错误验证码
message String 请求成功
data Object Null
success Boolean 表示请求成功

6.1.5 示例

请求示例:

{
  "deviceId": "5114786354676736", 
  "productKey":"5100649308652544",
  "identifier":"set",
  "params": {
      "property01": 10,
      "test_wgq": 22
    },
    "time":1601017077064
}

响应示例:

{
    "code": "200",
    "message": "操作成功",
    "data": null,
    "success": true
}

6.2 调用设备的服务

6.2.1 接口说明

调用此接口可以调用设备服务,入参为服务提供的inputData,出参为服务对外提供的输出能力。

6.2.2 URI

请求方发 POST
URI /device/service/invoke
传输协议 HTTP
consumes JSON

6.2.3 请求参数

参数 类型 说明
productKey String 设备所属产品的唯一标识
deviceId String 设唯一ID
Identifier String 服务的identifier,参考DSL中dsl.service.identifier
params Object 服务定义的入参信息,格式为json,若入参为空,则为item={}
power Object 入参属性名称,参考DSL dsl.services.inputData
position Object 入参属性名称,参考DSL dsl.services.inputData
time Long 指令下发时间

6.2.4 返回数据

参数 类型 说明
code String 200,表示成功,其他参见错误验证码
message String 请求成功
data Object 服务的出参,具体参考设备模型的dsl.services.outputData
success Boolean 表示请求成功

6.2.5 示例

请求示例:

{
  "deviceId": "5114786354676736", 
  "productKey":"5100649308652544",
  "identifier":"test_service",
  "params": {
    "inputdata01":"333333"
  },
  "time":1601017077064
}

返回示例:

{
    "code": "9999",
    "message": "操作成功",
    "data": "{\"productKey\":\"5100649308652544\",\"deviceId\":\"5114786354676736\",\"items\":{\"outpudata01\":0.46030265},\"time\":1601018286806,\"identifier\":\"test_service\"}",
    "success": true
}

6.3 获取设备的属性值

6.3.1 接口说明

调用此接口查询指定设备的属性值。

6.3.2 URI

请求方发 POST
URI /device/service/invoke
传输协议 HTTP
consumes JSON

6.3.3 请求参数

参数 类型 说明
productKey String 设备所属产品的唯一标识
deviceId String 设唯一ID
Identifier String 固定值”get”
params Array数组 服务定义的入参信息,格式为json,若入参为空,则为item={}
power String 入参属性名称,参考DSL dsl.services.inputData
position String 入参属性名称,参考DSL dsl.services.inputData
time Long 指令下发时间

6.3.4 返回数据

参数 类型 说明
code String 200,表示成功,其他参见错误验证码
message String 请求成功
data Object 服务的出参,具体参考设备模型的dsl.services.identifier.outputData
success Boolean 表示请求成功

6.3.5 示例

请求示例:

{
  "deviceId": "5114786354676736", 
  "productKey":"5100649308652544",
  "identifier":"get",
  "params": ["property01","test_wgq"],
  "time":1601017077064
}

响应示例:

{
    "code": "9999",
    "message": "操作成功",
    "data": "{\"productKey\":\"5100649308652544\",\"deviceId\":\"5114786354676736\",\"items\":{\"property01\":432.0,\"test_wgq\":485.0},\"time\":1601017135980,\"identifier\":\"get\"}",
    "success": true
}

6.4 查询事件历史数据

6.4.1 接口说明

调用此接口可以获取设备的历史事件信息。

5.4.2 URI

请求方发 POST
URI /device/event/queryDeviceEventList
传输协议 HTTP

5.4.3 请求参数

参数 类型 必填 说明
productKey String false 设备所属产品的唯一标识
deviceId String false 设唯一ID
pageNo int true 请求页码,从1开始,默认1
pageSize int true 每页大小,默认20,最大100
startTime Date false 开始时间
endTime Date false 结束时间

5.4.4 返回数据

参数 类型 说明
code String 200,表示成功,其他参见错误验证码
message String 请求成功
data Object 事件的历史数据
success Boolean 表示请求成功

5.4.5 示例

请求数据:

参考postman中对应示例  

响应示例:

{
    "code":"200",
    "message":"success",
    "data":[
         {
           "productKey":"5100649308652544",
           "deviceId":"5114786354676736",
           "identifier":"test_service",
           "items":{
               "alamoutput":123
           },
           "time":1601019432057
        },
       {
           "productKey":"5100649308652544",
           "deviceId":"5114786354676736",
           "identifier":"test_service",
           "items":{
               "alamoutput":125
           },
           "time":1601019432057
        }
    ],
    "success":true
}

6.5 查询设备属性历史信息

6.5.1 接口说明

调用此接口可以获取到设备主动上报的属性的信息,支持历史查询,分页查询,按产品和设备查询。

6.5.2 URI

请求方发 POST
URI /device/event/queryDevicePropertyList
传输协议 HTTP

6.5.3 请求参数

参数 类型 必填 说明
productKey String false 设备所属产品的唯一标识
deviceId String false 设唯一ID
pageNo int true 请求页码,从1开始,默认1
pageSize int true 每页大小,默认20,最大100
startTime Date false 开始时间
endTime Date false 结束时间

6.5.4 返回数据

参数 类型 说明
code String 200,表示成功,其他参见错误验证码
message String 请求成功
data Object 设备上报的属性值
success Boolean 表示请求成功

6.5.5 示例

请求数据:

参考postman中对应示例  

响应数据:

{
    "code":"200",
    "message":"success",
    "data":[
         {
           "productKey":"5100649308652544",
           "deviceId":"5114786354676736",
           "items":{
               "property01":123,
               "test_wgq":11
           },
           "time":1601019432057
        },
       {
           "productKey":"5100649308652544",
           "deviceId":"5114786354676736",
           "items":{
                "property01":1232,
               "test_wgq":16
           },
           "time":1601019432057
        }
    ],
    "success":true
}

七 Kafka属性/事件数据对接

Topic: thing.event.post

7.1 属性上报数据

{
	"productKey":"5158643052495872",
    "deviceId":"5158653929849856",
    "pid":"40300210FFFFFFFFFFFFFFFFee6c5798130179d4",
    "items":{
        "test_int":{
            "type":"int",
            "value":2
        }
    },
    "time":1603699655704,
    "identifier":"post"
}

7.2 事件上报数据

{
    "productKey":"5158930055988224",
    "deviceId":"5158934179021824",
    "pid":"40300210FFFFFFFFFFFFFFFFee6c5798130179d4",
    "items":{
        "test_event_output":{
            "type":"int",
            "value":12
        }
    },
    "time":1603713083974,
    "identifier":"test_event"
}

八、 kafka 设备在线数据对接

Topic: thing.device.online

备注:0:离线 1:在线

{
  "productKey": "5162807804363776",
  "deviceId": "5181651340690432",
  "pid":"40300210FFFFFFFFFFFFFFFFee6c5798130179d4",
  "items": {
    "onlineStatus": {
      "type": "int",
      "value": 0
    }
  },
  "time": 1605098670498
}

附:20201202 第三方行业应用侧开发API.postman_collection.json

{
	"info": {
		"_postman_id": "3d9e970e-6936-42d8-a1ed-0ea8b39d957b",
		"name": "第三方行业应用侧开发API",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "3.1查询产品列表",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\r\n    \"pageNo\": 1,\r\n    \"pageSize\": 2\r\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "http://172.20.60.16:31509/product/queryProductPage",
					"protocol": "http",
					"host": [
						"172",
						"20",
						"60",
						"16"
					],
					"port": "31509",
					"path": [
						"product",
						"queryProductPage"
					]
				},
				"description": "查询产品的列表信息"
			},
			"response": []
		},
		{
			"name": "4.1查询指定产品下的设备列表",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\r\n    \"pageNo\": 1,\r\n    \"pageSize\": 10,\r\n    \"productKey\": \"\",\r\n    \"deviceKey\":\"\",\r\n    \"deviceType\":\"\"\r\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "http://172.20.60.16:31509/device/queryDevicePage",
					"protocol": "http",
					"host": [
						"172",
						"20",
						"60",
						"16"
					],
					"port": "30271",
					"path": [
						"device",
						"queryDevicePage"
					]
				},
				"description": "查询设备详情"
			},
			"response": []
		},
		{
			"name": "4.2查询子设备列表",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\r\n    \"deviceId\": \"DeviceName03\",\r\n    \"pageNo\": 1,\r\n    \"pageSize\": 5\r\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "http://172.20.60.16:31509/device/queryChildDevicePage",
					"protocol": "http",
					"host": [
						"172",
						"20",
						"60",
						"16"
					],
					"port": "31509",
					"path": [
						"device",
						"queryChildDevicePage"
					]
				},
				"description": "查询子设备列表"
			},
			"response": []
		},
		{
			"name": "4.3根据设备编号查询设备列表",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\r\n    \"deviceKeyList\":[\"21121221\"]\r\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "http://172.20.60.16:31509/device/queryDeviceByDeviceKeys",
					"protocol": "http",
					"host": [
						"172",
						"20",
						"60",
						"16"
					],
					"port": "31509",
					"path": [
						"device",
						"queryDeviceByDeviceKeys"
					]
				}
			},
			"response": []
		},
		{
			"name": "6.1查询指定产品的设备模型历史版本",
			"protocolProfileBehavior": {
				"disableBodyPruning": true
			},
			"request": {
				"method": "GET",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "http://172.20.60.16:31509/tsl/queryTslVersion?productKey=2020083101",
					"protocol": "http",
					"host": [
						"172",
						"20",
						"60",
						"16"
					],
					"port": "31509",
					"path": [
						"tsl",
						"queryTslVersion"
					],
					"query": [
						{
							"key": "productKey",
							"value": "2020083101"
						}
					]
				},
				"description": "6.1查询指定产品的设备模型历史版本"
			},
			"response": []
		},
		{
			"name": "6.2查询指定产品已发布设备模型中功能定义详情",
			"request": {
				"method": "GET",
				"header": [],
				"url": {
					"raw": "http://172.20.60.16:31509/tsl/queryTsl?productKey=2020083101",
					"protocol": "http",
					"host": [
						"172",
						"20",
						"60",
						"16"
					],
					"port": "31509",
					"path": [
						"tsl",
						"queryTsl"
					],
					"query": [
						{
							"key": "productKey",
							"value": "2020083101"
						},
						{
							"key": "tslType",
							"value": "service",
							"disabled": true
						}
					]
				},
				"description": "查询指定产品已发布设备模型中共鞥你定义详情"
			},
			"response": []
		},
		{
			"name": "7.1设置设备属性",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\r\n  \"deviceId\": \"5114786354676736\", \r\n  \"productKey\":\"5100649308652544\",\r\n  \"identifier\":\"set\",\r\n  \"params\": {\r\n      \"property01\": 10,\r\n      \"test_wgq\": 22\r\n    },\r\n    \"time\":1601017077064\r\n}\r\n",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "http://172.20.60.16:30271/device/service/invoke",
					"protocol": "http",
					"host": [
						"172",
						"20",
						"60",
						"16"
					],
					"port": "30271",
					"path": [
						"device",
						"service",
						"invoke"
					]
				},
				"description": "7.1设置设备属性"
			},
			"response": []
		},
		{
			"name": "7.2调用设备的服务",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\r\n  \"deviceId\": \"5114786354676736\", \r\n  \"productKey\":\"5100649308652544\",\r\n  \"identifier\":\"test_service\",\r\n  \"params\": {\r\n    \"inputdata01\":\"333333\"\r\n  },\r\n  \"time\":1601017077064\r\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "http://172.20.60.16:30271/device/service/invoke",
					"protocol": "http",
					"host": [
						"172",
						"20",
						"60",
						"16"
					],
					"port": "30271",
					"path": [
						"device",
						"service",
						"invoke"
					]
				},
				"description": "7.2调用设备的服务"
			},
			"response": []
		},
		{
			"name": "7.3获取设备的属性值",
			"request": {
				"method": "POST",
				"header": [],
				"body": {
					"mode": "raw",
					"raw": "{\r\n  \"deviceId\": \"5114786354676736\", \r\n  \"productKey\":\"5100649308652544\",\r\n  \"identifier\":\"get\",\r\n  \"params\": [\"property01\",\"test_wgq\"],\r\n  \"time\":1601017077064\r\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "http://172.20.60.16:30271/device/service/invoke",
					"protocol": "http",
					"host": [
						"172",
						"20",
						"60",
						"16"
					],
					"port": "30271",
					"path": [
						"device",
						"service",
						"invoke"
					]
				},
				"description": "7.3获取设备的属性值"
			},
			"response": []
		},
		{
			"name": "7.4查询事件历史数据",
			"request": {
				"method": "POST",
				"header": [],
				"url": {
					"raw": "http://172.20.60.16:30271/device/event/queryDeviceEventList?productKey&deviceId&pageNo&pageSize&startTime&endTime",
					"protocol": "http",
					"host": [
						"172",
						"20",
						"60",
						"16"
					],
					"port": "30271",
					"path": [
						"device",
						"event",
						"queryDeviceEventList"
					],
					"query": [
						{
							"key": "productKey",
							"value": null
						},
						{
							"key": "deviceId",
							"value": null
						},
						{
							"key": "pageNo",
							"value": null
						},
						{
							"key": "pageSize",
							"value": null
						},
						{
							"key": "startTime",
							"value": null
						},
						{
							"key": "endTime",
							"value": null
						}
					]
				},
				"description": "7.4查询时间历史数据"
			},
			"response": []
		},
		{
			"name": "7.5查询设备属性历史信息",
			"request": {
				"method": "POST",
				"header": [],
				"url": {
					"raw": "http://172.20.60.16:30217/device/event/queryDevicePropertyList?productKey&deviceId&pageNo&pageSize&startTime&endTime",
					"protocol": "http",
					"host": [
						"172",
						"20",
						"60",
						"16"
					],
					"port": "30217",
					"path": [
						"device",
						"event",
						"queryDevicePropertyList"
					],
					"query": [
						{
							"key": "productKey",
							"value": null
						},
						{
							"key": "deviceId",
							"value": null
						},
						{
							"key": "pageNo",
							"value": null
						},
						{
							"key": "pageSize",
							"value": null
						},
						{
							"key": "startTime",
							"value": null
						},
						{
							"key": "endTime",
							"value": null
						}
					]
				},
				"description": "7.5查询设备属性历史信息"
			},
			"response": []
		}
	],
	"protocolProfileBehavior": {}
}

空文件

简介

暂无描述 展开 收起
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
1
https://gitee.com/johnnym/pictures.git
git@gitee.com:johnnym/pictures.git
johnnym
pictures
Pictures
master

搜索帮助

14c37bed 8189591 565d56ea 8189591