Skip to content

设备互联

设备模型

设备模型用来对业务数据进行集中建模,点击【设备互联】【设备模型】菜单,进入设备模型管理界面,如下图所示:

image-20250603183232627

模型分组

模型分组用于对设备模型进行分组管理,点击【创建模型分组】按钮,创建一个模型分组,如下图所示:

img

img

新建模型

点击模型分组上的创建按键,创建一个新的设备模型,如下图所示:

img

image-20241011114300860

字段说明:

  • 模型标识:模型的标识信息,由英文和数字组成。
  • 模型名称:可输入除空格外的任意字符。
  • 设备模型分组:模型所属的分组。
  • 资产:选择“是”表示可用于设备维护管理。该选项仅在启用了“资产管理模块”时可见。
  • 设备绩效:选择“是”表示可用于设备绩效管理。该选项仅在启用了“设备绩效模块”时可见。
  • 模型描述:对设备模型的说明。

导入导出

点击模型列表中的【导入】【导出】按钮,可以实现批量导入、导出模型基本信息。

img

注意:导入导出只针对模型基本信息和测点列表,可用于设备模型的快速创建。

基本信息

在模型列表中,点击“编辑”按钮可对模型分组或设备模型的基本信息进行进行修改。

img

删除模型

在模型列表中,点击“编辑”按钮可删除模型分组或设备模型。

地理信息

通过绑定经纬度对应的测点,可以实现经纬度信息自动更新,用于实时更新设备的位置信息。

img

注意:地理信息不是必填内容,如果设备没有对应到经纬度的测点,可以不进行设置。

属性信息

用于定义设备模型的静态业务属性。在新建设备时,可根据设备模型定义的属性信息设置相应的业务属性值。img

测点信息

用于定义设备模型的测点信息。设备模型的测点信息只作用于启用了点表模板的设备。img

指标管理

对设备模型下要进行统计计算的指标进行管理。

img

支持的指标类型如下:

  • 开关统计:对布尔变量的变化时间进行记录,并统计变化次数。可用于统计“开关变化次数”、“故障次数”等。
  • 抄表统计:对累计量的测点进行统计,记录单位时间内的变化值。支持日、周、月 3 种统计周期。

设备接入

平台支持以下几种方式实现设备接入:

  • 直连接入:可在本地部署时使用,可不依赖物联网网关直接与 PLC、仪表等设备直接进行通讯。
  • 网关接入:可应用于适用于物联网场景,平台部署在云服务器无法直接与设备进行通讯,需要通过 MQTT 物联网网关实现平台与设备的互联互通。
  • 自主接入:在不依赖网关的情况下,实现设备直接跟平台进行通讯,支持 MQTT、CoAP、HTTP 三种协议。

直连接入

设备直连接入需要添加【接入通道】,根据不同的通讯规约,设置相应的通道连接参数。

img

目前可以支持以下几种通讯规约:

  • Modbus RTU:串口/以太网/透传
  • Modbus TCP:以太网通讯
  • 西门子 PLC:以太网通讯,S7-200-Smart,S7-200, S7-300, S7-400, S7-1200, S7-1500
  • 三菱 PLC、基恩士 PLC:以太网通讯 MC 协议
  • 欧姆龙 PLC:以太网通讯 FINS/TCP 协议
  • AB PLC:以太网通讯 CIP 协议
  • OPC DA
  • OPC UA
  • IEC-60870-104:电气规约
  • DLT-645-1997:电气规约
  • DLT-645-2007:电气规约

IMPORTANT

不同通讯规约的接入配置,请参考《数采实施手册》

通道管理

为方便对接入通道进行管理,可以创建通道分组。选中通道分组,可以修改其基本信息。选中通道,可以修改通道基本信息。

img

通道禁用重启

选中通道后,对通道进行“禁用”和“重启”。

通道“禁用”后,将关闭通道并停止与设备的通讯。

通道“重启”后,将重新扫描点表,并重新与设备建立通讯。

img

通道导入导出

可以通过Excel表格的方式一次性导入多个通道,单击导入选择相应的通道规则,然后下载Excel模板,根据模板内容录入通道和点表信息,完成Excel文件后再上传文件并导入:

img

img

通讯点表

选中通道后,点击“点表”选项卡,进入该通道下的点位管理界面。

