dtu设备接入平台，安装平台的服务器需要有公网ip。

1.设备表配置：添加设备表-安装g340t驱动-添加设备-配置手机号、站号-添加数据点。

配置说明：

• 手机号=DTU上配置的IMEI编号。
• 站号=modbus rtu站号
• 在线判断方式：心跳检测：用户维持链接的长连接，空闲时一般为一分钟发送一次。平台识别的心跳包为Q，当平台收到心跳包Q时，会立即响应A发送给设备，设备可通过心跳包交互来判断与设备的连接情况。
• 地址合并间隔：一个资产下同一个分区的数据点起始地址按照该间隔合并读取。
• 采集周期：表示读取传感器数据的周期时间。
• 自动化地址：开启自动化地址，数据点偏移地址从1开始。
• 通讯监控参数：通讯超时时间：单位秒（s）判断设备超时的时间标准，超时时间默认为定义采集周期的3倍。

2.数据点配置

读取区域

• 线圈状态：01读写，对开关量（bit位）进行读写，写入默认使用05功能码（不需要单独设置），该功能码一般针对PLC的开关输出点。
• 输入状态：02只读，对开关量（bit位）进行读，是只读的，不允许写入，一般针对PLC的开关输入点。
• 保持寄存器：03读写，对整形/浮点型数据进行读写，写入默认使用06功能码（16位整形数据）和10功能码（32位和64位整形和浮点型数据），也就是对单个寄存器写入使用06，多个寄存器使用10。
• 输入寄存器：04只读，对整形/浮点型数据进行读，只读不写。

偏移地址: 数据点所在寄存器起始地址。

寄存器个数: 数据点占用的寄存器个数，不填根据数据类型处理。

数据类型:

3.指令配置

写入区域

• 线圈状态：01读写，对开关量（bit位）进行读写，写入默认使用05功能码（不需要单独设置），该功能码一般针对PLC的开关输出点（比如西门子PLC的Q点）。
• 保持寄存器：03读写，对整形/浮点型数据进行读写，写入默认使用06功能码（16位整形数据）和10功能码（32位和64位整形和浮点型数据），也就是对单个寄存器写入使用06，多个寄存器使用10。

偏移地址: 所在寄存器起始地址。

数据类型: 同数据点。

默认写入值: 指令写入时候的默认值。

单字节: 勾选单字节后数据值按寄存器写入数据，否则多个寄存器同时写值。

4.开放端口：配置完成上述内容后进入运维管理：ip:13030.查看g340t驱动的端口号：开放此端口号。确保telnet能通。Telnet命令文档：
https://baijiahao.baidu.com/s?id=1723367561977342393&wfr=spider&for=pc

点击右侧三个点查看g340t驱动的日志，查看设备与平台连接情况。提示成功建立链接则连上平台。

！未提示链接成功检查以下几项：

• 13030运维管理中g340t驱动对应的端口是否开放,保证 telnet ip(公网ip)：端口正常.
• 检查dtu配置软件配置的是否是公网ip及运维中g340t驱动对应的端口.
• 平台配置完之后是否重启驱动.
• modscan 是否可以读上来数据.

dtu配置案例：

1.MQTT简介：

MQTT全称为消息队列遥测传输，是ISO 标准（ISO/IEC PRF 20922）下基于发布
(Publish)/订阅 (Subscribe)范式的消息协议，工作在 TCP/IP协议族上。
MQTT 协议定义两种网络实体：消息代理（message broker）与客户端（client）

• 消息代理用于接收来自客户端的消息并转发至目标客户端，也被称为MQTT服务器。
• MQTT 客户端可以是任何运行有 MQTT 库并通过网络连接至消息代理的设备，例如微型控制器或大型服务器。

MQTT 协议中，消息的传输是通过主题（topic）管理的，消息的发布者和订阅者均为客户端（client）。消息由主题（Topic）和负载（payload）两部分组成。
当某个客户端有需要分发的数据时，会向连接的消息代理（MQTT服务器）发送指定主题的携带有负载的消息。
服务器收到消息后，会向订阅此主题的客户端分发此消息。发布者不需要配置订阅者的相关信息和具体位置；同样，订阅者也不需要配置发布者的相关信息和具体位置。

2.平台配置说明

添加设备表-安装mqtt驱动-添加设备-配置驱动内容-添加数据点。

配置驱动参数

• MQTT服务器：填写要连接的mqtt服务器的地址。格式为tcp://服务器IP或域名:服务器端口 例如：tcp://127.0.0.1:1883（填写的是需要订阅的mqtt服务器，平台是mqtt的客户端）

• 用户名、密码：填写MQTT服务器的用户名和密码。

• 订阅消息主题：填写该模型要订阅的消息主题，可使用通配符#和+。

Topic是个utf-8编码的字符串，可由多个'/'分割开。
+：为单级通配符，如：check/+/baseline 
＃：为多级通配符，必须放在topic的最后，前一个字符必须是'/' 建议Topic中不要包含空格符。

• 通讯监控参数：平台通用配置，当某个资产数据点中的最新上数时间距离当前时间超过此参数时，平台判定资产掉线。

• 自定义脚本：由于mqtt协议中未规定具体的消息内容格式，因此需要用户编写自定义脚本，用于解析消息和组装要发送的消息内容。

3.使用示例

示例1
由于MQTT协议通过主题区分不同种类的消息，因此在使用时，不同的主题需要建立不同的模型，下边以网关常用的MQTT格式为例，介绍脚本的编写方法。示例中d1为数据点编号，资产id为订阅主题中间部分abcd1234。

消息格式

脚本

脚本示例：

示例2：资产id在报文中

数据格式案例：
{
"timestamp": 1617860319, //时间戳
"version": "5.0",
"messageId": "3",
"devices": [{
"deviceId": "xbzc-001", //资产id
"deviceState": 1,
"deviceData": {
"xbzc-temp": 37.0 //数据点标识和数据
}
}]
}

自定义脚本案例：

ParseHandle = function (topic, package) {
  // 解析数据
  let msg = JSON.parse(package.toString())
  // console.log(package.toString())
  //  { id, values, time }
  let arr = []
  if (msg.devices) {
    for (let i = 0; i < msg.devices.length; i++) {
      let id = msg.devices[i].deviceId
      let values = msg.devices[i].deviceData
      let time = msg.timestamp * 1000
      arr.push({ id, values, time })
    }
  }
  return arr
}

平台未采集到数据需检查如下内容

1.mqttbox或者其他客户端能否订阅到该主题消息（以mqttbox演示数据订阅）

• 打开工具界面如图，点击按钮，创建链接。

• 配置如图。

• 链接成功后提示绿色图标，设置右侧订阅的主题，主题内容与服务器发送主题保持一致，填写完成主题后，点击下方橙色按钮，等待消息。

• 如果成功订阅，订阅的消息就会显示在页面。

2.mqtt驱动的运维日志：运维管理地址（ip:13030）点击查看driver-mqtt-client的驱动日志，滚动条拉至最下方查看驱动日志error内容。

3.检查用户名，密码是否是mqtt服务器用户名密码，检查自定义脚本解析内容是否修改，检查资产编号是否对应。

.平台mqtt下发指令配置

op是对象
op.name 是指令名称
op.tag是指令配置的tag:写入
op.value是执行的时候输入的那个值 或者默认值

脚本例子：
CommandHandle = function (topic, id, op) {
let sendTopic = topic
let sendData = JSON.stringify([{ [op.tag]:op.value}])
return { sendTopic, sendData } //返回的对象中的key的名字必须为sendTopic,sendData
}
指令配置案例：

4.新建MQTT服务器方法

