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
package/.gitattributes
ADDED
package/.gitignore
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Logs
|
|
2
|
+
logs
|
|
3
|
+
*.log
|
|
4
|
+
npm-debug.log*
|
|
5
|
+
*.csv
|
|
6
|
+
|
|
7
|
+
# Dependency directories
|
|
8
|
+
node_modules/
|
|
9
|
+
.yalc/
|
|
10
|
+
yalc.lock
|
|
11
|
+
|
|
12
|
+
# dotenv environment variables file
|
|
13
|
+
.env
|
|
14
|
+
|
|
15
|
+
# package
|
|
16
|
+
.npm
|
|
17
|
+
package-lock.json
|
|
18
|
+
.yarn-integrity
|
|
19
|
+
yarn.lock
|
|
20
|
+
.yarn/
|
|
21
|
+
.yarnrc.yml
|
|
22
|
+
.pnp*js
|
|
23
|
+
/*-lock.yaml
|
|
24
|
+
|
|
25
|
+
# production
|
|
26
|
+
.vscode/
|
|
27
|
+
.vs/
|
|
28
|
+
|
|
29
|
+
/main.js
|
|
30
|
+
/cli.js
|
|
31
|
+
/layouts.yaml
|
|
32
|
+
|
|
33
|
+
# emulator descriptions generated by the controller (<controller>/emulator.yaml)
|
|
34
|
+
emulator.yaml
|
|
35
|
+
|
|
36
|
+
# local data
|
|
37
|
+
/.local
|
|
38
|
+
|
|
39
|
+
# agent guidance
|
|
40
|
+
CLAUDE.md
|
|
41
|
+
AGENTS.md
|
package/.local/TODO.md
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# TODO
|
|
2
|
+
|
|
3
|
+
- 完善测试:
|
|
4
|
+
- 对上服务端出口:寄存器按大端读写 `buffer` 已有测试;还缺组合字不做字节交换、经 handler 读到的位号与 coupling 偏移编号一致的用例(规范 3.6)。
|
|
5
|
+
- 真实点表:逐个核对各结构 coupling 位的寄存器位号与 `spec-modbus.md` 一致;
|
|
6
|
+
- 驱动层:`S7Client` 本身的地址换算和读写参数(MTClient 已覆盖;Binding 的远端地址映射已由 `binding_io_test.js` 覆盖)。
|
|
7
|
+
- es-modbus 目前为 `^0.3.0-beta.4`,正式版 v0.3.0 发布后升级并复测。
|
|
8
|
+
- 设定一个过渡版本 v0.7.0 为以后大改造版本留一个缓冲期, 让 HMI 相关的地址能在缓冲期更新到 v0.7.0 的数据地位上。
|
|
9
|
+
- 上位输入区 (0.7.0 之前):段的 `upward_input` 字已就位(Word,目前没有 tag)。
|
|
10
|
+
- 段的 `flow_override`,仍在段状态字位置(bit 12),需要移动进 `upward_input`。
|
|
11
|
+
- 段的 `man_stop_cmd` 移入 `upward_input`。
|
|
12
|
+
- 压力超驰 `press_override`(0.7.0 之前)
|
|
13
|
+
- 尚未增加。目前只实现节点的压力联锁使能。
|
|
14
|
+
- 在段的 `press_SD_trigger` 规则(`section_proc.js`)中用 `!press_override &&` 短路后面的节点压力触发或运算。
|
|
15
|
+
- protect_F 有没有必要作为 tag? (0.7.0)
|
|
16
|
+
- 现由段的 `protect_F` 规则计算:`comm_OK && work_OK && !pump_change_F && !flow_override && !line.flow_override`。
|
|
17
|
+
- 它只代表输差是否处于保护状态, 应当改名为 flow_protect_F
|
|
18
|
+
- HMI 侧完全可以 section.hangon_AF、 section.flow_override、 line.flow_override 取反相与来推定是否输差被保护
|
|
19
|
+
- 虽然 flow_protect_F 需要这么一个量, 但不用是 tag, 用普通变量即可
|
|
20
|
+
- 需要 tag 的递补状态量
|
|
21
|
+
- 现在的状态区的布局很紧张, 如上面的移动完成, 也只腾空出了 protect_F现位置、 flow_override现位置、 man_stop_cmd现位置
|
|
22
|
+
- 递补1: action_F ——> flow_action_F (只是改名, 不占布局)
|
|
23
|
+
- 递补2: press_action_F (建议占用 flow_override 现位置, 与flow_action_F相邻)
|
|
24
|
+
- 人工复位问题:目前 `action_F` 由 derive 规则 `action_F`(`section_proc.js`)每次扫描按变量 `section.press_action || section.flow_action` 重算,HMI 写入的 `action_F` 会被下一周期覆盖,无法人工复位动作标志。`press_action`、`flow_action` 转正为 Tag(`press_action_F` / `flow_action_F`)后,HMI 直接写这两个 Tag 即可复位,问题随之解决。(状态区写保护实施后改为上位输入区的复位命令位,见“未实现项”的“状态区写保护”。)
|
|
25
|
+
- protect_F 暂时只改名 flow_protect_F, 不废除。 等 0.7.0 版本时废除, 启用实施方案A
|
|
26
|
+
- 方案 A:控制器内部不保留状态变量,`pre_stop_notice` 规则直接计算 `flow_alarm_F && line.pump_run && !hangon_AF && !flow_override && !line.flow_override`,并在 `reads` 中声明这些键(规则按依赖自动排序,不再需要 `change` 监听);
|
|
27
|
+
- 规范中写明 HMI 的推定公式 `!hangon_AF && !flow_override && !line.flow_override`;
|
|
28
|
+
- `test/section_proc_test.js` 已删除;`test/system_test.js` 中断言 `protect_F` 的用例改为断言 `hangon_AF` / `flow_override` 或 `pre_stop_notice`。
|
|
29
|
+
- man_stop_cmd 的原位置, 暂时用 spare 这个名称占位
|
|
30
|
+
|
|
31
|
+
## 未实现项(见 design 第 13 节)
|
|
32
|
+
|
|
33
|
+
以下“对上写入”两项一起改:
|
|
34
|
+
|
|
35
|
+
- 对上写入的原子性:已由 modbus-emulator 0.2.0 解决(`set_holding_registers` / `set_coils` 在每个块的 `transaction` 内写完一个请求,一个 FC 16 只发出一次 `change`),只剩文档与测试。
|
|
36
|
+
- design §3.4(第 111 行“对每个寄存器单独写一次”)和 design 第 123 行的“中间值”说法已过时,改为新机制;第 173 行已是新说法。
|
|
37
|
+
- 补用例:经 handler 以 FC 16 写段或节点的 `Real`,断言只发出一次 `change`。
|
|
38
|
+
- 规范写明:32 位值(`Real`、`DInt`、`UDInt`)须用 FC 16 一次写入;用 FC 6 分两次写仍会出现中间值,这是协议固有的。
|
|
39
|
+
- 状态区写保护:正常运行时 HMI 写状态区(规范 5.2 分区表)被拒绝;测试经 Ldata / Ltag 操纵,不经 HMI 写入。
|
|
40
|
+
- 拒绝而非忽略:返回异常码 0x02(Illegal Data Address),并记 warn 日志;静默忽略会让 HMI 误以为写成功。
|
|
41
|
+
- 上游依赖:
|
|
42
|
+
- es-modbus:handler 抛出带 `exception_code` 的错误即按该码应答(es-modbus issue#bm63kw0g)。
|
|
43
|
+
- modbus-emulator:描述的块条目声明只读范围,写入只读的点时整个请求拒绝并应答 0x02;拒绝时发出 `write_refused`(已记入 modbus-emulator 的 `.local/TODO.md`)。不需要运行时开关:维护写入不经 Modbus(见下文维护命令)。
|
|
44
|
+
- 本项目:`src/description.js` 按分区表从布局生成各块的只读范围(分区边界须对齐寄存器);`init_controller` 把 `write_refused` 写成 warn 日志。
|
|
45
|
+
- 人工复位改走上位输入区:在 `upward_input` 中加复位命令位,由 act 规则清除 `press_action_F` / `flow_action_F`,取代“HMI 直接写这两个 Tag”的做法(见上文“人工复位问题”),HMI 正常操作不再需要写状态区。随输入区搬迁在 v0.7.0 之前做。
|
|
46
|
+
- 维护命令(异常时临时人工置位,属非常手段):对上 Modbus 始终保持写保护,维护经控制器进程的 WebSocket 服务按 Tag 名直接读写数据块,不经 Modbus(沿用 GooSCADA 的做法)。
|
|
47
|
+
- 控制器主进程开 WebSocket 服务;`ws:` / `wss:` 的 URL 已定位到进程,命令不需要指定控制器。
|
|
48
|
+
- 命令按 `<block>.<tag>` 读写(如读取、写入一个 Tag),不用寄存器地址和位号;运行时生效、不重启(状态都在内存中,重启会清掉要修复的状态)。
|
|
49
|
+
- 每次写入记 warn 日志(来源、Tag、旧值、新值)。
|
|
50
|
+
- 待定:监听地址与端口的配置(默认只监听本机?);鉴权方式(`wss:` + 令牌?);命令格式(JSON 消息);客户端是独立工具还是 `tlms` 的子命令。
|
|
51
|
+
- 文档写明:derive 规则的 Tag 写入后下一周期即被覆盖,维护写只对 act 写入的锁存状态有效;`tlms restart` 会重新初始化全部内存状态,也是一种恢复手段。
|
|
52
|
+
- 测试:写状态区返回 0x02 且数据不变;FC 16 范围跨入只读区时整个请求被拒;维护命令写入 Tag 生效并记日志。
|
|
53
|
+
- 顺序:es-modbus → modbus-emulator → 本项目(只读范围生成、复位命令位、WebSocket 维护服务、规范 5.2 与 design)。
|
|
54
|
+
|
|
55
|
+
- 动作记录位置对应:节点 1–4 按先首端、后末端占位,每个位置的压力、ID、泵状态取自同一执行器;修正 `pump_run` 取自 `pump_nodes` 导致的错位和 `node4_pump_run` 从不赋值。
|
|
56
|
+
- 字段不变,可以提前修;但 HMI 看到的取值会变,要写进变更说明。
|
|
57
|
+
- ID 规则(规范 4.1):线、段、执行器的 ID 全局互不相同(跨类型),同一执行器的节点数据块和命令块共用 ID;ID 直接作为对上 Modbus 单元号,必须不小于 1;动作记录固定用单元号 0,控制器配置去掉 `modbus_server.unit_id`。
|
|
58
|
+
- 前提已满足:es-modbus 已升级到 0.3.0 beta,TCP 服务端把单元 0 当普通单元,默认接受所有 ID。
|
|
59
|
+
- 单元号变更对 HMI 也是地址变更,宜随 v0.7.0 落地。
|
|
60
|
+
- 名称规则(规范 §4.2):控制器与执行器的 `name` 互不相同(同类型之间和跨类型),代码未校验(design §13);与 ID 规则的校验一起做,放在编译入口中。
|
|
61
|
+
- 增加 `tlms check` 命令(若 issue#v9xg9fxn 被接受,并入配置编译入口):读取并校验配置、报告全部错误,不启动控制器;校验包含 ID 规则,并可合并“配置引用缺少校验”一项。
|
|
62
|
+
- 布局校验已实现:layout-data 的登记域加载描述(`scope.load`,经 `emulator.load`)时校验全部布局,出错时抛出带 `errors` 的异常;`check` 只需把这些错误与配置错误一起报告。design §13 仍写“布局校验已在启动时执行(`main.js`)”,已过时,顺手改正(design §3 已是新说法)。
|
|
63
|
+
- 放在 ID 规则之后做。
|
|
64
|
+
|
|
65
|
+
## 缺陷(建议 v0.7.0 之前先修)
|
|
66
|
+
|
|
67
|
+
- 配置引用缺少校验(`config.js` 的 `line.sections` 映射、`init.js` 的 `begin_nodes` / `end_nodes` 循环):线引用不存在的段、段引用不存在的执行器时启动直接崩溃;应像 `id` 校验一样给出明确的配置错误。
|
|
68
|
+
|
|
69
|
+
## 清理
|
|
70
|
+
|
|
71
|
+
- nodes7 的问题解决后,移除 S7 驱动重连的临时代码(design 4.3 节)。
|
|
72
|
+
|
|
73
|
+
## v0.7.0 数据结构调整时一并考虑
|
|
74
|
+
|
|
75
|
+
- 命令块中已不用或将取消的字段:`response_code`、`overtime`、`reset_paras`。
|
|
76
|
+
- 节点数据块的 `response_code`:2025 版点表备注“应当改为 UDInt,今后要变更”。
|
|
77
|
+
- 段数据块长度:2025 版点表为 22 个寄存器,代码为 21 个,最后一个寄存器在调整时确定。
|
|
78
|
+
- 节点状态位 `delay_protect`:点表标注“暂不使用”。
|
|
79
|
+
- 写入所有权(规范 3.6):控制器写入与执行器写入的 Tag 不得共用写入单元。目前靠人工审查;调整布局时逐项确认,必要时给 Tag 增加“由谁写入”的属性,再纳入布局校验。
|
|
80
|
+
- 32 位组合字:目前只有 16 位组合字,位号规则只对 16 位定义;如需 DWord 组合字,先约定 4 字节的位偏移编号规则。
|
|
81
|
+
|
|
82
|
+
## 工具与文档
|
|
83
|
+
|
|
84
|
+
- 把点表生成脚本放进仓库(如 `scripts/gen-point-table.mjs`),数据结构变更后重新生成 `spec-modbus.md`;需先解决人工维护的说明文字不被覆盖的问题。
|
|
85
|
+
- 进程管理的命令接口将来从 design 移回 spec。
|
|
86
|
+
- 配置编译入口,见 issue#v9xg9fxn(accepted):配置的读取、合并、校验和描述生成全部移入独立的编译入口,为每个控制器输出子目录产物,`tlms` 只读产物;并入 `tlms check`,为将来无隙热加载打基础。
|
|
87
|
+
- 开始前:先裁定,并定下它的三个待定项(运行时配置格式、编译入口形式与输出目录、`config.js` / `init.js` 的划分)。
|
|
88
|
+
- “配置引用缺少校验”直接在编译入口中修,ID 规则的校验也在编译入口中加,不必先在 `config.js` 中实现再搬走。
|
|
89
|
+
- 运行方式变为“改配置后先编译再运行”,写进 v0.7.0 的变更说明。
|
|
90
|
+
- 执行器模拟器,见 issue#a6d39veq(open,待裁定):在编译入口上扩充执行器产物;单独入口,打包成小 JS 文件,按端点(IP + 端口)合并为一个模拟器,与其 `emulator.yaml` 同放一个子目录,整体复制到另一台电脑运行;子目录名称待定。
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: a6d39veq
|
|
3
|
+
opened: 2026-11-06T19:45:45.509Z
|
|
4
|
+
closed:
|
|
5
|
+
title: 执行器模拟器:单独入口,随描述文件部署
|
|
6
|
+
status: open # open | accepted | fixed | rejected | wontfix
|
|
7
|
+
labels: []
|
|
8
|
+
remote:
|
|
9
|
+
problem_title: 问题描述
|
|
10
|
+
proposal_title: 解决提案
|
|
11
|
+
decision_title: 裁定
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 问题描述
|
|
15
|
+
|
|
16
|
+
没有现场执行器(PLC)时,无法端到端地测试控制器:驱动的连接与重连、设备字节序、轮询与写入、命令下发后执行器状态的变化,都只能靠单元测试里的替身覆盖。
|
|
17
|
+
|
|
18
|
+
要模拟执行器,有几个现实约束:
|
|
19
|
+
|
|
20
|
+
- 控制器按配置中执行器的 IP 和端口去连接,模拟器必须在那个地址上提供服务,否则还要改控制器的配置。
|
|
21
|
+
- 各执行器通常使用相同的端口(如 Modbus TCP 的 502、S7 的 102),在一台电脑上用同一个地址同时运行多个模拟器基本不可能。
|
|
22
|
+
- 因此模拟器往往要运行在另一台电脑上,而那台电脑上不一定有本项目、它的配置目录和依赖。
|
|
23
|
+
|
|
24
|
+
## 解决提案
|
|
25
|
+
|
|
26
|
+
执行器模拟器作为单独的入口,打包成一个体积小的 JS 文件,和它的描述文件放在同一个子目录中,整体复制到要运行模拟器的电脑上。单独入口还使主程序 `tlms` 不必包含执行器的执行功能:执行器的行为在模拟器的描述和入口中,不在主程序中。
|
|
27
|
+
|
|
28
|
+
分工:
|
|
29
|
+
|
|
30
|
+
- 配置编译入口生成:在 issue#v9xg9fxn 的编译入口上扩充执行器的产物。按 issue#yqq38rn8 的约束,每个端点模拟器一个子目录(名称待定),描述文件为其中的 `emulator.yaml`;编译时生成描述并把打包好的入口复制进同一子目录。执行器的产物与控制器的产物由同一次编译产出,两边一致。
|
|
31
|
+
- 布局:执行器子目录要能整体复制到另一台电脑,编译时把程序自带的 `layouts.yaml` 复制一份进子目录,与描述一起加载(布局随程序发布,见 issue#v9xg9fxn);被模拟的执行器程序本应与这一版控制器程序的布局一致。
|
|
32
|
+
- 执行器的产物按 issue#v9xg9fxn 记录来源摘要,用于追溯其来源;模拟器入口可按同样的规则提醒来源变动,但不因此拒绝运行。
|
|
33
|
+
- 入口只运行:只读所在子目录中的描述文件,不读本项目的配置,不依赖本项目的目录结构;复制整个子目录后直接用 Node.js 运行。描述文件是两边唯一的约定。
|
|
34
|
+
- 本 issue 只规定执行器的模拟器。
|
|
35
|
+
|
|
36
|
+
按端点合并:
|
|
37
|
+
|
|
38
|
+
- 配置中的执行器与节点一一对应(模型约定),但一个物理执行器可以表现为多个配置中的执行器,它们的 IP 和端口相同。同一 IP 和端口只能由一个进程提供服务,所以模拟器按端点(IP + 端口)划分:一个端点一个模拟器、一个子目录,其描述包含该端点上所有节点的数据块和命令块。
|
|
39
|
+
- 编译时按 IP 和端口把执行器归组;同一组的节点在该端点上的 Modbus 地址(单元号及数据区、命令区的寄存器范围)不得重叠,重叠视为配置错误。
|
|
40
|
+
- 子目录的名称待定(见“待定”)。
|
|
41
|
+
|
|
42
|
+
描述的内容:
|
|
43
|
+
|
|
44
|
+
- 描述还原执行器自身的地址映射:执行器配置中的单元号、数据区和命令区的起始地址(`modbus_server`),不是控制器对上的点表。
|
|
45
|
+
- 描述中的块带 `endian` 字段,取自执行器配置的设备字节序(`BE`、`LE`、`BEBS`、`LEBS`)。modbus-emulator 目前只按大端提供数据,块条目也不接受这个键:按设备字节序提供数据依赖上游支持,但不影响描述中有这个字段。
|
|
46
|
+
|
|
47
|
+
地址:
|
|
48
|
+
|
|
49
|
+
- 描述中的服务绑定执行器配置的 IP,而不是 `0.0.0.0`:一台电脑的网卡加上多个 IP 后,可以同时运行多个同端口的执行器模拟器,各绑一个地址;需要时再分到多台电脑。
|
|
50
|
+
- 入口提供覆盖监听地址的参数(如 `--host`),用于目标电脑的 IP 与配置不一致的情况;这时控制器配置中该端点上各执行器的 IP 也要相应修改,文档中写明。
|
|
51
|
+
|
|
52
|
+
执行器的行为:
|
|
53
|
+
|
|
54
|
+
- 模拟器不只提供静态数据,还要有执行器的行为(如收到停泵命令后泵状态变化、响应参数写入)。
|
|
55
|
+
- 执行器的自动化比较简单,用 Tag 处理(Tag 的事件和循环)就足够,不需要控制器那样的数据流扫描和驱动。
|
|
56
|
+
- 因此本 issue 依赖 modbus-emulator 实现描述文件中的 Tag 处理脚本(描述文件的根键,可设置 Tag 的事件和循环):编译入口把执行器的行为写成描述中的脚本,模拟器入口只加载描述并运行,不含本项目的规则、调度器或驱动。
|
|
57
|
+
- 入口本身因此很薄,可以直接用 modbus-emulator 的通用 CLI(它的 TODO 中计划增加)打包而成。
|
|
58
|
+
|
|
59
|
+
待定:
|
|
60
|
+
|
|
61
|
+
- 测试场景的驱动方式:模拟器用于测试 ESD,要能在运行中制造泄漏、压力下降、通信中断等工况。Tag 脚本处理“命令→状态”的自动化,场景切换需要外部控制。方向之一是在 modbus-emulator 中实现 WebSocket 协议的命令(按 Tag 名读写),由外部驱动场景。
|
|
62
|
+
- 端点模拟器子目录的名称:按端点合并后,节点名不再能直接作为子目录名。一个考虑是在配置中把执行器(物理设备)的名称从节点名称中独立出来,以执行器名为子目录名。
|
|
63
|
+
|
|
64
|
+
打包:
|
|
65
|
+
|
|
66
|
+
- es-modbus 的串口原生模块是按需加载的:只在第一次打开串口时加载,入口只用 TCP,不会加载它,打包成单个 JS 文件照样可以运行,不需要专门排除。
|
|
67
|
+
- modbus-emulator 不提供 S7 服务端,常见的 S7 服务端库是原生模块,做不成单个 JS 文件。S7 执行器的模拟先不做,另行选型。
|
|
68
|
+
|
|
69
|
+
不采用的做法:
|
|
70
|
+
|
|
71
|
+
- 作为 `tlms` 的子命令运行:要求运行模拟器的电脑上安装本项目和它的配置目录,不便部署到另一台电脑,主程序也要带上执行器的执行功能。
|
|
72
|
+
- 模拟器绑定 `0.0.0.0`:同一台电脑上同端口的模拟器只能运行一个。
|
|
73
|
+
- 在本项目的入口中用控制器的扫描、规则和驱动实现执行器的行为:执行器的自动化很简单,这套机制过重,也让入口带上本项目的大量代码。
|
|
74
|
+
|
|
75
|
+
## 裁定
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: v9xg9fxn
|
|
3
|
+
opened: 2026-11-06T19:56:24.547Z
|
|
4
|
+
closed:
|
|
5
|
+
title: 配置编译入口:配置先编译为各控制器、执行器子目录中的产物
|
|
6
|
+
status: accepted # open | accepted | fixed | rejected | wontfix
|
|
7
|
+
labels: []
|
|
8
|
+
remote:
|
|
9
|
+
problem_title: 问题描述
|
|
10
|
+
proposal_title: 解决提案
|
|
11
|
+
decision_title: 裁定
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 问题描述
|
|
15
|
+
|
|
16
|
+
控制器每次启动都要读取配置目录、合并 YAML、填充默认值、校验,再由对象图生成模拟器描述(issue#yqq38rn8)。这带来几个问题:
|
|
17
|
+
|
|
18
|
+
- 配置的读取、校验和描述生成都在 `tlms` 中,主程序内容多;计划中的执行器模拟器(issue#a6d39veq)也需要由配置生成描述,生成功能放在哪个入口都会让那个入口变重。
|
|
19
|
+
- 配置错误要到启动时才暴露;计划中的 `tlms check` 要单独实现一遍“读取并校验配置、不启动”。
|
|
20
|
+
- 如果只把描述生成拆出去,`tlms` 运行时仍要从配置建对象图(规则需要线、段、限值和驱动参数,这些不在描述中),就有配置和描述两份来源:改了配置未重新生成、或升级后 `layouts.yaml` 变了,块名、单元号、布局就可能对不上,只能靠启动时校验去发现。
|
|
21
|
+
- 将来若要热加载配置,在运行中读取、校验、转换配置,出错时会留下半新半旧的状态,切换不能做到无隙。
|
|
22
|
+
|
|
23
|
+
## 解决提案
|
|
24
|
+
|
|
25
|
+
增加一个独立的配置编译入口,把配置的全部处理移进去;`tlms` 只读编译产物。
|
|
26
|
+
|
|
27
|
+
编译:
|
|
28
|
+
|
|
29
|
+
- 读取配置目录、合并、填充默认值、校验,报告全部错误;有错误时不输出任何产物。计划中的 `tlms check` 并入编译入口:校验就是编译的第一步。
|
|
30
|
+
- 配置的全部校验都在编译入口中,包括配置引用的校验:线引用不存在的段、段引用不存在的执行器时给出明确的配置错误,不再在启动时崩溃;ID 规则(规范 4.1)和名称规则(规范 4.2)的校验也属于编译入口。
|
|
31
|
+
- 为每个控制器输出一个子目录 `<控制器名>/`(沿用 issue#yqq38rn8 的子目录约束),其中是规范化后的运行时配置和模拟器描述 `emulator.yaml`。描述只含 `blocks` 和 `servers`,按布局名引用布局,不内联布局。
|
|
32
|
+
- 运行时配置和模拟器描述由同一次编译产出,从结构上消除两者不一致,不需要指纹或启动时一致性校验。
|
|
33
|
+
- 产物的种类可以扩充:别的产物(如执行器模拟器的子目录,issue#a6d39veq)加入同一次编译,同样与控制器的产物保持一致。
|
|
34
|
+
|
|
35
|
+
布局:
|
|
36
|
+
|
|
37
|
+
- 布局(`layouts.yaml`)由本项目决定,随程序发布,与使用者的配置分开:使用者的配置和编译产物中都不含布局。
|
|
38
|
+
- 布局是程序与执行器程序、HMI 之间的协议,规则代码按某一版布局编写;布局随程序走,运行时使用的布局就与规则代码属于同一版本。
|
|
39
|
+
- 控制器运行时把程序自带的 `layouts.yaml` 与子目录中的描述一起交给模拟器加载(modbus-emulator 的一次 `load` 可读入多个来源),不需要修改 modbus-emulator。
|
|
40
|
+
|
|
41
|
+
运行:
|
|
42
|
+
|
|
43
|
+
- `tlms` 只读自己子目录中的产物,不再包含 YAML 合并、默认值填充和配置校验;配置变更后先编译再运行。
|
|
44
|
+
- 找不到产物时,`tlms` 给出明确的提示(先编译),不回退到读取配置。
|
|
45
|
+
- 部署时复制子目录即可运行。
|
|
46
|
+
- 子目录按名称建立,名称规则(规范 4.2)保证各控制器、执行器的子目录不会冲突。
|
|
47
|
+
|
|
48
|
+
产物的写出与运行时文件:
|
|
49
|
+
|
|
50
|
+
- 产物原子地写出:先写到临时位置,全部完成后整体替换旧产物。运行中的 `tlms`、正在启动的 `tlms` 和将来的热加载都不会读到写了一半的产物。
|
|
51
|
+
- 运行时文件(动作记录、日志)与产物分开:重新编译只替换产物,不删除、不覆盖运行时文件。运行时文件的位置随产物目录确定。
|
|
52
|
+
- 产物带格式版本号;运行程序遇到不同的格式版本时只记 warn,格式确实不兼容时由加载报出具体错误。
|
|
53
|
+
|
|
54
|
+
随之修改:
|
|
55
|
+
|
|
56
|
+
- CLI:`tlms start` 等命令的目录参数改为指向产物;编译入口提供编译命令。
|
|
57
|
+
- 开发与测试:`pnpm dev` 先编译再运行;测试的 harness 先编译到临时目录再运行。
|
|
58
|
+
- 规范:配置要求(§4)、对上接口中的描述文件(§5.5)和运行与运维中的 CLI 能力(§5.6)相应修改。
|
|
59
|
+
|
|
60
|
+
来源摘要:
|
|
61
|
+
|
|
62
|
+
- 产物记录配置来源:配置目录的绝对路径,参与编译的每个文件的文件名及其内容的 SHA-256,编译器版本和编译时间。按文件记录,提醒时能指出哪个文件被修改、新增或删除。
|
|
63
|
+
- `tlms` 启动时,记录的配置目录可访问则按同一规则重新计算,不一致时记 warn(如某文件在编译后已修改,建议重新编译),照常运行;配置目录不可访问(如产物已复制到另一台电脑)时记 info 说明跳过检查。编译器版本与运行程序版本不同时同样只记 warn。
|
|
64
|
+
- 摘要只用于提醒,不是校验:无论是否一致,都按产物运行,不回读配置,保证编译后的产物可独立运行。
|
|
65
|
+
- 扩充的产物记录同样的字段。
|
|
66
|
+
|
|
67
|
+
热加载:
|
|
68
|
+
|
|
69
|
+
- 本 issue 不实现热加载,但先编译的方式是它的前提:新产物在编译时已完整校验,切换时只需加载一份已知有效的产物,不会出现半新半旧的状态,切换可以做到无隙。
|
|
70
|
+
|
|
71
|
+
待定:
|
|
72
|
+
|
|
73
|
+
- 规范化运行时配置的格式(字段、是否沿用 YAML)。
|
|
74
|
+
- 编译入口的形式(独立的打包文件,或 `tlms` 的一个只做编译的命令)和产物的输出目录。
|
|
75
|
+
- `config.js`、`init.js` 在编译入口与运行入口之间的划分。
|
|
76
|
+
|
|
77
|
+
不采用的做法:
|
|
78
|
+
|
|
79
|
+
- 只把描述生成拆出去、`tlms` 仍读配置:留下配置与描述两份来源,要靠指纹校验发现不一致,`tlms` 也只少了描述生成这一块。
|
|
80
|
+
- 维持每次启动重新生成:主程序仍承担全部配置处理,错误到启动时才暴露,也无法支撑无隙的热加载。
|
|
81
|
+
- 编译时把布局内联进产物:布局被绑定在编译时的程序版本上,升级程序而未重新编译时,产物中的旧布局与运行中的新规则代码不一致。
|
|
82
|
+
|
|
83
|
+
本提案取代 issue#yqq38rn8 中“描述文件每次启动重新生成”和“描述文件内联布局”的做法。
|
|
84
|
+
|
|
85
|
+
## 裁定
|
|
86
|
+
接受。把配置的全部处理移入独立的编译入口,从结构上消除运行时配置与模拟器描述的不一致,配置错误在编译时就能暴露,布局随程序发布,也为将来无隙热加载打下基础。按解决提案实施,待定项在实施前确定。
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: yqq38rn8
|
|
3
|
+
opened: 2026-10-29T16:59:59.000Z
|
|
4
|
+
closed: 2026-11-14T07:04:08.981Z
|
|
5
|
+
title: 适配 layout-data 0.6.0、modbus-emulator 0.3.0 和 es-modbus 0.3.0
|
|
6
|
+
status: fixed # open | accepted | fixed | rejected | wontfix
|
|
7
|
+
labels: []
|
|
8
|
+
remote:
|
|
9
|
+
problem_title: 问题描述
|
|
10
|
+
proposal_title: 解决提案
|
|
11
|
+
decision_title: 裁定
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 问题描述
|
|
15
|
+
|
|
16
|
+
依赖 layout-data、modbus-emulator 和 es-modbus 先后改了接口,本项目要跟着适配。
|
|
17
|
+
|
|
18
|
+
- layout-data 0.5.0 引入登记域:布局登记在登记域里,没有全局登记;布局描述改为 `layouts` 列出布局名、`item_tables` 存放条目表;字节映射由 `Layout#io_index_table` 给出;类型生成改为它的开发工具 `layout-types`,modbus-emulator 不转发。
|
|
19
|
+
- layout-data 0.6.0:`yaml_file` 改名为 `desc_file`;登记域的 `register_layout` 换成 `scope.load(descriptions)`,它在登记布局的同时创建描述中数据块的 Ldata,同一布局下块名不能重复。
|
|
20
|
+
- modbus-emulator 0.2.0:构造函数只接受登记域名,`new Modbus_Emulator(scope)`;描述由 `emulator.load(paths)` 加载,可调用多次,每次要么全部成功、要么不改变任何东西;`load` 只接受描述文件的路径,不再接受对象形式的描述;构造时的 `warnings` 数组改为 `warning` 事件;`stop()` 把块名交还给布局。
|
|
21
|
+
- modbus-emulator 0.3.0(依赖 es-modbus 0.3.0):
|
|
22
|
+
- 数据块由单元条目放置:描述增加根键 `units`,数据块条目只保留 `name` 和 `layout`,不再接受 `unit_id`、`start` 和 `offset`(多余的键是错误);一个单元条目代表一台设备,用 `blocks` 把本描述中的数据块放到该单元的 `start` 处,描述中的每个数据块都必须由某个单元放置且只放置一次,同一单元号只能由一个单元条目声明。
|
|
23
|
+
- 单元条目新增可选的 `endian`(默认 `BE`)、`unmapped_read`(默认 `zero`)、`unmapped_write`(默认 `ignore`),放置新增可选的 `readonly`(默认 `none`);取默认值时行为与 0.2.0 相同。
|
|
24
|
+
- `Unit_Map#attach_unit(unit_id, block, start, offset)` 改为 `attach_unit(unit_id, block, { start, offset, readonly })`。
|
|
25
|
+
- `unmapped` 事件只对成功的请求发出,并带有 `operation`(`read` 或 `write`);新增被拒请求的 `request_refused` / `request_refused_limit` 事件。
|
|
26
|
+
- TCP 端口取 1 到 65535,端口 0 被拒绝。
|
|
27
|
+
- es-modbus 0.3.0(相对 0.3.0-beta.4):`Modbus_Client` 只接受一个选项对象,由 `tcp`、`rtu_over_tcp`、`serial` 三者之一选择传输方式,其值为目标,如 `new Modbus_Client({ tcp: "10.0.0.5:502" })`;构造参数 `address` 和选项 `port`、`rtu` 被去掉;不适用于所选传输方式的选项抛出异常;`host:port` 中的 IPv6 主机要加方括号,端口 0 不被接受。
|
|
28
|
+
|
|
29
|
+
本项目原来由 `create_upward` 在内存中拼出对象形式的描述交给模拟器,依赖的是模拟器不公开的入口(代码里用 `@ts-expect-error` 标明),这个入口去掉后就无法构造模拟器。依赖更新到最新版后,全部测试文件在加载阶段失败。
|
|
30
|
+
|
|
31
|
+
只适配到 modbus-emulator 0.2.0 和 es-modbus 0.3.0-beta.4 时,依赖再更新到最新版,还会出现以下失败:
|
|
32
|
+
|
|
33
|
+
- 生成的描述在数据块条目中写了 `unit_id` 和 `start`,模拟器 0.3.0 加载时报错,控制器无法启动。
|
|
34
|
+
- `MTClient` 以 `new Modbus_Client(host, { port, rtu, ... })` 构造客户端,主机字符串不是选项对象,es-modbus 0.3.0 构造时抛出异常,无法连接 Modbus TCP 执行器。
|
|
35
|
+
- 测试以 `attach_unit(UNIT, block, 400)` 放置命令块,第三个参数不是选项对象,命令块被放在字节 0,与数据块重叠而报错。
|
|
36
|
+
|
|
37
|
+
## 解决提案
|
|
38
|
+
|
|
39
|
+
直接适配 layout-data 0.6.0 和新的模拟器接口,不单独适配 layout-data 0.5.0:modbus-emulator 不会发布适配 0.5.0 的版本,单独适配 0.5.0 的提交无法依赖已发布的包。
|
|
40
|
+
|
|
41
|
+
布局与登记域:
|
|
42
|
+
|
|
43
|
+
- 控制器布局登记在登记域 `tlms`(`LAYOUT_SCOPE`),布局从登记域取得,数据块的 Ldata 由登记域加载描述时创建。
|
|
44
|
+
- `layouts.yaml` 采用新的描述格式,各布局条目的名字、类型、偏移和初值不变,寄存器映射不变。
|
|
45
|
+
- IO 绑定的字节映射取自布局(`Layout#io_index_table`)。
|
|
46
|
+
- `layout-data` 作为开发依赖,版本与 modbus-emulator 所依赖的一致,`gen:types` 改用 `layout-types`。
|
|
47
|
+
|
|
48
|
+
依赖版本:modbus-emulator 取 `^0.3.0`;es-modbus 取 `^0.3.0`,与 modbus-emulator 所依赖的 0.3.0 一致,进程和打包结果中只有一份;layout-data 仍为 0.6.0。
|
|
49
|
+
|
|
50
|
+
模拟器描述:控制器把模拟器描述生成为文件,再由模拟器加载这个文件。
|
|
51
|
+
|
|
52
|
+
- 模拟器的文件单独放在配置目录下以控制器名命名的子目录中,描述文件为其中的 `emulator.yaml`(即 `<控制器名>/emulator.yaml`),每次启动重新生成;读取配置只读配置目录本层,不读子目录,因此不需要按文件名跳过描述文件。将来各执行器的模拟器实现也照此产出描述文件:以执行器名为子目录,描述文件放在其中。文件内联 `layouts.yaml` 的布局,连同 `blocks`、`units`、`servers`,是一份完整的描述,运行方打开它就能看到模拟器的全部数据块和服务。
|
|
53
|
+
- 描述按 modbus-emulator 0.3.0 的格式分为数据块和单元:数据块条目只写 `name` 和 `layout`;单元号取自 `controller.modbus_server.unit_id`,每个单元号一个单元条目,在其中放置该单元的数据块:动作记录、管线、管段的数据块放在字节 0,执行器的 data 放在字节 0、command 放在字节 400。单元的 `endian`、`unmapped_read`、`unmapped_write` 和放置的 `readonly` 都取默认值,对上的寄存器映射和应答行为不变。
|
|
54
|
+
- 描述不写根键 `scope`:登记域由代码选定(`new Modbus_Emulator(LAYOUT_SCOPE)`),模拟器不读这个键,写在文件里会让运行方误以为描述决定登记域。
|
|
55
|
+
- 块名在建对象图时确定并存在对象上:管线、管段、节点的块名就是对象的 `name`,命令块名和记录块名存在专门字段中。块名与 Ldata 实例分开存放,不先存名字再覆盖为实例。
|
|
56
|
+
- 生成描述是只读对象图的纯函数;主调度函数依次建对象图、生成并写出描述文件、构造模拟器并加载描述、把 Ldata 实例挂到对象图上(`data`、`command` 及记录块),`main.js` 和测试共用它。`build_runtime` 直接使用挂好的实例,不再接收模拟器。
|
|
57
|
+
- 测试把描述文件写到临时目录;测试自己的布局改用 `desc_file` 和 `scope.load` 登记。
|
|
58
|
+
- 模拟器的 `unmapped` 事件写入日志时带上 `operation`。
|
|
59
|
+
- 测试直接用 `Unit_Map` 放置数据块时改用选项对象 `attach_unit(unit_id, block, { start })`。
|
|
60
|
+
|
|
61
|
+
Modbus TCP 客户端:`MTClient` 以 `{ tcp: "<host>:<port>", reconnect_time, reconnect_max }` 构造 es-modbus 客户端,不再传 `rtu`;主机是 IPv6 地址时加方括号。配置中 `host`、`port` 的含义和缺省值不变。
|
|
62
|
+
|
|
63
|
+
`doc/design.md` 中对上服务端(§4.4)和 MTClient(§4.2)的说明随之更新。
|
|
64
|
+
|
|
65
|
+
不采用的做法:
|
|
66
|
+
|
|
67
|
+
- 继续在内存中传对象形式的描述:依赖模拟器的内部入口,已被去掉。
|
|
68
|
+
- 运行时用 `yaml(JSON.stringify(...))` 生成描述文本、不写文件:能用,但运行方看不到模拟器实际加载了什么。
|
|
69
|
+
- 让 modbus-emulator 的 `load` 也接受对象:描述文件对运行方本身有用,不必为本项目扩大模拟器的接口。
|
|
70
|
+
- 借这次适配给对上服务端设置单元字节序、只读点或拒绝未映射地址:会改变 HMI 看到的协议行为,不属于适配,需要时另立 issue。
|
|
71
|
+
|
|
72
|
+
## 裁定
|
|
73
|
+
|
|
74
|
+
接受。依赖的新版本不再支持原来的构造方式,必须适配;生成的描述文件同时让运行方能看到模拟器的数据块和服务,按解决提案实施。
|
package/.npmignore
ADDED
package/AGENTS.md
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# Coding Rules
|
|
2
|
+
|
|
3
|
+
## Working Platform
|
|
4
|
+
|
|
5
|
+
- The user's machine is Windows 11 (zh-CN locale).
|
|
6
|
+
- The default shell is PowerShell 7.6.
|
|
7
|
+
- Microsoft.Coreutils is installed.
|
|
8
|
+
- like MinGW64, there is some Unix commands.
|
|
9
|
+
- other Unix Command Alternatives:
|
|
10
|
+
- `sed`: use `sd`
|
|
11
|
+
- `find`: use `fd`
|
|
12
|
+
- `xxd`: use `hexyl`
|
|
13
|
+
|
|
14
|
+
## Language
|
|
15
|
+
|
|
16
|
+
- All code, variable names, function names, comments, and commit messages must be in English.
|
|
17
|
+
- Use `snake_case` (lowercase with underscores) for variables, members, methods, instances, and other identifiers that are neither types nor constants.
|
|
18
|
+
- Use `Snake_Pascal_Case` (each word capitalized, joined by underscores, e.g. `Some_Var`) for all user-defined type names: classes, interfaces, structs, enums, traits, type aliases, etc.
|
|
19
|
+
- Use `UPPER_SNAKE_CASE` for constants and enum members. A constant is a compile-time constant: a constant expression under the language's own rules, not whatever an optimizer happens to fold. Without a compile phase (JS, Python, shell), it is a literal or an expression of only literals and other constants. It never depends on run-time input (arguments, environment, configuration, I/O, clock).
|
|
20
|
+
- Judge by where the value comes from, NOT by keywords or immutability: `const`/`final`/`readonly`/non-`mut` alone do not make a constant.
|
|
21
|
+
- Constant: `const MAX_RETRY = 3;`, `static TIMEOUT_MS: u32 = 5 * 1000;`, an enum or flag member.
|
|
22
|
+
- Not a constant (use `snake_case`): `const port = process.env.PORT;`, `let result = compute();`.
|
|
23
|
+
- Names from libraries or built-ins that follow their own conventions are exempt from the rules above.
|
|
24
|
+
- The English-language requirement does not impose an ASCII-only character set. Non-ASCII characters are allowed anywhere in source files, including comments and string literals, when all of the following hold:
|
|
25
|
+
- They carry explicit meaning rather than typography, e.g. `§`, `→`, `≤`, `μ`, `Δ`, `°`. Typographic and invisible characters are not allowed (em/en dashes, curly quotes, `…`, decorative emoji, zero-width characters, BOM, NBSP, bidirectional controls); use ASCII equivalents.
|
|
26
|
+
- They are not specific to a non-English natural language. Text in such a language belongs in the project's i18n/l10n mechanism when one exists, or in documents intended for users of that language.
|
|
27
|
+
|
|
28
|
+
## Encoding & Line Endings
|
|
29
|
+
|
|
30
|
+
- All source files must use UTF-8 encoding and LF line endings.
|
|
31
|
+
- `.gitattributes` must include `* text=auto eol=lf` plus standard settings for binary files.
|
|
32
|
+
|
|
33
|
+
## Project Configuration Files
|
|
34
|
+
|
|
35
|
+
- `.gitignore` must exclude `.local` directories, dependency directories and build/compile targets, `CLAUDE.md` and `AGENTS.md` files in the project.
|
|
36
|
+
|
|
37
|
+
## Project Guidance Document
|
|
38
|
+
|
|
39
|
+
- Maintain a unified specification document system under `doc/` for all code work:
|
|
40
|
+
- The entry point is `doc/spec.md`. For complex projects, split topics into sub-documents named `doc/spec-<topic>.md` and reference them from `doc/spec.md`.
|
|
41
|
+
- When initializing a new project, create `doc/spec.md` and populate it with project goals, scope, tools, dependencies, and build requirements.
|
|
42
|
+
- When new requirements or spec changes arise, update the existing document system (edit `doc/spec.md` or add/update a `doc/spec-<topic>.md`) — do not create parallel spec files outside this structure.
|
|
43
|
+
- There may also be `doc/design-<topic>.md` and `doc/plan-<topic>.md` document series in the project. Code generation shall be carried out according to the instructions in the `spec` and `design` series only.
|
|
44
|
+
- The spec defines what to build and why — requirements, scope, behavior, and constraints.
|
|
45
|
+
- The design defines how to build it — technical implementation details, architecture decisions, algorithms, and internal mechanics.
|
|
46
|
+
- Think before coding. If there is any ambiguity or doubt in the `spec` or `design`, clarify with the user first — do not improvise.
|
|
47
|
+
|
|
48
|
+
## Personal TODO
|
|
49
|
+
|
|
50
|
+
- When the user mentions "the TODO document" (or "TODO 文档"), it generally means `.local/TODO.md` in the project root.
|
|
51
|
+
- It is a local file for the user's own project tracking, not a document for collaboration: do not commit it, and do not reference it from the `doc/` series.
|
|
52
|
+
|
|
53
|
+
## YAML
|
|
54
|
+
|
|
55
|
+
- Indent mappings by 2 spaces. A block sequence that is the value of a mapping key puts its `-` at the indentation of that key, not one level deeper:
|
|
56
|
+
```yaml
|
|
57
|
+
servers:
|
|
58
|
+
- host: 127.0.0.1
|
|
59
|
+
port: 502
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Node.js
|
|
63
|
+
|
|
64
|
+
- Always use pnpm as the package manager for Node.js projects.
|
|
65
|
+
- Source files are ES modules only (`import`/`export`). No CommonJS syntax in source files.
|
|
66
|
+
|
|
67
|
+
## Testing
|
|
68
|
+
|
|
69
|
+
- Keep test helper code thin. Do not grow test utilities into a sub-project of their own that needs its own tests.
|
|
70
|
+
- Do not write tests for tests. Check a new or changed test once, after it is written: make it fail on purpose (temporarily break the code under test, or feed it a known-bad case, with a throwaway script if needed), confirm it fails for the expected reason, then restore. Throwaway scripts live in a temp directory and are never committed.
|
|
71
|
+
- If a helper is too complex to check this way, simplify it. If it truly must be complex, it is not a test helper: move it into the codebase as a module and test it like any other code.
|
|
72
|
+
|
|
73
|
+
## Git Commits
|
|
74
|
+
|
|
75
|
+
- **Commit messages** follow [Conventional Commits](https://www.conventionalcommits.org/):
|
|
76
|
+
```
|
|
77
|
+
type: brief description
|
|
78
|
+
Optional body with rationale or migration notes.
|
|
79
|
+
```
|
|
80
|
+
Scope is optional: `feat(cli): add delete subcommand`.
|
|
81
|
+
- Use imperative mood in the description (e.g., "add feature" not "added feature").
|
|
82
|
+
- Do not include AI/assistant co-author or attribution info in commit messages (no `Co-Authored-By` for AI, no "Generated with" lines).
|
|
83
|
+
|
|
84
|
+
## Git Rewrite Workflow
|
|
85
|
+
|
|
86
|
+
When the content (the changed files) of the current git version or commit (assume it is A) is wrong and needs to be rewritten, split into multiple commits, or otherwise reconstructed:
|
|
87
|
+
|
|
88
|
+
- Create a temporary branch from the parent commit of A.
|
|
89
|
+
- Hard reset the temporary branch to the parent of A.
|
|
90
|
+
- Cherry-pick the content of A onto the temporary branch.
|
|
91
|
+
- Make the required code changes on the temporary branch.
|
|
92
|
+
- Create the replacement commit or commits on the temporary branch.
|
|
93
|
+
- Do not use temporary files as part of this workflow.
|
|
94
|
+
- Preserve safety by keeping all work in branches and commits.
|
|
95
|
+
|
|
96
|
+
Before rewriting the original branch:
|
|
97
|
+
|
|
98
|
+
- Wait for explicit user confirmation.
|
|
99
|
+
|
|
100
|
+
After explicit confirmation:
|
|
101
|
+
|
|
102
|
+
- Hard reset the original branch to the validated result on the temporary branch.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
# Project: TLMS_ESD (Pipeline Leakage Emergency Shutdown System)
|
|
107
|
+
|
|
108
|
+
A Node.js (ESM) controller that polls field actuators (PLCs) over Modbus TCP or Siemens S7, computes per-section flow-difference / pressure alarms, issues pump-stop commands, and re-exposes all state through its own Modbus TCP server for an upstream HMI/SCADA.
|
|
109
|
+
|
|
110
|
+
Requirements live in `doc/spec.md`, implementation design in `doc/design.md`.
|
|
111
|
+
|
|
112
|
+
## Commands
|
|
113
|
+
|
|
114
|
+
- `pnpm build` - bundle `src/main.js` -> `./main.js` and `src/cli.js` -> `./cli.js` with rolldown (both outputs are gitignored; `cli.js` imports `./main.js` as external).
|
|
115
|
+
- `pnpm dev` - run controller `TC` directly from source using the YAML files in `example/` (cwd must be the config directory).
|
|
116
|
+
- `pnpm watch` - same as `dev`, restarted by nodemon on `src/` changes.
|
|
117
|
+
- `pnpm test` - `node --test` (runs `test/*_test.js`); single file: `node --test test/block_test.js`; single case: `node --test --test-name-pattern="<name>" test/block_test.js`.
|
|
118
|
+
- Lint/format: ESLint + `@stylistic/eslint-plugin` (`eslint.config.js`): `pnpm lint`, `pnpm lint --fix`. Indent JS with tabs (display width 4); YAML and Markdown use 2 spaces. Do not use Biome or Prettier: they re-wrap hand-laid tables.
|
|
119
|
+
- Installed CLI `tlms start|stop|restart|debug|list|log|flush [controller] [--path dir]` wraps pm2 (process name `tlms_esd`); `debug` runs in the foreground with `LOG_LEVEL=debug`.
|
|
120
|
+
|
|
121
|
+
## Runtime model
|
|
122
|
+
|
|
123
|
+
- Every `*.yaml`/`*.yml` in the working directory is loaded (YAML 1.2) via `src/gcl.js`, and merged by `src/config.js` into `cfg_controllers`, `cfg_lines`, `cfg_sections`, `cfg_actuators`. These arrays double as maps keyed by `name` and `ID<id>`. Defaults for `modbus_server` / `s7_server` (ports, unit_id, area, db, start, endian) and alarm limits are filled in here; an actuator's `supported_commands` becomes its `command_mask`.
|
|
124
|
+
- Hierarchy: controller -> lines -> sections -> actuators (nodes). A section has `begin_nodes` / `end_nodes`; nodes with `pumps` become `pump_nodes`. `src/init.js#prepare_controller` builds this object graph for one controller (argv[2], default: first).
|
|
125
|
+
- `src/init.js#init_controller(name, dir)` (shared by `main.js` and `test/harness.js`) builds the object graph (`prepare_controller`, which also names the data blocks: a line, section and node use their `name`, plus `node.command_name` and `controller.record_name`), writes the emulator description from `src/description.js#build_description` (layouts inlined, the data blocks, one unit entry per unit id from `controller.modbus_server.unit_id` placing its blocks with node commands at byte 400, the Modbus TCP server; no `scope` key) to `<dir>/<controller>/emulator.yaml` (the emulator of a controller keeps its files in a subdirectory named after it), lets `modbus-emulator` load it, and mounts the blocks on the graph (`line.data`, `section.data`, `node.data`, `node.command`, `controller.record_data`); `read_config` reads the top level of the directory only. `src/runtime.js#build_runtime` uses the mounted blocks, never creating a Ldata itself, creates the scan `Scheduler` (`src/scan.js`), registers every block with the scheduler (`add_data` listens to its `write` event and calls `request_scan()`) and declares all rules; `main.js` starts the emulator and `runtime.start()`.
|
|
126
|
+
- Drivers (`src/drivers/`): `MTClient` (es-modbus, constructed with `{ tcp: "<host>:<port>" }`) and `S7Client` (@st-one-io/nodes7) share `Base_Driver` tick/reconnect logic and are pooled per host/port(/rack/slot). They emit `connect`, `connfailed`, `io_error`, `io_ok`, `tick`. `Binding` (`src/drivers/binding.js`) maps a block to a driver area: device byte order (`BE`, `LE`, `BEBS`, `LEBS`), write units, groups (`create_group`: `data_payload`, `data_parameters`, `commands_payload`), and the states `connected` / `read_ok` / `write_done(group)`.
|
|
127
|
+
- Logic is a scan (doc/design.md 5): input (load fresh device data), evaluate (all rules in a fixed dependency order), publish (detect changes, emit `change` events), output (flush registered writes; start reads on periodic ticks). A scan runs every `MAIN_PERIOD` (500 ms) and on `request_scan()`, which every block write, device read and binding state change calls.
|
|
128
|
+
- Rules (`src/rules.js`, doc/design.md 6) are declared in `node_rules` / `section_rules` / `line_rules` (+ `action_record_rule`, `node_mask_rule`) with `derive` (sole writer, recomputed every scan) or `act` (edge / conditional writes), their `reads` / `writes` / `reads_previous` keys, and a per-rule `Ticker` (`on_delay` = TON, `off_delay` = TOF). Rules write the bits of a combined word, never the word. Event handlers only log.
|
|
129
|
+
|
|
130
|
+
## Split packages (layout-data, modbus-emulator)
|
|
131
|
+
|
|
132
|
+
- The typed data layer and the upward Modbus server are separate packages, listed in `devDependencies` and bundled into `main.js` by rolldown. `modbus-emulator` is declared from npm (`^0.4.0`); it depends on exact versions of `es-modbus` and `layout-data`. Keep the `es-modbus` range of this project satisfied by the version `modbus-emulator` depends on, so the process and the bundle hold one copy. Develop the three packages together in the pnpm workspace `D:/codes/AS/emulator` (outside every repository: a private `package.json` and a `pnpm-workspace.yaml` listing `../../ECMAScript/layout_data`, `../es-modbus`, `../modbus_emulator` and `../TLMS_ESD.js`, with `linkWorkspacePackages`, `preferWorkspacePackages`, and the overrides `es-modbus`, `layout-data` and `modbus-emulator`: `"workspace:*"`, so each stays linked whatever the range of its dependent): `pnpm install` there links the local `layout-data`, `es-modbus` and `modbus-emulator` into their dependents while every `package.json` keeps its npm ranges, so the local versions must satisfy them, and the process holds the one local `layout-data`. Install and run scripts from the workspace root (`pnpm install`, `pnpm --filter tlms_esd test`, ...); `pnpm install` inside this directory alone reinstalls from npm and drops the links, and `pnpm run` here checks the stale standalone lockfile against the release-age policy, so run `node --test`, `node_modules/.bin/eslint .`, `node_modules/.bin/rolldown -c` directly when working here. `layout-data` publishes `dist/`: rebuild it there (`pnpm build`) after changing its source. Never use `link:`, `file:` or yalc. It forwards the API of `layout-data` that this project uses (`Ldata`, `Ltag`, `create_scope`, `get_scope`, `yaml`, `desc_file` and their types): import it from `modbus-emulator` only, never from `layout-data` (a copy of `layout-data` with another version would have its own scope registry). Type generation is a development tool of `layout-data` that modbus-emulator does not forward: `layout-data` is a dev dependency pinned to the exact version `modbus-emulator` depends on (keep them equal), used only for its `layout-types` command (`pnpm gen:types`, Node.js >= 24.2) and for the `Ldata` type import of the generated `src/layout_types.d.ts`; ESLint forbids importing `layout-data` and its subpaths in code. Layouts live in a scope, and modbus-emulator registers them: the generated description inlines the layouts of `layouts.yaml`; `new Modbus_Emulator(LAYOUT_SCOPE)` then `emulator.load(file)` registers them in the scope `LAYOUT_SCOPE` (`tlms`, `src/layouts.js`) and creates the Ldata of every block (`scope.load`: a layout keeps its blocks by name, unique per layout; `emulator.stop()` gives the names back). After that, get a layout with `get_scope(LAYOUT_SCOPE).get_layout(name)` (`LINE`, `SECTION`, `NODE`, `COMMAND`, `RECORD`), create a block with `layout.create_ldata(name)` (`new Ldata` throws), and take the byte map with `layout.io_index_table(endian)`. When the description is invalid, `emulator.load` throws an error with `errors`, which `main.js` logs one by one before it exits. Tests that need layouts of their own load the controller layouts plus their own in that scope (`desc_file`, `yaml`, `scope.load`) through `test/share.js` (`register_test_layouts`, `get_layout`, `create_block`). Edit the packages in their own repositories, not here.
|
|
133
|
+
- `layout-data` (source in `D:/codes/ECMAScript/layout_data`): `Ldata` / `Ltag`, layout compilation and validation, change detection, device byte order conversion (`Layout#io_index_table`, `load_entry` / `store_entry`), layout scopes (`create_scope`, `get_scope`). Its spec and design are in its own `doc/`; the API is `doc/spec-data-api.md` there.
|
|
134
|
+
- `modbus-emulator` (`D:/codes/AS/modbus_emulator`): `Unit_Map`, `create_handler`, `create_tcp_server(unit_map, options)` (TCP, or RTU over TCP with `rtu: true`; port 1..65535), `Unit_Map#attach_unit(unit_id, block, { start, offset, readonly })`, `create_rtu_server`, and `Modbus_Emulator` (a YAML-described device emulator). It outputs nothing itself: diagnostics are events (`warning`, `server_<name>`, ...), which `init_controller` writes to the log. This project builds all its data blocks and the upward server through `Modbus_Emulator`, which loads description files only (`emulator.load(paths)`).
|
|
135
|
+
- `src/layouts.yaml` declares PLC-compatible layouts (`name`, `type`, bit `offset`, optional bit `length`, optional `init_value`); the root key `layouts` lists the layout names, and `item_tables` holds the item tables of the layouts and of the fragments they reference by name. Offsets are in bits; a Bool at offset n lives in byte `n >> 3`, bit `n % 8` (coupling lists 8..15 before 0..7 to match the PLC byte order). `is_combined` + `coupling` define a Word composed of bit tags; `includes` splices a shared item list (e.g. `node_parameters`). `src/layouts.js` only provides the layout sources: it exports the path of `layouts.yaml` (`layouts_file`, resolved from the module location; the build outputs the file next to `main.js`), its layout description (`layout_description`: `layouts` and `item_tables`, inlined in the emulator description), the scope name `LAYOUT_SCOPE`, and the parameter block items `node_parameters` and the command bits `node_commands` read from `item_tables` (item lists that the configuration and the node rules use by name); `pnpm gen:types` regenerates `src/layout_types.d.ts` with `layout-types` (its `--scope tlms` must match `LAYOUT_SCOPE`; `test/types_test.js` runs the command with `LAYOUT_SCOPE` and compares).
|
|
136
|
+
- These layouts must stay byte-compatible with the PLC-side programs and with the HMI register map - changing an offset is a protocol change.
|
|
137
|
+
- `Ldata` owns an internal big-endian buffer and exposes each tag through prototype accessors (`data.pressure = ...`) and `data.get(name)`. A block detects changes after every write; the scheduler listens to its `write` event to `request_scan()`. The `buffer` and the detection are private to `Ldata`: code reads and writes bytes through `read_bytes` / `write_bytes` / `write_bit`, and converts device byte order per tag with `Ltag#load` / `Ltag#store` (`Layout#io_index_table` for the byte map). `Layout` exposes `name`, `length`, `size`, the frozen `items`, `scope`, `create_ldata(name)` and `io_index_table(endian)`.
|
|
138
|
+
|
|
139
|
+
## Logging
|
|
140
|
+
|
|
141
|
+
- log4js via `logger` in `src/util.js`; level from `LOG_LEVEL` (default `info`); files under `logs/` relative to the working directory.
|
|
142
|
+
- Some existing log/error strings contain Chinese (e.g. config validation); new code should follow the non-ASCII character rule in the Language section.
|
|
143
|
+
|
|
144
|
+
## Project Conventions
|
|
145
|
+
|
|
146
|
+
### Documentation
|
|
147
|
+
|
|
148
|
+
- Spec vs design split: `doc/spec*.md` holds requirement-level constraints; `doc/design.md` holds the implementation choices that satisfy them.
|
|
149
|
+
- Spec examples: "implemented in JavaScript", "runs in the background, one instance at a time", CLI capabilities (start/stop/list/log), timing requirements (main period, delays, polling period).
|
|
150
|
+
- Design examples: Node.js, pm2, dependency libraries, pnpm, rolldown, ESLint.
|
|
151
|
+
- When adding doc content, decide whether it is a requirement or a means of meeting one. Do not edit the ancestor `D:\codes\AGENTS.md` to encode this split; it stays generic on purpose.
|
|
152
|
+
- Docs describe mechanisms only (controller, actuator, node, line, section and their processing). Never record which concrete actuator, PLC or site implements which command or feature, nor site/station names from example configs or the user manual. Instance differences belong in configuration (e.g. a per-actuator supported command list); if the code lacks such a mechanism, mark it in `doc/design.md` as unimplemented.
|
|
153
|
+
- In Chinese documents, translate "spec" as 规范, never 规格 (e.g. "规范说明", "见规范 §3").
|