img

点表参数说明:

参数名称必填说明
设备标识点位关联的设备
测点标识点位关联的测点
仿真表达式仿真模式下用于生成仿真数据
设备地址设备通讯地址
点位地址虚拟点表达式或点位寄存器地址
数值类型点位的数值类型
存储周期点位数据存储周期
扫描周期采集频率
死区值如果测点输出值变化量未超过死区值,则认为数据未变化
死区时间当测点输出值数据保持不变时,如果超过了死区时间,侧强制更新
计算公式/取反计算公式:用于浮点型或整数型测点,通过设置基值和系数,对采集值进行计算输出测点值。取反:用于布尔型测点,表示是否对采集值进行取反处理。
虚拟点位是否是虚拟点位。
仿真模式

选中通道后,可修改仿真模式选项,如果启用了“仿真模式”,通道将停止与设备进行通讯,不再采集设备数据,改为模拟生成仿真数据。详细使用,请参考《数采实施手册》。

img

实时数据

选中通道后,点击“实时数据”选项卡,可查看该通道下采集到的的测点实时数据。可修改测点值,实现指令下发。可查看测点历史数据。

img

实时日志

选中通道后,点击“实时日志”选项卡,可查看当前通道的实时通讯日志、通讯报文。

img

历史日志

选中通道后,点击“历史日志”选项卡,可按时间范围查询当前通道的历史日志(历史日志默认保存 1 天)。

img

网关接入

网关是指物联网网关,主要用于云边协助,网关和平台之间采用 MQTT 协议进行通讯(最新版本的协议为 TopLink V3 协议)。

可应用于适用于物联网场景,由于平台部署在云服务器无法直接与设备进行通讯,需要通过物联网网关实现平台与设备的互联互通。

我们将网关分为纳管型和非纳管型。

  • 纳管型网关,是指集成了Edge软件的网关,支持在平台对其进行数采配置,网关应用安装&升级及运行监控等管理;
  • 非纳管型网关,只允许接入网关及其子设备,对网关的资源,配置等管理由第三方软件完成。

在【设备接入】界面,切换到【网关接入】页签,如下图所示:

img

MQTT 配置

在网关接入前需要先设置 MQTT 连接参数,配置界面位于【平台管理】【MQTT配置】,详细使用方式请参考平台设置。配置界面如下图所示:

img

网关导入

通过导入 excel 文件,实现批量创建网关。

导入的文件必须是xlsx 且文件大小不超过5MB。

操作步骤:

点击【导入】按键,弹出导入对话框,如下图所示:

img

如没有模板需要先【下载模板文件】,按照模板填入信息后【点击上传】完成导入,如下图所示:

img

网关导出

将查询的所有网关信息导出到 excel 文件中。

操作步骤:

按需要查询出网关信息后,点击【导出】按钮,如下图所示:

报文监测

通过网关报文监测,可以实时查看 MQTT 通讯消息内容。

选中相应的网关,点击【更多】【报文】,如下图所示:

img

img

子设备管理

如果想对网关下的子设备进行管理,请先选中相应的网关,点击【更多】【设备】,如下图所示:

img

弹出设备列表,在设备列表中可对网关子设备进行管理:

img

纳管型网关

纳管型网关是指集成了Edge软件的网关,支持在平台对其进行数采配置,网关应用安装&升级及运行监控等管理。

如果想对纳管型网关进行管理,请先选中相应的网关,点击【查看】按钮,如下图所示:

img

弹出【网关详情】界面,如下图所示:

img

主机监控

显示网关的基本信息、CPU 使用情况、内存使用情况、网络带宽占用情况。

数据通道

对网关下的数据采集通道进行管理。

部署

远程方式对网关进行配置,将平台侧设置的通道、点表信息下载到网关。

离线部署

将网关配置信息导出为离线包,可用于在网关边缘侧单独进行离线部署。

上载

将网关的配置内容读取到平台。

自主接入

自主接入适用于,在不依赖网关的情况下,由设备直接跟平台进行通讯,支持 MQTT、CoAP、HTTP 三种协议。

在【设备接入】界面,切换到【自主接入】页签,如下图所示:

img

在【自主接入】界面,可以对接入的【通道】进行管理,创建【通道】时需要指定相应的接入协议,每个通道下可以关联多个设备。