1. Windows

• 在软件安装的目录下找到mosquitto文件夹复制并重命名，重命名后在文件夹下找到mosquitto.conf文件以记事本方式打开，在211行找到port 1883。将端口进行修改 例如1884 然后在文件夹窗口下输入cmd进入命令窗口输入mosquitto.exe -c mosquitto.conf运行。
  

• 在软件平台中添加mqtt的服务器
  进入到运维平台127.0.0.1:13030中，点击服务管理—— 添加服务——高级添加应用名称例如：mqtt2， 命令：mosquitto.exe -c mosquitto.conf 目录：../mqtt2 (mqtt2为本文档一中复制的文件夹重命名后名称)
  

2. Linux

• Linux平台启用mqtt server：
  找到docker-compose.yml文件位置
  
  

• 将下面这句复制到docker-compose.yml里，按照截图修改格式。
  mqttserver: container_name: mqttserver
  environment:
  RABBITMQ_DEFAULT_USER=admin
  RABBITMQ_DEFAULT_PASS=public
  image: airiot/rabbitmq:3.8.3-management-alpine logging: driver: json-file
  options: max-size: 100m max-file: "1" networks: backend
  ports:1884:1883 restart: always ulimits: nproc: 40960 nofile: soft: 10240 hard: 30720 volumes:
  /etc/localtime:/etc/localtime:ro
  
  配置完成后需要进入平台安装目录下 创建并启动服务：docker-compose up -d
  查看mqtt服务是否启动：docker ps | grep mqtt

1.Modbus TCP协议概述

MODBUS是OSI模型第7层上的应用层报文传输协议，它在连接至不同类型总线或网络的设备之间提供客户机/服务器通信。平台的MBTCP协议是建立在TCP协议之上的应用层协议。自带MODBUS TCP协议的设备一般为TCP server端（只能由客户端主动连接，不能主动连接平台），所以需要一个TCPserver转TCPclient的透明转发模块，来连接设备和平台。当然，如果设备本身支持client模式可直连。

2.平台配置说明：

设备表配置：

• 设备IP：设备的IP地址。
• 端口：设备的端口号。
• 连接超时时间：单位秒，默认10s，创建连接的最长超时时间及读写数据的最长超时时间。
• 连接空闲时间：单位秒，默认30s，从上一次请求后超过时间链接未使用，关闭当前链接。
• 连接使用间隔：单位毫秒，默认1毫秒，同一设备IP和端口下的设备，读取的时间间隔。
• 站号：将请求发送到 Modbus TCP 从站设备的设备ID。
• 采集周期：表示读取传感器数据的周期时间，单位秒。
• 自动化地址：开启自动化地址，数据点偏移地址从1开始。 偏置表示的是数据地址。如果数据地址是16进制表示（0x0000开始），则需要把16进制转为十进制并加1，才是偏置的值。如果地址使用区号+序号表示（比如40001），则偏置只取序号就可以了（也就是1）。
• 通讯监控参数：通讯超时时间：单位秒（s），判断设备超时的时间标准，超时时间默认为定义采集周期的3倍。

数据点配置：

• 名称：数据点名称
• 标识：数据点唯一标识
• 读取区域
  1） 线圈状态：01读写，对开关量（bit位）进行读写，写入默认使用05功能码（不需要单独设置），该功能码一般针对PLC的开关输出点（比如西门子PLC的Q点）。
  2） 输入状态：02只读，对开关量（bit位）进行读，是只读的，不允许写入，一般针对PLC的开关输入点（比如西门子PLC的I点）。
  3）保持寄存器：03读写，对整形/浮点型数据进行读写，写入默认使用06功能码（16位整形数据）和10功能码（32位和64位整形和浮点型数据），也就是对单个寄存器写入使用06，多个寄存器使用10。
  4）输入寄存器：04只读，对整形/浮点型数据进行读，只读不写。
• 偏移地址：数据点所在寄存器起始地址。
• 寄存器个数：数据点占用的寄存器个数，不填根据数据类型处理。

数据类型

指令配置：

写入区域

• 线圈状态：01读写，对开关量（bit位）进行读写，写入默认使用05功能码（不需要单独设置），该功能码一般针对PLC的开关输出点（比如西门子PLC的Q点）。
• 保持寄存器：03读写，对整形/浮点型数据进行读写，写入默认使用06功能码（16位整形数据）和10功能码（32位和64位整形和浮点型数据），也就是对单个寄存器写入使用06，多个寄存器使用10。
  偏移地址
  点所在寄存器起始地址。

数据类型：同数据点。

默认写入值：指令写入时候的默认值。

单字节：勾选单字节后数据值按寄存器写入数据，否则多个寄存器同时写值。

西门子PLC平台配置说明：

1.AIRIOT与西门子300 1200 1500 PLC连接配置说明：
选择西门子siemens-s7驱动程序，设备表配置页面示例：

设备配置页面示例：

数据点配置示例：取位的数据点需要选择“位下标”。

指令配置页面示例：

注意：在TIA软件中，设备视图——常规——保护，勾选“允许从远程伙伴（PLC、HMI、OPC、…）使用PUT/GET通信访问”。

2.AIRIOT与西门子s7-200、smart200 PLC连接
选择西门子siemens-s7-200s驱动程序，设备表配置页面示例：

默认localTsap为0101，remoteTsap为0301,如果用户进行了修改，需要以实际的为准。

设备配置页面示例：

数据点配置示例：取位的数据点需要选择“位下标”。

FINS协议简述

FINS通讯服务是由欧姆龙提供的PLC和计算机对各种网络相互通信的方式，欧姆龙(Omron)是来自日本的知名电子和自控设备制造商，其中、小型PLC在国内市场有较高的占有率，有CJ、CM等系列。PLC可以支持Fins、Host link等协议进行通信。 支持以太网的欧姆龙PLC CPU、以太网通信模块根据型号的不同，一般都会支持FINS(Factory Interface Network Service)协议，一些模块也会支持EtherNet/IP协议。Omron fins协议缺省TCP/UDP端口号为9600。Fins协议封装在TCP/UDP之上，需要注意的是基于TCP的Fins数据包和基于UDP的包在头部上差异较大。协议的具体构造可以参考欧姆龙官方文档。

平台配置：
选择欧姆龙驱动程序，设备表配置页面示例：

• 设备ip：plc设备的ip地址
• 端口：plc设备的端口号，通常默认9600
• 设备节点: 在同一级网络里,各个连接节点的节点号需要设置为不一样的号码, 一个节点对应一个PLC.如果是以太网网络,节点号一般是IP地址的最后一个字段.
• 站号： 在同一个PLC中,各个模块站号互不相同,CPU一直为0,其余的自行设置.
• 网络: 如果只有一个本地网络, 那么网络号都设置为0,代表只有一个网络. 如果有多个网络, 为了避免冲突,那么就必须指定各级网络号,范围是1-127.

数据点

• 存储地址：需要读取的寄存器的首地址

• 寄存器数：需要读取的寄存器的个数

• 偏移地址：按位读取的时候，配置的偏移地址

• 数据类型：
  

• 内存地址

测试过程：

• 原始数据：

• 参数汇总：

• 流程画面：

1.Modbus RTU协议概述

Modbus是OSI模型第7层上的应用层报文传输协议，它在连接至不同类型总线或网络的设备之间提供客户机/服务器通信。平台的MBRTU协议是建立在TCP协议之上的应用层协议。一般使用DTU实现底层TCP连接，然后平台和设备进行应用层的modbus协议通讯。

2.平台配置概述

