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.
Files changed (71) hide show
  1. package/.git-blame-ignore-revs +5 -0
  2. package/.gitattributes +9 -0
  3. package/.gitignore +41 -0
  4. package/.local/TODO.md +90 -0
  5. package/.local/data_structure2025.xlsx +0 -0
  6. package/.local/data_structure2026.xlsx +0 -0
  7. package/.local/issues/a6d39veq-actuator-emulator.md +75 -0
  8. package/.local/issues/v9xg9fxn-config-compile-entry.md +86 -0
  9. package/.local/issues/yqq38rn8-adapt-layout-data-emulator.md +74 -0
  10. package/.npmignore +18 -0
  11. package/AGENTS.md +153 -0
  12. package/CHANGELOG.md +192 -0
  13. package/cli.js +185 -263
  14. package/doc/design.md +691 -0
  15. package/doc/design.zh-cn.md +690 -0
  16. package/doc/spec-modbus.md +263 -0
  17. package/doc/spec-modbus.zh-cn.md +261 -0
  18. package/doc/spec.md +310 -0
  19. package/doc/spec.zh-cn.md +308 -0
  20. package/eslint.config.js +58 -0
  21. package/issues/yqq38rn8-adapt-layout-data-emulator.md +71 -0
  22. package/layouts.yaml +208 -0
  23. package/logs/error_2024-10-11.log +2 -0
  24. package/logs/error_2026-10-09.log +36 -0
  25. package/logs/error_2026-10-10.log +1 -0
  26. package/logs/error_2026-10-11.log +0 -0
  27. package/logs/error_2026-10-12.log +0 -0
  28. package/logs/error_2026-10-13.log +0 -0
  29. package/logs/error_2026-10-15.log +0 -0
  30. package/logs/error_2026-10-16.log +0 -0
  31. package/logs/error_2026-10-17.log +0 -0
  32. package/logs/error_2026-10-23.log +0 -0
  33. package/logs/error_2026-10-25.log +3 -0
  34. package/logs/error_2026-10-27.log +0 -0
  35. package/logs/error_2026-10-28.log +0 -0
  36. package/logs/error_2026-10-30.log +0 -0
  37. package/logs/error_2026-11-05.log +0 -0
  38. package/logs/error_2026-11-07.log +0 -0
  39. package/logs/error_2026-11-14.log +1 -0
  40. package/logs/error_2026-11-15.log +0 -0
  41. package/logs/error_2026-11-17.log +0 -0
  42. package/logs/error_2026-11-18.log +0 -0
  43. package/logs/error_2026-11-22.log +0 -0
  44. package/logs/info_2024-10-11.log +2 -0
  45. package/logs/info_2026-10-09.log +36 -0
  46. package/logs/info_2026-10-10.log +1 -0
  47. package/logs/info_2026-10-11.log +0 -0
  48. package/logs/info_2026-10-12.log +0 -0
  49. package/logs/info_2026-10-13.log +0 -0
  50. package/logs/info_2026-10-15.log +0 -0
  51. package/logs/info_2026-10-16.log +0 -0
  52. package/logs/info_2026-10-17.log +0 -0
  53. package/logs/info_2026-10-23.log +0 -0
  54. package/logs/info_2026-10-25.log +3 -0
  55. package/logs/info_2026-10-27.log +0 -0
  56. package/logs/info_2026-10-28.log +0 -0
  57. package/logs/info_2026-10-30.log +0 -0
  58. package/logs/info_2026-11-05.log +0 -0
  59. package/logs/info_2026-11-07.log +0 -0
  60. package/logs/info_2026-11-14.log +1 -0
  61. package/logs/info_2026-11-15.log +0 -0
  62. package/logs/info_2026-11-17.log +0 -0
  63. package/logs/info_2026-11-18.log +0 -0
  64. package/logs/info_2026-11-22.log +0 -0
  65. package/main.js +27852 -8191
  66. package/nodemon.json +9 -11
  67. package/package.json +24 -25
  68. package/rolldown.config.js +35 -0
  69. package/dev.js +0 -5
  70. package/emulator.js +0 -7768
  71. package/rollup.config.js +0 -41