IMPORTANT

多个设备可以共用一个自主接入通道。

MQTT
实时数据上报

用于设备向平台侧上报实时数据。平台为订阅方,设备为发送方。消息格式支持两种方式分别对应不同的消息主题。

主题:api/v4/event/real/[通道标识]

主题(snappy 压缩):api/v4/event/real_snappy/[通道标识]

主题(gzip 压缩):api/v4/event/real_gz/[通道标识]

每次发送多个测点的数据,消息体格式为JSON数组。timestamp字段可以省略。

如果网关支持压缩传输,当数据量比较大时会自动改为压缩传输。

示例:

json
[
    {
        "deviceID" : "device-001",
        "pointID" : "Ia",
        "value" : 25.05,
        "timestamp" : 1523000206274,
        "quality" : 0
    },
    {
        "deviceID" : "device-001",
        "pointID" : "DI1",
        "value" : false,
        "timestamp" : 1523000206274,
        "quality" : 0
    }
]

字段说明:

字段类型必选描述
deviceIDstring设备标识
pointIDstring点位标识
valuestring|number|boolean点位值
timestampstring|number时间戳:string 类型采用 ISO 8601格式: YYYY-MM-DDTHH:MM:SSZnumber 类型采用毫秒数时间戳
qualitynumber数据质量
历史数据上报

用于设备平台上报历史数据。平台为订阅方,设备为发送方。主要用于断点续传场景,如果设备未连接到MQTT服务器,可以将数据保存为历史数据,恢复通讯后,将未上报的历史数据上传到平台侧。

消息主题:api/v4/event/his/[通道标识]

消息主题(snappy压缩):api/v4/event/his_snappy/[通道标识]

消息主题(gzip压缩):api/v4/event/his_gz/[通道标识]

消息体为 JSON 数组,格式与实时数据相同。

设备状态上报

当设备状态发生变化时,向平台侧推送设备状态信息。平台为订阅方,设备为发送方。

消息主题格式:api/v4/event/dev_state/[通道标识]

Retain: true

Qos: 1

消息格式为JSON对象:

json
{
    "deviceID" : "device-001",
    "state" : 1,
    "timestamp" : "2018-04-06T15:36:46.2744203+08:00"
}

timestamp 字段可以省略,state 表示设备通讯状态,0 表示离线,1 表示在线。

控制指令下发

用于实现单个数据点的远程控制或远程调参操作。平台侧发出请求命令,设备侧执行后返回响应结果。

数据下行。

请求主题:api/v4/service/set_value/[通道标识]/[设备标识],Qos: 0

响应主题:api/v4/service/ack/[通道标识],Qos:1

写入请求消息格式如下:

json
{
    "id": "<uuid>", // 控制命令ID
    "deviceID": "xxx",
    "pointID" : "DO1",
    "value": "false"
}

字段说明:

字段类型描述
idstring消息ID全局唯一,用于网关侧回复响应
deviceIDstring设备标识
pointIDstring点位标识
valuestring写入值

设备响应消息格式如下:

json
{
    "id": "<uuid>", // 控制命令ID,平台侧发送响应
    "errCode": 0,          // 错误码,0 表示成功 
    "errMsg" : "",         // 错误信息
}

字段说明:

字段类型描述
idstring收到的请求命令中的ID保持一致
errCodeint错误码0 表示成功
errMsgstring错误消息,可省略
CoAP

平台支持通过 CoAP 协议实现设备数据接入,CoAP协议适用在资源受限的低功耗设备上,尤其是NB-IoT的设备使用。

WARNING

目前只支持设备数据上报,不支持反写。

协议规范

协议版本

支持RFC 7252 Constrained Application Protocol协议,更多信息,请参见RFC 7252

通道安全

使用DTLS v1.2保证通道安全,更多信息,请参见DTLS v1.2

开源客户端

客户端开源程序包:libcoap-develop

限制说明

  • 暂时不支持资源发现
  • 仅支持UDP协议,支持 DTLS 安全模式通讯。
  • 支持的 Body 最大长度为 1kb
  • 设备身份注册成功后,针对同一设备身份信息,只可选择一种通信协议接入物联网平台,不可多种类型通信协议同时混用。