• 串口：设备的串口号。
• 串口配置：设备的串口配置。
• 连接超时时间：单位秒，默认10s，创建连接的最长超时时间及读写数据的最长超时时间。
• 连接空闲时间：单位秒，默认30s，从上一次请求后超过时间链接未使用，关闭当前链接。
• 连接使用间隔：单位毫秒，默认1毫秒，同一设备IP和端口下的设备，读取的时间间隔。
• 采集周期：表示读取传感器数据的周期时间，单位秒，最小值0.001秒，由于MODBUS协议是请求应答式协议，每次读数据都会等待接收，等待的过程会产生延时，最长等待超时时间（秒），所以越多数据不响应，采集周期会越长。
• 站号：将请求发送到 Modbus TCP 从站设备的设备ID。
• 自动化地址：开启自动化地址，数据点偏移地址从1开始。 偏置表示的是数据地址。如果数据地址是16进制表示（0x0000开始），则需要把16进制转为十进制并加1，才是偏置的值。如果地址使用区号+序号表示（比如40001），则偏置只取序号就可以了（也就是1）。
• 通讯监控参数：通讯超时时间：单位秒（s），判断设备超时的时间标准，超时时间默认为定义采集周期的3倍。

3.数据点配置

• 名称：数据点名称
• 标识：数据点唯一标识
• 读取区域：
• • 线圈状态：01读写，对开关量（bit位）进行读写，写入默认使用05功能码（不需要单独设置），该功能码一般针对PLC的开关输出点（比如西门子PLC的Q点）。
• • 输入状态：02只读，对开关量（bit位）进行读，是只读的，不允许写入，一般针对PLC的开关输入点（比如西门子PLC的I点）。
• • 保持寄存器：03读写，对整形/浮点型数据进行读写，写入默认使用06功能码（16位整形数据）和10功能码（32位和64位整形和浮点型数据），也就是对单个寄存器写入使用06，多个寄存器使用10。
• • 输入寄存器：04只读，对整形/浮点型数据进行读，只读不写。
• 偏移地址：数据点所在寄存器起始地址。
• 寄存器个数：数据点占用的寄存器个数，不填根据数据类型处理。
• 数据类型
  

4.指令配置

• 写入区域
• • 线圈状态：01读写，对开关量（bit位）进行读写，写入默认使用05功能码（不需要单独设置），该功能码一般针对PLC的开关输出点（比如西门子PLC的Q点）。
• • 保持寄存器：03读写，对整形/浮点型数据进行读写，写入默认使用06功能码（16位整形数据）和10功能码（32位和64位整形和浮点型数据），也就是对单个寄存器写入使用06，多个寄存器使用10。
• 偏移地址：点所在寄存器起始地址。
• 数据类型：同数据点。
• 默认写入值：指令写入时候的默认值。
• 单字节：勾选单字节后数据值按寄存器写入数据，否则多个寄存器同时写值。

windows测试工具链接端口前，先检查端口是否被监听
netstat -ano|findstr 端口

链接tcp-server驱动，调试工具链接不上端口（运维管理地址的端口号），检查tcp-server驱动的四个处理脚本是否全部修改保存。驱动案例脚本是展示的功能，不生效，修改保存后才会生效。再点击重启驱动

TCP Server 驱动 v3.2

该驱动内置了一个 tcp server 服务, 驱动启动后可以接收客户端的连接和数据, 同时也可以向客户端发送数据. 如果使用容器部署时, 需要将 tcp 服务端口开放.

注: 每个驱动实例只能添加一个模型

配置说明
以下内容为 tcp-server 驱动的配置项

数据处理流程说明

• 当接收到客户端发送的数据时, 会读取所有的发送数据并存放到 Buffer 中, 然后调用 数据包拆分脚本

• 列表数据包拆分脚本 从 Buffer 中提取完整的数据包信息或.

脚本说明
脚本语言: JavasScript ECMAScript 5.1

驱动使用时要求提供 数据包拆分脚本, 数据处理脚本 和 指令处理脚本 3 个脚本函数来处理接收和发送数据过程中的协议和数据格式问题.

在脚本的上下文中内置了 Buffer 包, 可用于处理接收或发送二进制数据.

除此之外, 还内置了 lodash, crypto-js, moment, xml-js 和 formulajs(Excel函数) 包.

注: 所有的脚本函数名必须为 **handler**

客户端对象

在 数据包拆分脚本, 数据处理脚本, 指令处理脚本 和 连接处理脚本 函数的参数中提供了 client 对象, 该对象为当前 TCP 连接客户端对象, 可以通过该对象实现向客户端发送数据的功能. 例如: 向客户端发送 ack 信息等.

该对象提供了以下函数:

register
用于注册设备. 接收到客户端发送的设备注册信息时, 在脚本函数中通过调用 client 对象中的 register 函数注册该设备, 驱动会将该设备与当前连接绑定. 当需要向设备发送指令时, 会通过该绑定关系向对应的连接发送数据. 如果协议未定义设备注册, 会向上次接收到该设备数据的连接发送. 详细信息见 设备与连接绑定关系说明

参数说明

返回值

string 或 undefined 如果参数不正确、部分设备标识错误或对应的设备不存在时返回 string, 内容为错误说明. 如果所有设备注册成功, 返回 undefined

示例

unregister
用于注销设备. 注销设备与连接的绑定关系, 参数及返回值说明同 register

示例

send
用于向客户端发送数据. 例如: 在接收到数据时向客户端发送 ack 信息.

参数说明

返回值

string 或 undefined 如果参数不正确(字节数组为空或空数组)或发送失败则返回 string 内容为错误说明, 如果发送成功则返回 undefined.

示例

getRemoteAddr
用于获取客户端地址信息.

参数说明

无

返回值

string. 格式: IP:Port. 例如: 192.0.2.1:25

示例

getRemoteIp

用于获取客户端 IP 地址信息.

参数说明
无

返回值

string. 例如: 192.0.2.1

示例

reportCommand
上报指令执行结果. 有些场景指令的执行结果反馈是异步的, 在指令发送后， 过一段时间才会收到响应报文, 此时可以在接收到响应报文时通过 client.reportCommand(...) 方法上报指令执行结果.

参数说明

注: serialNo 为平台在发送指令时生成, 会传入到 指令处理脚本 中, 当指令执行结果为异步反馈时, 可以将 serialNo 保存到 设备上下文 中, 以便在后续 reportCommand 使用

返回值

string 或 undefined. 如果返回 undefined 则表示发送成功, 否则返回数据为错误原因.

示例

getMediaFile
请求媒体库文件

参数说明

返回值

示例

getMediaFileByURL
请求媒体库文件

参数说明

返回值

示例

uploadMediaFile
上传文件到媒体库

参数说明

返回值

示例

deleteMediaFile
删除媒体库文件

参数说明

返回值

示例

saveWorkTableRow
向工作表写入一条数据

参数说明

返回值

示例

updateWorkTableRow
更新工作表中的数据

updateNodeById
根据资产标识更新资产数据

getContext
用于获取上下文对象, 可以在上下文中存储数据. 详细信息

注: 第一次调用的时候才会创建上下文

getDeviceContext
用于获取设备上下文对象, 使用设备标识作为上下文标识, 可以在上下文中存储数据. 详细信息

与 getContext 不同的是, 当设备被删除后, 重启驱动时会自动清理被删除设备的上下文对象.

注: 第一次调用的时候才会创建上下文

removeContext
删除上下文对象

removeDeviceContext
删除设备上下文对象

getContextIds
获取全部上下文标识(不包含设备上下文)

getDeviceContextIds
获取全部设备上下文标识(只包含设备上下文)

