diff --git a/neuronex/directory.json b/neuronex/directory.json index 3126e4d..ad9a546 100644 --- a/neuronex/directory.json +++ b/neuronex/directory.json @@ -3,11 +3,42 @@ { "title": "产品概览", "path": "./", - "children": [] + "children": [ + { + "title": "架构", + "path": "intro/architecture" + }, + { + "title": "数采模块列表", + "path": "intro/plugin-list" + }, + { + "title": "许可证政策", + "path": "intro/license-policy" + } + ] }, { - "title": "插件", - "path": "intro/plugin-list" + "title": "快速入门", + "path": "quick_start/quick_start" + }, + { + "title": "安装", + "path": "install/introduction", + "children": [ + { + "title": "使用 .tar.gz 包安装", + "path": "install/linux" + }, + { + "title": "通过Docker部署", + "path": "install/docker" + }, + { + "title": "申请和安装许可证", + "path": "install/license_setting" + } + ] }, { "title": "数据采集配置", @@ -18,10 +49,6 @@ "path": "config/south-devices/south-devices", "collapsed": true, "children": [ - { - "title": "File", - "path": "config/south-devices/file/file" - }, { "title": "Modbus RTU", "path": "config/south-devices/modbus-rtu/modbus-rtu", @@ -236,6 +263,10 @@ { "title": "导入/导出点位配置", "path": "config/import-export" + }, + { + "title": "基于模板配置", + "path": "config/templates/templates" } ] }, @@ -284,13 +315,17 @@ { "title": "订阅南向数据", "path": "config/subscription" + }, + { + "title": "管理插件模块", + "path": "config/ecp_edge_plugin" + }, + { + "title": "数据监控", + "path": "monitor/introduction" } ] }, - { - "title": "数据监控", - "path": "monitor/introduction" - }, { "title": "数据流处理", "path": "streaming-processing/overview", @@ -458,9 +493,25 @@ ] }, { - "title": "管理", + "title": "HTTP API", + "path": "api/api" + }, + { + "title": "运维指南", "path": "management/introduction", "children": [ + { + "title": "数据监控", + "path": "management/monitoring" + }, + { + "title": "数据统计", + "path": "management/data-statistics" + }, + { + "title": "配置管理", + "path": "management/conf-management" + }, { "title": "日志", "path": "management/logs" @@ -935,7 +986,7 @@ ] }, { - "title": "管理", + "title": "运维指南", "path": "management/introduction", "children": [ { @@ -948,6 +999,10 @@ } ] }, + { + "title": "HTTP API", + "path": "http-api/http-api" + }, { "title": "发版历史", "path": "release_history/release_history" diff --git a/neuronex/zh_CN/api/api.md b/neuronex/zh_CN/api/api.md new file mode 100644 index 0000000..eb16e0d --- /dev/null +++ b/neuronex/zh_CN/api/api.md @@ -0,0 +1,18 @@ +# HTTP API + +IIoT平台或其他监控应用可以通过使用提供的HTTP-API来监视和控制Neuron设备。这些API的关键功能如下： + +[获取数据：](./rw.md) HTTP-API允许平台监视与IIoT平台连接的设备所获取的数据。这使得能够实时监控传感器读数、操作参数和设备状态。 + +[控制命令：](./rw.md) API还支持向Neuron设备发送控制命令，使平台能够远程控制和管理设备。这实现了对设备功能的无缝管理。 + +[远程设置和配置：](./configuration.md) 平台可以通过HTTP-API远程设置和配置设备连接。这确保了在无需物理访问的情况下方便高效地管理设备。[插件设置](./plugin-setting.md) 也可用。 + +[JWT身份验证：](./jwt.md) API采用JWT身份验证，确保IIoT平台或监控应用与Neuron设备之间的安全通信和身份验证。这增强了系统的整体安全性。 + +[Prometheus兼容指标：](./metrics.md) API提供与Prometheus兼容的指标数据。这使得可以轻松与Prometheus监控工具集成，便于对设备指标进行有效监控和分析。 + +[错误代码描述：](./data-type.md) API包括全面的错误代码描述，提供有关遇到的错误的性质和原因的信息。这有助于有效的故障排除和问题解决。 + +[数据类型描述：](./error-code.md) 为了确保数据的表示和解释清晰一致，API描述了使用的数据类型。这促进了IIoT平台或监控应用中数据的无缝集成和分析。 + diff --git a/neuronex/zh_CN/api/configuration.md b/neuronex/zh_CN/api/configuration.md new file mode 100644 index 0000000..e68a5fa --- /dev/null +++ b/neuronex/zh_CN/api/configuration.md @@ -0,0 +1,2286 @@ +# 配置 + +Neuron 将为 IIoT 平台提供一系列 API 服务，用于查询基本信息、控制网关行为或设置轮询配置。 IIoT 平台必须通过向 Neuron 发送请求消息来启动通信。 通过返回，Neuron 将返回所需的信息或执行相应的操作。 如果有错误，将返回一个错误代码来说明失败的原因。 + +## Ping + +*POST* **/api/v2/ping** + +### 响应状态 + +* 200 OK + +## 登录 + +*POST* **/api/v2/login** + +### 请求头部 + +**Content-Type** application/json + +### 响应状态 + +* 200 OK +* 401 + * 1004, 缺少令牌 + * 1005, 解码令牌错误 +* 403 + * 1006, 令牌过期 + * 1007, 验证令牌错误 + * 1008, 无效令牌 + +### 请求体 + +```json +{ + "name": "admin", + "pass": "0000" +} +``` + +### 响应 + +```json +{ + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzcyODcxNjMsImlhdCI6MTYzNzIwMDc2MywiaXNzIjoiRU1RIFRlY2hub2xvZ2llcyBDby4sIEx0ZCBBbGwgcmlnaHRzIHJlc2VydmVkLiIsInBhc3MiOiIwMDAwIiwidXNlciI6ImFkbWluIn0.2EZzPC9djErrCeYNrK2av0smh-eKxDYeyu7cW4MyknI" +} +``` + +## 更改密码 + +*POST* **/api/v2/password** + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 401 + * 1004, 缺少令牌 + * 1005, 解码令牌错误 + * 1012, 密码长度太短或太长 + * 1013, 密码重复 +* 403 + * 1006, 令牌过期 + * 1007, 验证令牌错误 + * 1008, 无效令牌 + +### 请求体 + +```json +{ + "name": "admin", + "old_pass": "01234", + "new_pass": "56789" +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 添加 Node + +*POST* **/api/v2/node** + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 400 + * 2001 node 类型无效 +* 404 + * 2301 未找到插件库 +* 409 + * 2002 node 不存在 + +### 请求体 + +```json +{ + //node name + "name": "modbus-tcp-node", + //plugin name + "plugin": "Modbus TCP" +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 删除 Node + +*Delete* /api/v2/node + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 2003 node not exist + +### 请求体 + +```json +{ + //node name + "name": "modbus-tcp-node" +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 更新 Node + +*PUT* **/api/v2/node** + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 400 + * 2013 node 不允许更新 + * 2015 node 名称不允许为空 +* 404 + * 2003 node 不存在 +* 409 + * 2002 node 已存在 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 请求体 + +```json +{ + "name": "modbus-node" + "new_name": "modbus-tcp-node" +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 获取 Node + +*GET* /api/v2/node + +### 请求参数 + +**type** 必需 + +**plugin** 可选 + +**node** 可选 + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK + +### 响应 + +```json +{ + "nodes": [ + { + //node name + "name": "sample-driver-adapter", + //plugin name + "plugin": "Modbus TCP" + }, + { + "name": "modbus-tcp-adapter", + "plugin": "Modbus TCP" + } + ] +} +``` + +## 配置 Node + +*POST* /api/v2/node/setting + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 400 + * 2003 node 不存在 + * 2004 node 配置无效 + +### 请求体 + +```json +//The parameter fields in json fill in different fields according to different plugins +{ + //node name + "node": "modbus-node", + "params": { + "param1": 1, + "param2": "1.1.1.1", + "param3": true, + "param4": 11.22 + } +} +``` + +:::tip +每个插件的配置参数具体可参考 [插件设置](./plugin-setting.md)。 +::: + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 获取 Node 配置 + +*GET* /api/v2/node/setting + +### 请求参数 + +**node** 必需 + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK + * 2005 node 配置未发现 +* 404 + * 2003 node 不存在 + +### 响应 + +```json +//The parameter fields in json fill in different fields according to different plugins +{ + "node": "modbus-node", + "params": { + "param1": "1.1.1.1", + "param2": 502 + } +} +``` + +## 控制 Node + +*POST* /api/v2/node/ctl + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 请求状态 + +* 200 OK +* 409 + * 2006 node not ready + * 2007 node is running + * 2008 node not running + * 2009 node is stopped + +### 请求体 + +```json +{ + //node name + "node": "modbus-node", + //0 start, 1 stop + "cmd": 0 +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 获取 Node 状态 + +*GET* /api/v2/node/state + +### 请求参数 + +**node** optional + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK + +### 响应 + +```json +{ + "states": [ + { + // node name + "node": "modbus-node1", + //running state + "running": 2, + //link state + "link": 1, + //average round trip time communicating with devices + "rtt": 100 + }, + { + "node": "modbus-node2", + "running": 1, + "link": 0, + "rtt": 9999 + } + ] +} +``` + +## 添加 Group + +*POST* /api/v2/group + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 2003 node not exist +* 409 + * 2103 group not allow + +### 请求体 + +```json +{ + //group name + "group": "gconfig1", + //node name + "node": "modbus-node", + //read/upload interval(ms) + "interval": 10000 +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 删除 Group + +*DELETE* /api/v2/group + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 412 + * 2101 group already subscribed +* 404 + * 2003 node not exist + * 2101 group not exist + +### 请求体 + +```json +{ + //node name + "node": "modbus-node", + //group name + "group": "gconfig1" +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 更新 Group + +*PUT* /api/v2/group + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 2003 node not exist + * 2106 group not exist +* 409 + * 2104 group exist + +### 请求体 + +```json +{ + //node name + "node": "node1", + //group name + "group": "group", + //read/upload interval(ms) + "interval": 20000 +} +``` + +更新 group name: +```json +{ + //node name + "node": "modbus-node", + //group name + "group": "gconfig1", + //group new name + "new_name": "group1" +} +``` + +更新 group interval: +```json +{ + //node name + "node": "modbus-node", + //group name + "group": "gconfig1", + //read/upload interval(ms) + "interval": 10000 +} +``` + +同时更新 group name 和 interval: +```json +{ + //node name + "node": "modbus-node", + //group name + "group": "gconfig1", + //group new name + "new_name": "group1", + //read/upload interval(ms) + "interval": 10000 +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 获取 Group + +*GET* /api/v2/group + +### 请求参数 + +**node** 可选 + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK + +### 响应 + +````json +{ + "groups": [ + { + //group name + "name": "config_modbus_tcp_sample_2", + //read/upload interval(ms) + "interval": 2000, + //tag count + "tag_count": 0 + }, + { + "name": "gconfig1", + "interval": 10000, + "tag_count": 0 + } + ] +} +```` + +## 添加 Tag + +*POST* /api/v2/tags + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 206 + * 2202 tag name conflict + * 2203 tag attribute not support + * 2204 tag type not support + * 2205 tag address format invalid +* 404 + * 2003 node not exist + +### 请求体 + +```json +{ + //node name + "node": "modbus-node", + //group name + "group": "config_modbus_tcp_sample_2", + "tags": [ + { + //tag name + "name": "tag1", + //tag address + "address": "1!400001", + //tag attribute + "attribute": 8, + //tag type + "type": 4, + //optional, float/double precision, optional(0-17) + "precision": 0, + //optional, decimal + "decimal": 0, + //optional, description + "description": "", + //optional, when the attribute is static,the value field needs to be added. + "value": 12 + }, + { + "name": "tag2", + "address": "1!00001", + "attribute": 3, + "type": 3, + "decimal": 0.01 + }, + { + "name": "tag3", + "address": "1!400009", + "attribute": 3, + "type": 9, + "precision": 3 + }, + { + "name": "static_tag", + "address": "", + "attribute": 10, + "type": 1, + "description": "It is a static tag", + "value": 42 + } + ] +} +``` + +### 响应 + +```json +{ + "index": 1, + "error": 0 +} +``` + +## 获取 Tag + +*GET* /api/v2/tags + +### 请求参数 + +**node** 必需 + +**group** 必需 + +**name** 可选 + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 2003 node 不存在 + +### 响应 + +```json +{ + "tags": [ + { + //tag name + "name": "tag1", + //tag type + "type": 4, + //tag address + "address": "1!400001", + //tag attribute + "attribute": 8, + //description + "description": "", + //float/double precision + "precison": 0, + //decimal + "decimal": 0, + //optional, when the attribute is static + "value": 12 + }, + { + "name": "tag2", + "type": 14, + "address": "1!00001", + "attribute": 3, + "description": "", + "precison": 0, + "decimal": 0, + }, + { + "name": "tag3", + "type": 11, + "address": "1!400009", + "attribute": 3, + "description": "", + "precison": 0, + "decimal": 0, + } + ] +} +``` + +## 更新 Tag + +*PUT* /api/v2/tags + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 206 + * 2201 tag 不存在 + * 2202 tag 名字冲突 + * 2203 tag 属性不支持 + * 2204 tag 类型不支持 + * 2205 tag 地址格式无效 +* 404 + * 2003 node 不存在 + * 2106 group 不存在 + +### 请求体 + +```json +{ + //node name + "node": "modbus-tcp-test", + //group name + "group": "group1", + "tags": [ + { + //tag name + "name": "tag1", + //tag type + "type": 8, + //tag attribute + "attribute": 0, + //tag address + "address": "1!400001", + //description + "description":"", + //float/double precision + "precison": 0, + //decimal + "decimal": 0, + //when the attribute is static,the value field needs to be added. + "value": 12 + }, + { + "name": "tag2", + "type": 6, + "attribute": 0, + "address": "1!400002", + "description":"", + "precison": 0, + "decimal": 0, + }, + { + "name": "static_tag", + "address": "", + "attribute": 10, + "type": 1, + "description":"", + "precison": 0, + "decimal": 0, + "value": 42 + } + ] +} +``` + +### 响应 + +```json +{ + "error": 0, + "index": 1 +} +``` + +## 删除 Tag + +*DELETE* /api/v2/tags + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 2003 node 不存在 + +### 请求体 + +```json +{ + //group name + "group": "config_modbus_tcp_sample_2", + //node name + "node": "modbus-node", + //tag names + "tags": [ + "tag1", + "tag2" + ] +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 添加插件 + +*POST* /api/v2/plugin + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK + +* 400 + + * 2302 库信息无效 + +### 请求体 + +```json +{ + //plugin library name + "library": "plugin_name.so" +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 删除插件 + +*DELETE* /api/v2/plugin + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK + +### 请求体 + +```json +{ + //plugin name + "plugin": "modbus-tcp" +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 获取插件 + +*GET* /api/v2/plugin + +### 请求参数 + +**plugin** optional + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK + +### 响应 + +```json +{ + "plugins": [ + { + //plugin kind + "kind": 1, + //node type + "node_type": 1, + //plugin name + "name": "Modbus TCP", + //plugin library name + "library": "libplugin-modbus-tcp.so", + "description": "description", + "description_zh": "描述", + "schema": "modbus-tcp" + }, + { + "kind": 1, + "node_type": 2, + "name": "MQTT", + "library": "libplugin-mqtt.so", + "description": "Neuron northbound MQTT plugin bases on NanoSDK.", + "description_zh": "基于 NanoSDK 的 Neuron 北向应用 MQTT 插件", + "schema": "mqtt" + } + ] +} +``` + +## 获取插件 Schema + +*GET* /api/v2/schema + +### 请求参数 + +**schema_name** 必需 + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK + +### 响应 + +```json +{ + "tag_regex": [ + { + "type": 3, + "regex": "^[0-9]+![3-4][0-9]+(#B|#L|)$" + }, + { + "type": 4, + "regex": "^[0-9]+![3-4][0-9]+(#B|#L|)$" + }, + { + "type": 5, + "regex": "^[0-9]+![3-4][0-9]+(#BB|#BL|#LL|#LB|)$" + }, + { + "type": 6, + "regex": "^[0-9]+![3-4][0-9]+(#BB|#BL|#LL|#LB|)$" + }, + { + "type": 7, + "regex": "^[0-9]+![3-4][0-9]+(#B|#L|)$" + }, + { + "type": 8, + "regex": "^[0-9]+![3-4][0-9]+(#B|#L|)$" + }, + { + "type": 9, + "regex": "^[0-9]+![3-4][0-9]+(#BB|#BL|#LL|#LB|)$" + }, + { + "type": 10, + "regex": "^[0-9]+![3-4][0-9]+(#B|#L|)$" + }, + { + "type": 11, + "regex": "^[0-9]+!([0-1][0-9]+|[3-4][0-9]+\\.([0-9]|[0-1][0-5]))$" + }, + { + "type": 13, + "regex": "^[0-9]+![3-4][0-9]+\\.[0-9]+(H|L|)$" + } + ], + "group_interval": 1000, + "connection_mode": { + "name": "Connection Mode", + "name_zh": "连接模式", + "description": "Neuron as the client, or as the server", + "description_zh": "Neuron 作为客户端或服务端", + "attribute": "required", + "type": "map", + "default": 0, + "valid": { + "map": [ + { + "key": "Client", + "value": 0 + }, + { + "key": "Server", + "value": 1 + } + ] + } + }, + "interval": { + "name": "Send Interval", + "name_zh": "指令发送间隔", + "description": "Send reading instruction interval(ms)", + "description_zh": "发送读指令时间间隔，单位为毫秒", + "attribute": "required", + "type": "int", + "default": 20, + "valid": { + "min": 0, + "max": 3000 + } + }, + "host": { + "name": "IP Address", + "name_zh": "IP地址", + "description": "Local IP in server mode, remote device IP in client mode", + "description_zh": "服务端模式中填写本地 IP，客户端模式中填写目标设备 IP", + "attribute": "required", + "type": "string", + "valid": { + "regex": "/^((2[0-4]\\d|25[0-5]|[01]?\\d\\d?)\\.){3}(2[0-4]\\d|25[0-5]|[01]?\\d\\d?)$/", + "length": 30 + } + }, + "port": { + "name": "Port", + "name_zh": "端口号", + "description": "Local port in server mode, remote device port in client mode", + "description_zh": "服务端模式中填写本地端口号，客户端模式中填写远程设备端口号", + "attribute": "required", + "type": "int", + "default": 502, + "valid": { + "min": 1, + "max": 65535 + } + }, + "timeout": { + "name": "Connection Timeout", + "name_zh": "连接超时时间", + "description": "Connection timeout(ms)", + "description_zh": "连接超时时间，单位为毫秒", + "attribute": "required", + "type": "int", + "default": 3000, + "valid": { + "min": 1000, + "max": 65535 + } + } +} +``` + +## 订阅 + +*POST* /api/v2/subscribe + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 2106 group 不存在 + +### 请求体 + +```json +{ + //app name + "app": "mqtt", + //driver name + "driver": "modbus-tcp", + //driver node group name + "group": "group-1", + //when using the MQTT plugin, the topic field needs to be added + "params": { + "topic": "/neuron/mqtt/group-1" + } +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 订阅多个组 + +*POST* /api/v2/subscribes + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 2106 group 不存在 + +### 请求体 + +```json +{ + //app name + "app": "mqtt", + "groups": [ + { + //driver name + "driver": "modbus1", + //group name + "group": "group1", + //optional, depends on plugins + "params": { + //when using the MQTT plugin, the topic key is the upload topoic + "topic": "/neuron/mqtt/modbus1/group1" + } + }, + { + "driver": "modbus2", + "group": "group2", + "params": { + "topic": "/neuron/mqtt/modbus2/group2" + } + } + ] +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 更新订阅参数 + +*PUT* /api/v2/subscribe + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 2106 group 不存在 + +### 请求体 + +```json +{ + //app name + "app": "mqtt", + //driver name + "driver": "modbus-tcp", + //driver node group name + "group": "group-1", + "params": { + //when using the MQTT plugin, the topic key is the upload topic + "topic": "/neuron/mqtt/group-1" + } +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 取消订阅 + +*DELETE* /api/v2/subscribe + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 2106 group 不存在 + +### 请求体 + +```json +{ + //app name + "app": "mqtt", + //driver name + "driver": "modbus-tcp", + //driver node group name + "group": "group-1", + //optional, when using the MQTT plugin, the topic field needs to be added + "params": { + "topic": "/neuron/mqtt/group-1" + } +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 获取订阅的 Group + +*GET* /api/v2/subscribe + +### 请求参数 + +**app** 必需 + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 +* 400 + +### 响应 + +```json +{ + "groups": [ + { + //driver name + "driver": "modbus-tcp", + //group name + "group": "group-1", + //optional, when using the MQTT plugin, the topic field needs to be added + "params": { + "topic": "/neuron/mqtt/group-1" + } + }, + { + //driver name + "driver": "modbus-tcp", + //group name + "group": "group-2", + //when using the MQTT plugin, the topic field needs to be added + "params": { + "topic": "/neuron/mqtt/group-2" + } + } + ] +} +``` + +## 获取版本信息 + +*GET* /api/v2/version + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 +* 500 + * 1001 服务器内部错误 + +### 响应 + +```json +{ + "build_date": "2022-06-01", + "revision": "99e2184+dirty", // dirty 表示有未提交的更改 + "version": "2.4.0" +} +``` + +## 上传 License + +*POST* /api/v2/license + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 + * 0 OK + * 2402 license 过期 +* 400 + * 2401 license 无效 +* 500 + * 1001 服务器内部错误 + +### 请求体 + +```json +{ + "license": "-----BEGIN CERTIFICATE-----\nMIID2TCCAsGgAwIBAgIEATSJqjA....." +} +``` + +### 响应 + +```json +{ + "error": 2401 +} +``` + +## 获取 License 信息 + +*GET* /api/v2/license + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 2400 license 未找到 +* 500 + * 1001 服务器内部错误 + +### 响应 + +```json +{ + "valid_until": "2023-03-15 08:11:19", + "valid_since": "2022-03-15 08:11:19", + "valid": false, + "max_nodes": 1, + "max_node_tags": 1, + "used_nodes": 12, + "used_tags": 846, + "license_type": "retail", + "error": 0, + "enabled_plugins": [ + "MODBUS TCP Advance", + "OPC UA" + ], + "hardware_token": "I+kZidSifiyVSbz0/EgcM6AcefnlfR4IU19ZZUnTS18=", + "object": "emq", + "email_address": "emq@emqx.io" +} +``` + +## 下载日志文件 + +*GET* /api/v2/logs + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 1011 文件不存在 + * 1014 执行指令失败 +* 500 + * 1001 内部错误 + +### 响应 + +如果有错误返回时响应： + +```json +{ + "error": 1014 +} +``` + +## 修改节点日志等级 + +*PUT* /api/v2/log/level + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 404 + * 2003 node 不存在 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 请求体 + +```json +{ + // node name + "node": "modbus-tcp" +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +:::tip +调用接口修改节点的日志等级为 debug，十分钟左右自动切回默认等级。 +::: + +## 下载文件 + +*GET* /api/v2/file + +### 请求头部 + +**Authorization** Bearer \ + +### 请求参数 + +**file_path** 必需，文件的绝对路径 + +### 响应状态 + +* 404 + * 1011 文件不存在 + * 4101 文件打开失败 + * 4102 文件读失败 + +### 响应 + +当正常响应时，返回文件内容并下载文件。 + +当错误响应时，返回对应的错误码。 + +```json +{ + "error": 1011 +} +``` + +## 获取文件列表 + +*GET* /api/v2/file/info + +### 请求头部 + +**Authorization** Bearer \ + +### 请求参数 + +**dir_path** 必需，目录的绝对路径 + +### 响应状态 + +* 404 + * 1011 文件不存在 + * 4101 文件打开失败 + +### 响应 + +当正确响应时，响应文件名称、文件大小、文件创建时间和文件更新时间。 + +```json +{ + "files": [ + { + "name": "neuron", + "size": 4096, + "ctime": "Wed Jan 4 02:38:12 2023", + "mtime": "Mon Dec 26 09:48:42 2022" + }, + { + "name": "test.txt", + "size": 13, + "ctime": "Wed Jan 4 02:38:12 2023", + "mtime": "Mon Dec 26 09:48:42 2022" + } + ] +} +``` + +当错误响应时，响应对应的错误码。 + +```json +{ + "error": 1011 +} +``` + +## 添加 Template + +*POST* /api/v2/template + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 206 + * 2203 tag 属性不支持 + * 2204 tag 类型不支持 + * 2205 tag 地址格式无效 + * 2206 tag 名字太长 + * 2207 tag 地址太长 + * 2208 tag 描述太长 + * 2209 tag 精度无效 +* 400 + * 2105 group 参数无效 + * 2107 group 名称太长 + * 2502 模板名字太长 + * 3013 插件名字太长 + * 3016 插件不支持模板 +* 404 + * 3014 插件不存在 +* 409 + * 2104 group 已存在 + * 2202 tag 名称冲突 + * 2500 模板已存在 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 请求体 + +```json +{ + "name": "rtu template", + "plugin": "Modbus RTU", + "groups": [ + { + "name": "group1", + "interval": 2000, + "tags": [ + { + "name": "tag1", + "type": 4, + "address": "1!400001", + "attribute": 1, + "precison": 1, + "decimal": 0 + }, + { + "name": "tag2", + "type": 11, + "address": "1!400009", + "attribute": 3 + } + ] + } + ] +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 删除 Template + +*DELETE* /api/v2/template + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 请求参数 + +**name** 可选，要删除的模板的名字。若未提供该参数，则删除所有模板。 + +### 响应状态 + +* 200 OK +* 404 + * 2501 模板不存在 +* 500 + * 1010 程序繁忙 + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 获取 Template + +*GET* /api/v2/template + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 请求参数 + +**name** 可选，要获取的 template 的名字。 + +### 响应状态 + +* 200 OK +* 400 + * 1003 请求 param 无效 +* 404 + * 2501 模板不存在 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 响应 + +未指定 **name** 参数时，则返回所有模板的列表。 + +```json +{ + "templates": [ + { + "name": "template1", + "plugin": "modbus tcp" + }, + { + "name": "template2", + "plugin": "opc ua" + } + ] +} +``` + +如果请求指定了 **name** 参数，则返回相应模板的详细信息。 + +```json +{ + "name": "rtu template", + "plugin": "Modbus RTU", + "groups": [ + { + "name": "group1", + "interval": 2000, + "tags": [ + { + "name": "tag1", + "type": 4, + "address": "1!400001", + "attribute": 1, + "precison": 1, + "decimal": 0 + }, + { + "name": "tag2", + "type": 11, + "address": "1!400009", + "attribute": 3 + } + ] + } + ] +} +``` + +## 实例化 Template + +*POST* /api/v2/template/inst + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 400 + * 2304 库打开失败 + * 2502 模板名字太长 +* 404 + * 2301 库未找到 + * 2501 模板不存在 +* 409 + * 2002 node 已存在 + * 2307 插件不允许实例化 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 请求体 + +```json +{ + "name": "rtu template", + "node": "modbus-rtu", +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 多节点实例化 Template + +*POST* /api/v2/template/instances + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 400 + * 2304 库打开失败 + * 2502 模板名字太长 +* 404 + * 2301 库未找到 + * 2501 模板不存在 +* 409 + * 2002 node 已存在 + * 2307 插件不允许实例化 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 请求体 + +```json +{ + "nodes": [ + { + "name": "rtu template", + "node": "node1" + }, + { + "name": "tcp template", + "node" "node2" + } + ] +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 添加 Template Group + +*POST* /api/v2/template/group + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 400 + * 2105 group 参数无效 + * 2107 group 名称太长 + * 2502 模板名字太长 +* 404 + * 2501 模板不存在 +* 409 + * 2104 group 已存在 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 请求体 + +```json +{ + "template": "modbus-template", + "group": "group1", + "interval": 10000 +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 删除 Template Group + +*DELETE* /api/v2/template/group + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 400 + * 2107 group 名称太长 + * 2502 模板名字太长 +* 404 + * 2106 group 不存在 + * 2501 模板不存在 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 请求体 + +```json +{ + "template": "modbus-template", + "group": "group1" +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 更新 Template Group + +*PUT* /api/v2/template/group + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + + +* 200 OK +* 400 + * 2105 group 参数无效 + * 2107 group 名称太长 + * 2502 模板名字太长 +* 404 + * 2106 group 不存在 + * 2501 模板不存在 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 请求体 + +更新 group name: +```json +{ + //template name + "template": "modbus-template", + //group name + "group": "gconfig1", + //group new name + "new_name": "group1" +} +``` + +更新 group interval: +```json +{ + //template name + "template": "modbus-template", + //group name + "group": "gconfig1", + //interval(ms) + "interval": 10000 +} +``` + +同时更新 group name 和 interval: +```json +{ + //template name + "template": "modbus-template", + //group name + "group": "gconfig1", + //group new name + "new_name": "group1", + //interval(ms) + "interval": 10000 +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 获取 Template Group + +*GET* /api/v2/template/group + +### 请求参数 + +**name** 必需，template 的名字。 + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 400 + * 1003 请求 param 无效 +* 404 + * 2501 模板不存在 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 响应 + +````json +{ + "groups": [ + { + "name": "group1", + "interval": 2000, + "tag_count": 2 + } + ] +} +```` + +## 添加 Template Tag + +*POST* /api/v2/template/tag + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 206 + * 2203 tag 属性不支持 + * 2204 tag 类型不支持 + * 2205 tag 地址格式无效 + * 2206 tag 名字太长 + * 2207 tag 地址太长 + * 2208 tag 描述太长 + * 2209 tag 精度无效 +* 400 + * 2107 group 名称太长 + * 2502 模板名字太长 +* 404 + * 2106 group 不存在 + * 2501 模板不存在 +* 409 + * 2202 tag 名称冲突 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 请求体 + +```json +{ + "template": "modbus-template", + "group": "group1", + "tags": [ + { + "name": "tag1", + "address": "1!400001", + "attribute": 8, + "type": 4, + "precision": 0, + "decimal": 0, + "description": "", + "value": 12 + }, + { + "name": "tag2", + "address": "1!00001", + "attribute": 3, + "type": 3, + "decimal": 0.01 + } + ] +} +``` + +### 响应 + +```json +{ + "index": 2, + "error": 0 +} +``` + +## 更新 Template Tag + +*PUT* /api/v2/template/tag + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 206 + * 2201 tag 不存在 + * 2203 tag 属性不支持 + * 2204 tag 类型不支持 + * 2205 tag 地址格式无效 + * 2206 tag 名字太长 + * 2207 tag 地址太长 + * 2208 tag 描述太长 + * 2209 tag 精度无效 +* 400 + * 2107 group 名称太长 + * 2502 模板名字太长 +* 404 + * 2106 group 不存在 + * 2501 模板不存在 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 请求体 + +```json +{ + "template": "modbus-template", + "group": "group1", + "tags": [ + { + "name": "tag1", + "address": "1!400001", + "attribute": 8, + "type": 4, + "precision": 0, + "decimal": 0, + "description": "", + "value": 12 + }, + { + "name": "tag2", + "address": "1!00001", + "attribute": 3, + "type": 3, + "decimal": 0.01 + } + ] +} +``` + +### 响应 + +```json +{ + "index": 2, + "error": 0 +} +``` + +## 删除 Template Tag + +*DELETE* /api/v2/template/tag + +### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 206 + * 2206 tag 名字太长 +* 400 + * 2107 group 名称太长 + * 2502 模板名字太长 +* 404 + * 2106 group 不存在 + * 2501 模板不存在 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + +### 请求体 + +```json +{ + "template": "modbus-template", + "group": "group1", + "tags": [ + "tag1", + "tag2" + ] +} +``` + +### 响应 + +```json +{ + "error": 0 +} +``` + +## 获取 Template Tag + +*GET* /api/v2/template/tag + +### 请求参数 + +**template** 必需，template 的名字。 + +**group** 必需，group 的名字。 + +**name** 可选，用于过滤 tag 名字。 + +### 请求头部 + +**Authorization** Bearer \ + +### 响应状态 + +* 200 OK +* 400 + * 1003 请求 param 无效 +* 404 + * 2106 group 不存在 + * 2501 模板不存在 +* 500 + * 1001 内部错误 + * 1010 程序繁忙 + + +### 响应 + +```json +{ + "tags": [ + { + "name": "tag1", + "type": 4, + "address": "1!400001", + "attribute": 8, + "description": "", + "precision": 0, + "decimal": 0, + "value": 12 + }, + { + "name": "tag2", + "type": 14, + "address": "1!00001", + "attribute": 3, + "description": "", + "precison": 0, + "decimal": 0, + } + ] +} +``` diff --git a/neuronex/zh_CN/api/data-type.md b/neuronex/zh_CN/api/data-type.md new file mode 100644 index 0000000..8920ecd --- /dev/null +++ b/neuronex/zh_CN/api/data-type.md @@ -0,0 +1,114 @@ +# 数据类型 + +## 概念解析 + +### Node 节点 + +在 Neuron 中每个节点都可以与一台设备或一个北向应用建立连接。 +* 在设备节点中，可以添加和管理设备点位。 +* 在北向节点中，可以选择需要订阅的数据组。 + +### Group 组 + +每个节点底下都可以创建多个数据组，对点位进行分类。例如，一台设备连接多个温度传感器和多个湿度传感器，可以创建温度和湿度两个数据组对采集的点位进行分类。Neuron 按组为单位，将采集数据上传到北向应用。 +### Tag 点位 + +在每个组底下可以创建多个采集点位，例如，一台温度传感器采集多个温度值，一个温度值作为一个点位。 + +### Plugin 插件 + +在 Neuron 中，每个插件对应一种协议的实现。例如，一种 modbus tcp 协议对应一个插件，mqtt 协议对应一个插件。 + +## 数据类型 + +* INT8 = 1 +* UINT8 = 2 +* INT16 = 3 +* UINT16 = 4 +* INT32 = 5 +* UINT32 = 6 +* INT64 = 7 +* UINT64 = 8 +* FLOAT = 9 +* DOUBLE = 10 +* BIT = 11 +* BOOL = 12 +* STRING = 13 +* BYTES = 14 +* ERROR = 15 +* WORD = 16 +* DWORD = 17 +* LWORD = 18 + +## 串口 + +### 波特率 + +* 115200 = 0 +* 57600 = 1 +* 38400 = 2 +* 19200 = 3 +* 9600 = 4 +* 4800 = 5 +* 2400 = 6 +* 1800 = 7 +* 1200 = 8 +* 600 = 9 + +### 校验位 + +* NONE = 0 +* ODD = 1 +* EVEN = 2 +* MARK = 3 +* SPACE = 4 + +### 停止位 + +* Stop_1 = 0 +* Stop_2 = 1 + +### 数据位 + +* Data_5 = 0 +* Data_6 = 1 +* Data_7 = 2 +* Data_8 = 3 + +## 点位属性 + +* READ = 0x01 + +* WRITE = 0x02 + +* SUBSCRIBE = 0x04 + +## Node 节点 + +### Node 类型 + +* DRIVER = 1 +* APP = 2 + +### Node 控制 + +* START = 0 +* STOP = 1 + +### Node 状态 + +* INIT = 1 +* READY = 2 +* RUNNING = 3 +* STOPPED = 4 + +### Node 连接状态 + +* DISCONNECTED = 0 +* CONNECTED = 1 + +## 插件类型 + +* STATIC = 0 +* SYSTEM = 1 +* CUSTOM = 2 diff --git a/neuronex/zh_CN/api/error-code.md b/neuronex/zh_CN/api/error-code.md new file mode 100644 index 0000000..e805055 --- /dev/null +++ b/neuronex/zh_CN/api/error-code.md @@ -0,0 +1,183 @@ +# 错误代码 + +本文档描述了 Neuron 在调用 http api 和 mqtt api 时会响应的错误码。 + +## api 请求错误代码 + +* 1000 通用错误 + +* 1001 内部错误 + +* 1002 请求 body 无效 +* 1003 请求 param 无效 +* 1004 缺少令牌 +* 1005 解码令牌错误 +* 1006 令牌过期 +* 1007 验证令牌错误 +* 1008 无效令牌 +* 1009 用户名或密码错误 +* 1010 程序繁忙 +* 1011 文件不存在 +* 1012 密码长度太短或太长 +* 1013 密码重复 +* 1014 执行指令失败 +* 1015 ip 地址无效 +* 1016 ip 地址已占用 +* 1017 用户名无效 +* 1018 密码无效 + +## 添加/删除/更新 node/tag/plugin/group 错误代码 + +* 2002 node 已存在 +* 2003 node 不存在 +* 2004 node 设置无效 +* 2005 node 设置未找到 +* 2006 node 未准备好 +* 2007 node 正在运行 +* 2008 node 未运行 +* 2009 node 已停止 +* 2010 node 名称太长 +* 2011 node 不允许删除 +* 2012 node 不允许订阅 +* 2013 node 不允许更新 +* 2014 node 不支持图 +* 2015 node 名称不允许为空 + +* 2101 group 已经被订阅 +* 2102 group 未被订阅 +* 2103 group 不允许 +* 2104 group 已存在 +* 2105 group 参数无效 +* 2106 group 不存在 +* 2107 group 名称太长 + +* 2201 tag 不存在 +* 2202 tag 名称冲突 +* 2203 tag 属性不支持 +* 2204 tag 类型不支持 +* 2205 tag 地址格式无效 +* 2206 tag 名字太长 +* 2207 tag 地址太长 +* 2208 tag 描述太长 +* 2209 tag 精度无效 +* 2210 tag 已存在 + +* 2301 库未找到 +* 2302 库信息无效 +* 2303 库名称冲突 +* 2304 库打开失败 +* 2305 库模块无效 +* 2306 系统库不允许删除 +* 2307 插件不允许实例化 +* 2308 插件不支持此架构 + +* 2400 license 未找到 +* 2401 license 无效 +* 2402 license 过期 +* 2403 license 未启用插件 +* 2404 达到 license 授权的最大节点数 +* 2405 达到 license 授权的最大点位数 +* 2406 license 硬件不匹配 +* 2407 license 检测到时钟异常 +* 2408 license 模块无效 + +* 2500 模板已存在 +* 2501 模板不存在 +* 2502 模板名字太长 + +## 插件常见的错误代码 + +* 3000 插件读失败 +* 3001 插件写失败 +* 3002 插件未连接 +* 3003 插件 tag 不允许读 +* 3004 插件 tag 不允许写 +* 3007 插件 tag 类型不匹配 +* 3008 插件 tag 值失效 +* 3009 插件协议解析失败 +* 3010 插件未运行 +* 3011 插件 tag 未就绪 +* 3012 插件报文乱序 +* 3013 插件名字太长 +* 3014 插件不存在 +* 3015 插件设备未响应 +* 3016 插件不支持模板 +* 3017 插件不支持写点位 + +## FILE 错误码 + +* 4100 字符串太长 +* 4101 打开文件失败 +* 4102 读文件失败 +* 4103 写文件失败 + +## OPCUA 错误码 + +* 10001 opcua tag 不存在 +* 10002 opcua 连接配置错误 +* 10003 opcua 访问超时 +* 10004 opcua tag 不可读 +* 10005 opcua tag 不可写 +* 10006 opcua tag 不支持 + +## S7COMM 错误码 + +* 10101 硬件错误 +* 10103 对象无访问权限 +* 10105 无效地址 +* 10106 数据类型不支持 +* 10107 数据类型不一致 +* 10110 对象不存在 +* 10150 COTP 连接断开 +* 10151 S7 连接断开 +* 10152 没有值 +* 10153 值长度太短 + +## KNX 错误码 + +* 10200 设备不存在 + +## NONA11 错误码 + +* 10400 无效地址 + +## FINS 错误码 + +* 10500 fins 连接断开 +* 10501 fins 错误 +* 10502 本地节点错误 +* 10503 目标节点错误 +* 10504 控制器错误 +* 10505 服务不受支持 +* 10506 路由表错误 +* 10507 命令格式错误 +* 10508 参数错误 +* 10509 无法读取 +* 10510 无法写入 +* 10511 当前模式不可执行 +* 10512 单元不存在 +* 10513 无法启动/停止 +* 10514 单元错误 +* 10515 命令错误 +* 10516 访问权限错误 +* 10517 中止 + +## FOCAS 错误码 + +* 10600 focas 错误 + +## EtherNet/IP 错误码 + +* 10701 - 10744 EtherNet/IP 错误 +* 10797 EtherNet/IP 没有 CIP 连接 +* 10798 EtherNet/IP 数据类型不匹配 +* 10799 EtherNet/IP 未注册 session + +## Profinet IO 错误码 + +* 10800 Profinet IO 未识别 +* 10801 Profinet IO 未连接 +* 10802 Profinet IO 未准备好 +* 10803 Profinet IO 参数未准备好 +* 10804 Profinet IO 没有写入权限 +* 10805 Profinet IO 等待 HELLO 响应 \ No newline at end of file diff --git a/neuronex/zh_CN/api/jwt.md b/neuronex/zh_CN/api/jwt.md new file mode 100644 index 0000000..c4e5581 --- /dev/null +++ b/neuronex/zh_CN/api/jwt.md @@ -0,0 +1,66 @@ +# 自定义 JWT + +在 Neuron 中调用 API 时，需先调用登录接口生成 JWT，再调用其他接口进行 JWT 验证。默认生成的 JWT 过期时间为一小时，可以自己生成 JWT，自定义过期时间。 + +## 什么是 JWT？ + +JWT 是一种用于安全传输信息的开放标准（RFC 7519）。JWT 结构包含三个部分，分别是头部（Header）、载荷（Payload）和签名（Signature）。 + +Neuron 先根据 **iss** 字段查找 neuron 安装目录下的子目录 **certs** 是否包含该名称对应的 .pem 或 .pub 文件，再根据里面的字段进行校验。Neuron 中所需要的 JWT 结构如下： + +```json +header +{ + "alg": "RS256", + "typ": "JWT" +} + +payload +{ + "iss": "username", + "iat": "1679622798", + "exp": "1679626398", + "aud": "neuron", + "bodyEncode": "0" +} +``` + +### 头部 + +* 令牌类型（typ）：使用 JWT +* 使用的算法（alg）：使用 RS256 + +### 载荷 + +* 签发者（iss）：根据需求自己定义，但要确保与生成的公钥文件名称一致。例如，iss 为 neuron，则需要生成 neuron.pem 的公钥文件。 +* 签发时间（iat）：签发时间 +* 过期时间（exp）：签发过期时间 +* 受众（aud）：neuron，不能修改 + +## 生成公私钥 + +签发 JWT 前需要生成一对公私钥，并把生成的公钥 public.pem 放在 Neuron 安装目录下的子目录 **certs** 中。Neuron 自动加载 **certs** 中的文件，根据公钥解码。 + +:::tip +Docker 以及 deb/rpm 安装包的默认安装路径为 `/opt/neuron`。 + +公钥文件名称必须要与 JWT 中的签发者保持一致。 +::: + +使用 OpenSSL 命令行工具生成 RSA 密钥： + +```bash +# 生成私钥 +$ openssl genrsa -out private.key 2048 +# 生成公钥 +$ openssl rsa -in private.key -out public.pem -pubout +``` + +## 如何生成 JWT？ + +使用 [JWT 官网](https://jwt.io/)工具生成。在 Decoded 中填写： + +* Algorithm：RS256 +* Header：头部 +* Payload：载荷 +* Verify Signature：填写公私钥 `-----BEGIN PUBLIC KEY-----` 和 `-----BEGIN RSA PRIVATE KEY-----`。 \ No newline at end of file diff --git a/neuronex/zh_CN/api/metrics.md b/neuronex/zh_CN/api/metrics.md new file mode 100644 index 0000000..b90b739 --- /dev/null +++ b/neuronex/zh_CN/api/metrics.md @@ -0,0 +1,88 @@ +# 统计信息 + +这个 API 由 [Monitor 插件]实现，提供兼容 [Prometheus] 的统计数据。 + +[Prometheus]: https://prometheus.io/ +[Monitor 插件]: ../configuration/north-apps/monitor/overview.md + +## 获取统计信息 + +*GET* /api/v2/metrics + +### 请求头部 + +**Authorization** Bearer \ + +### 请求参数 + +**category** 可选, 取值为 `global`, `driver` 或 `app` 之一 + +**node** 可选, 用节点名过滤, 且必须指定 `category=driver` 或 `category=app` + +### 响应状态 + +* 200 OK +* 400 请求错误 +* 500 服务器内部错误 + +### 响应 + +```text +# HELP core_dumped Whether there is any core dump +# TYPE core_dumped gauge +core_dumped 0 +# HELP uptime_seconds Uptime in seconds +# TYPE uptime_seconds counter +uptime_seconds 314 +# HELP north_nodes_total Number of north nodes +# TYPE north_nodes_total gauge +north_nodes_total 1 +# HELP north_running_nodes_total Number of north nodes in running state +# TYPE north_running_nodes_total gauge +north_running_nodes_total 1 +# HELP north_disconnected_nodes_total Number of north nodes disconnected +# TYPE north_disconnected_nodes_total gauge +north_disconnected_nodes_total 1 +# HELP south_nodes_total Number of south nodes +# TYPE south_nodes_total gauge +south_nodes_total 1 +# HELP south_running_nodes_total Number of south nodes in running state +# TYPE south_running_nodes_total gauge +south_running_nodes_total 0 +# HELP south_disconnected_nodes_total Number of south nodes disconnected +# TYPE south_disconnected_nodes_total gauge +south_disconnected_nodes_total 1 +# HELP send_msgs_total Total number of messages sent +# TYPE send_msgs_total counter +send_msgs_total{node="data-stream-processing"} 0 +# HELP send_msg_errors_total Total number of errors sending messages +# TYPE send_msg_errors_total counter +send_msg_errors_total{node="data-stream-processing"} 0 +# HELP recv_msgs_total Total number of messages received +# TYPE recv_msgs_total counter +recv_msgs_total{node="data-stream-processing"} 0 +# HELP last_rtt_ms Last request round trip time in milliseconds +# TYPE last_rtt_ms gauge +last_rtt_ms{node="modbus"} 9999 +# HELP send_bytes Total number of bytes sent +# TYPE send_bytes gauge +send_bytes{node="modbus"} 0 +# HELP recv_bytes Total number of bytes received +# TYPE recv_bytes gauge +recv_bytes{node="modbus"} 0 +# HELP tag_reads_total Total number of tag reads including errors +# TYPE tag_reads_total counter +tag_reads_total{node="modbus"} 0 +# HELP tag_read_errors_total Total number of tag read errors +# TYPE tag_read_errors_total counter +tag_read_errors_total{node="modbus"} 0 +# HELP group_tags_total Total number of tags in the group +# TYPE group_tags_total gauge +group_tags_total{node="modbus",group="grp"} 1 +# HELP group_last_send_msgs Number of messages sent on last group timer invocation +# TYPE group_last_send_msgs gauge +group_last_send_msgs{node="modbus",group="grp"} 0 +# HELP group_last_timer_ms Time in milliseconds consumed on last group timer invocation +# TYPE group_last_timer_ms gauge +group_last_timer_ms{node="modbus",group="grp"} 0 +``` diff --git a/neuronex/zh_CN/api/plugin-setting.md b/neuronex/zh_CN/api/plugin-setting.md new file mode 100644 index 0000000..6f4dbe2 --- /dev/null +++ b/neuronex/zh_CN/api/plugin-setting.md @@ -0,0 +1,338 @@ +# 插件设置 + +## MQTT + +```json +{ + "node": "", + "params": { + // required, subscription data reporting channel + "upload-topic": "", + // required, the json format selection of the reported data, 0 values (default), 1 tags + "format": 1, + // required, the size limit of memory cache + "cache-mem-size": 0, + // required, the size limit of disk cache + "cache-disk-size": 0, + + // required, MQTT Broker host + "host": "", + // required, MQTT Broker port number + "port": 1883, + // optional, username to use when connecting to the broker + "username": "", + // optional, the password to use when connecting to the broker + "password": "", + + // optional, whether to enable mqtt ssl + "ssl": true, + // ca file, only enabled when the ssl value is true, in which case it is required + "ca": "", + // optional, cert file, only enabled when the ssl value is true + "cert": "", + // optional, key file, only enabled when the ssl value is true + "key": "", + // optional, key file password, only enabled when the ssl value is true + "keypass": "" + } +} + +``` + +## Modbus + +### Modbus TCP QH + +```json +{ + "node": "modbus-tcp", + "params": { + // required, the ip of the remote device + "host": "127.0.0.1", + // required, the tcp port of the remote device + "port": 502, + // required, timeout for sending requests to the device + "timeout": 3000, + // required, 0 the neuron driver is used as the client, 1 the neuron driver is used as the server + "connection_mode": 0 + } +} +``` + +### Modbus TCP + +```json +{ + "node": "modbus-tcp", + "params": { + // required, 0 the neuron driver is used as the client, 1 the neuron driver is used as the server + "connection_mode": 0, + // required, client: host means the ip of the remote device. server: it means the ip used by neuron locally + "host": "127.0.0.1", + // required, client: port means the tcp port of the remote device. server: it means the tcp port used by neuron locally + "port": 502, + // required, timeout for sending requests to the device + "timeout": 3000, + // required, send reading instruction interval(ms) + "interval": 20, + // required, TCP transfer(0) or UDP transfer(1) + "transport_mode": 0, + // required, the maximum number of retries after a failed attempt to send a read command + "max_retries": 0, + // required, resend reading instruction interval(ms) after a failed attempt to send a read command + "retry_interval": 0 + } +} +``` + +### Modbus RTU + +#### 串口连接设置 + +```json +{ + "node": "modbus-rtu", + "params": { + // required, connection method, 0 serial port, 1 tcp, + "link": 0, + // required, timeout for sending requests to the device + "timeout": 3000, + // serial port required, use a serial device + "device": "dev/ttyUSB0", + // serial port required, stopbits + "stop": 0, + // serial port required, parity bit + "parity": 0, + // serial port required, baudrate + "baud": 4, + // serial port required, bytesize + "data": 3 + } +} +``` + +#### TCP 连接设置 + +```json +{ + "node": "modbus-rtu", + "params": { + // required, connection method, 0 serial port, 1 tcp, + "link": 1, + // required, timeout for sending requests to the device + "timeout": 3000, + // tcp required, client: host means the ip of the remote device. server: it means the ip used by neuron locally + "host": "127.0.0.1", + // tcp required, client: port means the tcp port of the remote device. server: it means the tcp port used by neuron locally + "port": 502, + // tcp required, 0 the neuron driver is used as the client, 1 the neuron driver is used as the server + "connection_mode": 0, + // required, send reading instruction interval(ms) + "interval": 20, + // required, the maximum number of retries after a failed attempt to send a read command + "max_retries": 0, + // required, resend reading instruction interval(ms) after a failed attempt to send a read command + "retry_interval": 0 + } +} +``` + +## OPC UA + +```json +{ + "node": "opc ua", + "params": { + // required, the address of the remote access plc + "url": "opc.tcp://127.0.0.1:4840/", + // optional, the user used when connecting to plc + "username": "", + // optional, the password used when connecting to plc + "password": "", + // optional, the certificate to provide login user authentication + "cert": "", + // optional, the private key to provide signature and encrypted transmissions + "key": "" + } +} +``` + +## Simemens S7 ISOTCP + +```json +{ + "node": "s7", + "params": { + // required, remote plc ip + "host": "127.0.0.1", + // required, remote plc port + "port": 102, + // required, plc rack number + "rack": 0, + // required, plc cpu slot + "slot": 1 + } +} +``` + +## OMRON FINS on TCP + +```json +{ + "node": "fins", + "params": { + // required, remote plc ip + "host": "127.0.0.1", + // required, remote plc port + "port": 9600 + } +} +``` + +## Mitsubishi MELSEC-Q E71 + +```json +{ + "node": "e71", + "params": { + // required, remote plc ip + "host": "127.0.0.1", + // required, remote plc port + "port": 2000 + } +} +``` + +## IEC 60870-5-104 + +```json +{ + "node": "iec104", + "params": { + // required, device ip + "host": "127.0.0.1", + // required, device port + "port": 2404, + // required, common address + "ca": 1, + // required, station interrogation interval + "interval": 10 + } +} +``` + +## BACnet/IP + +```json +{ + "node": "bacnet", + "params": { + // required, BACnet device ip + "host": "127.0.0.1", + // required, BACnet device port + "port": 47808 + } +} +``` + +## DL/T645-2007 + +### 串口连接设置 + +```json +{ + "node": "dlt645-1", + "params": { + // required, connection method, 0 serial port, 1 tcp + "link": 0, + // required, contact address + "mail_address": 210220003011, + // required, timeout for sending requests to the device + "timeout": 3000, + // serial port required, use a serial device + "device": "dev/ttyUSB0", + // serial port required, stopbits + "stop": 0, + // serial port required, parity bit + "parity": 2, + // serial port required, baudrate + "baud": 4, + // serial port required, bytesize + "data": 3 + } +} +``` + +### TCP 连接设置 + +```json +{ + "node": "dlt645-1", + "params": { + // required, connection method, 0 serial port, 1 tcp + "link": 1, + // required, contact address + "mail_address": 210220003011, + // required, timeout for sending requests to the device + "timeout": 3000, + // tcp required, client: host means the ip of the remote device. server: it means the ip used by neuron locally + "host": "127.0.0.1", + // tcp required, client: port means the tcp port of the remote device. server: it means the tcp port used by neuron locally + "port": 502, + // tcp required, 0 the neuron driver is used as the client, 1 the neuron driver is used as the server + "connection_mode": 0 + } +} +``` + +## Sparkplug_B + +```json +{ + "node": "sparkplugb", + "params": { + // required, MQTT client ID, A unique identifier that can represent the edge end + "client-id": "saprk-test", + // required, the top-level logical group in Sparkplug_B + "group-id": "test", + // required, the egde node id + "node-id": "neuron1" + // required, whether to enable mqtt ssl, + "ssl": false, + // required, MQTT Broker host + "host": "broker.emqx.io", + // required, MQTT Broker port number + "port": 1883, + // optional, username to use when connecting to the broker + "username": "", + // optional, the password to use when connecting to the broker + "password": "", + // required, ca file, only enabled when the ssl value is true + "ca": "", + // optional, cert file, only enabled when the ssl value is true + "cert": "", + // optional, key file, only enabled when the ssl value is true + "key": "", + // optional, key file password, only enabled when the ssl value is true + "keypass": "" + } +} +``` + +## NON A11 + +```json +{ + "node": "nona11", + "params": { + // required, 0 the neuron driver is used as the client, 1 the neuron driver is used as the server + "connection_mode": 0, + // required, client: port means the tcp port of the remote device. server: it means the tcp port used by neuron locally + "host": "127.0.0.1", + // required, client: port means the tcp port of the remote device. server: it means the tcp port used by neuron locally + "port": 10, + // required, NON-A11 device site number + "site": 1 + } +} +``` diff --git a/neuronex/zh_CN/api/rw.md b/neuronex/zh_CN/api/rw.md new file mode 100644 index 0000000..5d45122 --- /dev/null +++ b/neuronex/zh_CN/api/rw.md @@ -0,0 +1,142 @@ +# 读写 + +## 读 Tag + +*POST* /api/v2/read + +### 请求头部 + +**Content--Type** application/json + +**Authorization** Bearer \ + +### 响应状态 + +* 200 + +### 请求体 + +```json +{ + //node name + "node": "modbus-tcp-1", + //group name + "group": "config_modbus_tcp_sample_2" +} +``` + +### 响应 + +```json +{ + "tags": [ + { + //tag nmae + "name": "data1", + //tag value + "value": 1, + }, + { + "name": "data2", + "error": 2014 + }, + { + "name": "data3", + "value": true, + } + ] +} +``` + +::: tip +当某个点位读数值出错时，将显示 **error** 字段，不再显示 **value** 字段。 +::: + +## 写 Tag + +### 写一个 Tag + +*POST* /api/v2/write + +#### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +#### 响应状态 + +* 200 OK + +#### 请求体 + +```json +{ + "node": "modbus-tcp-1", + "group": "config_modbus_tcp_sample_2", + "tag": "tag1", + "value": 1234 +} +``` + +#### 响应 + +```json +{ + "error": 0 +} +``` + +### 写多个 Tag + +*POST* /api/v2/write/tags + +#### 请求头部 + +**Content-Type** application/json + +**Authorization** Bearer \ + +#### 响应状态 + +* 200 OK + +#### 请求体 + +```json +{ + "node": "modbus-tcp-1", + "group": "group1", + "tags": [ + + { + "tag": "tag1", + "value": 123 + }, + { + "tag": "tag2", + "value": 1233 + }, + { + "tag": "tag3", + "value": 7788 + }, + { + "tag": "tag4", + "value": 1 + }, + { + "tag": "tag5", + "value": "asdfda" + } + ] +} +``` + +#### 响应 + +```json +{ + "error": 0 +} +``` \ No newline at end of file diff --git a/neuronex/zh_CN/config/south-devices/file/file.md b/neuronex/zh_CN/config/south-devices/file/file.md deleted file mode 100644 index a7cf5d0..0000000 --- a/neuronex/zh_CN/config/south-devices/file/file.md +++ /dev/null @@ -1,33 +0,0 @@ -# File - -## 模块描述 - -File 插件用于读写文件。 - -## 插件配置 - -| 字段 | 说明 | -| ----------- | --------------------- | -| 文件最大长度（file_length） | 设置读写文件内容的字符长度 | - -## 点位配置 - -### 支持的数据类型 - -* STRING - -### 地址 - -FILE PATH - -#### 地址示例 - -| 地址 | 数据类型 | 说明 | -| ------------------------ | ------ | ------------------------ | -| /home/root/test/test.txt | string | 读写 test.txt 文件中的内容 | - -::: tip -地址需填写文件的绝对路径。 - -写操作时，写入的内容将会覆盖之前的文件内容。 -::: diff --git a/neuronex/zh_CN/config/templates/assets/template_add_device.png b/neuronex/zh_CN/config/templates/assets/template_add_device.png new file mode 100644 index 0000000..495d559 Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_add_device.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_add_dialog.png b/neuronex/zh_CN/config/templates/assets/template_add_dialog.png new file mode 100644 index 0000000..defdbaa Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_add_dialog.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_add_group.png b/neuronex/zh_CN/config/templates/assets/template_add_group.png new file mode 100644 index 0000000..5e8837b Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_add_group.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_add_tag.png b/neuronex/zh_CN/config/templates/assets/template_add_tag.png new file mode 100644 index 0000000..b00629f Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_add_tag.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_device_group.png b/neuronex/zh_CN/config/templates/assets/template_device_group.png new file mode 100644 index 0000000..cf293f3 Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_device_group.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_device_list.png b/neuronex/zh_CN/config/templates/assets/template_device_list.png new file mode 100644 index 0000000..910f9c4 Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_device_list.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_device_setting.png b/neuronex/zh_CN/config/templates/assets/template_device_setting.png new file mode 100644 index 0000000..1cc1e5d Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_device_setting.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_device_tag.png b/neuronex/zh_CN/config/templates/assets/template_device_tag.png new file mode 100644 index 0000000..36da5ca Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_device_tag.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_export.png b/neuronex/zh_CN/config/templates/assets/template_export.png new file mode 100644 index 0000000..5773566 Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_export.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_group_list.png b/neuronex/zh_CN/config/templates/assets/template_group_list.png new file mode 100644 index 0000000..ccdb13b Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_group_list.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_import_1.png b/neuronex/zh_CN/config/templates/assets/template_import_1.png new file mode 100644 index 0000000..ef3e119 Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_import_1.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_import_2.png b/neuronex/zh_CN/config/templates/assets/template_import_2.png new file mode 100644 index 0000000..f2e2197 Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_import_2.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_import_result.png b/neuronex/zh_CN/config/templates/assets/template_import_result.png new file mode 100644 index 0000000..3cd6d64 Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_import_result.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_list.png b/neuronex/zh_CN/config/templates/assets/template_list.png new file mode 100644 index 0000000..18ee52c Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_list.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_tag_list_1.png b/neuronex/zh_CN/config/templates/assets/template_tag_list_1.png new file mode 100644 index 0000000..e6aae6b Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_tag_list_1.png differ diff --git a/neuronex/zh_CN/config/templates/assets/template_tag_list_2.png b/neuronex/zh_CN/config/templates/assets/template_tag_list_2.png new file mode 100644 index 0000000..2c89c5c Binary files /dev/null and b/neuronex/zh_CN/config/templates/assets/template_tag_list_2.png differ diff --git a/neuronex/zh_CN/config/templates/templates.md b/neuronex/zh_CN/config/templates/templates.md new file mode 100644 index 0000000..6338755 --- /dev/null +++ b/neuronex/zh_CN/config/templates/templates.md @@ -0,0 +1,103 @@ +# 基于模板配置 + +实际使用场景中， Neuron 用户经常需要创建大量配置相似的节点。 +这是个耗时且容易出现错误的过程，特别是在大规模部署中。 +为了简化这个过程， Neuron **2.5.0** 版本引入了模板功能。 + +Neuron 的模板功能允许用户创建带有指定插件和配置（包括组和标签）的模板。 +然后，用户可以以该模板为基础创建新节点。 +通过使用模板，用户可以快速、轻松地创建具有相似配置的新节点，从而节省时间和精力。 + +::: tip +Neuron 2.5.0 版本模板功能只支持南向插件。 +::: + +## 创建模板 + +### 添加模板 + +点击**配置 -> 模板管理 -> 添加模板**打开**添加模板**对话框。 + + ![Add template dialog](./assets/template_add_dialog.png) + +填写模板名称并选择插件，然后点击**创建**按钮。 +创建成功后就可以在**模板管理**标签页看到新建的模板。 + + ![Add template result](./assets/template_list.png) + +### 添加模板数据组 + +至此，模板中还没有配置数据。 +点击新建的模板打开**组列表**页面。 + + ![Add template group](./assets/template_add_group.png) + +为模板添加数据组的操作流程基本与[配置采集数据组和点位](../south-devices/south-devices.md#设置组和点位)中的相同。 +此处我们添加一个名为 *grp* 的数据组，时间间隔为 *3000* 。 + + ![Template group list](./assets/template_group_list.png) + +### 添加模板数据点 + +点击新建的 *grp* 数据组进入**点位列表**页面。 + + ![Add template tag](./assets/template_tag_list_1.png) + +点击**创建**按钮进入**添加点位**页面。 + + ![Add template tag](./assets/template_add_tag.png) + +简单起见，这里我们只添加两个数据点。 +点击**创建**按钮提交点位数据，如**点位列表**页面所示。 + + ![Template tag list](./assets/template_tag_list_2.png) + + +## 基于模版新增设备 + +点击**配置 -> 南向设备 -> 添加设备**打开**新增设备**对话框。 + + ![Template instantiation](./assets/template_add_device.png) + +填写设备名称，然后选择**模板**模式和之前创建的模板。 +点击**创建**按钮进入**设备配置**页面。 + + ![Template device setting](./assets/template_device_setting.png) + +填写配置项然后点击**提交**。 +如果操作成功，**南向设备**标签页会显示新增的南向设备。 + + ![Template device](./assets/template_device_list.png) + +点击创建完成的南向设备进入**组列表**页面。 +该南向设备与实例化的模板一样有一个名为 *grp* 的数据组，时间间隔为 *3000* 。 + + ![Template device group](./assets/template_device_group.png) + +点击 *grp* 数据组，进入**点位列表**页面。可以看到列表中有两个点位，与模板一样。 + + ![Template device tag](./assets/template_device_tag.png) + + +## 导出与导入模板 + +### 导出模板 + +在**模板**标签页，点击想要导出的模板上的**导出**按钮，就可将模板导出为 JSON 文件。 + + ![Template export](./assets/template_export.png) + +### 导入模板 + +在**模板**标签页，点击**导入模板**，提供想要导入的 JSON 文件。 + + ![Template import](./assets/template_import_1.png) + +在**导入模板**对话框中，用户可以修改模板名字。 +点击**创建**按钮完成导入操作。 + + ![Template import](./assets/template_import_2.png) + +在**模板标签页**中可以看到导入成功的模板。 + + ![Template import result](./assets/template_import_result.png) diff --git a/neuronex/zh_CN/intro/architecture.md b/neuronex/zh_CN/intro/architecture.md new file mode 100644 index 0000000..465aa3c --- /dev/null +++ b/neuronex/zh_CN/intro/architecture.md @@ -0,0 +1 @@ +# 架构 \ No newline at end of file diff --git a/neuronex/zh_CN/intro/license-policy.md b/neuronex/zh_CN/intro/license-policy.md new file mode 100644 index 0000000..dde4158 --- /dev/null +++ b/neuronex/zh_CN/intro/license-policy.md @@ -0,0 +1,27 @@ +# 许可证政策 + +Neuron 是一个开源项目。我们鼓励我们的社区开发自己的插件模块。 + +核心架构，仪表板和一些驱动模块（例如 modbus-tcp，mqtt 和 eKuiper 等）是在 LGPLv3 许可下开源的。您无需安装 EMQ 许可证即可运行这些开源模块。 + +对于商业模块，Neuron 提供了 30 个点（30 个连接和 30 个数据标签）的免费额度。您可在不安装 EMQ 许可证的情况下，运行这些商业模块。超出免费额度后，则必须安装有效的试用版或官方 EMQ 许可证。 + +:::tip 注意 + +Fanuc Focas Ethernet 和 Mitsubishi CNC 插件不在 30 点永久免费的范围内。如希望体验，可直接 [联系我们](https://www.emqx.com/zh/contact?product=neuron)。 + +::: + +## 申请许可证 + +试用的 EMQ 许可证可从[ EMQ 官方网站](https://www.emqx.com/zh/apply-licenses/neuron)上下载 。所有可用的模块都可以在 100 个连接和 1000 个数据标签的限制下试用 15 天。 如果试用 EMQ 许可证过期，您可以通过我们的官网重新申请试用 EMQ 许可证。 但是，一个邮箱最多只能申请两次试用许可证。 + +:::tip +官网申请试用许可证时，必须使用硬件标识进行设备的绑定。您可直接[联系我们](https://www.emqx.com/zh/contact?product=neuron)申请不需要硬件标识绑定设备的许可证，或申请正式许可证。 +::: + +## 管理许可证 + +申请许可证后，您可在登录 Neuron 后，点击页面顶部工具栏的 系统信息 -> License 上传许可证，或管理许可证文件。 + +![image-20230717142817902](./assets/license.png) \ No newline at end of file diff --git a/neuronex/zh_CN/management/assets/cli_info.png b/neuronex/zh_CN/management/assets/cli_info.png new file mode 100644 index 0000000..efa24e0 Binary files /dev/null and b/neuronex/zh_CN/management/assets/cli_info.png differ diff --git a/neuronex/zh_CN/management/assets/data-monitoring.png b/neuronex/zh_CN/management/assets/data-monitoring.png new file mode 100644 index 0000000..c867f96 Binary files /dev/null and b/neuronex/zh_CN/management/assets/data-monitoring.png differ diff --git a/neuronex/zh_CN/management/assets/monitor.png b/neuronex/zh_CN/management/assets/monitor.png new file mode 100644 index 0000000..7a9e166 Binary files /dev/null and b/neuronex/zh_CN/management/assets/monitor.png differ diff --git a/neuronex/zh_CN/management/assets/north_statistics.png b/neuronex/zh_CN/management/assets/north_statistics.png new file mode 100644 index 0000000..883aa69 Binary files /dev/null and b/neuronex/zh_CN/management/assets/north_statistics.png differ diff --git a/neuronex/zh_CN/management/assets/south_statistics.png b/neuronex/zh_CN/management/assets/south_statistics.png new file mode 100644 index 0000000..0cf20e4 Binary files /dev/null and b/neuronex/zh_CN/management/assets/south_statistics.png differ diff --git a/neuronex/zh_CN/management/assets/write.png b/neuronex/zh_CN/management/assets/write.png new file mode 100644 index 0000000..bcbfc66 Binary files /dev/null and b/neuronex/zh_CN/management/assets/write.png differ diff --git a/neuronex/zh_CN/management/conf-management.md b/neuronex/zh_CN/management/conf-management.md new file mode 100644 index 0000000..9c7f0ce --- /dev/null +++ b/neuronex/zh_CN/management/conf-management.md @@ -0,0 +1,34 @@ +# 配置管理 + +Neuron 支持通过`命令行`、`环境变量`、`配置文件`的方式，对Neuron的配置参数进行修改，可以提供更加灵活的启动和运行方式。 +如果同时配置了`命令行`、`环境变量`、`配置文件`，三者的优先级关系为：命令行 > 环境变量 > 配置文件 + +## 命令行 + +![cli_info](./assets/cli_info.png) + +## 环境变量 + +Neuron 支持在启动过程中读取环境变量来配置启动参数，目前支持的环境变量如下: + +| 配置名 | 配置作用 | +| ---------------------- | --------------------------------------------------------------------------- | +| NEURON_DAEMON | 设置为1，Neuron 守护进程运行；设置为0，Neuron 正常运行 | +| NEURON_LOG | 设置为1，Neuron Log输出到标准输出stdout；设置为0，Neuron Log不输出到标准输出stdout； | +| NEURON_LOG_LEVEL | Neuron日志输出等级，可设置为DEBUG或NOTICE | +| NEURON_RESTART | Neuron重启设置，可设置为never，always，on-failure或者NUMBER（1,2,3,4） | +| NEURON_DISABLE_AUTH | 设置为1，Neuron 关闭Token鉴权认证；设置为0，Neuron 开启Token鉴权认证 | +| NNEURON_CONFIG_DIR | Neuron配置文件目录 | +| NEURON_PLUGIN_DIR | Neuron插件文件目录 | + + +## 配置文件 + +Neuron提供 json 格式配置文件配置Neuron相关个性化参数，目前支持 ip，port 和 disable_auth 三个配置项目，配置文件路径为neuron安装目录config/neuron.json。默认配置内容如下: +```json +{ + "ip": "0.0.0.0", + "port": 7000, + "disable_auth": 0 +} +``` diff --git a/neuronex/zh_CN/management/data-statistics.md b/neuronex/zh_CN/management/data-statistics.md new file mode 100644 index 0000000..912807b --- /dev/null +++ b/neuronex/zh_CN/management/data-statistics.md @@ -0,0 +1,47 @@ +# 数据统计 + +Neuron 支持基于 Prometheus 的数据模型的南北向节点数据统计功能，用于监测节点运行状态。Prometheus 的基本原理是通过 HTTP 协议周期性抓取被监控组件的状态，任意组件只要提供对应的 HTTP 接口就可以接入监控，Neuron 提供对应的接口，可以顺利接入 Prometheus 进行监控。 + +每个节点卡片都有一个 `数据统计` 的操作按键，用于显示该节点统计的信息。目前，Neuron 已实现一些全局字段和南北向字段的统计，后续会根据需求持续增加统计字段。 + +## 全局字段统计 + +部分全局字段说明如下。 + +| 参数 | 说明 | +| --------------- | --------------------------------------- | +| uptime_seconds | 显示 Neuron 运行时长，页面上以 5 s 的频率刷新 | +| core_dumped | 显示系统运行状态是否有异常 | + +## 北向节点统计 + +北向应用节点已支持一些字段的统计，但每个应用需要统计的字段会有些差异，后面版本有计划不断更新每个应用的统计字段，部分字段说明如下。 + +![north_statistics](./assets/north_statistics.png) + +| 参数 | 说明 | +| ----------------------- | ----------------- | +| send_msgs_total | 发送消息总条数 | +| send_msg_errors_total | 消息发送失败的总条数 | +| recv_msgs_total | 接收消息的总条数 | +| link_state | 节点连接状态：
· DISCONNECTED = 0
· CONNECTED = 1 | +| running_state | 节点状态 ：
· INIT = 1
· READY = 2
· RUNNING = 3
· STOPPED = 4 | + +## 南向节点统计 + +南向驱动节点已支持一些字段的统计，但每个驱动需要统计的字段会有些差异，后面版本有计划不断更新每个驱动的统计字段。部分字段说明如下。 + +![south_statistics](./assets/south_statistics.png) + +| 参数 | 说明 | +| ---------------------- | --------------------------------------- | +| last_rtt_ms | 收发一次指令的时间间隔，以毫秒为单位 | +| send_bytes | 发送指令的总字节数 | +| recv_bytes | 接收指令的总字节数 | +| tag_reads_total | 读取点位的总指令数，包括读失败 | +| tag_read_errors_total | 读取点位失败的总指令数 | +| group_tags_total | 组的总点位数 | +| group_last_send_msgs | 调用一次 group timer 发送的消息数 | +| group_last_timer_ms | 调用一次 group timer 的时间，以毫秒为单位 | +| link_state | 节点连接状态
DISCONNECTED = 0
CONNECTED = 1 | +| running_state | 节点状态
INIT = 1
READY = 2
RUNNING = 3
STOPPED = 4 | diff --git a/neuronex/zh_CN/management/monitoring.md b/neuronex/zh_CN/management/monitoring.md new file mode 100644 index 0000000..c1a052b --- /dev/null +++ b/neuronex/zh_CN/management/monitoring.md @@ -0,0 +1,48 @@ +# 数据监控 + +在 **监控** 菜单下选择 **数据监控**，选择南向设备和组名称，查看点位数值，如下图所示。 + +![data-monitoring](./assets/data-monitoring.png) + +* 南向设备：选择想要查看的南向设备，例如，选择已创建的设备 modbus-tcp-1; +* 组名称：选择想要查看的南向设备下的组，例如，选择已创建的组 group-1； +* 数据监控以组为单位显示数值，页面将会展示读取到的组底下每一个标签的值。 + +## 反控设备 + +Neuron 提供南向节点命令和控制能力。这种南向控制和命令使得能够代表以下各项向设备发出命令或动作: + +* 同一实例中的其他北向节点（例如，边缘分析或规则引擎服务） +* 可能与 Neuron 实例存在于同一系统上的其他应用程序（例如，需要打开阀门的管理代理） +* 需要命令这些设备的任何外部系统（例如，基于云的应用程序，它确定需要修改一组设备上的设置） + +向设备发送命令有三种方式。 + +* 用户可以在[仪表板监控屏幕](#界面更改值)上发出命令。 +* 通过 [RESTful APIs](../http-api/rw.md) 传递命令。 +* 任何外部系统，如基于云的平台，都可以将命令发布到特定主题，命令将被发送到 Neuron，然后发送到设备。 + +### 界面更改值 + +当 Tag 设置了写属性时，数据监控界面的 Tag 会有一个写操作，点 **Write** 可以实现反控设备，例如，修改具有写属性的 1!40001 点位地址的值，如下图所示。 + +:::tip +配置点位详细信息时，必须激活写入属性。否则，就没有办法控制设备。 +::: + +![write](./assets/write.png) + +* 单击要改值的标签末尾的 **写**按键； +* 选择是否以十六进制方式输入，不选择； +* 输入标签新值，例如，123； +* 单击 **提交** 按键提交新的值。 + +::: tip +设备中该点位也必须具有可写属性，否则无法写成功。 +::: + +### 查看设备点位值是否修改成功 + +打开 Modbus 模拟器，查看点位值是否变化，如下图所示。 + +monitor \ No newline at end of file