使用说明

  • 客户端缓存认证返回的Token是请求的令牌。
  • 传输的数据大小依赖于MTU的大小,建议在1 KB以内。
  • 如果设备在空闲时长内使用CoAP协议上报过数据,则设备在物联网平台控制台显示为在线状态。
连接CoAP服务器

平台支持加密与非加密两种设备接入方式,其中加密业务数据交互端口为5684端口,采用DTLS+CoAP协议通道接入,非加密端口为5682,接入协议为CoAP。从安全角度考虑,强烈建议采用安全接入方式。

如果采用 DTLS 安全模式通讯,需要使用 PSK 加密算法进行加密,PSK对应的加密方式如下。

bash
psk_id: "${authType}" + "|" + "${signMethod}" + "|" + "${channelID}" + "|" + "${deviceID}" + "|" + "${timestamp}"
psk: signMethod(channelSecret, "${channelID}" + "|" + "${deviceID}" + "|"  + "${timestamp}")

字段说明:

字段是否必需说明
authType认证类型,这里设为固定值:devicename。
signMethod算法类型,支持hmacmd5、hmacsha1、hmacsha256。
channelID设备所属通道标识。
deviceID设备标识。
channelSecret设备所属通道认证密钥
timestamp时间戳。
设备认证

使用auth接口认证设备,获取Token。上报数据时,需携带Token信息。

设备认证请求:

bash
POST /auth
Host: ${YourEndpoint}
Port: 5684
Accept: application/json or application/cbor
Content-Format: application/json or application/cbor
payload: {"channelID":"ZG1EvTE****","deviceID":"NlwaSPXsCpTQuh8FxBGH","clientId":"mylight1000002","sign":"bccb3d2618afe74b3eab12b94042****"}

表1:参数说明

参数说明
Method请求方法,只支持POST方法。
URLURL地址,取值:/auth。
HostHTTP接入地址。
Accept设备接收的数据编码方式。目前,支持两种方式:application/json和application/cbor。
Content-Format设备发送给平台的上行数据的编码格式,目前,支持两种方式:application/json和application/cbor。
payload设备认证信息内容,JSON数据格式。具体参数,请参见下表Payload说明。

表2:body参数

字段名称是否必需说明
channelId设备所属通道的标识(ID)。可从平台工作台对应的自主接入管理页面获取。
deviceId设备标识。可从平台工作台对应的设备管理页面获取。
clientId客户端ID。长度为64字符内,建议以MAC地址或SN码作为clientId
timestamp时间戳。校验时间戳15分钟内的请求有效。时间戳格式为数值,值为自GMT 1970年01月01日0时0分到当前时间点所经过的毫秒数。
seq认证消息中携带的序号,是设备端生成的随机数。
sign签名。您需将根据签名计算方法signmethod(channelSecret,content)计算出的值,作为sign的值。支持hmacmd5和hmacsha1方法。签名计算所需参数:signmethod:签名方法,需与您的传入signmethod取值一致。channelSecret:设备所属通道的认证密钥。可在平台自主接入管理界面中查看。content:将设备标识(deviceId)、客户端ID(clientId)、时间戳(timestamp)、序号(seq),拼接组合(无拼接符号)的结果。签名计算示例:假设:clientId = mylight1000002,deviceID = http_test,channelId = a1FHTWxQ****,timestamp = 1567003778853,signmethod = hmacmd5,channelSecret = 89VTJylyMRFuy2T3sywQGbm5Hmk1****,seq=1签名计算为:**hmacmd5("89VTJylyMRFuy2T3sywQGbm5Hmk1**","http_testmylight100000215670037788531").toHexString();**其中,**toHexString()**是将计算结果二进制数据的每个byte按4 bit转化为十六进制字符串,大小写不敏感。例如,计算结果byte数组是:[60 68 -67 -7 -17 99 30 69 117 -54 -58 -58 103 -23 113 71],转换后得到的字符串为:3C44BDF9EF631E4575CAC6C667E97147。
signmethod算法类型,支持hmacmd5和hmacsha1。若不传入此参数,则默认为hmacmd5。
version版本号。若不传入此参数,则默认default。

设备认证返回结果示例:

json
{"token":"MZ8m37hp01w1SSqoDFzo001050****.ad2b"}