context
上下文对象, 用来存储数据, 上下文中的数据可以在不同的脚本中共享. 例如: 可以在 指令处理脚本中 写入数据, 然后从 数据处理脚本 中读取数据. 不同上下文彼此独立, 互不影响.

注: 可以根据需求创建多个上下文对象, 但是上下文对象以及上下文中的数据需要及时清理, 否则会造成 **OOM** 问题, 导致驱动程序崩溃.

put
用于向上下文中存储数据.

注: 存入的数据需要自行清理, 否则可能导致 OOM 等问题.

containsKey
判断上下文中是否存在指定的 key

get
从上下文中获取指定的 key 对应的数据. 如果 key 不存在则返回 undefined

getAndRemove
从上下文中获取指定的 key 对应的数据并且在返回后 删除 该 key. 如果 key 不存在则返回 undefined.

注: 该函数返回后, 再使用 get 或 getAndRemove 均返回 undefined.

remove
从上下文中删除指定的 key, 如果 key 不存在则不执行任何操作.

内置函数
crc 校验
驱动中内置了 crc 对象, 可以在脚本中直接使用 crc 对象中的校验函数.

• 使用 checksum16 实现 crc16 校验

• 使用 checksum32 实现 crc32 校验

• 使用 checksum64 实现 crc64 校验

• 使用 checksumModbus 实现 modbus 协议 crc 校验

modbus 校验为 crc16, 所以校验码类型为 uint16. 另外, checksumModbus 不需要 poly 多项式参数.

数据包拆分脚本

该脚本用于处理接收数据过程中的半包和粘包问题, 该函数需要根据协议和数据格式判断接收到的字节数组中是否包含完整的数据包, 如果包含了完整数据包则返回完据包的起始位置和长度. 或者当数据包有错误时丢掉该数据包或有问题部分的数据.

如果字节数组中不包含完整的数据包, 直接返回 undefined 表示需要从客户端接收更多的数据.

函数定义如下:

参数说明

返回值说明

• 当字节数组中包含完整数据包时, 返回包含 package 字段的对象.
• 如果字节数组中存在错误, 则返回包含 drop 字段的对象, 丢弃掉错误的数据.
• 如果字节数组中即不包含完整的数据包也不存在错误, 直接返回 undefined, 表示需要从客户端接收更多的数据. | 参数名 | 参数类型 | 参数说明 | 示例值 | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------- | | package | object | 数据包信息, 如果要丢弃数据该字段不需要返回 | {"start": 0, "length": 128, "next": 129} | | start | 数值 | 数据包在 data | | 中的起始位置 | 4 表示第 5 个字节为数据包的起始位置 | | length | 数值 | 数据包的长度, 表示从 start | | 后多少个字节为一个完整的数据包 | start=4, length=128 表示从第 5 个字节开始(包括第 5 个字节)连续 128 个字节为一个完整的数据包 | | next | 数值 | 下一个数据包的起始位置 | 例如: 在使用 \r\n | | 作为数据包间的固定分隔符时, 下一个数据包的起始位置应该为 start + length + 2 | | drop | 数值 | 要丢弃的字节数量, 即丢弃字节数组中 data[0:drop] | | 内容 | 128 表示丢弃前 128 个字节. 一般用于数据包错误时丢弃掉错误的数据包场景 |

正常接收数据
当数据包拆分脚本返回以下内容时, 表示已接收到的数据中包含了完整的数据包. 该数据包在所有数据中的起始位置为 0, 长度为 128, 下一个数据包的起始位置为 129

例如, 使用 \r\n 作为数据包间的分隔符, 以解析该数据时 {"a":1,"b":2}\r\n{"a":3,"b":4}\r\n, 拆分结果为 {"package":{"start":0,"length":13,"next":15}}. 此时, 数据处理脚本 中接收到的数据为 {"a":1,"b":2}, 并不会包含 \r\n, 而下一次数据拆分脚本接收到的数据为 {"a":3,"b":4}\r\n.

包含错误或不完整数据包时
返回以下内容时, 表示接收到的数据不完整, 需要丢弃 0 - 12 部分内容.

例如, 接收到的内容为 :1,"b":2}\r\n{"a":3,"b":4}\r\n 时, :1,"b":2}\r\n 为不完整的数据包需要丢弃, 则需要返回 {"drop":11}. 下一次数据拆分脚本接收到的数据为 {"a":3,"b":4}\r\n

不包含完整的数据包和错误包时
例如, 接收到的数据为 {"a":1, 未找到分隔符 \r\n, 此时返回 undefined 表示需要接收更多的数据. 当客户端发送 "b":2}\r\n{"a":3,"b":4}\r\n 数据时, 会再次调用 数据包拆分脚本, 此时 Buffer 中的数据为 {"a":1,"b":2}\r\n{"a":3,"b":4}\r\n, 此时可以提取出完整的数据包.

注: 如果返回结果中同时包含了 drop 和 package 字段并且 drop 的值大于 0 时, 只做丢弃数据处理.

示例

驱动内置数据包拆包函数

• 固定长度头 该函数会取前 N 个字节作为长度信息, 然后根据长度信息读取主体内容. +--------+-----------+ | Length | Data | +--------+-----------+

在数据包拆分脚本中直接使用内置的拆分函数, 如下所示:

• 固定分隔符 该函数会使用固定分隔符拆分数据包. 使用方式如下所示:

• 固定开始和结束符 该函数会读取指定开始符和结束符之间的数据做为一个完整的数据包. 使用方式如下所示:

数据处理脚本
该脚本用于处理 数据包拆分脚本 函数解析得到的完整数据包, 根据协议和数据格式将数据包解析为平台定义的数据格式.

函数定义如下:

参数说明

返回值

注: 返回值必须为 **Object[]** 或 **undefined** 其中之一. 返回空数组表示未从接收到的数据中解析出有效数据, **undefined**表示无返回结果, 驱动程序无须处理返回结果. 例如: 接收到的数据为心跳数据, 不包含采集数据.

示例

指令处理脚本

该脚本用于将发送的指令内容转换为字节数组, 当向设备发送指令时, 驱动会将要发送的内容先经过 命令处理脚本 函数处理, 返回结果作为实际发送的内容.

函数定义如下:

参数说明

指令格式如下:

以 test 指令为例

注: ops.value 通常为实际发送的内容, 该字段为必填值. opts 为数组, 目前长度固定为 1.

当要发送的数据内容比较复杂时, 可以先转发送内容转换为 base64 格式的字符串, 然后在在指令脚本中再进行 base64 解码后再发送.

返回值说明

必须值必须为 Buffer 对象.