package/doc/spec.md ADDED
@@ -0,0 +1,310 @@
1
+ # TLMS_ESD Specification (Draft)
2
+
3
+ > English version of [spec.zh-cn.md](spec.zh-cn.md), the primary Chinese version. When the two differ, update both.
4
+ >
5
+ > This document was reverse-engineered from the existing code and describes what the system does and why. For the implementation see [design.md](design.md).
6
+
7
+ ## 1. Goals
8
+
9
+ TLMS_ESD (Pipeline Leakage Emergency Shutdown System) protects oil pipelines against leakage. A pipeline is organized in lines and sections, with measurement and control points at both ends of each section. The system monitors them continuously and shuts down automatically on anomalies:
10
+
11
+ - **Flow difference monitoring**: when the flow difference of a section (total flow at the begin end minus total flow at the end end) exceeds the warning value (WH), the system raises a warning; when it exceeds the alarm value (AH), the whole line is shut down. A countdown precedes the shutdown, and an operator can interrupt it during the countdown.
12
+ - **Pressure monitoring**: when the pressure of a measurement point exceeds the warning value (WH), the system raises a warning; when it exceeds the alarm value (AH), the section of that point is shut down, without a countdown. The pressure shutdown can be enabled or disabled per measurement point.
13
+ - **Hang-on**: the flow difference protection works per section. While a section is hung on, the system no longer stops pumps because of its flow difference, but alarms are still raised. The system hangs a section on automatically on a communication failure, an abnormal measurement point (such as a faulty measuring device), during a period after pumps start or stop, and so on; while the measuring devices are under maintenance, the section must be hung on manually to avoid false actions. Hang-on does not affect the pressure shutdown.
14
+ - **Central monitoring and traceability**: the states of lines, sections and measurement points are collected and offered to the HMI/SCADA for monitoring and operation, and every interlock shutdown action is recorded.
15
+
16
+ This project implements only the controller program; the programs on the measurement point side are implemented by the actuators (see §3).
17
+
18
+ ## 2. Scope
19
+
20
+ ### 2.1 Included
21
+
22
+ - Reading the YAML configuration and running one of its controllers by name;
23
+ - Communication with actuators over two protocols: Modbus TCP and Siemens S7;
24
+ - Section-level flow difference alarm, pressure alarm aggregation, interlock pump stop and cancel stop;
25
+ - Line-level manual hang-on (`flow_override`), alarm aggregation, automatic / manual stop pump commands;
26
+ - Publishing actuator parameters and writing them back, sending actuator commands;
27
+ - Interlock action records (persisted as CSV, the latest N records browsable over Modbus);
28
+ - Logging;
29
+ - The command-line tool `tlms`, which runs and manages controller instances in the background.
30
+
31
+ ### 2.2 Not included
32
+
33
+ - The PLC programs of the actuators (pressure limit checks and the actual pump start / stop are done by the actuators);
34
+ - HMI screens;
35
+ - Line-level flow difference (`LINE.flow_diff` is reserved and not implemented).
36
+
37
+ ## 3. Terminology and object model
38
+
39
+ ### 3.1 Core terms
40
+
41
+ The system has only two kinds of runtime entities:
42
+
43
+ - **Controller**: this program. A controller is one TLMS process. It manages several lines as configured, polls actuator data periodically, evaluates flow differences and interlocks, and acts as a Modbus TCP server that offers all state to the HMI/SCADA. The HMI/SCADA communicates only with the controller.
44
+ - **Actuator**: a PLC in the field and its program, not part of this project. An actuator acquires flow, pressure, temperature and pump running states, checks pressure limits, reports its own working state, and stops pumps and changes parameters on the controller's commands. An actuator is a Modbus TCP or S7 server, and the controller connects to it.
45
+
46
+ ### 3.2 Nodes and actuators
47
+
48
+ - **Node**: a measurement and control point at an end of a section. A node has its own flow, pressure, temperature and pump running states, and occupies one data area and one command area on its actuator.
49
+ - Relation between actuators and nodes: an actuator usually corresponds to one node, but may also hold two or more nodes, which may belong to different lines or sections.
50
+ - Simplification in the program: the controller treats each node as an independent actuator.
51
+ - Each entry of `actuators` in the configuration and each actuator object in the code corresponds to one node;
52
+ - Several nodes on the same actuator are written as several `actuators` entries, each with its own data area and command area; under Modbus TCP they share the IP and port;
53
+ - The controller keeps two blocks per node: the node data (NODE) and the command block (COMMAND), both sharing the Modbus unit id of the node (the node ID, see §4.1).
54
+ - So both words, "node" and "actuator", appear in the configuration and the code, but they correspond essentially one to one. When this document describes the processing of the controller it says "actuator", meaning such an object with one node per actuator.
55
+ - An actuator with `pumps` configured is called an actuator with pumps; it is the target of stop pump commands.
56
+
57
+ ### 3.3 Logical objects in the controller
58
+
59
+ The following objects exist only inside the controller, to organize actuators and aggregate states:
60
+
61
+ | Object | Description |
62
+ | --- | --- |
63
+ | Line | A pipeline, made of several sections, belonging to one controller. |
64
+ | Section | A piece of pipe with nodes at both ends: the begin actuators (`begin_nodes`) and the end actuators (`end_nodes`). The section is the basic unit of flow difference evaluation, hang-on and interlock. |
65
+ | Action record | A snapshot of the field when an interlock pump stop happens. |
66
+
67
+ Relations: controller 1-N lines, line 1-N sections, section N-N actuators (the same actuator can be a begin or end actuator in different sections).
68
+
69
+ ### 3.4 Division of evaluation and protection
70
+
71
+ | Evaluation | Where | Processing |
72
+ | --- | --- | --- |
73
+ | Flow difference over limit | Controller | Computes the flow difference per section; above WH for the delay, warns; above AH for the delay, issues the stop pump notice and counts down; when the countdown ends, shuts down the whole line. |
74
+ | Pressure over limit | Actuator | The actuator checks the pressure limits and reports `pressure_AH_F`, together with whether the pressure interlock shutdown is allowed (`pressure_SD_F`); only for actuators that allow the pressure interlock, the controller shuts down the section immediately when their pressure is in alarm and a pump in the section is running, without a countdown. |
75
+ | Hang-on | Controller | The section's `hangon_AF` (automatic hang-on) and `flow_override` (manual hang-on). It applies only to the flow difference interlock: a hung-on section does not stop pumps because of the flow difference, and a manual hang-on during the countdown interrupts the shutdown. The pressure interlock is not restricted by hang-on. |
76
+ | Input signal debouncing | Actuator | Signals reported by an actuator are debounced by the actuator; the controller neither debounces nor filters the values reported by actuators and processes the values as received. |
77
+
78
+ ### 3.5 Deployment
79
+
80
+ - One controller connects to several actuators, each with one or more nodes:
81
+ - Modbus TCP: the nodes of the same actuator share the IP and port and are distinguished by address, e.g. the data of the first node at register 0 and its commands at register 100, the next node at 200 and 300;
82
+ - S7: data and commands are in different DBs, e.g. DB1 and DB2.
83
+ - The `IP` of a controller in the configuration records the deployment address of the controller itself; the program does not read it, and the server always listens on all addresses.
84
+
85
+ ### 3.6 Ldata, Ltags and variables
86
+
87
+ The state inside the controller is of two kinds, which discussions and documents must keep clearly apart:
88
+
89
+ | Term | Meaning | Nature |
90
+ | --- | --- | --- |
91
+ | Ldata / block | Ldata is the class that holds data in a fixed layout, and a block is an instance of it; lines, sections, nodes, commands and action records each have their own block, whose layout is given by the data structure definition | The bridge between actuators, HMI and controller |
92
+ | Tag | A named entry of a block, e.g. `press_alarm_F` of a section | External interface (API) |
93
+ | Variable | An ordinary program variable on a controller object, belonging to no block | Internal implementation, free to change |
94
+
95
+ The requirements of the data blocks themselves (the validity rules of fixed layouts, access by name, change events, combined words and their bit numbers, the conversion between the internal big-endian and the device byte order) are specified by the layout-data package, see its `doc/spec.md` and `doc/spec-data-api.md`; the upward Modbus slave service (address mapping, handling of unmapped addresses) is specified by the modbus-emulator package, see its `doc/spec.md`. The controller has the following further requirements on blocks:
96
+
97
+ - **The layout is the protocol**: the same layout is both the memory image of the actuator data / command area and the register point table of the HMI (see [spec-modbus.md](spec-modbus.md)).
98
+ - **Layout validation**: at startup the controller validates all layouts; on violations it reports all of them and refuses to start; the configuration check command (see §5.6) runs the same validation.
99
+ - **Exchange with drivers**: a block exchanges data with the actuator as a whole or in groups through the Modbus TCP or S7 driver; the device byte order is converted only at this boundary, and inside the controller everything is big-endian.
100
+ - **Write unit**: the smallest unit written to an actuator is set by the protocol. Under Modbus TCP the controller uses only holding registers (function code 03 for reading, 06 / 16 for writing), and the write unit is one register; under S7 the write unit is one byte. A group write writes only the write units holding the Tags of the group.
101
+ - **Write ownership**: Tags written by the controller and Tags written by the actuator must not share a write unit, so that a write of one side does not overwrite the data of the other. Adding or adjusting Tags must follow this rule.
102
+ - **Upward publishing**: blocks are mounted on the Modbus TCP server of the controller, and the HMI reads and writes their content directly.
103
+ - **Processing and event order**: the aggregations and interlocks of the controller are evaluated in each processing on one set of inputs, and the results do not depend on the order in which change events arrive.
104
+ - **Group synchronization**: several Tags can be grouped and synchronized with the actuator as a whole.
105
+
106
+ Tags are the interface:
107
+
108
+ - Adding or removing a Tag, or changing the name, type, offset or meaning of a Tag, is a protocol change: the actuator programs and the HMI must change accordingly, and the point table must be updated.
109
+ - Protocol changes should be concentrated in the version planning, to avoid repeated changes of the point table.
110
+ - State used only inside the controller, which need not be exchanged with the actuators or the HMI, must be implemented as variables, and must not take space in a block for that (including unused bits of internal bit words such as `inner_word`).
111
+ - A proposal for new state must say whether it is a Tag or a variable; unless a layout change has been confirmed, it is a variable by default.
112
+
113
+ ## 4. Configuration requirements
114
+
115
+ - All `*.yaml` / `*.yml` files at the top level of the working directory are read and merged, and subdirectories are not read (the emulator description generated by the controller is in a subdirectory, §5.5); they are parsed as YAML 1.2, and the YAML 1.1 merge keys (`<<`) are not supported.
116
+ - Top-level keys: `controllers`, `lines`, `sections`, `actuators`.
117
+ - Controller:
118
+ - `name`, `records_size` (number of action records kept, default 10);
119
+ - `modbus_server.port`;
120
+ - Modbus unit ids are no longer configured: the unit id of a line, section or actuator is its ID, and the action record is fixed at unit id 0 (see §4.1).
121
+ - Line:
122
+ - `id`, `name`;
123
+ - `controller`: name of the controller it belongs to;
124
+ - `sections`: list of section names.
125
+ - Section:
126
+ - `id`, `name`;
127
+ - `begin_nodes`, `end_nodes`: lists of actuator names;
128
+ - `flow_diff_WH` / `flow_diff_WH_delay`: flow difference warning limit and its delay (ms);
129
+ - `flow_diff_AH` / `flow_diff_AH_delay`: flow difference alarm limit and its delay (ms);
130
+ - `action_time`: interlock countdown (ms).
131
+ - Actuator (`actuators`):
132
+ - `id`: must be a non-zero number, otherwise the program exits;
133
+ - `name`, `IP`;
134
+ - `pumps`: optional, each entry of the form `"running signal, stop output"`;
135
+ - one of `modbus_server` or `s7_server`, each able to configure the `data` and `commands` areas; the area start `start` is in bytes, and under Modbus corresponds to register `start / 2` (e.g. `start: 200` is register 100);
136
+ - `supported_commands`: list of supported commands (see the command support configuration in §5.1);
137
+ - `endian`: byte order, default `BE`.
138
+ - The configuration files are also the basis for programming the actuators; the controller takes only the parts relevant to itself:
139
+ - Actuator fields taken by the controller: `id`, `name`, `IP`, the protocol with its data / command areas, whether `pumps` is configured, the list of supported commands;
140
+ - The IDs, limits, delays and `action_time` of sections and lines are the initial values of the corresponding block;
141
+ - The other actuator fields (pressure / temperature ranges and limits, `pressure_SD`, `pressure_AI`, `temperature_AI`, `flows`, pump signal addresses) are for programming the actuators, and the controller does not take them directly;
142
+ - Actuator parameters and states follow what the actuator reports; the controller publishes them and writes them back to the actuator on HMI commands (see §5.1).
143
+
144
+ ### 4.1 ID rules
145
+
146
+ - The `id` of all lines, sections and actuators (nodes) must be distinct.
147
+ - The uniqueness applies across types: lines, sections and actuators must not repeat each other's IDs either; e.g. the ID of a section must not equal the ID of any actuator.
148
+ - Several blocks of the same object share the object's ID, which is not a duplicate. E.g. an actuator has both a node block and a command block, and both share the ID of the actuator.
149
+ - The ID is also the unit id of the object on the Modbus TCP server of the controller (see §5.5), so:
150
+ - the ID must be a valid Modbus unit id, and at least 1;
151
+ - unit id 0 is reserved for the action record.
152
+ - These rules are validated by the configuration check (see §5.6); a violation is a configuration error.
153
+
154
+ ### 4.2 Name rules
155
+
156
+ - The `name`s of controllers and actuators are all distinct: no repetition among controllers, among actuators, or between controllers and actuators.
157
+ - The name is also the name of the subdirectory of the object's files (such as the emulator description `<controller name>/emulator.yaml` of a controller, see §5.5), and repeated names would make the subdirectories collide.
158
+ - The `name`s of controllers, lines, sections and actuators are identifiers: ASCII letters, digits and `_`, not starting with a digit. The names of lines, sections and actuators also name their data areas in the emulator description (§5.5).
159
+ - These rules are validated by the configuration check (see §5.6); a violation is a configuration error.
160
+
161
+ ## 5. Functional requirements
162
+
163
+ ### 5.1 Actuators
164
+
165
+ - Read the actuator data periodically: ID, status word (communication / working OK, pump running, the states of each pump, pressure / temperature alarm enables and limit flags), temperature, pressure, flow, command response code, parameter block.
166
+ - On a communication failure or a data read failure, after the delay of the parameter `delay_protect_time`, set `comm_OK` / `work_OK` to false respectively.
167
+ - 2 s after the communication recovers, refresh the parameters in the command block with the current parameters of the actuator, so that the HMI sees the same parameters as the field.
168
+ - Command enumeration: the table below is the complete list of commands, all of which the controller must implement. The command names are used in the HMI point table (see [spec-modbus.md](spec-modbus.md) §5) and in the command support configuration of actuators; the bit is the position of the command in the command word, agreed with the actuators, and must not change.
169
+
170
+ | Bit | Command | Effect | Source |
171
+ | --- | --- | --- | --- |
172
+ | 0 | `stop_pumps` | Stop pumps | Interlock logic (see §5.2) |
173
+ | 1 | `cancel_stop` | Cancel stop, so the actuator releases the stop pump output | Interlock logic (see §5.2) |
174
+ | 2 | `horn` | Output alarm | HMI |
175
+ | 3 | `reset_horn` | Stop alarm | HMI |
176
+ | 4 | `enable_pressure_SD` | Enable the pressure interlock pump stop | HMI |
177
+ | 5 | `disable_pressure_SD` | Disable the pressure interlock pump stop | HMI |
178
+ | 6 | `read_paras` | Read parameters: refresh the parameters in the command block with the current parameters of the actuator, without sending to the actuator | HMI |
179
+ | 7 | `write_paras` | Write parameters: write the parameters in the command block to the actuator | HMI |
180
+ | 8 | `enable_pressure_alarm` | Enable the pressure alarm | HMI |
181
+ | 9 | `disable_pressure_alarm` | Disable the pressure alarm | HMI |
182
+ | 10 | `enable` | Allow the actuator to work | HMI |
183
+ | 11 | `disable` | Forbid the actuator to work | HMI |
184
+ | 12 | `reset_CPU` | Reset the actuator CPU | HMI |
185
+ | 13 | `reset_conn` | Reset the connection | HMI |
186
+
187
+ Bit 14 (`reserve`) of the command word is reserved, and bit 15 (`executing`) is a status bit; neither is a command. A new command must be added to this list first.
188
+
189
+ - Command handshake:
190
+ - After a command is set, the controller sends the command word together with the ID and the parameter block to the actuator;
191
+ - The actuator acknowledges the executed command bits with `response_code`, and the controller clears those command bits when it receives it;
192
+ - The enable / disable pressure interlock pump stop commands are cleared when the `pressure_SD_F` reported by the actuator reaches the corresponding state;
193
+ - Without an acknowledgement for 3 consecutive cycles, the command is sent again.
194
+ - Stop and cancel stop:
195
+ - Normally, after the controller issues `stop_pumps`, the actuator stops the pumps and the reported pump running state becomes false; the controller then withdraws `stop_pumps`, and `cancel_stop` is not needed;
196
+ - Abnormally, the pump running state may stay true (e.g. a faulty state signal). Even after the controller withdraws `stop_pumps`, the actuator keeps its stop pump output, which is not released because of the pump state and prevents the other pumps on the same actuator from starting;
197
+ - So when the stop command is withdrawn, the controller must send `cancel_stop` to the actuators concerned, which then release the stop pump output.
198
+ - Command support configuration: different actuators may support different commands. Each actuator lists the commands it supports (taken from the command enumeration above) in the configuration, and the controller sends an actuator only the commands it supports; the controller resets unsupported command bits directly without sending them, and the HMI sees those bits reset.
199
+ - The configuration field is `supported_commands`, whose value is a list of command names taken from the command enumeration, for example:
200
+
201
+ ```yaml
202
+ actuators:
203
+ - id: 1001
204
+ name: A1
205
+ supported_commands:
206
+ - stop_pumps
207
+ - cancel_stop
208
+ ```
209
+
210
+ - When `supported_commands` is omitted, all commands are supported by default
211
+
212
+ ### 5.2 Sections
213
+
214
+ - `comm_OK` / `work_OK`: true when all actuators of the section are OK.
215
+ - `pump_run` / `pump_change_F`: true when any actuator with pumps has a pump running / a pump in the start-stop transition.
216
+ - `press_warning_F` / `press_alarm_F`: true when any actuator has a pressure warning / alarm.
217
+ - Flow:
218
+ - `flow_begin` is the sum of the flows of the begin actuators, `flow_end` the sum of the flows of the end actuators;
219
+ - `flow_diff = flow_begin - flow_end`.
220
+ - Flow difference evaluation:
221
+ - After the flow difference stays above `flow_diff_WH` for `flow_diff_WH_delay`, `flow_warning_F` is set;
222
+ - After it stays above `flow_diff_AH` for `flow_diff_AH_delay`, `flow_alarm_F` is set.
223
+ - Protection state:
224
+ - When communication is OK, work is OK, no pump is in a start-stop transition, and the section is not hung on manually (`flow_override`), the section is in the protection state (`protect_F`);
225
+ - When any of the first three conditions fails, the section is hung on automatically (`hangon_AF`).
226
+ - Stop pump notice:
227
+ - When this section's `flow_alarm_F`, this section's `protect_F` and the `pump_run` of its line all hold, the stop pump notice (`pre_stop_notice`) is issued and the `action_time` countdown starts (`countdown`, in s);
228
+ - The pump running condition takes the line's `pump_run`, not this section's: the flow difference interlock stops the whole line in order to avoid pressurizing the buffer tanks of intermediate stations; the leaking section itself may have no running pump (e.g. driven across stations by an upstream section), and as long as a pump runs on the line, the line must be stopped. The pressure interlock stops only this section and still takes this section's `pump_run`;
229
+ - When the countdown ends and the conditions still hold, the flow interlock is executed;
230
+ - When any condition disappears during the countdown (e.g. a manual hang-on clears `protect_F`), the countdown is reset and the shutdown is interrupted.
231
+ - Interlock actions: a section records two kinds of action separately, the pressure action and the flow difference action, each set and reset on its own; the section's `action_F` is their OR.
232
+ - Flow difference interlock (stop the line): when the countdown expires, a flow difference action occurs, which records the line's `action_section_ID`, sets the line's `auto_stop_cmd`, and marks this section as the line action source (`line_action_source`). The stop command of the line applies to all sections of the line, and every section with a pump running stops its pumps;
233
+ - Pressure interlock (stop the section): when `pressure_AH_F` is true for any actuator of the section whose `pressure_SD_F` is true, and a pump of this section is running, a pressure action occurs, which records the line's `action_section_ID` and sets the section's `auto_stop_cmd`. An actuator whose `pressure_SD_F` is false only raises an alarm and does not trigger a pump stop. The pressure interlock is not restricted by hang-on (`protect_F`). For now the pressure interlock stops only this section; it may be extended to stop the line in the future;
234
+ - The section's `press_alarm_F` still aggregates `pressure_AH_F` of all actuators, for the alarm display, whether the pressure interlock is allowed or not.
235
+ - Pump stop: when an automatic / manual stop command exists on the section or its line and a pump of this section is running, a stop pump command is issued to all actuators with pumps of this section; when the command is withdrawn, a cancel stop command is issued.
236
+ - Reset:
237
+ - After all pumps of this section stop, the section's `auto_stop_cmd` / `man_stop_cmd` are cleared;
238
+ - The action state is kept during the stop, so the HMI can see the reason of the shutdown;
239
+ - Pressure action: reset when a pump of this section runs, the pressure interlock condition has disappeared, and the section's `auto_stop_cmd` has been cleared;
240
+ - Flow difference action: reset when a pump of its line runs, this section's `flow_alarm_F` has disappeared, and this section is no longer the line action source;
241
+ - The reset conditions are evaluated in each processing and not latched: if the alarm is still present when the pumps restart and disappears later, the action is reset all the same;
242
+ - After both kinds of action are reset, `action_F` is cleared; the line's `action_section_ID` is cleared if it is still this section's ID, and left alone if another section has overwritten it.
243
+ - Every time a pressure action or a flow difference action occurs (from absent to present), an action record is created (see §5.4).
244
+
245
+ ### 5.3 Lines
246
+
247
+ - `pump_run`: true when any section has a pump running;
248
+ - `alarm_F`: true when any section has a flow alarm or a pressure alarm;
249
+ - `pre_stop_notice`: true when any section is in the stop pump notice;
250
+ - `flow_override` (manual hang-on of the whole line): a line-level master switch; while set, no section of the line is protected, and after it is reset protection resumes; it does not overwrite any section's own `flow_override`, so a hang-on set on a single section stays after the line master switch is reset; the HMI should show the `flow_override` of both the line and the sections;
251
+ - After all pumps of the line stop, the line's `auto_stop_cmd` / `man_stop_cmd` are cleared;
252
+ - `man_stop_cmd` is written by the HMI, for a manual pump stop.
253
+
254
+ ### 5.4 Action records
255
+
256
+ - Content:
257
+ - Time (year / month / day / hour / minute / second), ID of the action section;
258
+ - Begin and end flows and the flow difference;
259
+ - Pressure, ID and pump running state of the actuators of the action section, in 4 fixed positions (nodes 1-4);
260
+ - Action reason: the pressure reason (`press_action`) and the flow reason (`flow_action`) take the pressure action and flow difference action states of the section at recording time (see §5.2); the record holds the actions that actually occurred, not the alarm states.
261
+ - Actuator positions:
262
+ - The 4 fixed positions keep the data structure compatible with the original PLC controller; variable-length records are not supported;
263
+ - The 4 positions do not distinguish begin and end: the actuators of the action section take nodes 1-4 in order, begin actuators first, then end actuators; e.g. with 2 begin actuators and 2 end actuators, they take nodes 1, 2 and nodes 3, 4;
264
+ - The pressure, ID and pump running state of each position come from the same actuator;
265
+ - When the section has more than 4 actuators, only the first 4 are recorded; unused positions are 0 / false.
266
+ - Persistence: appended to `action_records.csv` in the working directory, created automatically when missing.
267
+ - Browsing: the latest `records_size` records are kept in memory; the HMI writes `index` (0 is the latest) to switch the displayed record; `index = -1` means no record.
268
+
269
+ ### 5.5 Upward interface (Modbus TCP server)
270
+
271
+ - The controller listens on `controller.modbus_server.port` at address `0.0.0.0`.
272
+ - Each line, each section, each actuator and the action record take one unit id each: the unit id of a line, section or actuator is its ID (see §4.1), and the action record is fixed at unit id 0.
273
+ - In an actuator unit, the node data area starts at register 0 and the command block at register 200.
274
+ - Reading and writing holding registers, reading input registers, and reading and writing coils are supported. A write from the HMI triggers the processing of the resulting state changes immediately.
275
+ - Addresses of a unit without a data area (e.g. the gap between the node data area and the command block in an actuator unit) read as 0 and writes to them are ignored, without an exception response, so a block read across the gap still succeeds.
276
+ - When the upward service cannot start (e.g. the port is in use), the controller logs an error and exits, to be restarted by the background process management; it does not keep running without the upward service.
277
+ - The layouts are defined by `src/layouts.yaml` and must stay consistent with the HMI and the actuator programs. The complete point table is in [spec-modbus.md](spec-modbus.md).
278
+ - The emulator of the controller uses a subdirectory of the working directory named after the controller, in which the controller generates `emulator.yaml` (i.e. `<controller name>/emulator.yaml`) at every startup, overwriting the old file. It is the complete description of the upward service: all layouts, the name, layout, unit id and start byte of each data area, and the protocol, address and port of the service. Opening it, the operator sees what the upward service actually provides. The file is only for viewing, and changing it does not affect the controller.
279
+
280
+ ### 5.6 Running and operation
281
+
282
+ - The controller runs as a resident background process, independent of a login session; only one controller instance runs at a time, and starting one stops the existing instance first.
283
+ - The command-line tool `tlms` supports:
284
+ - starting with a configuration directory and a controller name (`start`), and restarting (`restart`, same as `start`);
285
+ - stopping (`stop`);
286
+ - listing the instances running in the background (`list`);
287
+ - viewing the log (`log`) and clearing the logs (`flush`);
288
+ - checking whether the configuration is valid (`check`): reads and validates the configuration in the given configuration directory, reports all errors, and does not start the controller; the validation includes the ID rules of 4.1 and the layout rules of 3.6;
289
+ - running in the foreground (`debug`) with log level debug, for debugging;
290
+ - showing the version and help.
291
+ - When the controller name is omitted, the first controller of the configuration runs.
292
+ - Logging:
293
+ - Normal logs and error logs are written to `logs/info_<date>.log` and `logs/error_<date>.log` in the working directory (a date such as `2026-11-14`), rolled daily, each file limited to 10 MB and compressed;
294
+ - When running in the foreground, the logs are also written to the console;
295
+ - The log level is set by the environment variable `LOG_LEVEL`, default `info`.
296
+ - Uncaught exceptions are only logged and do not exit the process, so that the protection keeps running.
297
+
298
+ ## 6. Performance and timing
299
+
300
+ - Main loop period 500 ms (`MAIN_PERIOD`); the flow difference delays, the countdown, the communication failure delay and the parameter refresh delay accumulate in this step.
301
+ - Driver polling period 1 s. Reconnection starts 5 s after a disconnection; the reconnect interval of Modbus TCP doubles each time up to 20 s, and returns to 5 s once the connection is stable again; S7 reconnects every 5 s at a fixed interval.
302
+ - When reads and writes with an actuator keep failing for 5 s, it is a communication failure (handled the same as a disconnection).
303
+ - Processing happens right after actuator data is read back, after HMI writes and after communication state changes: state aggregation, trigger bits, the protection state, the interlock actions and the stop command are computed completely in the same processing, and the resulting commands are sent immediately, without debounces; when the condition of a flow difference delay or of the countdown disappears, it is reset immediately.
304
+
305
+ ## 7. Implementation constraints
306
+
307
+ - Implemented in JavaScript.
308
+ - Communication with actuators must support both Modbus TCP and Siemens S7; upward, only a Modbus TCP server is offered.
309
+ - The configuration format is YAML, the action records are persisted as CSV.
310
+ - The runtime environment, dependencies, process management and build are in [design.md](design.md) §12.
@@ -0,0 +1,308 @@
1
+ # TLMS_ESD 规范说明(初稿)
2
+
3
+ > 本文根据现有代码反向整理,描述系统“做什么、为什么”。实现方式见 [design.zh-cn.md](design.zh-cn.md)。
4
+
5
+ ## 1. 目标
6
+
7
+ TLMS_ESD(Pipeline Leakage Emergency Shutdown System,管道泄漏紧急停输系统)用于输油管线的泄漏防护。管线按线、段组织,段的两端设有测控点,系统持续监视并在异常时自动停输:
8
+
9
+ - **输差监视**:每一段的输差(首端流量合计减末端流量合计)大于警告值(WH)时报警,大于报警值(AH)时停输整条线。停输前有倒计时,倒计时期间可以人为中断。
10
+ - **压力监视**:每个测控点的压力大于警告值(WH)时报警,大于报警值(AH)时停输所在段,没有倒计时。压力停输可按测控点单独允许或禁止。
11
+ - **挂起**:输差防护以段为单位。段挂起后,系统不再因输差对该段执行停泵,但报警照常。通信中断、测控点工作异常(如测量设备故障)、起停泵后的一段时间等情况由系统自动挂起;人工检修测量设备时,必须手动挂起该段,避免误动作。挂起不影响压力停输。
12
+ - **集中监控与追溯**:汇总线、段、测控点的状态,提供给 HMI/SCADA 监视和操作,并记录每次联锁停输动作。
13
+
14
+ 本项目只实现其中的控制器程序,测控点一侧的程序由执行器实现(见§3)。
15
+
16
+ ## 2. 范围
17
+
18
+ ### 2.1 包含
19
+
20
+ - 读取 YAML 配置,按控制器名称运行其中一个控制器;
21
+ - 与执行器通信:Modbus TCP、Siemens S7 两种协议;
22
+ - 段级流量差报警、压力报警汇总、联锁停泵、取消停泵;
23
+ - 线级人工挂起(`flow_override`)、报警汇总、自动/手动停泵命令;
24
+ - 执行器参数的发布与写回、执行器命令下发;
25
+ - 联锁动作记录(CSV 持久化,经 Modbus 浏览最近 N 条);
26
+ - 日志记录;
27
+ - 命令行工具 `tlms`,用于后台运行和管理控制器实例。
28
+
29
+ ### 2.2 不包含
30
+
31
+ - 执行器的 PLC 程序(压力越限判断、泵的实际启停由执行器完成);
32
+ - HMI 画面;
33
+ - 线级流量差(`LINE.flow_diff` 保留,未实现)。
34
+
35
+ ## 3. 术语与对象模型
36
+
37
+ ### 3.1 核心术语
38
+
39
+ 本系统只有两类运行实体:
40
+
41
+ - **控制器(controller)**:即本程序。一个控制器是一个 TLMS 进程,按配置管理若干条线,周期采集执行器数据,做输差判断和联锁,同时作为 Modbus TCP 服务端,把全部状态提供给 HMI/SCADA。HMI/SCADA 只与控制器通信。
42
+ - **执行器(actuator)**:现场的 PLC 及其程序,不属于本项目。执行器负责采集流量、压力、温度和泵运行状态,判断压力越限,报告自身工作状态,并按控制器的命令停泵、修改参数。执行器作为 Modbus TCP 或 S7 的服务端,由控制器主动连接。
43
+
44
+ ### 3.2 节点与执行器
45
+
46
+ - **节点(node)**:段两端的测控点。一个节点有自己的流量、压力、温度和泵运行状态,在执行器上占用一组数据区和一组命令区。
47
+ - 执行器与节点的关系:一个执行器通常对应一个节点,也可以包含两个或以上的节点,这些节点可以属于不同的线或段。
48
+ - 程序中的简化:控制器把每个节点当作一个独立的执行器处理。
49
+ - 配置中 `actuators` 的每一项、代码中的每个 actuator 对象都对应一个节点;
50
+ - 同一执行器上的多个节点写成多个 `actuators` 项,各自配置数据区和命令区,Modbus TCP 下共用 IP 和端口;
51
+ - 控制器为每个节点维护两个 block:节点数据(NODE)和命令块(COMMAND),两者共用该节点的 Modbus 单元号(即节点 ID,见 §4.1)。
52
+ - 因此在配置和代码中“节点”与“执行器”两个词都会出现,但基本一一对应。本文在描述控制器的处理时统一称“执行器”,指的就是这种一个节点对应一个执行器的对象。
53
+ - 配置了 `pumps` 的执行器称为带泵执行器,是停泵命令的对象。
54
+
55
+ ### 3.3 控制器内的逻辑对象
56
+
57
+ 以下对象只存在于控制器内部,用于组织执行器并汇总状态:
58
+
59
+ | 对象 | 说明 |
60
+ | --- | --- |
61
+ | 线(line) | 一条管线,由若干段组成,属于一个控制器。 |
62
+ | 段(section) | 一段管道,两端为节点:首端执行器(`begin_nodes`)和末端执行器(`end_nodes`)。段是输差判断、挂起和联锁的基本单位。 |
63
+ | 动作记录(action record) | 一次联锁停泵发生时的现场快照。 |
64
+
65
+ 关系:控制器 1—N 线,线 1—N 段,段 N—N 执行器(同一执行器可在不同段中作为首端或末端)。
66
+
67
+ ### 3.4 判断与保护的分工
68
+
69
+ | 判断 | 位置 | 处理 |
70
+ | --- | --- | --- |
71
+ | 输差超限 | 控制器 | 按段计算输差;超过 WH 并持续延时后警告,超过 AH 并持续延时后发出停泵预告并倒计时,倒计时结束后停输整条线。 |
72
+ | 压力超限 | 执行器 | 执行器判断压力越限并上报 `pressure_AH_F`,同时上报是否允许压力联锁停输(`pressure_SD_F`);控制器只对允许压力联锁的执行器,在其压力报警且段内有泵运行时立即停输所在段,没有倒计时。 |
73
+ | 挂起 | 控制器 | 即段的 `hangon_AF`(自动挂起)和 `flow_override`(人工挂起),只作用于输差联锁:段挂起时不因输差停泵,倒计时期间人工挂起即中断停输。压力联锁不受挂起约束。 |
74
+ | 输入信号去抖 | 执行器 | 执行器上报的信号由执行器去抖;控制器不对执行器上报的值做去抖或滤波,按收到的值处理。 |
75
+
76
+ ### 3.5 部署形态
77
+
78
+ - 一个控制器连接多个执行器,每个执行器上有一个或多个节点:
79
+ - Modbus TCP:同一执行器上的节点共用 IP 和端口,按地址区分,例如第一个节点的数据位于寄存器 0、命令位于寄存器 100,下一个节点位于 200 和 300;
80
+ - S7:数据和命令分别位于不同的 DB,例如 DB1 和 DB2。
81
+ - 控制器配置中的 `IP` 用于记录控制器自身的部署地址,程序不读取,服务端固定监听所有地址。
82
+
83
+ ### 3.6 Ldata、Ltag 与变量
84
+
85
+ 控制器内的状态分为两类,讨论和文档中必须明确区分:
86
+
87
+ | 术语 | 含义 | 性质 |
88
+ | --- | --- | --- |
89
+ | Ldata / block | Ldata 是按固定布局存放数据的类,block 是它的实例;线、段、节点、命令、动作记录各有自己的 block,布局由数据结构定义给出 | 执行器、HMI 与控制器之间的桥梁 |
90
+ | Tag | block 中的一个具名条目,例如段的 `press_alarm_F` | 对外接口(API) |
91
+ | 变量 | 控制器对象上的普通程序变量,不属于任何 block | 内部实现,可自由调整 |
92
+
93
+ 数据块本身的要求(固定布局的合法规则、按名访问、变化事件、组合字及其位号、内部大端与设备字节序的转换)由 layout-data 包规定,见其 `doc/spec.md` 和 `doc/spec-data-api.md`;对上的 Modbus 从站服务(地址映射、未映射地址的处理)由 modbus-emulator 包规定,见其 `doc/spec.md`。控制器对 block 另有以下要求:
94
+
95
+ - **布局即协议**:同一布局同时是执行器数据区 / 命令区的内存映像和 HMI 的寄存器点表(见 [spec-modbus.zh-cn.md](spec-modbus.zh-cn.md))。
96
+ - **布局校验**:控制器启动时校验全部布局,发现违规时报告全部违规项并拒绝启动;配置检查命令(见 §5.6)执行同样的校验。
97
+ - **与驱动交换**:block 经 Modbus TCP 或 S7 驱动与执行器整块或分组交换数据;设备字节序只在这个边界上转换,控制器内部统一按大端存放。
98
+ - **写入单元**:向执行器写入的最小单位由协议决定。Modbus TCP 下控制器只使用保持寄存器(读用功能码 03,写用 06 / 16),写入单元为一个寄存器;S7 下写入单元为一个字节。分组写入时只写组内 Tag 所在的写入单元。
99
+ - **写入所有权**:由控制器写入的 Tag 与由执行器写入的 Tag 不得共用同一个写入单元,避免一方的写入覆盖另一方的数据。新增或调整 Tag 时须遵守这一规则。
100
+ - **对上发布**:block 挂载到控制器的 Modbus TCP 服务端,HMI 直接读写其内容。
101
+ - **处理与事件顺序**:控制器的汇总与联锁在每次处理中基于同一份输入求值,结果与变化事件到达顺序无关。
102
+ - **分组同步**:可以把若干 Tag 编为一组,作为一个整体与执行器同步。
103
+
104
+ Tag 即接口:
105
+
106
+ - 增加、删除 Tag,或改变 Tag 的名称、类型、偏移、含义,都属于协议变更,执行器程序和 HMI 必须同步修改,并须更新点表。
107
+ - 协议变更应集中安排在版本规划中,避免点表反复变动。
108
+ - 只在控制器内部使用、不需要与执行器或 HMI 交换的状态,应当用变量实现,不得为此占用 block 空间(包括 `inner_word` 等内部位字的空位)。
109
+ - 提出新增状态时,须写明是 Tag 还是变量;未经确认需要变更布局的,默认用变量。
110
+
111
+ ## 4. 配置要求
112
+
113
+ - 工作目录本层的所有 `*.yaml` / `*.yml` 文件都会被读取并合并,子目录不读取(控制器生成的模拟器描述在子目录中,§5.5);按 YAML 1.2 解析,不支持 YAML 1.1 的合并键(`<<`)。
114
+ - 顶层键:`controllers`、`lines`、`sections`、`actuators`。
115
+ - 控制器:
116
+ - `name`、`records_size`(动作记录保留条数,默认 10);
117
+ - `modbus_server.port`;
118
+ - 不再配置 Modbus 单元号:线、段、执行器的单元号直接取各自的 ID,动作记录固定为单元号 0(见 §4.1)。
119
+ - 线:
120
+ - `id`、`name`;
121
+ - `controller`:所属控制器名称;
122
+ - `sections`:段名称列表。
123
+ - 段:
124
+ - `id`、`name`;
125
+ - `begin_nodes`、`end_nodes`:执行器名称列表;
126
+ - `flow_diff_WH` / `flow_diff_WH_delay`:流量差警告上限及延时(ms);
127
+ - `flow_diff_AH` / `flow_diff_AH_delay`:流量差报警上限及延时(ms);
128
+ - `action_time`:联锁倒计时(ms)。
129
+ - 执行器(`actuators`):
130
+ - `id`:必须是非零数字,否则程序退出;
131
+ - `name`、`IP`;
132
+ - `pumps`:可选,每项形如 `"运行信号, 停止输出"`;
133
+ - `modbus_server` 或 `s7_server` 二选一,可分别配置 `data` 与 `commands` 区域;区域起点 `start` 以字节计,Modbus 下对应寄存器 `start / 2`(例如 `start: 200` 即寄存器 100);
134
+ - `supported_commands`:支持的命令列表(见 §5.1 命令支持配置);
135
+ - `endian`:字节序,默认 `BE`。
136
+ - 配置文件同时是执行器编程的依据,控制器只采用其中与自身有关的部分:
137
+ - 控制器采用的执行器字段:`id`、`name`、`IP`、通信协议及数据 / 命令区、是否配置了 `pumps`、支持的命令列表;
138
+ - 段与线的 ID、限值、延时、`action_time` 作为对应 block 的初始值;
139
+ - 其余执行器字段(压力 / 温度量程与限值、`pressure_SD`、`pressure_AI`、`temperature_AI`、`flows`、泵信号地址)用于执行器编程,控制器不直接采用;
140
+ - 执行器参数和状态以执行器上报为准,控制器负责对外发布,并按 HMI 的命令写回执行器(见 §5.1)。
141
+
142
+ ### 4.1 ID 规则
143
+
144
+ - 所有线、段、执行器(节点)的 `id` 必须互不相同。
145
+ - 唯一性跨类型要求:线、段、执行器之间也不能重复,例如一个段的 ID 不能等于任何执行器的 ID。
146
+ - 同一对象有多个 block 时共用该对象的 ID,不算重复。例如一个执行器既有节点 block 又有命令块,两者共用该执行器的 ID。
147
+ - ID 同时作为该对象在控制器 Modbus TCP 服务端上的单元号(unit id,见 §5.5),因此:
148
+ - ID 必须是合法的 Modbus 单元号,且不小于 1;
149
+ - 单元号 0 固定留给动作记录。
150
+ - 以上规则由配置检查(见 §5.6)校验;违反时视为配置错误。
151
+
152
+ ### 4.2 名称规则
153
+
154
+ - 控制器与执行器的 `name` 互不相同:控制器之间、执行器之间、控制器与执行器之间都不能重复。
155
+ - 名称同时作为该对象的文件子目录名(如控制器的模拟器描述 `<控制器名>/emulator.yaml`,见 §5.5),重复的名称会使子目录冲突。
156
+ - 控制器、线、段、执行器的 `name` 是标识符:由 ASCII 字母、数字和 `_` 组成,不以数字开头。线、段、执行器的名称同时作为其数据区在模拟器描述中的名称(§5.5)。
157
+ - 以上规则由配置检查(见 §5.6)校验;违反时视为配置错误。
158
+
159
+ ## 5. 功能需求
160
+
161
+ ### 5.1 执行器
162
+
163
+ - 周期读取执行器数据:ID、状态字(通信 / 工作正常、泵运行、各泵状态、压力 / 温度报警使能与越限标志)、温度、压力、流量、命令响应码、参数块。
164
+ - 通信中断或数据读取失败时,经过参数 `delay_protect_time` 的延时后,分别将 `comm_OK` / `work_OK` 置为 false。
165
+ - 通信恢复后,2 s 后用执行器当前参数刷新命令块中的参数,保证 HMI 看到的参数与现场一致。
166
+ - 命令枚举:下表是命令的完整清单,控制器必须全部实现。命令名用于 HMI 点表(见 [spec-modbus.zh-cn.md](spec-modbus.zh-cn.md) §5)和执行器的命令支持配置;位号是命令在命令字中的位置,与执行器约定一致,不得改变。
167
+
168
+ | 位 | 命令 | 作用 | 来源 |
169
+ | --- | --- | --- | --- |
170
+ | 0 | `stop_pumps` | 停泵 | 联锁逻辑(见 §5.2) |
171
+ | 1 | `cancel_stop` | 取消停泵,让执行器解除停泵输出 | 联锁逻辑(见 §5.2) |
172
+ | 2 | `horn` | 输出报警 | HMI |
173
+ | 3 | `reset_horn` | 停止报警 | HMI |
174
+ | 4 | `enable_pressure_SD` | 允许压力联锁停泵 | HMI |
175
+ | 5 | `disable_pressure_SD` | 取消压力联锁停泵 | HMI |
176
+ | 6 | `read_paras` | 读取参数:用执行器当前参数刷新命令块中的参数,不发送给执行器 | HMI |
177
+ | 7 | `write_paras` | 写参数:把命令块中的参数写入执行器 | HMI |
178
+ | 8 | `enable_pressure_alarm` | 允许压力报警 | HMI |
179
+ | 9 | `disable_pressure_alarm` | 禁止压力报警 | HMI |
180
+ | 10 | `enable` | 允许该执行器工作 | HMI |
181
+ | 11 | `disable` | 禁止该执行器工作 | HMI |
182
+ | 12 | `reset_CPU` | 重置执行器 CPU | HMI |
183
+ | 13 | `reset_conn` | 重置连接 | HMI |
184
+
185
+ 命令字的位 14(`reserve`)保留,位 15(`executing`)是状态位,都不是命令。新增命令必须先加入本清单。
186
+
187
+ - 命令握手:
188
+ - 命令置位后,控制器把命令字连同 ID 和参数块发送给执行器;
189
+ - 执行器用 `response_code` 应答已执行的命令位,控制器收到后清除对应命令位;
190
+ - 允许 / 取消压力联锁停泵命令,在执行器上报的 `pressure_SD_F` 变为对应状态时清除;
191
+ - 连续 3 个周期没有应答时,重新发送命令。
192
+ - 停泵与取消停泵的关系:
193
+ - 正常情况下,控制器下达 `stop_pumps` 后,执行器停泵,上报的泵运行状态变为 false,控制器即收回 `stop_pumps`,不需要 `cancel_stop`;
194
+ - 异常情况下,泵运行状态可能一直为 true(例如状态信号故障)。这时即使控制器收回了 `stop_pumps`,执行器一侧仍保持停泵输出,而且这个输出不会因泵状态而撤销,会阻碍同一执行器上其他泵启泵;
195
+ - 因此停泵命令撤销时,控制器必须向相关执行器发送 `cancel_stop`,由执行器解除停泵输出。
196
+ - 命令支持配置:不同执行器支持的命令可能不同。每个执行器在配置中列出自己支持的命令(取自上面的命令枚举),控制器只向执行器发送它支持的命令;不支持的命令位由控制器直接复位,不发送,HMI 看到该命令位被复位。
197
+ - 配置字段为 `supported_commands`,值是命令名列表,命令名取自命令枚举,例如:
198
+
199
+ ```yaml
200
+ actuators:
201
+ - id: 1001
202
+ name: A1
203
+ supported_commands:
204
+ - stop_pumps
205
+ - cancel_stop
206
+ ```
207
+
208
+ - 省略 `supported_commands` 时的默认值为支持全部命令
209
+
210
+ ### 5.2 段
211
+
212
+ - `comm_OK` / `work_OK`:段内所有执行器都正常时为 true。
213
+ - `pump_run` / `pump_change_F`:任一带泵执行器有泵运行 / 泵处于启停过渡期时为 true。
214
+ - `press_warning_F` / `press_alarm_F`:任一执行器压力警告 / 报警时为 true。
215
+ - 流量:
216
+ - `flow_begin` 为首端执行器流量之和,`flow_end` 为末端执行器流量之和;
217
+ - `flow_diff = flow_begin - flow_end`。
218
+ - 流量差判定:
219
+ - 流量差持续超过 `flow_diff_WH` 达到 `flow_diff_WH_delay` 后,`flow_warning_F` 置位;
220
+ - 持续超过 `flow_diff_AH` 达到 `flow_diff_AH_delay` 后,`flow_alarm_F` 置位。
221
+ - 保护状态:
222
+ - 当通信正常、工作正常、无泵启停过渡,且未被手动挂起(`flow_override`)时,段处于保护状态(`protect_F`);
223
+ - 前三个条件中任一不满足时,自动挂起(`hangon_AF`)。
224
+ - 停泵预告:
225
+ - 本段 `flow_alarm_F`、本段 `protect_F` 与所属线的 `pump_run` 同时成立时,发出停泵预告(`pre_stop_notice`),并开始 `action_time` 倒计时(`countdown`,单位 s);
226
+ - 泵运行条件取线的 `pump_run`,而不是本段的:输差联锁停整条线,目的是避免中间站缓冲罐带压;泄漏段本身可能没有运行的泵(例如由上游段跨站驱动),只要线上有泵运行就应当停线。压力联锁只停本段,仍取本段的 `pump_run`;
227
+ - 倒计时结束仍满足条件时,执行流量联锁;
228
+ - 倒计时期间任一条件消失(例如人工挂起使 `protect_F` 失效),倒计时清零,停输被中断。
229
+ - 联锁动作:段分别记录两类动作,即压力动作和输差动作,两者各自置位、各自复位;段的 `action_F` 取两者的“或”。
230
+ - 输差联锁(停线):倒计时结束时发生输差动作,记录线的 `action_section_ID`,置位线的 `auto_stop_cmd`,并标记本段为线动作源(`line_action_source`)。线的停泵命令作用于线内所有段,凡有泵运行的段都会停泵;
231
+ - 压力联锁(停段):段内任一 `pressure_SD_F` 为真的执行器 `pressure_AH_F` 为真,且本段有泵运行时,发生压力动作,记录线的 `action_section_ID`,置位段的 `auto_stop_cmd`。`pressure_SD_F` 为假的执行器只报警,不触发停泵。压力联锁不受挂起(`protect_F`)约束。目前压力联锁只停本段,将来可能扩展为停线;
232
+ - 段的 `press_alarm_F` 仍汇总全部执行器的 `pressure_AH_F`,用于报警显示,不论是否允许压力联锁。
233
+ - 停泵:段或所属线上存在自动 / 手动停泵命令,且本段有泵运行时,向本段所有带泵执行器下发停泵命令;命令撤销时下发取消停泵命令。
234
+ - 复位:
235
+ - 本段泵全部停止后,清除段的 `auto_stop_cmd` / `man_stop_cmd`;
236
+ - 停泵期间保留动作状态,便于 HMI 查看停输原因;
237
+ - 压力动作:本段有泵运行、压力联锁条件已消失、且段的 `auto_stop_cmd` 已清除时复位;
238
+ - 输差动作:所属线有泵运行、本段 `flow_alarm_F` 已消失、且本段不再是线动作源时复位;
239
+ - 复位条件每次处理都判断,不锁存:泵重新启动时报警仍在,之后报警消失,动作同样复位;
240
+ - 两类动作都复位后,`action_F` 清除;线的 `action_section_ID` 仍为本段 ID 时清零,已被其他段改写时不动。
241
+ - 压力动作或输差动作每次发生(由无到有)都生成一条动作记录(见 §5.4)。
242
+
243
+ ### 5.3 线
244
+
245
+ - `pump_run`:任一段有泵运行时为 true;
246
+ - `alarm_F`:任一段流量报警或压力报警时为 true;
247
+ - `pre_stop_notice`:任一段处于停泵预告时为 true;
248
+ - `flow_override`(全线人工挂起):线级总闸,置位时线内所有段均不保护,复位后恢复;它不改写任何段自己的 `flow_override`,因此各段单独设置的挂起在线总闸复位后依然保持;HMI 应同时显示线与段的 `flow_override`;
249
+ - 线内泵全部停止后,清除线的 `auto_stop_cmd` / `man_stop_cmd`;
250
+ - `man_stop_cmd` 由 HMI 写入,用于手动停泵。
251
+
252
+ ### 5.4 动作记录
253
+
254
+ - 内容:
255
+ - 时间(年 / 月 / 日 / 时 / 分 / 秒)、动作段 ID;
256
+ - 首末端流量及流量差;
257
+ - 动作段执行器的压力、ID 和泵运行状态,固定 4 个位置(节点 1–4);
258
+ - 动作原因:压力原因(`press_action`)、流量原因(`flow_action`)分别取记录时段的压力动作、输差动作状态(见 §5.2),记录的是实际发生的动作,而不是报警状态。
259
+ - 执行器位置:
260
+ - 固定 4 个位置是为了与原 PLC 控制器的数据结构兼容,不支持变长记录;
261
+ - 4 个位置不区分首端和末端:动作段的执行器按先首端、后末端的顺序依次占用节点 1–4,例如 2 个首端执行器和 2 个末端执行器,分别占用节点 1、2 和节点 3、4;
262
+ - 每个位置的压力、ID、泵运行状态都取自同一个执行器;
263
+ - 段内执行器超过 4 个时,只记录前 4 个;未占用的位置为 0 / false。
264
+ - 持久化:追加写入工作目录下的 `action_records.csv`,文件不存在时自动创建。
265
+ - 浏览:内存中保留最近 `records_size` 条,HMI 写入 `index`(0 为最新)即可切换显示的记录;`index = -1` 表示无记录。
266
+
267
+ ### 5.5 对上接口(Modbus TCP 服务端)
268
+
269
+ - 控制器在 `controller.modbus_server.port` 上监听,地址为 `0.0.0.0`。
270
+ - 每条线、每个段、每个执行器、动作记录各占一个单元号(unit id):线、段、执行器的单元号就是各自的 ID(见 §4.1),动作记录固定为单元号 0。
271
+ - 执行器单元中,从寄存器 0 开始是节点数据区,从寄存器 200 开始是命令块。
272
+ - 支持读写保持寄存器、读输入寄存器、读写线圈。HMI 的写入会立即触发相应的状态变化处理。
273
+ - 单元内没有数据区的地址(例如执行器单元中节点数据区与命令块之间的空档)读为 0,写入被忽略,不应答异常,因此跨越空档的整块读取仍然成功。
274
+ - 对上服务无法启动(例如端口被占用)时,控制器记录错误并退出,由后台进程管理重新启动;不在没有对上服务的情况下继续运行。
275
+ - 各布局由 `src/layouts.yaml` 定义,必须与 HMI 及执行器程序保持一致。完整点表见 [spec-modbus.zh-cn.md](spec-modbus.zh-cn.md)。
276
+ - 控制器的模拟器使用工作目录下以控制器名命名的子目录,控制器每次启动时在其中生成 `emulator.yaml`(即 `<控制器名>/emulator.yaml`),覆盖旧文件。它是对上服务的完整描述:全部布局、每个数据区的名称、布局、单元号和起始字节,以及服务的协议、地址和端口。运行方打开它就能看到对上服务实际提供的内容。这个文件只供查看,修改它不影响控制器。
277
+
278
+ ### 5.6 运行与运维
279
+
280
+ - 控制器以后台常驻进程运行,不依赖登录会话;同一时间只运行一个控制器实例,启动时先停止已有实例。
281
+ - 提供命令行工具 `tlms`,支持:
282
+ - 指定配置目录和控制器名称启动(`start`),以及重启(`restart`,同 `start`);
283
+ - 停止(`stop`);
284
+ - 列出后台运行的实例(`list`);
285
+ - 查看日志(`log`)和清空日志(`flush`);
286
+ - 检查配置是否有效(`check`):读取指定配置目录下的配置并校验,报告全部错误,不启动控制器;校验内容包括 4.1 的 ID 规则和 3.6 的布局规则;
287
+ - 前台运行(`debug`),日志级别为 debug,用于调试;
288
+ - 显示版本号和帮助。
289
+ - 控制器名称省略时,运行配置中的第一个控制器。
290
+ - 日志:
291
+ - 普通日志和错误日志分别写入工作目录下的 `logs/info_<日期>.log` 与 `logs/error_<日期>.log`(日期形如 `2026-11-14`),按天滚动,单个文件上限 10 MB 并压缩;
292
+ - 前台运行时同时输出到控制台;
293
+ - 日志级别由环境变量 `LOG_LEVEL` 控制,默认 `info`。
294
+ - 未捕获的异常只记录日志,不退出进程,以保证保护功能持续运行。
295
+
296
+ ## 6. 性能与时序
297
+
298
+ - 主循环周期 500 ms(`MAIN_PERIOD`),流量差延时、倒计时、通信中断延时和参数刷新延时都以此为步长累计。
299
+ - 驱动轮询周期 1 s。断线后 5 s 开始重连;Modbus TCP 的重连间隔逐次加倍,最长 20 s,连接恢复稳定后回到 5 s;S7 固定每 5 s 重连。
300
+ - 与执行器的读写持续失败 5 s,视为通信故障(与断线同等处理)。
301
+ - 执行器数据读回、HMI 写入和通信状态变化后立即处理:状态汇总、触发位、保护状态、联锁动作和停泵命令在同一次处理中算完,由此产生的命令立即发出,不设防抖;流量差延时与倒计时的条件消失时立即复位。
302
+
303
+ ## 7. 实现约束
304
+
305
+ - 使用 JavaScript 实现。
306
+ - 与执行器通信须支持 Modbus TCP 和 Siemens S7 两种协议;对上只提供 Modbus TCP 服务端。
307
+ - 配置文件格式为 YAML,动作记录持久化格式为 CSV。
308
+ - 运行环境、依赖库、进程管理和构建方式见 [design.zh-cn.md](design.zh-cn.md) §12。