tlms_esd 0.1.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.git-blame-ignore-revs +5 -0
- package/.gitattributes +9 -0
- package/.gitignore +41 -0
- package/.local/TODO.md +90 -0
- package/.local/data_structure2025.xlsx +0 -0
- package/.local/data_structure2026.xlsx +0 -0
- package/.local/issues/a6d39veq-actuator-emulator.md +75 -0
- package/.local/issues/v9xg9fxn-config-compile-entry.md +86 -0
- package/.local/issues/yqq38rn8-adapt-layout-data-emulator.md +74 -0
- package/.npmignore +18 -0
- package/AGENTS.md +153 -0
- package/CHANGELOG.md +192 -0
- package/cli.js +185 -263
- package/doc/design.md +691 -0
- package/doc/design.zh-cn.md +690 -0
- package/doc/spec-modbus.md +263 -0
- package/doc/spec-modbus.zh-cn.md +261 -0
- package/doc/spec.md +310 -0
- package/doc/spec.zh-cn.md +308 -0
- package/eslint.config.js +58 -0
- package/issues/yqq38rn8-adapt-layout-data-emulator.md +71 -0
- package/layouts.yaml +208 -0
- package/logs/error_2024-10-11.log +2 -0
- package/logs/error_2026-10-09.log +36 -0
- package/logs/error_2026-10-10.log +1 -0
- package/logs/error_2026-10-11.log +0 -0
- package/logs/error_2026-10-12.log +0 -0
- package/logs/error_2026-10-13.log +0 -0
- package/logs/error_2026-10-15.log +0 -0
- package/logs/error_2026-10-16.log +0 -0
- package/logs/error_2026-10-17.log +0 -0
- package/logs/error_2026-10-23.log +0 -0
- package/logs/error_2026-10-25.log +3 -0
- package/logs/error_2026-10-27.log +0 -0
- package/logs/error_2026-10-28.log +0 -0
- package/logs/error_2026-10-30.log +0 -0
- package/logs/error_2026-11-05.log +0 -0
- package/logs/error_2026-11-07.log +0 -0
- package/logs/error_2026-11-14.log +1 -0
- package/logs/error_2026-11-15.log +0 -0
- package/logs/error_2026-11-17.log +0 -0
- package/logs/error_2026-11-18.log +0 -0
- package/logs/error_2026-11-22.log +0 -0
- package/logs/info_2024-10-11.log +2 -0
- package/logs/info_2026-10-09.log +36 -0
- package/logs/info_2026-10-10.log +1 -0
- package/logs/info_2026-10-11.log +0 -0
- package/logs/info_2026-10-12.log +0 -0
- package/logs/info_2026-10-13.log +0 -0
- package/logs/info_2026-10-15.log +0 -0
- package/logs/info_2026-10-16.log +0 -0
- package/logs/info_2026-10-17.log +0 -0
- package/logs/info_2026-10-23.log +0 -0
- package/logs/info_2026-10-25.log +3 -0
- package/logs/info_2026-10-27.log +0 -0
- package/logs/info_2026-10-28.log +0 -0
- package/logs/info_2026-10-30.log +0 -0
- package/logs/info_2026-11-05.log +0 -0
- package/logs/info_2026-11-07.log +0 -0
- package/logs/info_2026-11-14.log +1 -0
- package/logs/info_2026-11-15.log +0 -0
- package/logs/info_2026-11-17.log +0 -0
- package/logs/info_2026-11-18.log +0 -0
- package/logs/info_2026-11-22.log +0 -0
- package/main.js +27852 -8191
- package/nodemon.json +9 -11
- package/package.json +24 -25
- package/rolldown.config.js +35 -0
- package/dev.js +0 -5
- package/emulator.js +0 -7768
- package/rollup.config.js +0 -41
|
@@ -0,0 +1,690 @@
|
|
|
1
|
+
# TLMS_ESD 设计说明
|
|
2
|
+
|
|
3
|
+
> 本文描述系统“怎么做”,即架构、数据结构、算法和内部机制。需求见 [spec.zh-cn.md](spec.zh-cn.md),Ldata / Ltag 的编程接口见 layout-data 包的 `doc/spec-data-api.md`。
|
|
4
|
+
|
|
5
|
+
## 1. 模块划分
|
|
6
|
+
|
|
7
|
+
| 路径 | 职责 |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| `src/cli.js` | `tlms` 命令行,解析参数,调用 pm2 或直接 `import('./main.js')`。 |
|
|
10
|
+
| `src/main.js` | 进程入口:读取配置,构建控制器,提供按连接复用的真实驱动,启动 Modbus 服务端和扫描。 |
|
|
11
|
+
| `src/runtime.js` | `build_runtime`:使用对象图上已挂好的 Ldata,调用各 `*_init`,创建扫描调度器并声明全部规则,提供 `start` / `stop`。驱动由调用方经 `get_drivers` 提供。 |
|
|
12
|
+
| `src/gcl.js` | YAML 加载器(`yaml` 库,YAML 1.2),保留源码行号信息。 |
|
|
13
|
+
| `src/config.js` | 合并多份配置文档,填充默认值,建立名称与 ID 索引,把执行器的 `supported_commands` 转换为命令屏蔽字。 |
|
|
14
|
+
| `src/init.js` | `prepare_controller`:为选定的控制器构建运行时对象图;`init_controller`:建对象图、写出模拟器描述文件、构造模拟器并把 Ldata 挂到对象图上(§4.4)。 |
|
|
15
|
+
| `src/description.js` | `build_description`:由对象图生成模拟器描述;`write_description`:把描述写成文件(§4.4)。 |
|
|
16
|
+
| `src/node_proc.js` / `src/section_proc.js` / `src/line_proc.js` | 执行器(节点)、段、线的初始化(日志处理器、IO 绑定)与规则声明。 |
|
|
17
|
+
| `src/action_record.js` | 动作记录:CSV 读写。 |
|
|
18
|
+
| `src/action_record_proc.js` | 动作记录的规则:基于 index 浏览记录。 |
|
|
19
|
+
| `src/scan.js` | 扫描调度器 `Scheduler`(§5)。 |
|
|
20
|
+
| `src/rules.js` | 规则:`derive` / `act` 声明、排序与启动检查、`Ticker`、`on_delay` / `off_delay`(§6)。 |
|
|
21
|
+
| `src/drivers/` | `Base_Driver`、`MTClient`(Modbus TCP 客户端)、`S7Client`,以及 IO 绑定 `binding.js`(§4.5)。对上服务端来自 `modbus-emulator` 包(§4.4)。 |
|
|
22
|
+
| `layout-data`(外部包) | 数据层(§3):`Ldata` / `Ltag`、布局编译与校验、变化检测、字节序转换。 |
|
|
23
|
+
| `src/layouts.yaml` | LINE、SECTION、NODE、COMMAND、RECORD 的布局描述。 |
|
|
24
|
+
| `src/layouts.js` | 导出 `layouts.yaml` 的路径、布局的登记域名和业务需要的片段。 |
|
|
25
|
+
| `src/layout_types.d.ts` | 由布局生成的类型声明(`pnpm gen:types`)。 |
|
|
26
|
+
| `src/util.js` | log4js 日志、`Object.mixin`。 |
|
|
27
|
+
|
|
28
|
+
## 2. 启动流程
|
|
29
|
+
|
|
30
|
+
1. `cli.js` 先 `process.chdir(--path)`,再执行以下之一:
|
|
31
|
+
- `start`:`pm2 delete tlms_esd`,然后 `pm2 start main.js -- <controller>`,并设置 `TLMS=controller`,使日志不输出到控制台;
|
|
32
|
+
- `debug`:改写 `process.argv[2]`,设置 `LOG_LEVEL=debug`,然后动态 import `main.js`。
|
|
33
|
+
2. `main.js` 调用 `read_config(process.cwd())`:
|
|
34
|
+
1. `readdir` 列出工作目录本层的所有 `*.ya?ml`,不读子目录(§4.4 生成的描述文件在子目录中);
|
|
35
|
+
2. 每个文件经 `GCL.load` 解析为 JS 对象;
|
|
36
|
+
3. 每份文档经 `add_conf` 处理。
|
|
37
|
+
3. `add_conf` 把每类对象同时存进数组(`push`)和同一数组的属性(`[name]`,线 / 段 / 执行器另有 `[ID<id>]`),因此 `cfg_*` 既能遍历,也能按键查找。执行器的处理:
|
|
38
|
+
- 解析 `pumps` 字符串;
|
|
39
|
+
- 把 `modbus_server` / `s7_server` 规范化为带默认值的 `{data, commands, endian, ...}`;
|
|
40
|
+
- 压力和温度限值缺省时,取量程上下限;
|
|
41
|
+
- 由 `supported_commands` 算出命令屏蔽字 `command_mask`(§14.1)。
|
|
42
|
+
4. 全部文档合并后,用名称把线关联到控制器,把段关联到线(对象互相引用)。
|
|
43
|
+
5. `init_controller(name, process.cwd())`(§4.4):
|
|
44
|
+
1. `prepare_controller(name)`:
|
|
45
|
+
1. 选出控制器(为空或 0 时取第一个);
|
|
46
|
+
2. 重新生成精简的运行时对象 `line` / `section` / `actuator`;
|
|
47
|
+
3. 执行器的 `driver_info` 携带协议、地址和数据 / 命令区;
|
|
48
|
+
4. 同时按首端、末端、泵站分别放入 `section.begin_nodes` / `end_nodes` / `pump_nodes`;
|
|
49
|
+
5. 定下各数据块的块名;
|
|
50
|
+
2. 由对象图生成模拟器描述,写成工作目录下的 `<控制器名>/emulator.yaml`;
|
|
51
|
+
3. 构造模拟器并加载该文件,模拟器登记布局、创建全部 Ldata;
|
|
52
|
+
4. 把 Ldata 挂到对象图上;
|
|
53
|
+
5. 找不到控制器时返回 `undefined`,`main.js` 记录错误;描述不合法时抛出带 `errors` 的错误,`main.js` 逐条写入错误日志并以退出码 1 退出。
|
|
54
|
+
6. `run_controller`:
|
|
55
|
+
1. 用挂好的记录块初始化动作记录;
|
|
56
|
+
2. 调用 `build_runtime`(`runtime.js`):
|
|
57
|
+
1. 按 线 → 段 → 执行器 的顺序调用各自的 `*_init`;执行器的驱动由 `main.js` 的 `get_drivers` 按连接复用提供;
|
|
58
|
+
2. 创建扫描调度器(§5),登记全部 block、执行器的数据 Binding(输入分组为 `data_payload`)和只写的命令 Binding;
|
|
59
|
+
3. 对象图建好后,按执行器 → 段 → 线的顺序调用 `node_rules` / `section_rules` / `line_rules` 声明规则(§7、§8、§9),再声明动作记录的规则(§10)和各执行器的命令屏蔽规则(§14.1),然后 `prepare()` 排序检查;
|
|
60
|
+
4. 登记到调度器的 block,其 `write` 事件接到 `request_scan()`(§3.5);
|
|
61
|
+
3. 启动 Modbus TCP 服务端并等待其就绪;启动失败(如端口被占用)时记录错误并以退出码 1 退出,由 pm2 重启;
|
|
62
|
+
4. `runtime.start()` 先做一次初始扫描(算出全部派生量),再启动周期 tick(`MAIN_PERIOD = 500`);规则出错经调度器的 `on_error` 写入日志。
|
|
63
|
+
|
|
64
|
+
## 3. 数据层(layout-data 包)
|
|
65
|
+
|
|
66
|
+
Ldata(实例记作 block)与 Ltag 的术语和控制器对它们的要求见规范 §3.6,数据块自身的要求见 layout-data 的规范。数据层的实现在独立的 `layout-data` 包中:结构化、可响应、基于 buffer 的数据块,按名访问 tag,布局编译与校验,变化检测,设备字节序转换;它的规范和设计见该包的 `doc/spec.md`、`doc/spec-data-api.md`(编程接口)和 `doc/design.md`。本节只说明本项目如何使用它。
|
|
67
|
+
|
|
68
|
+
### 3.1 组件边界
|
|
69
|
+
|
|
70
|
+
- 本项目通过 `import ... from "modbus-emulator"` 取得 `layout-data` 的接口(`Ldata`、`Ltag`、`create_scope`、`get_scope`、`yaml`、`desc_file` 及其类型):modbus-emulator 转发这些接口,源码和测试不导入 `layout-data`,进程里只有一份,登记域(scope)也只有一套;ESLint 禁止导入 `layout-data` 及其子路径。类型生成是 layout-data 的开发工具(`layout-types` 命令),modbus-emulator 不转发它,所以 `layout-data` 以与 modbus-emulator 所依赖版本相同的精确版本列入开发依赖,只用于这个命令和生成文件中 `Ldata` 的类型导入。不再有 `src/typed_data/`;rolldown 构建时把 modbus-emulator 连同它依赖的 `layout-data` 打进 `main.js`;
|
|
71
|
+
- 该包不依赖本项目的配置、业务处理、布局和日志器,出错时抛出异常:布局错误在模拟器加载描述时抛出,`main.js` 写日志并退出(§3.2);
|
|
72
|
+
- 对上服务端(`Unit_Map`、handler、Modbus TCP 服务)在独立的 `modbus-emulator` 包中(§4.4)。
|
|
73
|
+
|
|
74
|
+
### 3.2 布局定义(`src/layouts.yaml`)
|
|
75
|
+
|
|
76
|
+
- 布局描述的格式(YAML 1.2、条目表、`coupling`、`includes`、条目字段、类型、初值规则、Bool 定位规则、布局校验)见 layout-data 的规范和设计文档;本项目的布局文件是 `src/layouts.yaml`:根键 `layouts` 列出布局名 `LINE`、`SECTION`、`NODE`、`COMMAND`、`RECORD`,根键 `item_tables` 下是这些布局和它们引用的片段(如 `node_commands`、`node_parameters`、`node_status`)的条目表。
|
|
77
|
+
- `src/layouts.js` 只提供布局来源:导出同目录 `layouts.yaml` 的路径 `layouts_file`(路径按模块位置解析;构建时 rolldown 把它作为独立文件输出到 `main.js` 同目录),导出布局的登记域名 `LAYOUT_SCOPE`(`tlms`),并从 `item_tables` 读出参数块条目 `node_parameters` 和命令位条目 `node_commands`(这两个片段的条目列表,供配置和节点规则按名使用)。布局由 modbus-emulator 登记:生成的模拟器描述文件内联 `layouts.yaml` 的 `layouts` 和 `item_tables`(§4.4),模拟器加载它时,把布局登记到登记域 `LAYOUT_SCOPE`,并创建描述中全部数据块的 Ldata;同一布局下块名不能重复。登记之后用 `get_scope(LAYOUT_SCOPE).get_layout(名字)` 取得 `LINE`、`SECTION`、`NODE`、`COMMAND`、`RECORD`;布局不合法时,模拟器抛出带 `errors` 的错误,由 `main.js` 逐条写入错误日志并退出。
|
|
78
|
+
- coupling 中偏移 8–15 对应寄存器的 bit0–7,偏移 0–7 对应 bit8–15;定义文件按 8–15、0–7 的顺序列出,就是按寄存器 bit0 到 bit15 的顺序排列;字值的第 k 位即寄存器 bit k,命令屏蔽字 `command_mask` 按这个位号计算(§14.1)。
|
|
79
|
+
- [spec-modbus.zh-cn.md](spec-modbus.zh-cn.md) 中的点表就是按这些规则从布局计算出来的。
|
|
80
|
+
- 组合字的位号完全由偏移编号保证,block 内部的组合字与其他多字节类型一样按大端存放;对上服务端和驱动都不为组合字单独交换字节(layout-data 规范)。
|
|
81
|
+
- 这些布局就是 Modbus 寄存器表和执行器数据区的内存映像,修改任何偏移都属于协议变更。
|
|
82
|
+
- 写入所有权(规范 §3.6)目前靠人工审查保证:布局中没有标注 Tag 由谁写入,校验不检查这一规则。现有写入路径都符合:命令块的 ID、命令字、参数块和节点 block 的参数块由控制器写入,均按字对齐且连续;节点 block 的其余部分由执行器写入,控制器只读。
|
|
83
|
+
- 布局校验由登记域加载描述(`scope.load`)时对全部布局执行;`tlms check` 与配置校验的错误一起报告(未实现,见§13)。
|
|
84
|
+
|
|
85
|
+
主要布局(字节偏移):
|
|
86
|
+
|
|
87
|
+
| 结构 | 关键 Tag |
|
|
88
|
+
| --- | --- |
|
|
89
|
+
| NODE | 0 ID;2 status;4 temperature;8 pressure;12 flowmeter;16 response_code;18 起为参数块 |
|
|
90
|
+
| COMMAND | 0 response_code(弃用);2 overtime(弃用);6 extra_commands(`has_commands`、`reset_paras`);16 ID;18 commands;20 起为参数块 |
|
|
91
|
+
| SECTION | 0 ID;2 upward_input(保留);4 status;6 flow_begin;10 flow_end;14 flow_diff;18–34 限值与延时;38 countdown |
|
|
92
|
+
| LINE | 0 status;2 ID;4 action_section_ID;6 flow_diff(保留) |
|
|
93
|
+
| RECORD | 0–10 时间;12 section_ID;14–36 流量与压力;42–48 执行器 ID;50 status;52 index |
|
|
94
|
+
|
|
95
|
+
### 3.3 访问追踪与类型声明
|
|
96
|
+
|
|
97
|
+
- 调度器的 `trace_dependencies()` 用 `Ldata.on_access` 订阅所有数据块的 `access` 事件,把规则对 tag 的读写记入“当前规则”的实际读写集合,`untrace_dependencies()` 取消订阅(§6.5)。
|
|
98
|
+
- 由布局生成类型声明 `src/layout_types.d.ts`(`pnpm gen:types`,即 layout-data 的命令 `layout-types src/layouts.yaml --scope tlms -o src/layout_types.d.ts`,需要 Node.js 24.2 以上;生成文件从 `layout-data` 导入 `Ldata` 类型,只用于类型检查,不进入运行时):每个布局一个接口,tag 为属性,`comment` 作为注释,为按名访问提供编辑器补全;生成物纳入版本库,由测试以同样的参数运行该命令,检查它与布局文件一致。
|
|
99
|
+
|
|
100
|
+
### 3.4 数据块内容的读写
|
|
101
|
+
|
|
102
|
+
- block 的字节不作为属性公开,内容只经 Ldata 读写,所以每次写入都经过 Ldata,不会漏检。读写途径任何时候都允许,不论是否在扫描中:
|
|
103
|
+
|
|
104
|
+
| 途径 | 使用者 |
|
|
105
|
+
| --- | --- |
|
|
106
|
+
| 按名读写(`data[name]`,`tag.value`) | 任何代码:规则、事件处理器、异步回调、普通程序 |
|
|
107
|
+
| 按 tag 做设备字节序转换:`tag.load(io_buffer, endian)`、`tag.store(io_buffer, endian)` | IO 绑定(§4.5) |
|
|
108
|
+
| 原始读写方法 `read_bytes(offset, length)`、`write_bytes(offset, source)`、`write_bit(offset, mask, value)`,以字节偏移定位 | 对上服务端(§4.4) |
|
|
109
|
+
|
|
110
|
+
- IO 绑定的装载(§4.5)在扫描的输入阶段进行,把一个分组的全部 tag 放进一个事务,提交时检测一次、发出一次 `write`;输入阶段的 `write` 引起的扫描请求被忽略(§5.2)。
|
|
111
|
+
- 功能码 16 请求会在同一个同步调用中连续写多个寄存器。`change` 在这次调用之后成批派发(§3.5),因此跨两个寄存器的 Real 只以完整的值发出一次 `change` 事件;规则同样不受影响,因为 `request_scan()` 会合并(§5.2),扫描在整个请求处理完之后才执行。
|
|
112
|
+
|
|
113
|
+
### 3.5 变化检测与写入通知
|
|
114
|
+
|
|
115
|
+
变化检测的机制(快照比对、事件顺序、振荡保护)和事务(`transaction(fn)`)见 layout-data 的设计文档:block 在写入语句内、新值生效之后立即发出 `write`;`change` 在写入所在的同步代码结束后由微任务派发,把这些写入的净变化成批发出。`change` 处理器抛出的异常不在写入处抛出:layout-data 把一次派发中的异常收集为一个 `Dispatch_Error`,作为该 block 的 `error` 事件发出,模拟器将其转发为 `block_error`(§4.4)。扫描不是 Ldata 的一部分,“上一次扫描结束时的值”由调度器自己保存(§5.1)。
|
|
116
|
+
|
|
117
|
+
**写入通知接到扫描请求。** 调度器登记 block(`add_data`)时监听它的 `write` 事件并请求扫描,所以控制器的全部 block(线、段、执行器的 data 和 command、动作记录)的任何写入(规则、事件处理器、HMI、异步回调)在写入时都请求一次扫描。理由:
|
|
118
|
+
|
|
119
|
+
- 写入立即生效,规则读到的永远是当前值;`change` 事件只是通知;
|
|
120
|
+
- 控制器的联锁和汇总都在规则中,不依赖事件(§6.6);
|
|
121
|
+
- `write` 在写入的调用栈中发出,调试时能追溯写入者。
|
|
122
|
+
|
|
123
|
+
异步的 `change` 只影响事件处理器(日志):一次扫描中规则做出的变化在扫描之后报告,每个 block 一批,每个 tag 报告净变化;处理器读到的是派发时的值。事件处理器只写日志;`change` 处理器的异常不会使控制器停止,而是经 `block_error` 按其 block 记入日志。
|
|
124
|
+
|
|
125
|
+
### 3.6 字节序转换
|
|
126
|
+
|
|
127
|
+
设备字节序(`BE`、`LE`、`BEBS`、`LEBS`,没有别名)与内部大端之间的转换由 layout-data 实现(规则见其设计文档):按 tag 转换用 `tag.load` / `tag.store`,IO 绑定用布局的 `io_index_table(endian)` 得到整个 block 的字节映射(§4.5),本包不自己实现转换;测试用 block 的 `load_tag` / `store_tag` 作为对照,核对 Binding 与它们逐字节一致。
|
|
128
|
+
|
|
129
|
+
## 4. 驱动
|
|
130
|
+
|
|
131
|
+
### 4.1 Base_Driver
|
|
132
|
+
|
|
133
|
+
- 以 `Object.mixin(this, new Base_Driver())` 的方式混入:只补充子类缺少的属性,判断时包含原型链,因此既不覆盖子类自己定义的 `start_tick` 等,也不遮蔽从驱动库继承的 `connect` / `disconnect`。
|
|
134
|
+
- `stop()` 停止定时器并调用库的 `disconnect()`(两个库在显式断开后都不再自动重连);之后再 `start()` 时先调用 `connect()` 重新连接。
|
|
135
|
+
- `start()` 每 `period_time`(1000 ms)执行一次 `start_tick`,已连接时发出 `tick`。
|
|
136
|
+
- `emit_io_ok` / `emit_io_error` 包装每次读写的结果:
|
|
137
|
+
- 首次出错时发出 `io_error`,出错后首次成功时发出 `io_ok`(不用 es-modbus 自带的逐事务 `data_error` 事件名,避免与之混淆);
|
|
138
|
+
- 若 `connfailed_time`(5000 ms)内一直没有成功的读写,就调用 `on_error`,进而发出 `connfailed`;
|
|
139
|
+
- `connfailed` 和 `io_error` 的参数是错误消息字符串(库给出 `Error` 时取其 `message`)。
|
|
140
|
+
- `reconnect_time` 只表示重连间隔,`connfailed_time` 只表示上面的升级时长,两者分开配置。驱动构造时的第二个参数 `options` 可传入 `period_time`、`reconnect_time`、`connfailed_time`(Modbus 另有 `reconnect_max`);控制器不传,用默认值。
|
|
141
|
+
- 驱动实例按连接参数复用:
|
|
142
|
+
- Modbus 按 `host:port`;
|
|
143
|
+
- S7 按 `host:port rack slot`;
|
|
144
|
+
- 同一驱动多次 `start()` 不会重复建立定时器。
|
|
145
|
+
|
|
146
|
+
### 4.2 MTClient(es-modbus)
|
|
147
|
+
|
|
148
|
+
- 连接:以 es-modbus 的 `tcp` 选项选择 Modbus TCP 传输,目标为 `<host>:<port>`(配置的 `host` 缺省 `127.0.0.1`,`port` 缺省 502),IPv6 主机加方括号。
|
|
149
|
+
- 地址换算:配置和 Ldata 中的区域都以字节计,字节起点 `start` 对应保持寄存器 PDU 地址 `start >> 1`(0 基),长度为 `length >> 1` 个寄存器;以 es-modbus 的结构化范围 `[func_code, pdu_addr, length]` 传入,不使用 Modicon 写法。
|
|
150
|
+
- es-modbus 对非法参数(范围、数量上限、unit_id)同步抛出;`read` / `write` 捕获后记录错误日志,并按读写失败处理(`emit_io_error`)。
|
|
151
|
+
- 只访问保持寄存器:功能码由 MTClient 显式给出,03 读,06(单个寄存器)/ 16(多个寄存器)写。不使用线圈、离散输入和输入寄存器。
|
|
152
|
+
- `write_unit = 2`:写入单元为一个寄存器。
|
|
153
|
+
- 写入的回显检查:es-modbus 的 `write()` 以“响应是否回显了请求”兑现。回显不符视为写入未确认:记录警告,按读写失败处理(`emit_io_error`),`write` 返回 `false`。
|
|
154
|
+
- 断线重连使用 es-modbus 自带的机制,`start_tick` 被重写为只发出 `tick`:
|
|
155
|
+
- 重连间隔从 `reconnect_time`(5000 ms)开始,每次失败加倍,最长 `reconnect_max`(20000 ms),连接稳定后回到初值;
|
|
156
|
+
- 连续 3 次请求超时(es-modbus 的 `max_timeouts` 默认值)视为死链,关闭连接并照常重连;连接断开时所有挂起的请求以 `connection lost` 失败。
|
|
157
|
+
|
|
158
|
+
### 4.3 S7Client(@st-one-io/nodes7)
|
|
159
|
+
|
|
160
|
+
- 通过 `readArea` / `writeArea` 读写 `DB` 或 `M` 区,起点与长度都以字节为单位。
|
|
161
|
+
- `write_unit = 1`:写入单元为一个字节。
|
|
162
|
+
- 由于 `S7Endpoint.connect()` 不完善,暂时使用库自带的自动重连(`autoReconnect`,取 `reconnect_time`,默认 5000 ms,间隔固定),`start_tick` 同样被重写(代码中已标记为临时代码)。
|
|
163
|
+
|
|
164
|
+
### 4.4 对上服务端(modbus-emulator)
|
|
165
|
+
|
|
166
|
+
- 数据块的创建和对上服务由独立的 `modbus-emulator` 包提供(规范和设计见该包的 `doc/`)。控制器把模拟器描述生成为文件,再由模拟器加载这个文件;描述文件是运行方可以查看的完整描述(规范 §5.5)。
|
|
167
|
+
- 块名:`prepare_controller` 建对象图时定下,存在对象上。线、段、执行器的数据块名就是对象的 `name`;执行器命令块的块名存在 `node.command_name`(`<执行器名>_command`),动作记录的块名存在 `controller.record_name`(`action_records`)。块名只出现在描述文件和诊断信息里,不影响 Modbus 地址。
|
|
168
|
+
- 数据块(单元号来自 `controller.modbus_server.unit_id`):动作记录(`RECORD`,字节 0);每条线(`LINE`)、每个段(`SECTION`)各一个;每个执行器的 data(`NODE`,字节 0)和 command(`COMMAND`,字节 400,即寄存器 200 起)共用执行器的单元。
|
|
169
|
+
- `src/description.js#build_description(controller)` 是只读对象图的纯函数,返回描述对象:`layouts` 和 `item_tables` 取自 `layouts.yaml`,`blocks` 为全部数据块(块名、布局),`units` 为每个单元号一个单元条目,在其中放置该单元的数据块及其起始字节,`servers` 为监听 `0.0.0.0:<modbus_server.port>` 的一个 TCP 服务。单元的字节序、未映射地址的应答和放置的只读点都取模拟器的默认值:大端,未映射地址读为 0、写入被忽略,全部点可写。描述不写登记域:登记域由代码选定(`new Modbus_Emulator(LAYOUT_SCOPE)`)。`write_description(file, description)` 把它写成 YAML 文件,文件头注明由控制器生成。
|
|
170
|
+
- `src/init.js#init_controller(name, dir)` 是 `main.js` 和测试共用的主调度函数:`prepare_controller` → `build_description` → 写出 `<dir>/<控制器名>/emulator.yaml`(子目录不存在时创建)→ `new Modbus_Emulator(LAYOUT_SCOPE)` → 接日志 → `emulator.load(文件)` → 挂载 Ldata。返回 `{ controller, emulator }`,`main.js` 还要用模拟器启动服务。`main.js` 传入工作目录,测试传入临时目录。
|
|
171
|
+
- 挂载:加载后遍历一次对象图,`line.data`、`section.data`、`node.data` 为各自块名的 Ldata,`node.command` 为命令块,`controller.record_data` 为动作记录块。对象图上不存放模拟器,`build_runtime` 直接使用挂好的 Ldata。
|
|
172
|
+
- 日志:模拟器自身不输出日志。`init_controller` 在加载前订阅它的 `warning` 事件(加载时发现的诊断)、转发的服务事件(`server_<name>`:启停、客户端连接与断开、各类错误)和 handler 事件(`unmapped`,带读写操作 `operation`;`unmapped_limit`;`listener_error`)以及其 block 的错误(`block_error`:一次 `change` 派发的 `Dispatch_Error`,其中每个异常记一条日志),写入项目日志。控制器的全部 block 都由模拟器创建,所以 `block_error` 覆盖全部 `change` 处理器的异常;调度器不订阅 block 的 `error` 事件,每个异常只记一次。
|
|
173
|
+
- 写入通知:不经模拟器传递。数据块创建时调度器还不存在,`build_runtime` 把数据块登记到调度器(`add_data`)时,调度器监听该 block 的 `write` 事件,请求扫描;其他需要知道写入的使用方同样各自监听。
|
|
174
|
+
- 寄存器和线圈的地址映射、未映射地址的处理、异常应答见 modbus-emulator 的规范;读经 Ldata 的 `read_bytes` / `read_bit`,写经 `write_bytes` / `write_bit`,由 Ldata 在每次写入后检测变化;一个 FC 15 / FC 16 请求在一个事务内写入同一 block。测试经 `emulator.handler` 模拟 HMI 请求;`emulator.stop()` 把块名交还给布局,同一进程中可以再次加载同名数据块。
|
|
175
|
+
- `src/layouts.js` 读出 `layouts.yaml` 的布局描述(`layouts`、`item_tables`)供生成描述文件,并导出按名使用的片段;布局的校验和登记由模拟器加载描述文件时完成,动作记录字段等布局元数据从登记后的 `Layout`(`block.layout`、登记域的 `get_layout`)取得。
|
|
176
|
+
|
|
177
|
+
### 4.5 IO 绑定(`src/drivers/binding.js`)
|
|
178
|
+
|
|
179
|
+
IO 绑定不属于数据层:它只通过 Ldata 和 Ltag 的接口按 tag 与设备交换数据。
|
|
180
|
+
|
|
181
|
+
- `new Binding(data, driver, { start, remote_start, length, endian, on_update }, ...extras)` 把 block 的交换区 `[start, start + length)` 对应到远端 `remote_start` 起的同长度区域;`extras` 原样传给驱动(Modbus 为 `unit_id`,S7 为 `area, db`)。交换区三项参数必须是驱动写入单元 `driver.write_unit`(缺省为 1)的整数倍,否则抛出异常,保证扩展后的写区间不越出交换区,且本地写入单元与远端写入单元对齐。
|
|
182
|
+
- Binding 持有按设备字节序存放的 `IO_buffer`(与 block 同长、同下标),驱动读入的数据只写入它。
|
|
183
|
+
- 字节映射 `io_index`:创建时由 block 布局的 `io_index_table(endian)`(`data.layout.io_index_table(endian)`)为 block 的每个字节算出它在 `IO_buffer` 中的下标(规则:设备字节序以 16 位寄存器和 32 位值为单位生效,见规范 §3.6 和 layout-data 的设计文档)。布局校验保证非 Bool 条目不重叠、Bool 只落在组合字内,所以每个字节的映射唯一。
|
|
184
|
+
- `create_group(...names)` 返回一组需要一起与设备同步的 tag(`Binding_Group`):
|
|
185
|
+
- 名称不存在、tag 落在交换区以外时抛出异常;同一 tag 重复添加时忽略;
|
|
186
|
+
- 创建时一次性取得组内每个 tag 的 Ltag,装载和导出不再按名查找;
|
|
187
|
+
- 写区间:由布局的 `items` 算出组内 tag 占用的字节(Bool 占一个字节),经 `io_index` 映射到 `IO_buffer` 的位置,向外扩展到写入单元,相邻的写入单元合并。
|
|
188
|
+
- 装载和导出都是按 tag 的转换,同一字节上属于不同分组的位互不影响:
|
|
189
|
+
|
|
190
|
+
```js
|
|
191
|
+
// load: IO_buffer -> block, one transaction: one detection and one write event
|
|
192
|
+
block.transaction(() => { for (const tag of group.tags) tag.load(IO_buffer, endian); });
|
|
193
|
+
// store: block -> IO_buffer, right before the group areas are written
|
|
194
|
+
for (const tag of group.tags) tag.store(IO_buffer, endian);
|
|
195
|
+
```
|
|
196
|
+
- 装载时 `write` 监听器抛出的异常在事务提交之后传出:数据已装载,`fresh` 照常清除,异常由调度器按 Binding 报告(§5.4)。
|
|
197
|
+
- 导出在写每个分组的区间之前进行:写区间是异步的,其间可能执行扫描,后面的分组导出的是最新的值。
|
|
198
|
+
|
|
199
|
+
- 读:`request_read()` 把整个交换区读入 `IO_buffer`,置 `fresh`,调用 `on_update`;正在进行的读取被共享,不重复发起,避免慢设备上请求堆积。`load(group)` 在扫描的输入阶段按掩码只装载本组的位并清除 `fresh`,组外的位(如由控制器维护的 `comm_OK`)保持不变;它只修改 `buffer`,不发事件,不请求扫描。
|
|
200
|
+
- 写:`request_write(group)` 登记写请求,同一分组在一次扫描内多次登记只写一次;`flush_writes()` 在扫描的输出阶段按掩码把本组的位导出到 `IO_buffer`,再按写区间逐段调用驱动写入,并把区间长度一并传给驱动。写入是异步的,不阻塞扫描。区间内不属于本组的位取自最近一次读入的值;按写入所有权规则,这些字节也由控制器写入,不会覆盖执行器的数据。
|
|
201
|
+
- 驱动未连接时不读不写,写请求保留到连接恢复后的 `flush_writes()`。
|
|
202
|
+
- 驱动事件和异步读写结果记录为 Binding 的状态,供规则读取(§6.1),只由 Binding 写入:
|
|
203
|
+
|
|
204
|
+
| 状态 | 更新时机 |
|
|
205
|
+
| --- | --- |
|
|
206
|
+
| `connected` | 驱动的 `connect` / `connfailed` 事件 |
|
|
207
|
+
| `read_ok` | 每次读取完成:成功为 true,失败为 false |
|
|
208
|
+
| `write_done(group)` | 某个分组的一次写入完成,记录完成序号和结果,供规则判断“上次请求的写入已完成” |
|
|
209
|
+
|
|
210
|
+
新数据到达、状态变化或写入完成时,Binding 调用创建时传入的 `on_update(binding)`,控制器把它接到 `request_scan()`。
|
|
211
|
+
|
|
212
|
+
## 5. 扫描(`src/scan.js`)
|
|
213
|
+
|
|
214
|
+
### 5.1 四个阶段
|
|
215
|
+
|
|
216
|
+
调度器的 `scan(tick)` 全程同步执行:
|
|
217
|
+
|
|
218
|
+
```js
|
|
219
|
+
function scan(tick) {
|
|
220
|
+
// 1 input: take the process image, advance running tickers on periodic ticks
|
|
221
|
+
phase = "input";
|
|
222
|
+
for (const { binding, input_group } of bindings) if (input_group && binding.fresh) binding.load(input_group);
|
|
223
|
+
if (tick) for (const ticker of running_tickers) ticker.count++;
|
|
224
|
+
// 2 evaluate: all rules in one fixed dependency order, each isolated (5.4)
|
|
225
|
+
phase = "evaluate";
|
|
226
|
+
for (const rule of ordered_rules) guarded(() => rule.run(rule.ticker), rule);
|
|
227
|
+
// 3 publish: the end of this scan, the used tags, binding states and variables save their values
|
|
228
|
+
phase = "publish";
|
|
229
|
+
take_scan_snapshots();
|
|
230
|
+
// 4 output: send what was requested, start reads on periodic ticks
|
|
231
|
+
phase = "output";
|
|
232
|
+
for (const { binding, input_group } of bindings) {
|
|
233
|
+
binding.flush_writes().catch(report);
|
|
234
|
+
if (tick && input_group) binding.request_read().catch(report);
|
|
235
|
+
}
|
|
236
|
+
phase = "idle";
|
|
237
|
+
}
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
1. **输入**:把有新数据的执行器从 `IO_buffer` 装载进 block,形成本次扫描的过程映像。没有新数据的执行器保持原值,通信异常由 `comm_OK` / `work_OK` 反映。周期 tick 的扫描还要把所有运行中的 ticker 计数加 1(§6.3)。
|
|
241
|
+
2. **求值**:按排好的顺序执行全部规则(§6),计算汇总量、触发位、计时、联锁动作,并登记写请求。
|
|
242
|
+
3. **发布**:保存本次扫描结束时的值(见下)。变化事件不在这里发出:block 在每次写入后立即检测并发出(§3.5),事件处理器只做日志(§6.6)。
|
|
243
|
+
4. **输出**:执行本次登记的写请求;周期 tick 的扫描还发起下一轮读取。读写是异步的,完成时 Binding 的 `on_update` 请求扫描,那时本次扫描已经结束。
|
|
244
|
+
|
|
245
|
+
“上一次扫描结束时的值”在发布阶段之后保存:本次扫描中规则和事件处理器所做的写入都算在本次扫描内。调度器自己保存三类值:规则用到的(`reads`、`writes`、`reads_previous` 中的)block tag,Binding 状态(`connected`、`read_ok`),以及登记的变量(§6.1);没有被任何规则使用的 tag 没有上一次扫描的值,取它会报错。调度器据此提供统一的上一次扫描的值和边沿判断:
|
|
246
|
+
|
|
247
|
+
```js
|
|
248
|
+
scheduler.previous(owner, name); // tag, binding state or variable: saved by the scheduler
|
|
249
|
+
scheduler.rose(owner, name); // !previous && current
|
|
250
|
+
scheduler.fell(owner, name); // previous && !current
|
|
251
|
+
scheduler.changed(owner, name); // previous differs from current (NaN equals NaN)
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
### 5.2 触发
|
|
255
|
+
|
|
256
|
+
扫描有两类触发:
|
|
257
|
+
|
|
258
|
+
| 触发 | 来源 | `tick` |
|
|
259
|
+
| --- | --- | --- |
|
|
260
|
+
| 周期 tick | 每 `MAIN_PERIOD`(500 ms)一次 | true |
|
|
261
|
+
| 扫描请求 | `request_scan()`:block 的写入(含 HMI 经 Unit_Map 的写入)、执行器数据读回、Binding 状态变化和写入完成 | false |
|
|
262
|
+
|
|
263
|
+
- `request_scan()` 用 `setImmediate` 合并:同一轮事件循环中的多次请求只引起一次扫描;周期 tick 到来时若有尚未执行的请求,由 tick 的扫描一并处理。
|
|
264
|
+
- 扫描进行中的请求来自本次扫描自己的写入(周期 tick 从不调用 `request_scan()`,外部的回调只能在两次扫描之间运行):
|
|
265
|
+
- 输入、求值阶段的请求忽略:本次扫描中后面的规则已能读到这些写入;而 derive 规则每次扫描都会写入,如果它们也引起扫描,扫描将不会停止;
|
|
266
|
+
- 发布阶段开始之后的请求安排下一次扫描:这些写入发生在求值之后,规则还没有据此求值。
|
|
267
|
+
- 在扫描进行中调用 `scan()` 时(例如在规则或事件处理器中),不嵌套执行,而是排到本次扫描之后。
|
|
268
|
+
- 计时只在 `tick` 为真时推进,请求触发的扫描不推进,所以扫描次数不影响计时(§6.3)。
|
|
269
|
+
|
|
270
|
+
### 5.3 时序
|
|
271
|
+
|
|
272
|
+
- 执行器数据读回、HMI 写入、连接状态变化后立即扫描:派生状态、联锁动作在这次扫描中完成,产生的命令在这次扫描的输出阶段发出。
|
|
273
|
+
- 读取按周期发起,执行器数据的新旧程度受读取周期限制;命令的应答在节点 block 的 `response_code` 中,随周期读取得到。
|
|
274
|
+
- 一个周期内会因不同执行器的读回发生多次扫描,段内首端和末端数据的读取时刻可能不同;输差判定有延时确认,不受瞬时不一致影响。
|
|
275
|
+
- 控制器不对执行器上报的值做去抖或滤波,信号去抖由执行器完成。
|
|
276
|
+
|
|
277
|
+
### 5.4 出错隔离
|
|
278
|
+
|
|
279
|
+
控制器是安全系统,一处缺陷不得让其他联锁停止工作:
|
|
280
|
+
|
|
281
|
+
- 每条规则单独执行,抛出异常时经调度器创建时注入的 `on_error(error, source)` 报告,然后继续执行后面的规则;`source` 为出错的规则、block 或 Binding;
|
|
282
|
+
- 输入阶段每个 Binding 的装载单独隔离,装载时 `write` 监听器抛出的异常按该 Binding 报告,其他 Binding 照常装载;
|
|
283
|
+
- 输出阶段的异步读写失败同样经 `on_error` 报告;
|
|
284
|
+
- `change` 处理器的异常在扫描之后派发,不由调度器报告:模拟器按其 block 记入日志(`block_error`,§4.4);
|
|
285
|
+
- 控制器把 `on_error` 接到日志;调度器本身不写日志,未注入时异常被忽略。
|
|
286
|
+
|
|
287
|
+
### 5.5 调度器接口
|
|
288
|
+
|
|
289
|
+
```js
|
|
290
|
+
const scheduler = new Scheduler({ period: MAIN_PERIOD, on_error });
|
|
291
|
+
scheduler.add_data(block); // every write to it requests a scan
|
|
292
|
+
scheduler.add_binding(binding, input_group); // loaded in the input phase, flushed and read in the output phase
|
|
293
|
+
scheduler.add_binding(binding); // output only: flushed in the output phase, never read nor loaded
|
|
294
|
+
scheduler.add_var(owner, name); // a shared variable: a property of an object (6.1)
|
|
295
|
+
scheduler.add_rule(rule); // built by derive() / act() (6.2)
|
|
296
|
+
scheduler.prepare(); // order the rules and check them (6.4); throws with every error
|
|
297
|
+
scheduler.start(); // periodic ticks: scan(true) every period
|
|
298
|
+
scheduler.request_scan(); // a coalesced triggered scan: scan(false)
|
|
299
|
+
scheduler.stop();
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
- `prepare()` 在第一次扫描之前调用一次:检查并排序全部规则,为每条规则分配一个 ticker,得到固定的执行表;之后不再登记。
|
|
303
|
+
- 不带输入分组登记的 Binding 只写不读,用于执行器的命令块:控制器只向执行器写命令,从不读回。
|
|
304
|
+
- `scan(tick)` 可以直接调用,供测试驱动扫描。
|
|
305
|
+
- `trace_dependencies()` / `untrace_dependencies()`:依赖追踪测试模式(§6.5)。
|
|
306
|
+
|
|
307
|
+
## 6. 规则(`src/rules.js`)
|
|
308
|
+
|
|
309
|
+
### 6.1 依赖键
|
|
310
|
+
|
|
311
|
+
规则读写的对象统一用“依赖键”表示,即 `(owner, name)` 二元组:
|
|
312
|
+
|
|
313
|
+
- owner 是 Ldata 时,name 是 tag 名,例如 `(section.data, 'comm_OK')`;
|
|
314
|
+
- owner 是段、线、执行器等普通对象时,name 是该对象的属性名,例如 `(section, 'press_SD_trigger')`。这样的变量必须用 `add_var` 登记;变量必须是某个对象的属性,裸变量不能作为依赖键;
|
|
315
|
+
- owner 是 Binding 时,name 是状态名,例如 `(binding, 'connected')`,只读。
|
|
316
|
+
|
|
317
|
+
这样 Tag、变量(规范 §3.6)和 Binding 状态按同一套规则排序。
|
|
318
|
+
|
|
319
|
+
组合字与它的组成位共用同一块数据,但名称不同,按名称建立的依赖看不出它们之间的关系。为此规定:
|
|
320
|
+
|
|
321
|
+
- 规则只写组成位,不写组合字。整字写入只来自装载和对上服务端,它们是扫描的输入;需要清除若干命令位时(应答握手、命令屏蔽),按名逐位写入;
|
|
322
|
+
- `reads` 中的组合字,在排序前展开为读它的全部组成位,之后依赖按名称建立。于是写某一位的规则排在读整字的规则之前;写不同位的两条规则之间没有依赖。
|
|
323
|
+
|
|
324
|
+
### 6.2 规则的两种类型
|
|
325
|
+
|
|
326
|
+
| 类型 | 写入约束 | 用途 |
|
|
327
|
+
| --- | --- | --- |
|
|
328
|
+
| derive(派生) | 是其写入键的唯一写入者,每次扫描完全决定写入键的值 | 汇总、差值、触发位、保护状态、计时、`comm_OK`、`action_F`、`stop_pumps` 等 |
|
|
329
|
+
| act(动作) | 写入键可以有多个写入者(包括 HMI、装载和其他 act),可以只在条件成立时写入 | 边沿动作、联锁置位 / 复位、命令收发、参数复制、动作记录、`work_OK` |
|
|
330
|
+
|
|
331
|
+
每条规则有一个名字 `name`,用于启动检查和出错报告,例如 `section S1 comm_OK`。规则声明的键分三类:
|
|
332
|
+
|
|
333
|
+
| 字段 | 含义 |
|
|
334
|
+
| --- | --- |
|
|
335
|
+
| `reads` | 读取本次扫描的值,构成依赖:写入者排在本规则之前 |
|
|
336
|
+
| `writes` | 写入的键 |
|
|
337
|
+
| `reads_previous` | 读取上一次扫描结束时的值(`scheduler.previous()`),不构成依赖,用于打断环(§6.4) |
|
|
338
|
+
|
|
339
|
+
规则发起的 IO(`request_write`)只是登记,真正的读写在输出阶段统一执行,不构成依赖,不声明。
|
|
340
|
+
|
|
341
|
+
规则可以使用两种状态:
|
|
342
|
+
|
|
343
|
+
| 状态 | 用途 | 上一次扫描的值、边沿判断 |
|
|
344
|
+
| --- | --- | --- |
|
|
345
|
+
| 依赖键(tag、Binding 状态、登记的变量) | 多条规则共享的状态,参与排序 | 由调度器提供(§5.1) |
|
|
346
|
+
| 闭包变量 | 只属于一条规则的状态:锁存、计数、自己需要的“上一次的值”等 | 规则自己保存 |
|
|
347
|
+
|
|
348
|
+
闭包变量不登记、不参与排序,只能被所属规则读写。计时不用闭包变量自行累加,而是使用调度器分配的 ticker(§6.3)。
|
|
349
|
+
|
|
350
|
+
```js
|
|
351
|
+
derive({
|
|
352
|
+
name: `section ${section.name} comm_OK`,
|
|
353
|
+
reads: all_nodes.map(node => [node.data, 'comm_OK']),
|
|
354
|
+
writes: [[section.data, 'comm_OK']],
|
|
355
|
+
run: () => { section.data.comm_OK = all_nodes.every(node => node.data.comm_OK); },
|
|
356
|
+
});
|
|
357
|
+
|
|
358
|
+
act({
|
|
359
|
+
name: `section ${section.name} stop commands reset`,
|
|
360
|
+
reads: [[section.data, 'pump_run']],
|
|
361
|
+
writes: [[section.data, 'auto_stop_cmd'], [section.data, 'man_stop_cmd']],
|
|
362
|
+
run: () => {
|
|
363
|
+
if (!scheduler.fell(section.data, 'pump_run')) return;
|
|
364
|
+
section.data.auto_stop_cmd = false;
|
|
365
|
+
section.data.man_stop_cmd = false;
|
|
366
|
+
},
|
|
367
|
+
});
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
### 6.3 计时(Ticker)
|
|
371
|
+
|
|
372
|
+
调度器为每条规则分配一个 Ticker,扫描时作为 `run(ticker)` 的参数传入。规则自己决定何时开始、何时停止计时,调度器只负责推进:
|
|
373
|
+
|
|
374
|
+
- `start()` 从 0 开始计时,运行中调用不起作用,所以持续成立的条件一直计时;`stop()` 停止并清零;`restart()` 先停止再开始;
|
|
375
|
+
- `count` 为开始以来的周期 tick 数,`elapsed` 为 `count * MAIN_PERIOD`;
|
|
376
|
+
- 推进:tick 扫描的输入阶段,调度器把运行中的 ticker 的 `count` 加 1(§5.1);请求触发的扫描不推进。只有运行中的 ticker 在集合里,推进开销与正在计时的数量成正比;
|
|
377
|
+
- 规则不接收 `tick` 标志,也不自行累加计数,所以扫描次数不影响计时;
|
|
378
|
+
- 每条规则只有一个 ticker。需要两个独立计时的逻辑拆成两条规则,例如段的输差警告延时和输差报警延时分属两条 derive 规则。
|
|
379
|
+
|
|
380
|
+
按值的延时用两个辅助函数表达:
|
|
381
|
+
|
|
382
|
+
```js
|
|
383
|
+
// true once cond has held for longer than delay_ms (as a PLC TON)
|
|
384
|
+
function on_delay(ticker, cond, delay_ms) {
|
|
385
|
+
if (cond) ticker.start();
|
|
386
|
+
else ticker.stop();
|
|
387
|
+
return ticker.elapsed > delay_ms;
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
// true while cond holds, and for delay_ms after it drops (as a PLC TOF)
|
|
391
|
+
function off_delay(ticker, cond, delay_ms) {
|
|
392
|
+
return !on_delay(ticker, !cond, delay_ms);
|
|
393
|
+
}
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
`off_delay` 的条件从一开始就不成立时,输出在启动后保持 `delay_ms` 再变为 false,与 TOF 的输出在输入为假时的表现一致。
|
|
397
|
+
|
|
398
|
+
按边沿启动的计时(事件发生后经过一段时间执行动作,中途可由规则自行中止)由 act 规则直接操作 ticker。边沿判断只在发生边沿的那一次扫描为真,检查计时必须放在边沿判断之外:
|
|
399
|
+
|
|
400
|
+
```js
|
|
401
|
+
act({
|
|
402
|
+
reads: [[binding, 'connected']],
|
|
403
|
+
writes: [[command, 'temperature_zero_raw'] /* ... all parameter tags */],
|
|
404
|
+
run: (ticker) => {
|
|
405
|
+
if (scheduler.rose(binding, 'connected')) ticker.restart();
|
|
406
|
+
if (!binding.connected) ticker.stop(); // aborted by the rule itself
|
|
407
|
+
if (ticker.running && ticker.elapsed >= 2000) {
|
|
408
|
+
ticker.stop();
|
|
409
|
+
copy_parameters();
|
|
410
|
+
}
|
|
411
|
+
},
|
|
412
|
+
});
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
计时语义:
|
|
416
|
+
|
|
417
|
+
- 条件消失或规则调用 `stop()` 时立即生效,不必等下一次 tick。例如倒计时期间人工挂起:HMI 写入段或线的 `flow_override` 触发扫描,`protect_F`、`pre_stop_notice` 在这次扫描中变为 false,倒计时规则停止 ticker,输差动作不会发生;
|
|
418
|
+
- 在两次 tick 之间启动的 ticker,下一次 tick 时 `count` 为 1:条件成立后,`on_delay` 在其后的第 `floor(delay / MAIN_PERIOD) + 1` 次 tick 输出 true;
|
|
419
|
+
- 在 tick 扫描中启动的 ticker,本次扫描 `count` 为 0,从下一次 tick 开始计数;
|
|
420
|
+
- 两次 tick 之间条件出现又消失,ticker 停止并清零,不影响计时;
|
|
421
|
+
- 请求触发的扫描中 `count` 不变,依赖计时结果的规则重复执行不会产生新的边沿;
|
|
422
|
+
- 计时值需要对外显示的(如 `countdown`),由规则在每次扫描中从 `elapsed` 换算,两次 tick 之间数值不变。
|
|
423
|
+
|
|
424
|
+
### 6.4 排序与检查
|
|
425
|
+
|
|
426
|
+
`prepare()` 对全部规则做一次拓扑排序(Kahn 算法),得到固定的执行顺序:
|
|
427
|
+
|
|
428
|
+
- 有向边:写入键 K 的规则 → 读取键 K 的规则;同一个键的多个写入者全部排在它的读取者之前;
|
|
429
|
+
- 一条规则读取自己也写入的键(读改写,例如 `line_action_source &&= line.auto_stop_cmd` 所在的规则),这次读取不构成依赖边;
|
|
430
|
+
- `reads_previous` 中的键不构成依赖边;
|
|
431
|
+
- 同一个键的多个写入者之间、以及没有依赖关系的规则之间,按声明顺序排列,保证结果可重复。
|
|
432
|
+
|
|
433
|
+
规则在整个对象图(全部 block、Binding 和变量)建好之后声明,因为上层的规则要引用下层的 block,下层的规则也会引用上层的 block(例如段的 `pre_stop_notice` 读线的 `pump_run`)。声明顺序为执行器 → 段 → 线,同类对象按配置顺序,然后是动作记录的规则,最后是各执行器的命令屏蔽规则(§14.1)。
|
|
434
|
+
|
|
435
|
+
例如段的 `pre_stop_notice` 读线的 `pump_run`,线的 `pump_run` 汇总各段的 `pump_run`,线的 `pre_stop_notice` 又汇总各段的 `pre_stop_notice`。按层级(段 → 线)无法给出正确顺序,按键排序得到:
|
|
436
|
+
|
|
437
|
+
```
|
|
438
|
+
node.pump_run -> section.pump_run -> line.pump_run
|
|
439
|
+
-> section.pre_stop_notice -> line.pre_stop_notice
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
同一次扫描内一次算对。
|
|
443
|
+
|
|
444
|
+
启动时检查以下错误,发现时报告全部错误并拒绝启动:
|
|
445
|
+
|
|
446
|
+
- 依赖成环:报告环上的规则和键,并提示可以用 `reads_previous` 打断;
|
|
447
|
+
- `reads_previous` 中的键取不到上一次扫描的值:只有 tag、Binding 的 `connected` / `read_ok` 和登记的变量有上一次扫描的值;
|
|
448
|
+
- 一个键有 derive 写入者,同时还有其他规则写入者;
|
|
449
|
+
- 规则写入了只读的 Binding 状态;
|
|
450
|
+
- 规则写入了组合字;
|
|
451
|
+
- 规则声明了不存在的 tag 名或 Binding 状态名;
|
|
452
|
+
- 规则声明了未用 `add_var` 登记的变量;
|
|
453
|
+
- 规则没有名字,或两条规则同名。
|
|
454
|
+
|
|
455
|
+
**环的打断。** 规则之间的依赖必须是无环的。业务上确实需要环时,由规则作者在环上选一处,改为读取上一次扫描结束时的值,即在声明中把这个键放进 `reads_previous`,并在 `run` 中用 `scheduler.previous()` 读取。这相当于控制系统中的单位延迟:该量总是比环上其他量晚一个扫描周期,语义固定。执行器参数的复制就是一例(§7.3)。
|
|
456
|
+
|
|
457
|
+
```js
|
|
458
|
+
derive({
|
|
459
|
+
name: 'line B',
|
|
460
|
+
reads_previous: [[section.data, 'A']],
|
|
461
|
+
writes: [[line.data, 'B']],
|
|
462
|
+
run: () => { line.data.B = g(scheduler.previous(section.data, 'A')); },
|
|
463
|
+
});
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
调度器不自动选择打断点,也不在一次扫描内反复求值直到稳定:收敛与否取决于规则中的函数,而不是依赖图的结构,一般无法判定;即使收敛,结果也可能随打断点或初值不同而不同。打断在哪里是业务判断,留给规则作者显式写出,便于审查。
|
|
467
|
+
|
|
468
|
+
### 6.5 依赖声明的核对
|
|
469
|
+
|
|
470
|
+
依赖靠显式声明,漏写读取键会导致排序错误而不报错。为此提供测试模式下的核对:
|
|
471
|
+
|
|
472
|
+
- 调度器的 `trace_dependencies()` 设置数据层的访问追踪钩子(§3.3),把访问记入“当前规则”的实际读写集合;测试运行若干次扫描后,实际访问了但没有声明的 tag 视为错误;读组合字按展开后的组成位比较(§6.1),写组合字本身就是错误;
|
|
473
|
+
- `scheduler.previous()` 从调度器保存的值取,不经过访问器,所以一个只在 `reads_previous` 中声明的 tag 被直接读取时,也报为错误(读到的是本次扫描的值);
|
|
474
|
+
- 钩子只能追踪 tag,Binding 状态和变量不经过访问器,不在核对范围内;
|
|
475
|
+
- 规则的写入在规则执行中就发出事件,事件处理器中的访问会记在该规则名下;按§6.6的约定,事件处理器只写日志,所需的值取自事件参数,不产生额外的访问;
|
|
476
|
+
- 系统测试的夹具在每个测试中都打开核对,要求没有未声明的访问。
|
|
477
|
+
|
|
478
|
+
运行时不设置钩子。没有采用“运行一遍自动推断依赖”的方式,因为 `&&`、`||` 短路和条件分支会使一次运行看不到全部读取。
|
|
479
|
+
|
|
480
|
+
### 6.6 事件处理器的编码约定
|
|
481
|
+
|
|
482
|
+
这是控制器代码的约定,不是 Ldata / Ltag 的限制:Ldata / Ltag 不阻止任何写入。
|
|
483
|
+
|
|
484
|
+
- 联锁、汇总等派生逻辑写成规则,不写在事件处理器中,以保证同一次扫描基于同一份输入、结果与事件顺序无关;
|
|
485
|
+
- 事件处理器用于日志;处理器中写 tag 是允许的,写入会请求一次扫描,在下一次扫描中被规则读到;
|
|
486
|
+
- 需要异步操作的逻辑写成 act 规则:规则登记请求,Binding 记录完成状态并请求扫描,后续处理由规则读取完成状态完成(§4.5)。
|
|
487
|
+
|
|
488
|
+
## 7. 执行器处理(`node_proc.js`)
|
|
489
|
+
|
|
490
|
+
### 7.1 IO 绑定
|
|
491
|
+
|
|
492
|
+
每个执行器的 data 和 command 各有一个 Binding(§4.5),保存在 `actuator.data_binding` / `actuator.command_binding`。
|
|
493
|
+
|
|
494
|
+
- data:
|
|
495
|
+
- 绑定整块结构,远端起点为 `driver_info.data.start`;
|
|
496
|
+
- `data_payload` 包含 ID、状态位、测量值、`response_code` 和参数块(不含 `comm_OK`,它由控制器自己维护);
|
|
497
|
+
- `data_parameters` 只包含参数块。
|
|
498
|
+
- command:
|
|
499
|
+
- 从本地字节 16 开始绑定(跳过 0–15 的本地区),远端起点为 `driver_info.commands.start`;
|
|
500
|
+
- `commands_payload` 包含 ID、commands 和参数块。
|
|
501
|
+
|
|
502
|
+
### 7.2 读取与写入
|
|
503
|
+
|
|
504
|
+
- 执行器数据的读取由扫描完成:周期 tick 的扫描在输出阶段发起读取,数据到达后 Binding 的 `on_update` 请求扫描,在输入阶段装载 `data_payload`,在发布阶段检测变化。
|
|
505
|
+
- 命令 Binding 只写不读(§5.5):规则登记写入,扫描的输出阶段写出;写入完成后 `on_update` 请求扫描。驱动未连接时写请求保留,连接恢复后写出。
|
|
506
|
+
- 驱动事件只记日志;连接和读取结果由 Binding 记为 `connected` / `read_ok`,供规则读取。
|
|
507
|
+
|
|
508
|
+
### 7.3 规则(`node_rules`)
|
|
509
|
+
|
|
510
|
+
| 规则 | 处理 |
|
|
511
|
+
| --- | --- |
|
|
512
|
+
| `comm_OK`(derive) | `off_delay(connected, delay_protect_time)`:已连接时为 true,断开后保持 `delay_protect_time` 再变为 false;从未连上时,启动后保持同样时长 |
|
|
513
|
+
| `work_OK` | `off_delay(read_ok, delay_protect_time)` 为 false,即读取持续失败超过 `delay_protect_time` 时置 false;读取成功后由装载恢复执行器上报的值 |
|
|
514
|
+
| 参数刷新 | `connected` 上升沿开始计时,满 2 s 时把节点 block 的参数复制到命令块;其间断开则停止 |
|
|
515
|
+
| `stop_pumps` 收回(带泵执行器) | `pump_run` 下降沿时清除命令块的 `stop_pumps` |
|
|
516
|
+
| 应答握手 | `response_code` 变化且不为 0 时,`response_code` 中置 1 的位,命令块中同名的命令位逐位清除,并清除 `executing` |
|
|
517
|
+
| `pressure_SD_F` | 变化时清除对应的允许或禁止命令位 |
|
|
518
|
+
| `read_paras` | 上升沿时把节点 block 的参数复制到命令块,并复位该位 |
|
|
519
|
+
| `write_paras` | 上升沿时把命令块的参数复制到节点 block,登记写入 `data_parameters`;写入完成(`write_done` 的序号到达)后复位该位 |
|
|
520
|
+
| `has_commands`(derive) | `commands` 不为 0 |
|
|
521
|
+
| 发送 | `commands` 变化时,或 `response_code` 变化且不为 0 时(让执行器看到已应答的位被清除),登记写入 `commands_payload` |
|
|
522
|
+
| 重发 | `has_commands` 持续超过 3 个 tick 后,每个 tick 再登记一次写入;每个执行器单独计时 |
|
|
523
|
+
|
|
524
|
+
- `write_paras` 把命令块的参数写入节点 block,而参数刷新、`read_paras` 把节点 block 的参数复制到命令块,`comm_OK` / `work_OK` 读节点 block 的 `delay_protect_time`,形成环。后者读节点参数在上一次扫描结束时的值(`reads_previous`,§6.4)打断这个环:节点参数来自执行器,晚一次扫描没有影响;`write_paras` 则必须读本次扫描的命令参数,HMI 常在同一请求中先写参数、再写 `write_paras`。
|
|
525
|
+
- 规则只写命令位,不写 `commands` 整字(§6.1)。
|
|
526
|
+
- `pump_run` 以执行器上报的值为准(执行器已对各泵的状态做“或”运算),控制器不另行计算。
|
|
527
|
+
- 状态变化只记日志;向段的汇总由段的规则完成(§8)。
|
|
528
|
+
|
|
529
|
+
## 8. 段处理(`section_proc.js`)
|
|
530
|
+
|
|
531
|
+
### 8.1 事件处理(`section_init`)
|
|
532
|
+
|
|
533
|
+
- 写入段的 ID、名称和输差参数(`flow_diff_WH` 等、`action_time`)。
|
|
534
|
+
- 状态变化(`action_F`、报警、挂起、`pre_stop_notice` 等)只记日志。
|
|
535
|
+
|
|
536
|
+
### 8.2 规则(`section_rules`)
|
|
537
|
+
|
|
538
|
+
段的变量和规则在对象图建好之后声明(§6.4)。段对象上的变量(不是 Tag,见规范 §3.6)用 `add_var` 登记:
|
|
539
|
+
|
|
540
|
+
- `flow_warning_trigger` / `flow_alarm_trigger`:输差警告和报警的触发位;
|
|
541
|
+
- `press_SD_trigger`:压力联锁条件;
|
|
542
|
+
- `countdown_expired`:倒计时结束;
|
|
543
|
+
- `press_action` / `flow_action`:压力动作和输差动作;
|
|
544
|
+
- `stop_pumps`:本段执行停泵。
|
|
545
|
+
|
|
546
|
+
derive 规则,每次扫描都执行,规则之间的顺序由排序决定:
|
|
547
|
+
|
|
548
|
+
| 规则 | 计算 |
|
|
549
|
+
| --- | --- |
|
|
550
|
+
| `comm_OK`、`work_OK` | 首末端全部执行器的“与” |
|
|
551
|
+
| `press_warning_F` / `press_alarm_F` | 首末端执行器 `pressure_WH_F` / `pressure_AH_F` 的“或” |
|
|
552
|
+
| `pump_run`、`pump_change_F` | 带泵执行器同名属性的“或” |
|
|
553
|
+
| `flow_begin` / `flow_end` | 首端 / 末端执行器 `flowmeter` 之和 |
|
|
554
|
+
| `flow_diff` | `flow_begin - flow_end` |
|
|
555
|
+
| 触发位 | `flow_warning_trigger = flow_diff > flow_diff_WH`,`flow_alarm_trigger` 同理 |
|
|
556
|
+
| `press_SD_trigger` | 首末端执行器 `pressure_AH_F && pressure_SD_F` 的“或”,变化时记日志 |
|
|
557
|
+
| 保护状态 | `protect_prereq = comm_OK && work_OK && !pump_change_F`;`protect_F = protect_prereq && !flow_override && !line.flow_override`,即本段与所属线的 `flow_override` 任一为真则不保护;`hangon_AF = !protect_prereq` |
|
|
558
|
+
| `flow_warning_F` / `flow_alarm_F` | 各一条规则:`on_delay(ticker, 触发位, *_delay)` |
|
|
559
|
+
| `pre_stop_notice` | `flow_alarm_F && line.pump_run && protect_F`:泵运行条件取线的(规范 §5.2),`stop_pumps` 和压力动作仍取本段的 |
|
|
560
|
+
| 倒计时 | `pre_stop_notice` 为真时计时,`countdown = (action_time - elapsed) / 1000`;结果小于 0 时 `countdown` 置 0,`countdown_expired` 为真 |
|
|
561
|
+
| `action_F` | `press_action \|\| flow_action` |
|
|
562
|
+
| `stop_pumps` | `(段 auto/man \|\| 线 auto/man) && pump_run` |
|
|
563
|
+
|
|
564
|
+
`pre_stop_notice` 读线的 `pump_run`,线的 `pump_run` 又汇总各段的 `pump_run`;排序后它们在同一次扫描中依次算出,不再需要线的变化事件补算。
|
|
565
|
+
|
|
566
|
+
### 8.3 联锁动作
|
|
567
|
+
|
|
568
|
+
act 规则,每次扫描都执行:
|
|
569
|
+
|
|
570
|
+
1. 停泵命令复位:`pump_run` 下降沿时清除段的 `auto_stop_cmd` / `man_stop_cmd`。它在压力动作之前声明,两者都写 `auto_stop_cmd`,按声明顺序排列。
|
|
571
|
+
2. 压力动作(变量 `press_action`):
|
|
572
|
+
- `press_SD_trigger && pump_run` 时置位,同时置位段的 `auto_stop_cmd`。不检查 `protect_F`,所以不受挂起约束;
|
|
573
|
+
- 否则在 `pump_run && !auto_stop_cmd` 时复位:本段泵在运行(必然是停泵后重新启动的),联锁条件已消失。
|
|
574
|
+
3. 输差动作(变量 `flow_action`):
|
|
575
|
+
- `countdown_expired` 时置位,同时置位线的 `auto_stop_cmd` 和本段的 `line_action_source`;
|
|
576
|
+
- 否则先执行 `line_action_source &&= line.auto_stop_cmd`,再在 `line.pump_run && !flow_alarm_F && !line_action_source` 时复位。泵运行条件取线的,与停泵预告一致,否则没有泵的段永远无法复位。
|
|
577
|
+
4. 复位条件每次扫描都判断,不锁存;停泵期间两个泵运行条件都不成立,所以动作状态保留到泵重新运行。
|
|
578
|
+
5. 动作记录:任一动作变量出现上升沿时,把线的 `action_section_ID` 设为本段 ID,并调用 `add_action_record()` 生成一条记录;同一次扫描两者同时发生只生成一条。两个动作变量都为 false 且线的 `action_section_ID` 等于本段 ID 时,把它清零,避免抹掉其他段的动作。
|
|
579
|
+
6. 泵命令:段的 `stop_pumps` 变化时,为真则对每个带泵执行器设置 `command.stop_pumps = node.data.pump_run`;为假则设置 `stop_pumps = false` 和 `cancel_stop = true`。
|
|
580
|
+
|
|
581
|
+
段的布局计划在将来一个专门调整布局的过渡版本中改变:届时把 `press_action` / `flow_action` 升级为 Tag,动作记录改由它们的变化事件触发,不再在动作记录规则中判断上升沿。
|
|
582
|
+
|
|
583
|
+
## 9. 线处理(`line_proc.js`)
|
|
584
|
+
|
|
585
|
+
- 规则(`line_rules`,derive):
|
|
586
|
+
- `pump_run`、`pre_stop_notice`:取各段同名属性的“或”;
|
|
587
|
+
- `alarm_F`:取各段 `flow_alarm_F` 与 `press_alarm_F` 的“或”。
|
|
588
|
+
- 线的 `flow_override` 只记日志,不改写任何段;其作用在段的 `protect_F` 规则中以与运算体现(见§8.2)。
|
|
589
|
+
- act 规则:`pump_run` 下降沿时,清除线的 `auto_stop_cmd` / `man_stop_cmd`。
|
|
590
|
+
|
|
591
|
+
## 10. 动作记录(`action_record.js`)
|
|
592
|
+
|
|
593
|
+
- CSV 列取自 RECORD 中除 Word 类型和 `index` 以外的 Tag。
|
|
594
|
+
- 启动时:
|
|
595
|
+
1. 文件不存在就写入表头;
|
|
596
|
+
2. 流式读取全部行,用 `unshift` 保留最近 `records_size` 条,最新的在前;
|
|
597
|
+
3. 对各列做类型还原。
|
|
598
|
+
- `update_record(fields)`:按 Tag 名写入记录字段,再调用 `add_record()`;字段与段的对应关系不在动作记录中。
|
|
599
|
+
- `add_record()`:
|
|
600
|
+
1. 写入当前时间;
|
|
601
|
+
2. 把记录放到内存列表头部;
|
|
602
|
+
3. 设置 `index = 0`;
|
|
603
|
+
4. 用 `appendFile` 追加一行。
|
|
604
|
+
- `index` 由一条 act 规则处理(`action_record_proc.js` 的 `action_record_rule`),在全部段的规则之后声明;规则在闭包中记住当前显示的记录:
|
|
605
|
+
- `index` 与当前显示的不同时:为 -1 时清空时间 Tag;否则把对应记录装载到 data,越界时恢复为原值。
|
|
606
|
+
- 记录内容由段的 `add_action_record()` 通过 `update_record()` 在压力动作或输差动作发生时填写(见§8.3);`press_action` / `flow_action` 取段的动作变量;执行器位置的对应规则见§13。
|
|
607
|
+
|
|
608
|
+
## 11. 日志
|
|
609
|
+
|
|
610
|
+
- log4js 有两个 category:
|
|
611
|
+
- `default`:写入 `logs/info.log` 和 `logs/error.log`,用 file appender 的日期模式 `yyyy-MM-dd`(`alwaysIncludePattern`、`keepFileExt`、`fileNameSep: "_"`),实际文件名为 `logs/info_<yyyy-MM-dd>.log` 和 `logs/error_<yyyy-MM-dd>.log`(按天滚动,单文件上限 10 MB,压缩);`TLMS !== 'controller'` 时还输出到控制台;
|
|
612
|
+
- `console`:只输出到控制台。
|
|
613
|
+
- `logger` 是一个可切换 category 的包装对象。
|
|
614
|
+
|
|
615
|
+
## 12. 运行环境、依赖与构建
|
|
616
|
+
|
|
617
|
+
### 12.1 运行环境与进程管理
|
|
618
|
+
|
|
619
|
+
- 运行环境:Node.js,源码为 ES 模块(使用 `import ... with { type: 'json' }`、`import.meta.dirname`)。
|
|
620
|
+
- 后台运行借助 pm2(peer 依赖):
|
|
621
|
+
- `tlms start` 先执行 `pm2 delete tlms_esd`,再用固定进程名 `tlms_esd` 执行 `pm2 start`,因此同一时间只有一个实例;
|
|
622
|
+
- `stop`、`list`、`log`、`flush` 分别对应 `pm2 delete`、`pm2 list`、`pm2 log`、`pm2 flush`;
|
|
623
|
+
- pm2 启动时设置 `TLMS=controller`,日志模块据此关闭控制台输出。
|
|
624
|
+
|
|
625
|
+
### 12.2 依赖库
|
|
626
|
+
|
|
627
|
+
| 库 | 用途 |
|
|
628
|
+
| --- | --- |
|
|
629
|
+
| `es-modbus` | Modbus TCP 客户端(连接执行器);对 HMI 的服务端经 `modbus-emulator` 使用它 |
|
|
630
|
+
| `modbus-emulator` | 数据块的创建和对上 Modbus TCP 服务端(§4.4),并转发 `layout-data` 的接口(§3.1) |
|
|
631
|
+
| `layout-data` | 数据层(§3),经 `modbus-emulator` 使用;本项目直接使用的只有类型生成命令(§3.3) |
|
|
632
|
+
| `@st-one-io/nodes7` | S7 客户端(连接执行器) |
|
|
633
|
+
| `yaml` | 配置与布局解析(YAML 1.2) |
|
|
634
|
+
| `csv-parser` | 读取动作记录 CSV |
|
|
635
|
+
| `log4js` | 日志 |
|
|
636
|
+
| `mri` | 命令行参数解析 |
|
|
637
|
+
|
|
638
|
+
### 12.3 开发工具
|
|
639
|
+
|
|
640
|
+
- 包管理:pnpm。
|
|
641
|
+
- 类型生成:layout-data 的 `layout-types` 命令(§3.3)。
|
|
642
|
+
- 测试:`node --test`。
|
|
643
|
+
- 代码检查:ESLint 加 `@stylistic/eslint-plugin`(`eslint.config.js`,`pnpm lint`),JS 用 tab 缩进。ESLint 查找代码问题,@stylistic 只规范空白、引号、分号等,不重新折行,手工对齐的布局表得以保留。不使用会重新折行的格式化工具(Biome、Prettier)。另外禁止使用与 `Number` 命名空间等价的全局量(`isNaN`、`isFinite`、`parseInt`、`parseFloat`、`NaN`、`Infinity`),改用 `Number.isNaN` 等。
|
|
644
|
+
|
|
645
|
+
### 12.4 构建与发布
|
|
646
|
+
|
|
647
|
+
- `rolldown.config.js` 生成两个 ES 模块包:
|
|
648
|
+
- `src/main.js` → `./main.js`;
|
|
649
|
+
- `src/cli.js` → `./cli.js`,其中 `./main.js` 设为 external,所以 `cli.js` 运行时 import 的是同目录下的打包产物。
|
|
650
|
+
- `package.json` 的 `prepare` 脚本会触发构建;`bin.tlms` 指向 `cli.js`。
|
|
651
|
+
|
|
652
|
+
## 13. 未实现项
|
|
653
|
+
|
|
654
|
+
规范已有要求、但当前代码尚未实现的内容:
|
|
655
|
+
|
|
656
|
+
| 项 | 规范要求 | 代码现状 | 涉及位置 |
|
|
657
|
+
| --- | --- | --- | --- |
|
|
658
|
+
| ID 唯一性校验 | 线、段、执行器的 ID 全局互不相同(跨类型),同一对象的多个 block 共用 ID(规范 §4.1) | `config.js` 只校验执行器 `id` 为非零数字;线、段、执行器各自按 `ID<id>` 建索引,重复或跨类型相同都不报错,同类型重复时后者静默覆盖前者 | `config.js` 的 `add_conf` |
|
|
659
|
+
| 名称唯一性校验 | 控制器与执行器的 `name` 互不相同,同类型之间和跨类型都不能重复(规范 §4.2) | 不校验;`cfg_controllers`、`cfg_actuators` 按 `name` 建索引,同类型重复时后者静默覆盖前者,控制器与执行器同名不报错 | `config.js` 的 `add_conf` |
|
|
660
|
+
| 名称格式校验 | 控制器、线、段、执行器的 `name` 是标识符(规范 §4.2) | 配置检查不校验;线、段或执行器的名称不是标识符时,`emulator.load` 报告块名无效,`main.js` 记录后退出 | `config.js` 的 `add_conf` |
|
|
661
|
+
| ID 作为对上单元号 | 线、段、执行器的 Modbus 单元号直接取各自的 ID(不小于 1),动作记录固定为单元号 0,控制器配置中不再有 `unit_id`(规范 §4.1、5.5) | `build_description` 按名称从 `controller.modbus_server.unit_id[name]` 查单元号(动作记录查 `unit_id.action_records`),每个对象都要在控制器配置中逐项列出 | `description.js` 的 `build_description` |
|
|
662
|
+
| 配置检查命令 | `tlms check` 读取并校验配置和全部布局(§3.2)、报告全部错误,不启动控制器(规范 §3.6、§5.6) | 无此命令;配置错误只在启动时发现,且多数直接退出或崩溃;布局校验已在启动时由模拟器加载描述文件时执行(`init_controller`,§4.4),尚未接入命令行 | `cli.js`;`config.js` 需拆出可单独调用、收集全部错误的校验函数 |
|
|
663
|
+
| 动作记录按位置对应执行器(现有代码有缺陷) | 节点 1–4 按先首端、后末端的顺序依次对应动作段的执行器,每个位置的压力、ID、泵运行状态取自同一个执行器(规范 §5.4) | 节点 1–3 固定取 `begin_nodes[0..2]`,节点 4 固定取 `end_nodes[0]`;`node1..3_pump_run` 取自 `pump_nodes[0..2]`(只含带泵执行器,与节点位置可能错位),`node4_pump_run` 从不赋值 | `section_proc.js` 的 `add_action_record` |
|
|
664
|
+
|
|
665
|
+
## 14. 命令处理
|
|
666
|
+
|
|
667
|
+
所有命令都走§7.3的通用握手(发送命令字,收到 `response_code` 后清除对应位);部分命令另有控制器本地处理:
|
|
668
|
+
|
|
669
|
+
| 命令 | 命令字位 | 控制器处理 |
|
|
670
|
+
| --- | --- | --- |
|
|
671
|
+
| `stop_pumps` | 0 | 由段的 `stop_pumps` 置位;执行器泵运行状态变为 false 时收回 |
|
|
672
|
+
| `cancel_stop` | 1 | 段的 `stop_pumps` 撤销时置位,让执行器解除停泵输出 |
|
|
673
|
+
| `horn` / `reset_horn` | 2 / 3 | 通用握手 |
|
|
674
|
+
| `enable_pressure_SD` / `disable_pressure_SD` | 4 / 5 | 通用握手,另在 `pressure_SD_F` 变化时清除 |
|
|
675
|
+
| `read_paras` | 6 | 本地处理(执行器参数复制到命令块),不需要发送 |
|
|
676
|
+
| `write_paras` | 7 | 本地处理:把参数直接写入执行器数据区,完成后复位 |
|
|
677
|
+
| `enable_pressure_alarm` / `disable_pressure_alarm` | 8 / 9 | 通用握手 |
|
|
678
|
+
| `enable` / `disable` | 10 / 11 | 通用握手 |
|
|
679
|
+
| `reset_CPU` / `reset_conn` | 12 / 13 | 通用握手 |
|
|
680
|
+
|
|
681
|
+
### 14.1 命令屏蔽
|
|
682
|
+
|
|
683
|
+
依据各执行器配置的 `supported_commands` 屏蔽命令(规范 §5.1):
|
|
684
|
+
|
|
685
|
+
- 解析:`config.js` 解析执行器时,把 `supported_commands` 数组转换为一个 16 位屏蔽字 `command_mask`。数组中每个命令名按命令枚举(`node_commands`)查出命令字位号 k,屏蔽字的第 k 位置 1;位号与寄存器 bit 一致(见§3.2)。
|
|
686
|
+
- 校验:数组中出现命令枚举以外的名称时,视为配置错误,启动时报错退出,与执行器 `id` 的校验方式一致。
|
|
687
|
+
- 省略字段时视为支持全部命令,`command_mask` 取命令枚举的全部位 0–13,即 `0x3FFF`。
|
|
688
|
+
- 使用:`command_mask` 随执行器对象带入运行时。每个执行器有一条屏蔽规则,每次扫描对 `command_mask` 中为 0 的命令位按名逐位复位;位 14(`reserve`)和位 15(`executing`)不是命令,不受影响。
|
|
689
|
+
- 屏蔽规则在全部规则之后声明:同一个命令位的多个写入者按声明顺序排列,所以它排在其他写命令位的规则之后;它写命令位,所以排在读 `commands` 的发送规则之前,不支持的命令位不会发出。
|
|
690
|
+
|