注: 可以使用 Buffer.from("this is a string"") 等方法创建 Buffer 对象. 关于 Buffer 的使用说明可以点击查看

示例

连接处理脚本
当客户端连接到驱动或断开时, 会调用 连接处理脚本.

函数定义如下:

参数说明

返回值说明

无返回值

示例

设备与连接绑定关系说明
设备与连接关系绑定, 主要用于向设备发送指令时, 驱动会根据该绑定关系确认通过哪个连接发送指令数据. 绑定关系的创建有以下两种:

• 当协议中定义了设备注册功能时, 由 数据处理脚本 函数在接收到设备注册数据包时, 通过调用 client 中的 register 向驱动注册设备实现设备与连接折绑定.
• 当协议中未定义设备注册功能时, 驱动会自动记录每个设备是由哪个连接上报实时数据的(设备每次上传实时数据时都会自动更新), 当驱动下发指令时, 会自动根据该信息向对应的连接发送指令数据.

注: 如果通过 **register** 函数注册了设备时, 会忽略根据实时数据建立的绑定关系. 如果协议中未定义设备注册功能并且设备未上报过实时数据时, 无法通过实时数据建立绑定关系, 此时无法向该设备发送数据

1.平台配置说明：
驱动市场安装，添加设备表在设备配置中，选择已安装的isc视频驱动，配置内容，再添加设备，1个设备对应一个摄像头。appKey和appSecret获取方式如下文介绍。

2.isc平台配置如下
1）首先登录iSC，进入系统管理。

2）按照iSC平台使用说明，在平台中添加编码设备和监控点。可以看到ip和端口号。

3）登入iSC管理页面，在状态监控页面左侧，点击API网关，点击API管理，进入API网关管理页面，在网关管理页面点击左侧合作方管理，点击右侧对内合作方，即可查看合作方Key和Secret。




3.添加完信息内容，重启驱动，添加画面-视频组件-选择isc设备查看对应视频画面。

平台驱动配置说明

驱动配置决定驱动如何连接 OPCDA 服务器，数据点配置决定驱动从 OPCDA 服务器上读取哪些数据。

如何测试

• 1.安装驱动，安装完成后在选择设备驱动时可以看到 opcda。没有驱动授权时也可以添加少量数据点做测试。
• 2.创建一个模型，设备驱动选择 opcda。创建一个属于该模型的资产。
• 3.参考驱动配置一节，配置模型中的驱动配置。
• 4.参考数据点配置一节，在模型中添加一个状态正常的数据点。
• 5.保存配置，点击重启驱动。
• 6.在模型的数据点的下拉框中选择第 2 步创建的资产，查看是否有数据。

一、驱动配置

1、前提：DCOM 配置
opc 经典协议基于 windows 的 COM/DCOM 技术，所以需要对此进行配置。可以参考：

• OPC和DCOM配置
• kepware: Quick Start Guide Remote OPC DA (DCOM)

2、打开设备表管理，切换到设备配置，选择OPCDA驱动程序。

参数说明

• IP: OPCDA 服务器所在计算机的 IP 地址
• 计算机名（Domain）: OPCDA 服务器所在计算机的计算机名
• progId: opc 程序名
• clsid：组件id，不填时自动获取（非必填）
• 用户名: 拥有 DCOM 权限的 windows 用户的用户名（DCOM 配置时需要给一个用户 DCOM 权限）
• 密码: 上述用户的密码
• 采集周期参数决定了驱动将数据上传到平台的频率，默认为5s。

OPCDA 驱动使用 IOPCSyncIO 接口读取数据，每个资产下的数据点属于同一个 Group

获取计算机名
方法一：控制面板 -> 系统和安全 -> 系统 -> 设备名称
方法二：命令行 -> hostname命令
方法三：文件管理器 -> 此电脑 -> 属性 -> 设备名称

获取 progId
progId 一般是由几段字符串（有字母或数字）通过“.”拼接而成， 一般可以在 OPCDA 服务器界面看到。如果没法找到则需要通过第三方客户端找。

第三方客户端都需要通过 OPCEnum 服务获取当前计算机上运行的 opc 服务器，需要确保 OPCEnum 服务运行。 任务管理器 -> 服务 -> OPCEnum

获取 clsid
clsid 至于 progId 有关（同一款 opcda 服务器装在不同的电脑上，clsid 应该是一样的）。不配置 clsid 时，驱动会使用 windows 的服务根据 progId 获取 clsid，配置时使用配置 clsid。

• 通过注册表获取
  在运行 OPCDA 服务器的机器上打开注册表，在 HKEY_CLASSES_ROOT 子目录下找到 progId 对应的条目（与 progId 完全一致）。点击 CLSID 目录，双击属性即可复制，注意不要复制两侧的括号。

Matrikon.OPC.Simulation.1 -> F8582CF2-88FB-11D0-B850-00C0F0104305 Kepware.KEPServerEX.V6 -> 7BC0CC8E-482C-47CA-ABDC-0FE7F9C6E729

• 通过第三方客户端获取
  部分第三方 OPC 客户端（比如 Matrikon explorer）在连接后可以在服务器属性中看到 clsid。

示例

二、数据点配置

OPCDA的itemId在OPC server中是唯一不重复的。 通过驱动扫点方式快速添加OPCDA数据点。

三、指令配置

配置指令时必填 ItemId，注意此时必须填写全部 ItemId（Item 前缀无效）。
每个资产有一个公共 group 用来写入（且与读数时的 group 不同），因此不用配置 group。

常见问题

启动问题需要通过容器日志查看，由于 opcda 造成的问题一般会有一个错误码

opcda 错误码: 0x80010111
windows 版本过新造成的问题。

• windows + R
• winver
• 查看版本号，大于等于2004（个人电脑2020-05-27发布，服务器2020-06-26发布）则属于版本过新

配置文件

配置文件修改后必须重启容器或者进程才能生效。

驱动是多个 OPCDA 客户端的集合。驱动的配置文件作用于驱动连接的所有服务器，不限制于某个设备表。

• client.checkInterval: 检查重连的间隔（以秒记），默认 60

OPCUA客户端平台配置说明

驱动配置决定驱动如何连接 OPCUA 服务器，数据点配置决定驱动从 OPCUA 服务器上读取哪些数据。

一、如何测试

• 1.安装驱动，安装完成后在选择设备驱动时可以看到 opcua。没有驱动授权时也可以添加少量数据点做测试。
• 2.创建一个模型，设备驱动选择 opcua。创建一个属于该模型的资产。
• 3.参考驱动配置一节，配置模型中的驱动配置。
• 4.参考数据点配置一节，在模型中添加一个状态正常的数据点。
• 5.保存配置，点击重启驱动。
• 6.在模型的数据点的下拉框中选择第 2 步创建的资产，查看是否有数据。

二、驱动配置说明

跟连接 OPCUA 服务器相关的配置有以下五项（前三项为必填项），这些信息一般从 OPCUA 服务器的配置页面上可以找到，简要说明如下：

• OPC主机URL：包含了 OPCUA 服务器的 ip 地址（也可以是域名或者计算机名）和端口。请确保驱动运行的服务器可以 ping 通 OPCUA 服务器的地址，并且 OPCUA 服务器的端口没有被占用。
• 安全模式：连接 OPCUA 服务器时的认证方式。有None，Sign ，和Sign&Encrypt三种，分别对应匿名登录，签名验证和签名与加密认证（不同厂商的翻译可能不同）。局域网环境通常允许匿名登录，不允许匿名登录时需要在驱动配置中填写用户名和密码。
• 安全策略：证书加密方式。驱动支持选择None，Basic128Rsa15 ，Basic256，和Basic256Sha256四种中的一种，OPCUA 服务器会支持若干种安全策略。当安全模式是None时安全策略也是None。
• 用户名：非匿名登录时可能需要填写。
• 密码：非匿名登录时可能需要填写。
  采集周期参数决定了驱动将数据上传到平台的频率，由于驱动是通过订阅的方式更新数据的，缩短采集周期并不会增加 OPCUA 服务器的负载。

除了采集周期外，OPCUA 服务器上的数据更新后平台上的数据多快更新还取决于 OPCUA 服务器采集实际设备的周期和推送数据更新信息的最小周期。这两个参数可以在驱动的配置文件配置中配置，但是实际的周期由 OPCUA 服务器根据自身能力决定。

示例
以KEPSevrer为例。版本为 V6.4 321.0。

匿名登录
此时支持匿名登录。

驱动配置如下：

非匿名登录
此时不能匿名登录。注意 KEPServer 支持两种加密方法（对应驱动的安全策略），勾选的加密方法后可以在下拉框中三选一（选择项对应驱动的安全模式）。

KEPServer 安全策略下拉框选项与驱动的安全模式的对应关系如下，需要注意在测试使用的版本中“签名与加密”比“签名；签名与加密”覆盖的范围更广。

增加和修改端点后，需要重启运行时后才能生效。方法为右键点击托盘中的 KEPServer 的绿色小图标，选择“重新初始化”。

根据上述配置，驱动的安全策略和安全模式有2*2=4种有效的组合，以下为其中一种有效配置：

当第一次运行驱动时候，需要在 OPCUA 服务器的配置界面添加证书。

驱动启动或者重启后，刷新受信任的客户端页面，会看到一个名为HTKJ Client的客户端。如果前面没有红叉，则无需做任何操作；如果前有个红叉，右键选择证书，点击信任。等待一段时间即可（驱动会自动重连）。

三、数据点配置说明

每个数据点有 3 个 OPCUA 相关的必填配置：

• 命名空间(NamespaceIndex)：整数，0 是 OPCUA 服务器的配置。KEPServer 上的数据点的命名空间一般是 2。
• 数据点ID(identifier)：字符串。一般不同层级之间用一个分隔符分开。
• 数据类型：实际没有影响，随便选一个就可以。
  数据点的名称和标识只跟平台功能相关，与 OPCUA 无关。

示例
需要第三方 OPCUA 客户端Ua Expert，请自行下载。

首先使用 UaExpert 连接上 OPCUA 服务器，配置与上一节类似（可以参考）

连接成功后，可以左侧看到一组多级目录（结构类似于下图），在目录中找到一个有效的数据点（图标为标签）。

单击标签页，看右侧的 NamespaceIndex 和 identifier。

在平台上，添加数据点，命名空间写 UaExpert 中 NamespaceIndex 对应的数值，数据点ID写 Identifier 对应的值。注意符号和大小写。

OPCUA 数据点的状态码不是 Good 时，驱动不会上传这个数据。

添加大量数据点时推荐使用数据点导入功能。

尽管 OPCUA 的数据点ID没有格式限制，但是实际上数据点ID由几段字符串拼接而成（与 OPCDA 相似）。比如上图中 OPCUA 服务器上的数据点实际上是在设备 Sim 的通道 dev1 下。

常见问题

1.如果驱动运行时实际设备掉线会发生什么

如果实际设备（如 PLC）掉线，一般 OPCUA 上的数据点的状态码会不正常（不是 Good）。此时驱动会发现数据点状态码的变化（前提是驱动中添加了这个数据点），之后不再向平台推送这个数据点的数据（不影响其他数据的推送），直到数据点的状态码变为 Good。

2.可以采集哪些数据类型
布尔型转为0和1，字符串类型（包含ByteString）保存为字符串，日期转化为长整型（毫秒级Unix时间戳），数值类型不做处理。

3.证书如何生成
驱动会自动生成证书，证书可以多次使用或导出（在与 jar 包同级的 cert 目录下）。暂不支持导入预先生成的证书。

4.避免多次信任证书
一般当安全策略和安全模式不是 None，则需要在 OPCUA 服务器上信任证书。而当容器删除后（比如升级驱动）证书会重新创建，则需要在 OPCUA 服务器上重新信任。可以通过持久化证书的方式解决这个问题（不要改文件名）。

• 1)正常运行驱动，并在 OPCUA 服务器上信任证书
• 2)信任后驱动可以正常上数
• 3)登上服务器，将容器中的 cert 目录拷贝到本地
• • 假设拷贝到 /home/app/ua 目录下，opcua 容器的驱动名是 opcua
• • mkdir -p /home/app/uacert
• • docker cp opcua:/app/cert /home/app/ua
• • 此时 /home/app/ua 下会有一个 cert 目录，里面有一个证书（没有说明没上数）
• 4)在运维平台中将证书挂载
• • 找到服务，点击修改，增加数据卷
• • 容器：/app/cert，主机：/home/app/ua/cert，模式：bind
• • 保存后会重启驱动
• 5)也可以直接修改 docker-compose文件
  在 windows 平台中，证书在驱动对应目录的 cert 子目录中，直接保存文件即可。以后更新版本后，在驱动运行前将保存的文件拷贝到 cert 子目录中。