说明

  • 请将返回的token值缓存到本地。
  • 每次上报数据时,都需要携带token信息。如果token失效,需要重新认证设备获取token。

表3:状态码说明

Code描述Payload备注
69Content认证通过:Token对象正确请求。
128Bad Requestno payload请求发送的Payload非法。
129Unauthorizedno payload未授权的请求。
160Internal Server Errorno payloadauth服务器超时或错误。
上报数据

设备发送实时数据到平台。

上报数据请求:

json
POST /data_upload
Host: ${YourEndpoint}
Port: 5684
Accept: application/json or application/cbor
Content-Format: application/json or application/cbor
payload: ${your_data}
CustomOptions: number:2088

上报数据请求参数说明:

参数是否必需说明
Method请求方法。支持POST方法。
URL/data_upload
HostEndpoint地址。
Port端口,取值:5684
Accept设备接收的数据编码方式。目前,支持两种方式:application/json和application/cbor。
Content-Format上行数据的编码格式,服务端对此不做校验。目前,支持两种方式:application/json和application/cbor。
CustomOptionsnumber取值:2088token为设备认证(auth)返回的token值。

IMPORTANT

每次上报数据都需要携带token信息。如果token失效,需要重新进行设备认证,获取token。

HTTP

用户可通过 HTTP 实现设备数据自主接入。

支持的HTTP协议版本

  • 支持 Hypertext Transfer Protocol — HTTP/1.0 协议,具体请参见:RFC 1945
  • 支持 Hypertext Transfer Protocol — HTTP/1.1 协议,具体请参见:RFC 2616

使用限制

  • 不支持以问号(?)形式传参数。
  • 暂时不支持资源发现。
  • 针对同一设备身份信息,只可选择一种通信协议接入平台,不可多种类型通信协议同时混用。

使用说明

  • 如果设备在空闲时长内使用 HTTP 协议上报过数据,则设备在平台控制台显示为在线状态。

接入流程主要包含:进行设备认证以获取设备token、使用获取的token进行持续地数据上报。

认证设备

认证设备,获取设备的token。认证设备请求:

bash
POST /api/v2/auth HTTP/1.1
Host: ${YourEndpoint}
Content-Type: application/json
Content-Length: 214
body: {"version":"default","clientId":"mylight1000002","signmethod":"hmacsha1","sign":"4870141D4067227128CBB4377906C3731CAC221C","channelID":"ZG1EvTE****","deviceId":"NlwaSPXsCpTQuh8FxBGH","timestamp":1501668289957}

表1:参数说明

参数说明
Method请求方法,只支持POST方法。
URLURL地址,取值:/api/v2/auth。
HostHTTP接入地址。
Content-Type设备发送给平台的上行数据的编码格式,目前只支持application/json。若使用其他编码格式,会返回参数错误。
Content-LengthHTTP消息体body的传输长度。重要对于字段Content-Length,HTTP/1.1及之后版本协议中,默认已携带,HTTP/1.0及之前版本协议中,默认未携带。使用HTTP协议认证设备时,必须传入字段Content-Length。字段Content-Length值必须与body传输长度完全一致,否则无法正确解析body内容,设备认证会失败。
body设备认证信息。JSON数据格式。具体信息,请参见下表body参数。

表2:body参数

字段名称是否必需说明
channelId设备所属通道的标识(ID)。可从平台工作台对应的自主接入管理页面获取。
deviceId设备标识。可从平台工作台对应的设备管理页面获取。
clientId客户端ID。长度为64字符内,建议以MAC地址或SN码作为clientId
timestamp时间戳。校验时间戳15分钟内的请求有效。时间戳格式为数值,值为自GMT 1970年01月01日0时0分到当前时间点所经过的毫秒数。
seq认证消息中携带的序号,是设备端生成的随机数。
sign签名。
signmethod算法类型,支持hmacmd5和hmacsha1。若不传入此参数,则默认为hmacmd5。
version版本号。若不传入此参数,则默认default。

签名说明:

您需将根据签名计算方法 signmethod(channelSecret,content) 计算出的值,作为 sign 的值。支持 hmacmd5hmacsha1 方法。