5.不上数了，怎么排查

很多原因都能导致不上数，建议按照如下顺序进行排查：

• OPCUA 驱动服务是否在运行
• • 列表平台后台首页左侧导航栏中找到系统操作，在驱动中是否有 OPCUA 驱动
• 驱动配置和数据点配置是否无误
• OPCUA 服务器是否正常工作
• • 用 UaExpert 能否连接到服务器
• • OPCUA 的端口是否被占用
• 运行平台的服务器能否 ping 通 OPCUA 服务器
• 驱动容器能否 ping 通 OPCUA 服务器

配置文件
配置文件尽量不要自行修改。修改后必须重启容器或者进程才能生效。

驱动是多个 OPCUA 客户端的集合。驱动的配置文件作用于驱动连接的所有服务器，不限制于某个模型或资产。

batchSize 的最大值，publishInterval 和 samplingInterval 的最小值由 OPCUA 服务器决定，需要通过 OPCUA 服务器的管理软件查看

• client.readMode: 读取数据的模式，分为 subscribe（订阅）和 direct（直接读取）两种。默认 subscribe，尽量不要使用 direct 模式。
• client.batchSize: 每个订阅包含的最大 NodeID 数量。整数，默认100。仅在订阅模式有效。
• client.publishInterval： 客户端希望服务器执行订阅的周期（秒），实际上的周期由服务器决定。小数，默认0.5，即周期为0.5*1000=500ms。仅在订阅模式有效。
• client.samplingInterval: 服务器对 MonitoredItems 的采样周期（秒）。小数，默认1.0，即周期为1.0*1000=1000ms。仅在订阅模式有效。
• client.maxPendingPublishRequests: 客户端 publishRequests 队列的长度，如果订阅模式时服务器总报Bad_TooManyPublishRequests，则要将这个值降低。整数，默认10。如果配置文件中的这个值<0，则实际的maxPendingPublishRequests=所有连接这台服务器的资产的数据点的不重复的NodeId数量/batchSize + 1，比如一个客户端需要订阅590个不同的Node，batchSize为100，则maxPendingPublishRequests=590/100 + 1=5+1=6.
• client.autoReconnect: 驱动运行一段时间后自动断开所有 opcua 客户端并重连（不断开驱动与平台的连接）。格式为XhYmZs，即X小时加Y分钟加Z秒（例：24h=24小时，1h30m=90分钟）。从配置文件中解析出来的时间不超过10分钟时不启用此功能。
• client.replaceURL：是否替换 endPointURL ，默认为false。客户端连接 OPCUA 服务器时，会先根据配置的 endpointURL 获取对应设备上的所有 OPCUA 服务器的信息（其中包含另一个 endpointURL ），然后再通过条件筛选出一台 OPCUA 服务器，最后使用服务器返回的信息配置客户端并连通。当平台上配置的 endpointURL 是代理的地址时，返回的服务器信息中的URL可能仍会是内网地址。将这个选项设置为true时，会在检测到两个 enpointURL 不一致时将最终客户端配置的URL替换为平台配置的URL。

一.TCP客户端驱动说明

该驱动每个模型可以配置一个服务器地址或为为每个设备单独配置一个服务器地址, 同一模型内服务器地址相同的设备将会使用同一个 TCP 连接(如果模型内所有设备都未配置服务器地址, 则该模型内的所有设备共用同一个连接).
驱动启动后, 每个模型都会主动与服务端建立连接, 然后接收服务端的数据.

1.当模型没有添加任何设备时, 该模型不会与服务器建立连接.
2.即使多个模型连接同一服务器, 也会为每个模型会创建一个独立的连接.

二.驱动脚本执行流程说明

以下处理流程以模型为单位, 多个模型之间独立执行, 互不影响.

• 当与服务器成功建立连接后, 会执行 连接处理脚本, 此时 state 参数的值为 true.
• 当接收到服务端发送的数据时, 会读取所有的发送数据并存放到 Buffer 中, 然后调用 数据包拆分脚本.
• 如果从已接收到的数据中拆分出完整的数据包，则将完整的数据包封装为 Buffer 交由 数据处理脚本.
• 如果未从已接收到的数据中拆分出完整的数据包, 则根据 数据包拆分脚本 返回的数据决定是等待接收更多的数据或是丢弃部分数据.
• 当连接断开时, 会执行 连接处理脚本, 此时 state 参数的值为 false.

三.客户端对象

客户端对象为当前 TCP 连接对象. 该对象除了提供与服务器通讯的功能外, 并且供一些常用的功能用于简化使用，提高效率.

在 数据包拆分脚本, 数据处理脚本, 指令处理脚本 和 连接处理脚本 函数的参数中提供了 client 对象参数, 在脚本中可以通过使用 client 中提供的函数完成数据的发送与采集.

该对象提供了以下函数:

• 与服务器交互：send(data) 向服务端发送数据
• 指令相关：reportCommand(serialNo,table,deviceId,state,result) 向平台上报指令执行结果
• 媒体库(未实现)：
• • getMediaFile(path) 请求媒体库文件
• • getMediaFileByURL(url) 请求媒体库文件
• • uploadMediaFile(filename,catalog,action,data) 上传文件到媒体库
• • deleteMediaFile(path) 删除媒体库文件
• 工作表：
• • saveWorkTableRow(tableId, rowData) 向工作表中写入数据
• • updateWorkTableRow(tableId,query,rowData) 更新工作表数据(未实现)
• • updateWorkTableRowById(tableId,rowId,rowData) 根据记录标识更新工作表数据
• 数据存储：
• • getContext(contextId) 获取数据上下文
• • removeContext(contextId) 删除数据上下文
• • getContextIds() 获取全部上下文标识
• • getDeviceContext(deviceId) 获取设备数据上下文
• • removeDeviceContext(deviceId) 删除设备上下文
• • getDeviceContextIds() 获取全部设备上下文标识**

函数案例：

①向服务端发送数据

用于向服务端发送数据. 例如: 在接收到数据时向服务端发送 ack 信息或发送心跳数据.

返回值
string 或 undefined. 如果参数不正确(字节数组为空或空数组)或发送失败则返回 string 内容为错误说明, 如果发送成功则返回 undefined.

②向平台上报指令执行结果

上报指令执行结果. 有些场景指令的执行结果反馈是异步的, 在指令发送后， 过一段时间才会收到响应报文, 此时可以在接收到响应报文时通过 client.reportCommand(...) 方法上报指令执行结果. 通过该方法上报的结果信息可以在平台中 指令状态管理 页面中查看.

1.serialNo 为平台在发送指令时生成, 会传入到指令处理脚本中, 当指令执行结果为异步反馈时, 可以将 serialNo 保存到设备上下文中，以便在后续 reportCommand 使用.

2.参数中的 table 来自于 指令处理函数 的参数,当需要通过 reportCommand 上报自定义的命令执行结果信息时,需要在指令处理函数中保存相关参数信息以便后续使用.

返回值

string 或 undefined. 如果返回 undefined 则表示发送成功, 否则返回数据为错误原因.

示例

③请求媒体库文件-路径

请求媒体库文件

参数说明

返回值

示例

④请求媒体库文件-URL

请求媒体库文件

参数说明

url 中 default 为项目ID, test 为目录, hello.txt 为文件名.

返回值

示例

⑤上传文件到媒体库

上传文件到媒体库

参数说明

返回值

示例

⑥删除媒体库文件

删除媒体库文件

参数说明

返回值

示例

⑦向工作表中写入数据

向工作表写入一条数据

参数说明

rowData 对象中必须包含 id 字段, 并且该字段做为数据的唯一标识, 必须唯一.

返回值

示例

⑧更新工作表数据

更新工作表中的数据

参数说明

返回值

示例

⑨根据记录标识更新工作表数据

根据记录标识更新记录

参数说明

返回值

示例

⑩获取数据上下文

用于获取上下文对象, 可以在上下文中存储数据. 详细信息

第一次调用的时候才会创建上下文

参数说明

返回值

Object. 数据上下文对象

示例

⑪删除数据上下文

删除上下文对象

参数说明

返回值

无

示例

⑫获取全部上下文标识

获取全部上下文标识(不包含设备上下文)

参数说明

无

返回值

String[]

示例

⑬获取设备数据上下文

用于获取设备上下文对象, 使用设备标识作为上下文标识, 可以在上下文中存储数据. 详细信息

与 getContext 不同的是, 当设备被删除后, 重启驱动时会自动清理被删除设备的上下文对象.

第一次调用的时候才会创建上下文

参数说明

返回值

Object. 数据上下文对象

示例

⑭删除设备上下文

删除设备上下文对象

参数说明

返回值

无

示例

⑮获取全部设备上下文标识

获取全部设备上下文标识(只包含设备上下文)

参数说明

无

返回值

String[]

示例

四.数据上下文

上下文对象, 用来存储数据, 上下文中的数据可以在不同的脚本中共享. 例如: 可以在 指令处理脚本中 写入数据, 然后从 数据处理脚本 中读取数据. 不同上下文彼此独立, 互不影响.

CAUTION
可以根据需求创建多个上下文对象, 但是上下文对象以及上下文中的数据需要及时清理, 否则会造成 OOM 问题, 导致驱动程序崩溃.

①向上下文中保存数据
用于向上下文中存储数据. 如果 key 已存在则会覆盖已有数据.

参数说明

返回值

无

示例

②判断上下文中是否包含指定数据

判断上下文中是否存在指定的 key

参数说明

返回值

bool. true 表示 key 存在, false 表示 key 不存在

示例

③获取数据
从上下文中获取指定的 key 对应的数据. 如果 key 不存在则返回 undefined

参数说明

返回值

any 或 undefined. 返回 put 时写入的数据.

示例

④获取并删除数据
从上下文中获取指定的 key 对应的数据并且在返回后 删除 该 key. 如果 key 不存在则返回 undefined.

TIP
该函数返回后, 再使用 get 或 getAndRemove 均返回 undefined.

参数说明

返回值

any 或 undefined. 返回 put 时写入的数据.

示例

⑤删除数据
从上下文中删除指定的 key, 如果 key 不存在则不执行任何操作.

参数说明

返回值

无

示例

五.内置对象

crc 循环冗余校验
驱动中内置了 crc 对象, 可以在脚本中直接使用 crc 对象中的校验函数.

• checksum16(Buffer,Poly) CRC-16循环冗余校验
• checksum32(Buffer,Poly) CRC-32循环冗余校验
• checksum64(Buffer,Poly) CRC-64循环冗余校验
• checksumModbus(Buffer) CRC-Modbus循环冗余校验

CRC-16循环冗余校验
使用 checksum16(Buffer, Poly) 实现 16位 的循环冗余校验

参数说明

返回值

uint16. 16位无符号整型

示例

CRC-32循环冗余校验
使用 checksum32(Buffer, Poly) 实现 32位 的循环冗余校验

参数说明

返回值

uint32. 32位无符号整型

示例