签名计算所需参数:

  • signmethod:签名方法,需与您的传入 signmethod 取值一致。
  • channelSecret:设备所属通道的认证密钥。可在平台自主接入管理界面中查看。
  • content:将设备标识(deviceId)、客户端ID(clientId)、时间戳(timestamp)、序号(seq),拼接组合(无拼接符号)的结果。

签名计算示例:

假设:

clientId = mylight1000002,

deviceID = http_test,

channelId = a1FHTWxQ****,

timestamp = 1567003778853,

signmethod = hmacmd5,

channelSecret = 89VTJylyMRFuy2T3sywQGbm5Hmk1****,

seq=1

签名计算为:

hmacmd5("89VTJylyMRFuy2T3sywQGbm5Hmk1**","http_testmylight100000215670037788531").toHexString();

其中,toHexString() 是将计算结果二进制数据的每个byte按4 bit转化为十六进制字符串,大小写不敏感。例如,计算结果byte数组是:[60 68 -67 -7 -17 99 30 69 117 -54 -58 -58 103 -23 113 71],转换后得到的字符串为:3C44BDF9EF631E4575CAC6C667E97147。

设备认证返回结果示例:

json
{
  "code": 0,
  "message": "success",
  "info": {
    "token":  "6944e5bfb92e4d4ea3918d1eda39****"
  }
}

说明

  • 请将返回的token值缓存到本地。
  • 每次上报数据时,都需要携带token信息。如果token失效,需要重新认证设备获取token。

表3:错误码说明

codemessage备注
10000common error未知错误。
10001param error请求的参数异常。
20000auth check error设备鉴权失败。
20004update session error更新失败。
40000request too many请求次数过多,流控限制。
上报数据

设备发送实时数据到平台。

上报数据请求:

bash
POST /api/v2/data_upload HTTP/1.1
Host: ${YourEndpoint}
password:${token}
Content-Type: application/octet-stream
Content-Length: 53
body: ${your_data}

表4:上报数据参数说明

参数说明
Method请求方法,只支持POST方法。
URL/api/v2/data_upload
HostEndpoint地址。
X-Auth-Token放在Header中的参数,取值为调用设备认证接口 /api/v2/auth 返回的token值。
Content-Type设备发送给物联网平台的上行数据的编码格式,目前仅支持application/octet-stream。若使用其他编码格式,会返回参数错误。
Content-LengthHTTP消息实体的传输长度。
body数据内容,JSON数据格式。

设备数据上报示例:

json
{
  "pointid1": {
    "value":  100,
    "time": 1689840427977
  },
  "pointid2": {
    "value":  100,
    "time": 1689840427977
  }
}

返回结果示例:

javascript
body:
{
  "code": 0,
  "message": "success",
}

错误码说明:

codemessage备注
10000common error未知错误。
10001param error请求的参数异常。
20001token is expiredtoken失效。需重新调用auth进行鉴权,获取token。
20002token is null请求header中无token信息。
20003check token error根据token获取identify信息失败。需重新调用auth进行鉴权,获取token。
30001publish message error数据上行失败。
40000request too many请求次数过多,流控限制。

设备管理

对设备进行管理。

img

基本属性

点击【创建】按钮,可以创建一个新设备。

img

名称说明
设备标识设备唯一识别信息,每台设备都有固定的识别编码
设备名称
设备编码
设备模型
用户组如果设置了用户组,则表示只有用户组内成员才可以管理该设备
设备分组
接入方式接入设备数据的方式
所属网关当接入方式为“网关”时有效
所属通道自主接入对应的通道
空闲时长当设备测点没有更新,则判断设备处于“空闲”状态,设备长时间空闲则认为设备“离线”。

设备导入导出

除了单个创建设备外,可以选择用Excel文件方式批量导入设备。可以下载导入设备的Excel模板文件,在文件中编辑相应内容,然后上传Excel文件批量创建设备:

img

设备属性设置

用于设置在设备模板中定义的静态属性。点击设备列表中“操作”按钮,点击【属性】弹出属性配置界面,如下图所示:

img

设备标签

设备标签可用于按不同的维度对设备进行检索。

点击设备列表中“操作”按钮,点击【标签】弹出设备标签设置窗口。

查看测点数据

点击设备列表中“操作”按钮,点击【数据】弹出测点实时数据窗口,如下图所示:

img

img