CRC-64循环冗余校验
使用 checksum64(Buffer, Poly) 实现 64位 的循环校验码

参数说明

返回值

uint64. 64位无符号整型

CRC-Modbus循环冗余校验
使用 checksumModbus(Buffer) 实现 modbus 的循环校验码.

modbus 校验与 crc16 相似, 校验码类型为 uint16. 另外, checksumModbus 不需要 poly 多项式参数.

参数说明

返回值

uint16. 16位无符号整型

六.内置函数

数据包拆分函数

• createFixedLengthSplitFn(Length,ByteOrder) 固定长度头
• createDelimiterSplitFn(Delimiter) 固定分隔符
• createStartEndDelimiterSplitFn(StartChars,EndChars) 固定开始和结束符

TIP
内置数据包拆分函数仅能用于 数据拆包脚本 中

固定长度头

该函数会取前 N 个字节作为长度信息, 然后根据长度信息读取主体内容.
在数据包拆分脚本中直接使用内置的拆分函数, 如下所示:

固定分隔符
该函数会使用固定分隔符拆分数据包. 使用方式如下所示:

CAUTION
数据包内容中不能包含分隔符

固定开始和结束符

该函数会读取指定开始符和结束符之间的数据做为一个完整的数据包. 使用方式如下所示:

INFO
开始符 和 结束符 可以包含多个字符.

CAUTION
如果一个数据包中存在多个 开始符 或 结束符 时无法使用该内置函数.
例如: 使用 @ 和 # 作为开始符和结束符时, 数据包主体部分不能包含 @ 和 #, 否则拆包结果不正确.

七.脚本说明

脚本语言: JavasScript ECMAScript 5.1

驱动使用时要求提供 数据包拆分脚本, 数据处理脚本, 连接处理脚本 和 指令处理脚本 脚本函数来处理接收和发送数据过程中的协议和数据格式问题.

在脚本的上下文中内置了 Buffer 包, 可用于处理接收或发送二进制数据.

除此之外, 还内置了 lodash, crypto-js, moment, xml-js 和 formulajs(Excel函数) 包.

TIP
所有的脚本中的函数名必须为 handler, 参数列表参考各脚本说明.

数据包拆分脚本

该脚本用于处理接收数据过程中的半包和粘包问题, 该函数需要根据数据格式判断接收到的字节数组中是否包含完整的数据包, 如果包含了完整数据包则返回完据包的起始位置和长度. 或者当数据包有错误时丢掉该数据包或有问题部分的数据.

如果字节数组中不包含完整的数据包, 直接返回 undefined 表示需要从客户端接收更多的数据.

函数定义如下:

TIP
驱动内置了常用的数据包拆分函数. 详情

参数说明

返回值说明

• 当字节数组中包含完整数据包时, 返回包含 package 字段的对象.
• 如果字节数组中存在错误, 则返回包含 drop 字段的对象, 丢弃掉错误的数据.
• 如果字节数组中即不包含完整的数据包也不存在错误, 直接返回 undefined, 表示需要从客户端接收更多的数据.

正常接收数据
当数据包拆分脚本返回以下内容时, 表示已接收到的数据中包含了完整的数据包. 该数据包在所有数据中的起始位置为 0, 长度为 128, 下一个数据包的起始位置为 129

例如, 使用 \r\n 作为数据包间的分隔符, 以解析该数据时 {"a":1,"b":2}\r\n{"a":3,"b":4}\r\n, 拆分结果为 {"package":{"start":0,"length":13,"next":15}}. 此时, 数据处理脚本 中接收到的数据为 {"a":1,"b":2}, 并不会包含 \r\n, 而下一次数据拆分脚本接收到的数据为 {"a":3,"b":4}\r\n.

包含错误或不完整数据包时

返回以下内容时, 表示接收到的数据不完整, 需要丢弃 0 - 12 部分内容.

例如, 接收到的内容为 :1,"b":2}\r\n{"a":3,"b":4}\r\n 时, :1,"b":2}\r\n 为不完整的数据包需要丢弃, 则需要返回 {"drop":11}. 下一次数据拆分脚本接收到的数据为 {"a":3,"b":4}\r\n

不包含完整的数据包和错误包时

例如, 接收到的数据为 {"a":1, 未找到分隔符 \r\n, 此时返回 undefined 表示需要接收更多的数据. 当客户端发送 "b":2}\r\n{"a":3,"b":4}\r\n 数据时, 会再次调用 数据包拆分脚本, 此时 Buffer 中的数据为 {"a":1,"b":2}\r\n{"a":3,"b":4}\r\n, 此时可以提取出完整的数据包.

注: 如果返回结果中同时包含了 drop 和 package 字段并且 drop 的值大于 0 时, 只做丢弃数据处理.

示例

数据处理脚本
该脚本用于处理 数据包拆分脚本 函数解析得到的完整数据包, 根据协议和数据格式将数据包解析为平台定义的数据格式.

函数定义如下:

参数说明

返回值

注: 返回值必须为 Object[] 或 undefined 其中之一. 返回空数组表示未从接收到的数据中解析出有效数据, undefined 表示无返回结果, 驱动程序无须处理返回结果. 例如: 接收到的数据为心跳数据, 不包含采集数据.

示例

指令处理脚本
该脚本用于将发送的指令内容转换为字节数组, 当向设备发送指令时, 驱动会将要发送的内容先经过 命令处理脚本 函数处理, 返回结果作为实际发送的内容.

函数定义如下:

参数说明

指令格式如下:

以 test 指令为例

注：ops.value 通常为实际发送的内容, 该字段为必填值. opts 为数组, 
目前长度固定为 1.

当要发送的数据内容比较复杂时, 可以先转发送内容转换为 base64 格式的字符串
然后在在指令脚本中再进行 base64 解码后再发送.

返回值说明

必须值必须为 Buffer 对象.

注: 可以使用 Buffer.from("this is a string"") 等方法创建 Buffer 对象. 关于 Buffer 的使用说明可以点击查看

示例

连接处理脚本
当客户端连接到驱动或断开时, 会调用 连接处理脚本.

函数定义如下:

参数说明

返回值说明

无返回值

示例

定时器脚本
用于周期性的执行一些操作. 例如: 定时发送心跳.

函数定义如下:

参数说明

返回值说明

无返回值

示例

示例
假设某设备使用 TCP 上报数据, 并且上报的数据格式如下所示:

我 现在看一下

发一下 远程码把

您可以联系下客户经理 帮您解答

可以设置数据源配置数据右侧的轮询时间

日志如果报错提示 未填写数据处理脚本，指令处理脚本，需要修改脚本内容，不可全部删除，必须有 handler 这个函数。因为初始驱动实例中的脚本只是例子，不生效，需修改后才生效。

如果发送端配置的ip+端口号的端口是通过 3030 或 31000 端口，需要修改配置文件：
1.需要在app目录下修改 docker-compose.yml 的配置，按照截图修改内容，并在请求的时候在请求头中加上项目的ID。（项目id是多空间版本的）
2.找到 http server 的驱动，添加截图上写的内容，如果不需要校验 token 的话，就把 middleware=auth 那行给删掉就可以。发送端设备需要在请求的时候加上请求头 x-request-project 就可以

1.点击进入脚本案例
2.平台配置：设备表配置信息

1）发送数据端的ip和port 是平台的ip和httpserver驱动的port
2）平台配置信息中的请求路径和发送端ports后面的保持一致即可，设备端往 url 上推送：比如填写的 /aaa/bbb
推送的时候，url 就是 http://ip:port/aaa/bbb
3）数据处理脚本可参考案例
4）判断是否连接成功可以看下运维管理中httpserver的驱动日志