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/design.md ADDED
@@ -0,0 +1,691 @@
1
+ # TLMS_ESD Design
2
+
3
+ > English version of [design.zh-cn.md](design.zh-cn.md), the primary Chinese version. When the two differ, update both.
4
+ >
5
+ > This document describes how the system works: architecture, data structures, algorithms and internal mechanisms. For the requirements see [spec.md](spec.md), for the programming interface of Ldata / Ltag see `doc/spec-data-api.md` of the layout-data package.
6
+
7
+ ## 1. Modules
8
+
9
+ | Path | Responsibility |
10
+ | --- | --- |
11
+ | `src/cli.js` | The `tlms` command line: parses arguments, calls pm2 or directly `import('./main.js')`. |
12
+ | `src/main.js` | Process entry: reads the configuration, builds the controller, provides the real drivers reused per connection, starts the Modbus server and the scan. |
13
+ | `src/runtime.js` | `build_runtime`: uses the Ldata already mounted on the object graph, calls each `*_init`, creates the scan scheduler and declares all rules, and provides `start` / `stop`. The drivers are provided by the caller through `get_drivers`. |
14
+ | `src/gcl.js` | YAML loader (`yaml` library, YAML 1.2), keeping source line information. |
15
+ | `src/config.js` | Merges several configuration documents, fills in defaults, builds the name and ID indexes, converts the `supported_commands` of actuators into command mask words. |
16
+ | `src/init.js` | `prepare_controller`: builds the runtime object graph for the selected controller; `init_controller`: builds the object graph, writes the emulator description file, constructs the emulator and mounts the Ldata on the object graph (§4.4). |
17
+ | `src/description.js` | `build_description`: generates the emulator description from the object graph; `write_description`: writes the description as a file (§4.4). |
18
+ | `src/node_proc.js` / `src/section_proc.js` / `src/line_proc.js` | Initialization (log handlers, IO binding) and rule declarations of actuators (nodes), sections and lines. |
19
+ | `src/action_record.js` | Action records: CSV reading and writing. |
20
+ | `src/action_record_proc.js` | The rule of the action record: browsing records by index. |
21
+ | `src/scan.js` | The scan scheduler `Scheduler` (§5). |
22
+ | `src/rules.js` | Rules: `derive` / `act` declarations, ordering and startup checks, `Ticker`, `on_delay` / `off_delay` (§6). |
23
+ | `src/drivers/` | `Base_Driver`, `MTClient` (Modbus TCP client), `S7Client`, and the IO binding `binding.js` (§4.5). The upward server comes from the `modbus-emulator` package (§4.4). |
24
+ | `layout-data` (external package) | Data layer (§3): `Ldata` / `Ltag`, layout compilation and validation, change detection, byte order conversion. |
25
+ | `src/layouts.yaml` | Layout descriptions of LINE, SECTION, NODE, COMMAND, RECORD. |
26
+ | `src/layouts.js` | Exports the path of `layouts.yaml`, the registration scope name of the layouts and the fragments the business needs. |
27
+ | `src/layout_types.d.ts` | Type declarations generated from the layouts (`pnpm gen:types`). |
28
+ | `src/util.js` | log4js logging, `Object.mixin`. |
29
+
30
+ ## 2. Startup
31
+
32
+ 1. `cli.js` first calls `process.chdir(--path)`, then does one of:
33
+ - `start`: `pm2 delete tlms_esd`, then `pm2 start main.js -- <controller>` with `TLMS=controller` set, so that the logs do not go to the console;
34
+ - `debug`: rewrites `process.argv[2]`, sets `LOG_LEVEL=debug`, then imports `main.js` dynamically.
35
+ 2. `main.js` calls `read_config(process.cwd())`:
36
+ 1. `readdir` lists all `*.ya?ml` at the top level of the working directory, without reading subdirectories (the description file generated by §4.4 is in a subdirectory);
37
+ 2. each file is parsed into a JS object by `GCL.load`;
38
+ 3. each document is processed by `add_conf`.
39
+ 3. `add_conf` stores each object both in an array (`push`) and as a property of the same array (`[name]`, lines / sections / actuators also `[ID<id>]`), so `cfg_*` can be iterated and looked up by key. Processing of actuators:
40
+ - parses the `pumps` strings;
41
+ - normalizes `modbus_server` / `s7_server` into `{data, commands, endian, ...}` with defaults;
42
+ - when the pressure and temperature limits are missing, takes the range limits;
43
+ - computes the command mask word `command_mask` from `supported_commands` (§14.1).
44
+ 4. After all documents are merged, lines are linked to controllers and sections to lines by name (objects referencing each other).
45
+ 5. `init_controller(name, process.cwd())` (§4.4):
46
+ 1. `prepare_controller(name)`:
47
+ 1. selects the controller (the first one when empty or 0);
48
+ 2. builds new, reduced runtime objects `line` / `section` / `actuator`;
49
+ 3. the `driver_info` of an actuator carries the protocol, the address and the data / command areas;
50
+ 4. actuators are also put into `section.begin_nodes` / `end_nodes` / `pump_nodes` by begin, end and pump station;
51
+ 5. fixes the block names of the data blocks;
52
+ 2. generates the emulator description from the object graph and writes it as `<controller name>/emulator.yaml` in the working directory;
53
+ 3. constructs the emulator and loads that file; the emulator registers the layouts and creates all Ldata;
54
+ 4. mounts the Ldata on the object graph;
55
+ 5. when the controller is not found, returns `undefined`, and `main.js` logs an error; when the description is invalid, throws an error with `errors`, and `main.js` writes each to the error log and exits with exit code 1.
56
+ 6. `run_controller`:
57
+ 1. initializes the action record with the mounted record block;
58
+ 2. calls `build_runtime` (`runtime.js`):
59
+ 1. calls each `*_init` in the order line -> section -> actuator; the drivers of the actuators are provided by `get_drivers` of `main.js`, reused per connection;
60
+ 2. creates the scan scheduler (§5), registers all blocks, the data Bindings of the actuators (with the input group `data_payload`) and the write-only command Bindings;
61
+ 3. after the object graph is built, calls `node_rules` / `section_rules` / `line_rules` in the order actuators -> sections -> lines to declare the rules (§7, §8, §9), then declares the rule of the action record (§10) and the command masking rule of each actuator (§14.1), then `prepare()` orders and checks;
62
+ 4. the `write` event of each block registered with the scheduler is wired to `request_scan()` (§3.5);
63
+ 3. starts the Modbus TCP server and waits until it is ready; when it fails to start (e.g. the port is in use), logs an error and exits with exit code 1, to be restarted by pm2;
64
+ 4. `runtime.start()` first runs an initial scan (computing all derived values), then starts the periodic tick (`MAIN_PERIOD = 500`); rule errors are written to the log through the `on_error` of the scheduler.
65
+
66
+ ## 3. Data layer (the layout-data package)
67
+
68
+ The terminology of Ldata (an instance written block) and Ltag and the requirements of the controller on them are in spec §3.6, the requirements of the data blocks themselves in the spec of layout-data. The data layer is implemented in the separate `layout-data` package: structured, reactive, buffer-based data blocks, tag access by name, layout compilation and validation, change detection, device byte order conversion; its spec and design are in `doc/spec.md`, `doc/spec-data-api.md` (programming interface) and `doc/design.md` of that package. This section describes only how this project uses it.
69
+
70
+ ### 3.1 Component boundary
71
+
72
+ - This project gets the interface of `layout-data` (`Ldata`, `Ltag`, `create_scope`, `get_scope`, `yaml`, `desc_file` and their types) through `import ... from "modbus-emulator"`: modbus-emulator forwards these interfaces, the sources and tests do not import `layout-data`, the process holds only one copy and only one set of registration scopes; ESLint forbids importing `layout-data` and its subpaths. Type generation is a development tool of layout-data (the `layout-types` command) that modbus-emulator does not forward, so `layout-data` is listed as a development dependency at the exact version modbus-emulator depends on, used only for this command and for the `Ldata` type import in the generated file. There is no `src/typed_data/` any more; at build time rolldown bundles modbus-emulator together with the `layout-data` it depends on into `main.js`;
73
+ - The package does not depend on the configuration, business processing, layouts or logger of this project, and throws on errors: layout errors are thrown when the emulator loads the description, and `main.js` logs them and exits (§3.2);
74
+ - The upward server (`Unit_Map`, handler, Modbus TCP service) is in the separate `modbus-emulator` package (§4.4).
75
+
76
+ ### 3.2 Layout definitions (`src/layouts.yaml`)
77
+
78
+ - The format of layout descriptions (YAML 1.2, item tables, `coupling`, `includes`, item fields, types, initial value rules, the Bool position rule, layout validation) is in the spec and design document of layout-data; this project's layout file is `src/layouts.yaml`: the root key `layouts` lists the layout names `LINE`, `SECTION`, `NODE`, `COMMAND`, `RECORD`, and under the root key `item_tables` are the item tables of these layouts and of the fragments they reference (such as `node_commands`, `node_parameters`, `node_status`).
79
+ - `src/layouts.js` only provides the layout source: it exports the path `layouts_file` of `layouts.yaml` in its directory (the path resolved from the module location; at build time rolldown outputs it as a separate file next to `main.js`), exports the registration scope name `LAYOUT_SCOPE` (`tlms`) of the layouts, and reads from `item_tables` the parameter block items `node_parameters` and the command bit items `node_commands` (the item lists of these two fragments, used by name by the configuration and the node rules). The layouts are registered by modbus-emulator: the generated emulator description file inlines `layouts` and `item_tables` of `layouts.yaml` (§4.4), and when the emulator loads it, it registers the layouts in the scope `LAYOUT_SCOPE` and creates the Ldata of all data blocks of the description; block names must not repeat within one layout. After registration, `get_scope(LAYOUT_SCOPE).get_layout(name)` gets `LINE`, `SECTION`, `NODE`, `COMMAND`, `RECORD`; when a layout is invalid, the emulator throws an error with `errors`, and `main.js` writes each to the error log and exits.
80
+ - Coupling offsets 8-15 are register bits 0-7, offsets 0-7 bits 8-15; the definition files list 8-15 before 0-7, i.e. in the order of register bit 0 to bit 15; bit k of the word value is register bit k, and the command mask word `command_mask` is computed with these bit numbers (§14.1).
81
+ - The point table in [spec-modbus.md](spec-modbus.md) is computed from the layouts by these rules.
82
+ - The bit numbers of a combined word are fully guaranteed by the offset numbering; inside a block a combined word is big-endian like any other multi-byte type, and neither the upward server nor the drivers swap bytes for combined words separately (spec of layout-data).
83
+ - These layouts are the memory images of the Modbus register table and of the actuator data areas; changing any offset is a protocol change.
84
+ - Write ownership (spec §3.6) is currently guaranteed by manual review: the layouts do not mark who writes a Tag, and the validation does not check this rule. The existing write paths all comply: the ID, command word and parameter block of the command block and the parameter block of the node block are written by the controller, all word aligned and contiguous; the rest of the node block is written by the actuator and only read by the controller.
85
+ - Layout validation is run on all layouts when the scope loads the description (`scope.load`); `tlms check` reports it together with the errors of the configuration validation (not implemented, see §13).
86
+
87
+ Main layouts (byte offsets):
88
+
89
+ | Structure | Key Tags |
90
+ | --- | --- |
91
+ | NODE | 0 ID; 2 status; 4 temperature; 8 pressure; 12 flowmeter; 16 response_code; parameter block from 18 |
92
+ | COMMAND | 0 response_code (deprecated); 2 overtime (deprecated); 6 extra_commands (`has_commands`, `reset_paras`); 16 ID; 18 commands; parameter block from 20 |
93
+ | SECTION | 0 ID; 2 upward_input (reserved); 4 status; 6 flow_begin; 10 flow_end; 14 flow_diff; 18-34 limits and delays; 38 countdown |
94
+ | LINE | 0 status; 2 ID; 4 action_section_ID; 6 flow_diff (reserved) |
95
+ | RECORD | 0-10 time; 12 section_ID; 14-36 flows and pressures; 42-48 actuator IDs; 50 status; 52 index |
96
+
97
+ ### 3.3 Access tracing and type declarations
98
+
99
+ - `trace_dependencies()` of the scheduler subscribes to the `access` events of all data blocks with `Ldata.on_access`, recording the reads and writes of tags by rules into the actual read and write sets of the "current rule"; `untrace_dependencies()` unsubscribes (§6.5).
100
+ - The type declarations `src/layout_types.d.ts` are generated from the layouts (`pnpm gen:types`, i.e. the layout-data command `layout-types src/layouts.yaml --scope tlms -o src/layout_types.d.ts`, which needs Node.js 24.2 or later; the generated file imports the `Ldata` type from `layout-data`, used only for type checking, not at run time): one interface per layout, the tags as properties, `comment` as doc comments, providing editor completion for access by name; the generated file goes into version control, and a test runs the command with the same arguments to check it matches the layout file.
101
+
102
+ ### 3.4 Reading and writing the content of data blocks
103
+
104
+ - The bytes of a block are not exposed as a property, and the content is read and written only through Ldata, so every write goes through Ldata and none is missed by detection. The ways of reading and writing are allowed at any time, whether during a scan or not:
105
+
106
+ | Way | Users |
107
+ | --- | --- |
108
+ | Reading and writing by name (`data[name]`, `tag.value`) | Any code: rules, event handlers, asynchronous callbacks, ordinary programs |
109
+ | Device byte order conversion per tag: `tag.load(io_buffer, endian)`, `tag.store(io_buffer, endian)` | The IO binding (§4.5) |
110
+ | The raw read and write methods `read_bytes(offset, length)`, `write_bytes(offset, source)`, `write_bit(offset, mask, value)`, located by byte offset | The upward server (§4.4) |
111
+
112
+ - The loading of the IO binding (§4.5) happens in the input phase of a scan and puts all tags of a group into one transaction, which on commit detects once and emits one `write`; scan requests caused by `write` in the input phase are ignored (§5.2).
113
+ - A function code 16 request writes several registers in a row within one synchronous call. `change` is dispatched after that call as one batch (§3.5), so a Real spanning two registers emits one `change` event with the complete value; rules are not affected either, because `request_scan()` merges (§5.2) and the scan runs only after the whole request has been handled.
114
+
115
+ ### 3.5 Change detection and write notification
116
+
117
+ The mechanism of change detection (snapshot comparison, event order, oscillation protection) and transactions (`transaction(fn)`) are in the design document of layout-data: a block emits `write` within the write statement, right after the new value takes effect; `change` is dispatched in a microtask after the synchronous code that wrote has ended, as one batch of the net changes of its writes. An exception thrown by a `change` handler is not thrown at the write: layout-data collects the exceptions of a dispatch in one `Dispatch_Error` and emits it as the `error` event of the block, which the emulator forwards as `block_error` (§4.4). The scan is not part of Ldata, and "the values at the end of the previous scan" are kept by the scheduler itself (§5.1).
118
+
119
+ **Write notifications are wired to scan requests.** When the scheduler registers a block (`add_data`), it listens to its `write` event and requests a scan, so any write (rules, event handlers, HMI, asynchronous callbacks) to any block of the controller (data and command of lines, sections and actuators, the action record) requests a scan at the write. The reasons:
120
+
121
+ - Writes take effect immediately, and rules always read the current value; `change` events are only notifications;
122
+ - The interlocks and aggregations of the controller are all in rules and do not depend on events (§6.6);
123
+ - `write` is emitted in the call stack of the write, so the writer can be traced when debugging.
124
+
125
+ The asynchronous `change` affects only event handlers (logging): the changes made by the rules of a scan are reported after the scan, one batch per block, with the net change of each tag; a handler reads the values at the time of the dispatch. Event handlers only log; an exception of a `change` handler does not stop the controller, and is logged under its block through `block_error`.
126
+
127
+ ### 3.6 Byte order conversion
128
+
129
+ The conversion between the device byte orders (`BE`, `LE`, `BEBS`, `LEBS`, without aliases) and the internal big-endian is implemented by layout-data (rules in its design document): conversion per tag uses `tag.load` / `tag.store`, and the IO binding gets the byte map of a whole block with `io_index_table(endian)` of the layout (§4.5); this package implements no conversion of its own; tests use `load_tag` / `store_tag` of the block as the reference to check that Binding agrees with them byte by byte.
130
+
131
+ ## 4. Drivers
132
+
133
+ ### 4.1 Base_Driver
134
+
135
+ - Mixed in with `Object.mixin(this, new Base_Driver())`: it only adds the properties the subclass lacks, taking the prototype chain into account, so it neither overrides those the subclass defines itself, such as `start_tick`, nor shadows `connect` / `disconnect` inherited from the driver library.
136
+ - `stop()` stops the timer and calls the library's `disconnect()` (neither library reconnects automatically after an explicit disconnect); a later `start()` first calls `connect()` to reconnect.
137
+ - `start()` runs `start_tick` every `period_time` (1000 ms) and emits `tick` when connected.
138
+ - `emit_io_ok` / `emit_io_error` wrap the result of every read and write:
139
+ - on the first error, `io_error` is emitted, and on the first success after an error, `io_ok` (not the per-transaction `data_error` event name of es-modbus, to avoid confusion with it);
140
+ - when no read or write succeeds within `connfailed_time` (5000 ms), `on_error` is called, which emits `connfailed`;
141
+ - the argument of `connfailed` and `io_error` is the error message string (its `message` when the library gives an `Error`).
142
+ - `reconnect_time` means only the reconnect interval, and `connfailed_time` only the escalation time above; the two are configured separately. The second constructor argument `options` of a driver can pass `period_time`, `reconnect_time`, `connfailed_time` (and `reconnect_max` for Modbus); the controller passes none and uses the defaults.
143
+ - Driver instances are reused by connection parameters:
144
+ - Modbus by `host:port`;
145
+ - S7 by `host:port rack slot`;
146
+ - calling `start()` several times on the same driver does not create timers again.
147
+
148
+ ### 4.2 MTClient (es-modbus)
149
+
150
+ - Connection: the `tcp` option of es-modbus selects the Modbus TCP transport, with the target `<host>:<port>` (the configured `host` defaults to `127.0.0.1`, `port` to 502), an IPv6 host in square brackets.
151
+ - Address conversion: areas in the configuration and in Ldata are in bytes; the byte start `start` corresponds to the holding register PDU address `start >> 1` (0-based), and the length is `length >> 1` registers; they are passed as the structured range `[func_code, pdu_addr, length]` of es-modbus, not in Modicon notation.
152
+ - es-modbus throws synchronously on invalid arguments (range, quantity limits, unit_id); `read` / `write` catch it, log an error, and treat it as a read / write failure (`emit_io_error`).
153
+ - Only holding registers are accessed: MTClient gives the function codes explicitly, 03 for reading, 06 (single register) / 16 (multiple registers) for writing. Coils, discrete inputs and input registers are not used.
154
+ - `write_unit = 2`: the write unit is one register.
155
+ - Echo check of writes: the `write()` of es-modbus resolves with whether the response echoed the request. A mismatching echo means the write is unconfirmed: a warning is logged, it is treated as a read / write failure (`emit_io_error`), and `write` returns `false`.
156
+ - Reconnection uses the mechanism of es-modbus itself; `start_tick` is overridden to only emit `tick`:
157
+ - the reconnect interval starts at `reconnect_time` (5000 ms), doubles on every failure up to `reconnect_max` (20000 ms), and returns to the initial value once the connection is stable;
158
+ - 3 consecutive request timeouts (the default `max_timeouts` of es-modbus) mean a dead link: the connection is closed and reconnected as usual; when the connection drops, all pending requests fail with `connection lost`.
159
+
160
+ ### 4.3 S7Client (@st-one-io/nodes7)
161
+
162
+ - Reads and writes the `DB` or `M` area with `readArea` / `writeArea`; start and length are in bytes.
163
+ - `write_unit = 1`: the write unit is one byte.
164
+ - Because `S7Endpoint.connect()` is incomplete, the library's own automatic reconnection is used for now (`autoReconnect`, taking `reconnect_time`, default 5000 ms, at a fixed interval), and `start_tick` is overridden too (marked as temporary code in the source).
165
+
166
+ ### 4.4 Upward server (modbus-emulator)
167
+
168
+ - The creation of data blocks and the upward service are provided by the separate `modbus-emulator` package (spec and design in `doc/` of that package). The controller generates the emulator description as a file, which the emulator then loads; the description file is a complete description the operator can look at (spec §5.5).
169
+ - Block names: fixed by `prepare_controller` when building the object graph and stored on the objects. The data block names of lines, sections and actuators are the `name` of the objects; the block name of the command block of an actuator is stored in `node.command_name` (`<actuator name>_command`), and the block name of the action record in `controller.record_name` (`action_records`). Block names appear only in the description file and in diagnostics, and do not affect Modbus addresses.
170
+ - Data blocks (unit ids from `controller.modbus_server.unit_id`): the action record (`RECORD`, byte 0); one for each line (`LINE`) and each section (`SECTION`); the data (`NODE`, byte 0) and command (`COMMAND`, byte 400, i.e. from register 200) of each actuator share the unit of the actuator.
171
+ - `src/description.js#build_description(controller)` is a pure function that only reads the object graph and returns the description object: `layouts` and `item_tables` come from `layouts.yaml`, `blocks` holds all data blocks (block name, layout), `units` one unit entry per unit id placing the data blocks of that unit with their start bytes, and `servers` one TCP service listening on `0.0.0.0:<modbus_server.port>`. The byte order of units, the response to unmapped addresses and the read-only points of placements take the defaults of the emulator: big-endian, unmapped addresses read as 0 and writes ignored, all points writable. The description does not name the scope: the scope is chosen by the code (`new Modbus_Emulator(LAYOUT_SCOPE)`). `write_description(file, description)` writes it as a YAML file, whose header notes that it is generated by the controller.
172
+ - `src/init.js#init_controller(name, dir)` is the main orchestration function shared by `main.js` and tests: `prepare_controller` -> `build_description` -> writes `<dir>/<controller name>/emulator.yaml` (creating the subdirectory when missing) -> `new Modbus_Emulator(LAYOUT_SCOPE)` -> wires the logs -> `emulator.load(file)` -> mounts the Ldata. It returns `{ controller, emulator }`, and `main.js` also uses the emulator to start the service. `main.js` passes the working directory, tests pass a temporary directory.
173
+ - Mounting: after loading, one pass over the object graph sets `line.data`, `section.data`, `node.data` to the Ldata of their block names, `node.command` to the command block and `controller.record_data` to the action record block. The emulator is not stored on the object graph, and `build_runtime` uses the mounted Ldata directly.
174
+ - Logs: the emulator outputs no logs itself. Before loading, `init_controller` subscribes to its `warning` events (diagnostics found while loading), the server events it forwards (`server_<name>`: start and stop, client connects and disconnects, the various errors) and the handler events (`unmapped`, with the read or write `operation`; `unmapped_limit`; `listener_error`), and the errors of its blocks (`block_error`: the `Dispatch_Error` of a dispatch of `change`, one log entry for each exception it holds), writing them to the project log. The emulator creates every block of the controller, so `block_error` covers the exceptions of all `change` handlers; the scheduler does not subscribe to the `error` event of the blocks, so each exception is logged once.
175
+ - Write notification: not passed through the emulator. When the data blocks are created the scheduler does not exist yet; when `build_runtime` registers the data blocks with the scheduler (`add_data`), the scheduler listens to the `write` event of the block and requests a scan; other users that need to know about writes listen on their own as well.
176
+ - The address mapping of registers and coils, the handling of unmapped addresses and exception responses are in the spec of modbus-emulator; reads go through `read_bytes` / `read_bit` of Ldata and writes through `write_bytes` / `write_bit`, and Ldata detects changes after every write; one FC 15 / FC 16 request writes the same block within one transaction. Tests simulate HMI requests through `emulator.handler`; `emulator.stop()` gives the block names back to the layouts, so data blocks of the same names can be loaded again in the same process.
177
+ - `src/layouts.js` reads the layout description of `layouts.yaml` (`layouts`, `item_tables`) for generating the description file, and exports the fragments used by name; the validation and registration of the layouts are done when the emulator loads the description file, and layout metadata such as the fields of the action record are taken from the registered `Layout` (`block.layout`, `get_layout` of the scope).
178
+
179
+ ### 4.5 IO binding (`src/drivers/binding.js`)
180
+
181
+ The IO binding is not part of the data layer: it exchanges data with devices tag by tag only through the interfaces of Ldata and Ltag.
182
+
183
+ - `new Binding(data, driver, { start, remote_start, length, endian, on_update }, ...extras)` maps the exchange area `[start, start + length)` of a block to the remote area of the same length from `remote_start`; `extras` is passed to the driver as is (`unit_id` for Modbus, `area, db` for S7). The three exchange area parameters must be whole multiples of the driver write unit `driver.write_unit` (default 1), otherwise an exception is thrown, so that the extended write ranges never leave the exchange area and the local write units align with the remote write units.
184
+ - Binding holds the `IO_buffer` in device byte order (as long as the block, with the same indexes), and data read by the driver is written only into it.
185
+ - Byte mapping `io_index`: at creation, `io_index_table(endian)` of the block layout (`data.layout.io_index_table(endian)`) computes for each byte of the block its index in `IO_buffer` (rule: the device byte order applies per 16-bit register and per 32-bit value, see spec §3.6 and the design document of layout-data). The layout validation guarantees that non-Bool items do not overlap and Bools fall only inside combined words, so the mapping of each byte is unique.
186
+ - `create_group(...names)` returns a group of tags to be synchronized with the device together (`Binding_Group`):
187
+ - a missing name or a tag outside the exchange area throws; adding the same tag again is ignored;
188
+ - the Ltag of each tag of the group is taken once at creation, and loading and exporting no longer look them up by name;
189
+ - write ranges: the bytes occupied by the tags of the group are computed from the `items` of the layout (a Bool occupies one byte), mapped through `io_index` to positions in `IO_buffer`, extended outward to write units, with adjacent write units merged.
190
+ - Loading and exporting are conversions tag by tag, and bits of the same byte belonging to different groups do not affect each other:
191
+
192
+ ```js
193
+ // load: IO_buffer -> block, one transaction: one detection and one write event
194
+ block.transaction(() => { for (const tag of group.tags) tag.load(IO_buffer, endian); });
195
+ // store: block -> IO_buffer, right before the group areas are written
196
+ for (const tag of group.tags) tag.store(IO_buffer, endian);
197
+ ```
198
+ - An exception thrown by a `write` listener during loading is passed out after the transaction commits: the data has been loaded, `fresh` is cleared as usual, and the exception is reported by the scheduler under the Binding (§5.4).
199
+ - Exporting happens right before the ranges of each group are written: writing a range is asynchronous, a scan may run in between, and the groups exported later export the latest values.
200
+
201
+ - Reading: `request_read()` reads the whole exchange area into `IO_buffer`, sets `fresh` and calls `on_update`; a read in progress is shared and not started again, so requests do not pile up on slow devices. `load(group)` loads, in the input phase of a scan, only the bits of the group by the mask and clears `fresh`; bits outside the group (such as `comm_OK`, maintained by the controller) stay unchanged; it changes only `buffer`, emits no events, and requests no scan.
202
+ - Writing: `request_write(group)` registers a write request, and the same group registered several times within one scan is written only once; `flush_writes()`, in the output phase of a scan, exports the bits of the group into `IO_buffer` by the mask, then calls the driver to write each write range, passing the length of the range to the driver as well. Writes are asynchronous and do not block the scan. Bits within a range that do not belong to the group take the values last read; by the write ownership rule these bytes are also written by the controller, so the data of the actuator is not overwritten.
203
+ - While the driver is not connected, nothing is read or written, and write requests are kept until the `flush_writes()` after the connection recovers.
204
+ - Driver events and the results of asynchronous reads and writes are recorded as states of Binding for rules to read (§6.1), written only by Binding:
205
+
206
+ | State | Updated when |
207
+ | --- | --- |
208
+ | `connected` | The driver's `connect` / `connfailed` events |
209
+ | `read_ok` | Each read completes: true on success, false on failure |
210
+ | `write_done(group)` | A write of a group completes; records the completion sequence number and result, for rules to decide "the write requested last time has completed" |
211
+
212
+ When new data arrives, a state changes or a write completes, Binding calls the `on_update(binding)` passed at creation, which the controller wires to `request_scan()`.
213
+
214
+ ## 5. Scan (`src/scan.js`)
215
+
216
+ ### 5.1 Four phases
217
+
218
+ The `scan(tick)` of the scheduler runs entirely synchronously:
219
+
220
+ ```js
221
+ function scan(tick) {
222
+ // 1 input: take the process image, advance running tickers on periodic ticks
223
+ phase = "input";
224
+ for (const { binding, input_group } of bindings) if (input_group && binding.fresh) binding.load(input_group);
225
+ if (tick) for (const ticker of running_tickers) ticker.count++;
226
+ // 2 evaluate: all rules in one fixed dependency order, each isolated (5.4)
227
+ phase = "evaluate";
228
+ for (const rule of ordered_rules) guarded(() => rule.run(rule.ticker), rule);
229
+ // 3 publish: the end of this scan, the used tags, binding states and variables save their values
230
+ phase = "publish";
231
+ take_scan_snapshots();
232
+ // 4 output: send what was requested, start reads on periodic ticks
233
+ phase = "output";
234
+ for (const { binding, input_group } of bindings) {
235
+ binding.flush_writes().catch(report);
236
+ if (tick && input_group) binding.request_read().catch(report);
237
+ }
238
+ phase = "idle";
239
+ }
240
+ ```
241
+
242
+ 1. **Input**: loads the actuators with new data from `IO_buffer` into their blocks, forming the process image of this scan. Actuators without new data keep their values, and communication anomalies are reflected by `comm_OK` / `work_OK`. The scan of a periodic tick also adds 1 to the count of all running tickers (§6.3).
243
+ 2. **Evaluate**: runs all rules in the arranged order (§6), computing aggregated values, trigger bits, timing and interlock actions, and registering write requests.
244
+ 3. **Publish**: saves the values at the end of this scan (see below). Change events are not emitted here: a block detects and emits right after every write (§3.5), and event handlers only log (§6.6).
245
+ 4. **Output**: performs the write requests registered in this scan; the scan of a periodic tick also starts the next round of reads. Reads and writes are asynchronous; when they complete, the `on_update` of Binding requests a scan, by which time this scan has ended.
246
+
247
+ "The values at the end of the previous scan" are saved after the publish phase: the writes made by rules and event handlers in this scan all count as part of this scan. The scheduler itself keeps three kinds of values: the block tags used by rules (in `reads`, `writes`, `reads_previous`), Binding states (`connected`, `read_ok`), and registered variables (§6.1); a tag used by no rule has no value of the previous scan, and getting it is an error. From these the scheduler provides uniform values of the previous scan and edge checks:
248
+
249
+ ```js
250
+ scheduler.previous(owner, name); // tag, binding state or variable: saved by the scheduler
251
+ scheduler.rose(owner, name); // !previous && current
252
+ scheduler.fell(owner, name); // previous && !current
253
+ scheduler.changed(owner, name); // previous differs from current (NaN equals NaN)
254
+ ```
255
+
256
+ ### 5.2 Triggers
257
+
258
+ Scans have two kinds of triggers:
259
+
260
+ | Trigger | Source | `tick` |
261
+ | --- | --- | --- |
262
+ | Periodic tick | Once every `MAIN_PERIOD` (500 ms) | true |
263
+ | Scan request | `request_scan()`: writes of blocks (including HMI writes through Unit_Map), actuator data read back, Binding state changes and write completions | false |
264
+
265
+ - `request_scan()` merges with `setImmediate`: several requests in the same round of the event loop cause only one scan; when a periodic tick arrives while a request is pending, the scan of the tick handles it as well.
266
+ - Requests during a scan come from the writes of the scan itself (the periodic tick never calls `request_scan()`, and external callbacks can only run between two scans):
267
+ - requests in the input and evaluate phases are ignored: the later rules of this scan already read these writes; derive rules write in every scan, and if they caused scans too, scanning would never stop;
268
+ - requests from the start of the publish phase on schedule the next scan: these writes happened after evaluation, and the rules have not yet evaluated them.
269
+ - When `scan()` is called during a scan (e.g. in a rule or an event handler), it does not run nested but is queued after the current scan.
270
+ - Timing advances only when `tick` is true, and scans triggered by requests do not advance it, so the number of scans does not affect timing (§6.3).
271
+
272
+ ### 5.3 Timing
273
+
274
+ - After actuator data is read back, an HMI write, or a connection state change, a scan runs immediately: derived states and interlock actions are completed in this scan, and the resulting commands are sent in the output phase of this scan.
275
+ - Reads are started periodically, and the freshness of actuator data is limited by the read period; the acknowledgement of commands is in `response_code` of the node block, obtained by the periodic read.
276
+ - Within one period several scans happen because of the read-backs of different actuators, and the begin and end data of a section may be read at different moments; the flow difference evaluation has a confirmation delay, so it is not affected by momentary inconsistencies.
277
+ - The controller neither debounces nor filters the values reported by actuators; signal debouncing is done by the actuators.
278
+
279
+ ### 5.4 Error isolation
280
+
281
+ The controller is a safety system, and one defect must not stop the other interlocks:
282
+
283
+ - Each rule runs on its own; when it throws, the exception is reported through `on_error(error, source)` injected when the scheduler is created, and the following rules continue; `source` is the failing rule, block or Binding;
284
+ - In the input phase the loading of each Binding is isolated on its own: an exception thrown by a `write` listener during loading is reported under that Binding, and the other Bindings load as usual;
285
+ - Failures of asynchronous reads and writes in the output phase are reported through `on_error` as well;
286
+ - Exceptions of `change` handlers are dispatched after the scan and are not reported by the scheduler: the emulator logs them under their block (`block_error`, §4.4);
287
+ - The controller wires `on_error` to the log; the scheduler itself does not log, and exceptions are ignored when it is not injected.
288
+
289
+ ### 5.5 Scheduler interface
290
+
291
+ ```js
292
+ const scheduler = new Scheduler({ period: MAIN_PERIOD, on_error });
293
+ scheduler.add_data(block); // every write to it requests a scan
294
+ scheduler.add_binding(binding, input_group); // loaded in the input phase, flushed and read in the output phase
295
+ scheduler.add_binding(binding); // output only: flushed in the output phase, never read nor loaded
296
+ scheduler.add_var(owner, name); // a shared variable: a property of an object (6.1)
297
+ scheduler.add_rule(rule); // built by derive() / act() (6.2)
298
+ scheduler.prepare(); // order the rules and check them (6.4); throws with every error
299
+ scheduler.start(); // periodic ticks: scan(true) every period
300
+ scheduler.request_scan(); // a coalesced triggered scan: scan(false)
301
+ scheduler.stop();
302
+ ```
303
+
304
+ - `prepare()` is called once before the first scan: it checks and orders all rules, assigns a ticker to each rule, and obtains a fixed execution table; nothing is registered afterwards.
305
+ - A Binding registered without an input group is write-only, used for the command blocks of actuators: the controller only writes commands to actuators and never reads them back.
306
+ - `scan(tick)` can be called directly, for tests to drive scans.
307
+ - `trace_dependencies()` / `untrace_dependencies()`: the dependency tracing test mode (§6.5).
308
+
309
+ ## 6. Rules (`src/rules.js`)
310
+
311
+ ### 6.1 Dependency keys
312
+
313
+ The objects that rules read and write are uniformly expressed as "dependency keys", i.e. `(owner, name)` pairs:
314
+
315
+ - when the owner is an Ldata, the name is a tag name, e.g. `(section.data, 'comm_OK')`;
316
+ - when the owner is an ordinary object such as a section, line or actuator, the name is a property name of that object, e.g. `(section, 'press_SD_trigger')`. Such variables must be registered with `add_var`; a variable must be a property of some object, and a bare variable cannot be a dependency key;
317
+ - when the owner is a Binding, the name is a state name, e.g. `(binding, 'connected')`, read-only.
318
+
319
+ So Tags, variables (spec §3.6) and Binding states are ordered by the same rules.
320
+
321
+ A combined word shares the same data with its component bits but has a different name, and dependencies built by name cannot see the relation between them. Therefore:
322
+
323
+ - Rules write only component bits, never combined words. Whole-word writes come only from loading and the upward server, which are inputs of the scan; when several command bits need to be cleared (the acknowledgement handshake, command masking), they are written bit by bit by name;
324
+ - A combined word in `reads` is expanded before ordering into reads of all its component bits, after which dependencies are built by name. So a rule writing a bit is ordered before a rule reading the whole word; two rules writing different bits have no dependency between them.
325
+
326
+ ### 6.2 The two kinds of rules
327
+
328
+ | Kind | Write constraint | Use |
329
+ | --- | --- | --- |
330
+ | derive | The only writer of its write keys, fully determining their values in every scan | Aggregations, differences, trigger bits, protection state, timing, `comm_OK`, `action_F`, `stop_pumps` and the like |
331
+ | act | Its write keys may have several writers (including the HMI, loading and other acts), and it may write only when a condition holds | Edge actions, interlock set / reset, sending and receiving commands, copying parameters, action records, `work_OK` |
332
+
333
+ Each rule has a name `name`, used in the startup checks and error reports, e.g. `section S1 comm_OK`. The keys declared by a rule are of three kinds:
334
+
335
+ | Field | Meaning |
336
+ | --- | --- |
337
+ | `reads` | Reads the values of this scan and forms dependencies: the writers are ordered before this rule |
338
+ | `writes` | The keys written |
339
+ | `reads_previous` | Reads the values at the end of the previous scan (`scheduler.previous()`), forming no dependency, used to break cycles (§6.4) |
340
+
341
+ IO started by a rule (`request_write`) is only registered; the actual reads and writes are performed together in the output phase, forming no dependency, and are not declared.
342
+
343
+ Rules can use two kinds of state:
344
+
345
+ | State | Use | Values of the previous scan, edge checks |
346
+ | --- | --- | --- |
347
+ | Dependency keys (tags, Binding states, registered variables) | State shared by several rules, taking part in ordering | Provided by the scheduler (§5.1) |
348
+ | Closure variables | State belonging to one rule only: latches, counts, the "previous value" it needs itself, and the like | Kept by the rule itself |
349
+
350
+ Closure variables are not registered and take no part in ordering, and only the rule they belong to may read and write them. Timing does not accumulate in closure variables, but uses the ticker assigned by the scheduler (§6.3).
351
+
352
+ ```js
353
+ derive({
354
+ name: `section ${section.name} comm_OK`,
355
+ reads: all_nodes.map(node => [node.data, 'comm_OK']),
356
+ writes: [[section.data, 'comm_OK']],
357
+ run: () => { section.data.comm_OK = all_nodes.every(node => node.data.comm_OK); },
358
+ });
359
+
360
+ act({
361
+ name: `section ${section.name} stop commands reset`,
362
+ reads: [[section.data, 'pump_run']],
363
+ writes: [[section.data, 'auto_stop_cmd'], [section.data, 'man_stop_cmd']],
364
+ run: () => {
365
+ if (!scheduler.fell(section.data, 'pump_run')) return;
366
+ section.data.auto_stop_cmd = false;
367
+ section.data.man_stop_cmd = false;
368
+ },
369
+ });
370
+ ```
371
+
372
+ ### 6.3 Timing (Ticker)
373
+
374
+ The scheduler assigns a Ticker to each rule and passes it as the argument of `run(ticker)` in scans. The rule decides itself when timing starts and stops, and the scheduler only advances it:
375
+
376
+ - `start()` starts timing from 0, and calling it while running has no effect, so a condition that keeps holding keeps counting; `stop()` stops and resets; `restart()` stops and then starts;
377
+ - `count` is the number of periodic ticks since the start, `elapsed` is `count * MAIN_PERIOD`;
378
+ - Advancing: in the input phase of a tick scan, the scheduler adds 1 to the `count` of the running tickers (§5.1); scans triggered by requests do not advance them. Only running tickers are in the set, so the cost of advancing is proportional to the number of timings in progress;
379
+ - Rules do not receive the `tick` flag and do not accumulate counts themselves, so the number of scans does not affect timing;
380
+ - Each rule has only one ticker. Logic that needs two independent timings is split into two rules; e.g. the flow difference warning delay and the flow difference alarm delay of a section belong to two derive rules.
381
+
382
+ Delays by value are expressed by two helper functions:
383
+
384
+ ```js
385
+ // true once cond has held for longer than delay_ms (as a PLC TON)
386
+ function on_delay(ticker, cond, delay_ms) {
387
+ if (cond) ticker.start();
388
+ else ticker.stop();
389
+ return ticker.elapsed > delay_ms;
390
+ }
391
+
392
+ // true while cond holds, and for delay_ms after it drops (as a PLC TOF)
393
+ function off_delay(ticker, cond, delay_ms) {
394
+ return !on_delay(ticker, !cond, delay_ms);
395
+ }
396
+ ```
397
+
398
+ When the condition of `off_delay` does not hold from the start, the output stays true for `delay_ms` after startup and then becomes false, consistent with the output of a TOF while its input is false.
399
+
400
+ Timing started by an edge (an action performed some time after an event, which the rule may abort on its own in between) is done by an act rule operating the ticker directly. An edge check is true only in the scan where the edge occurs, so the timing check must be outside the edge check:
401
+
402
+ ```js
403
+ act({
404
+ reads: [[binding, 'connected']],
405
+ writes: [[command, 'temperature_zero_raw'] /* ... all parameter tags */],
406
+ run: (ticker) => {
407
+ if (scheduler.rose(binding, 'connected')) ticker.restart();
408
+ if (!binding.connected) ticker.stop(); // aborted by the rule itself
409
+ if (ticker.running && ticker.elapsed >= 2000) {
410
+ ticker.stop();
411
+ copy_parameters();
412
+ }
413
+ },
414
+ });
415
+ ```
416
+
417
+ Timing semantics:
418
+
419
+ - When the condition disappears or the rule calls `stop()`, it takes effect immediately, without waiting for the next tick. E.g. a manual hang-on during the countdown: the HMI writes `flow_override` of the section or line, triggering a scan, in which `protect_F` and `pre_stop_notice` become false and the countdown rule stops its ticker, so no flow difference action occurs;
420
+ - A ticker started between two ticks has `count` 1 at the next tick: after the condition holds, `on_delay` outputs true at the `floor(delay / MAIN_PERIOD) + 1`-th following tick;
421
+ - A ticker started in a tick scan has `count` 0 in that scan and counts from the next tick;
422
+ - When the condition appears and disappears between two ticks, the ticker stops and resets, without affecting timing;
423
+ - In scans triggered by requests `count` does not change, so rules depending on timing results produce no new edges when run repeatedly;
424
+ - Timing values that need to be shown externally (such as `countdown`) are converted from `elapsed` by the rule in every scan, and the value does not change between two ticks.
425
+
426
+ ### 6.4 Ordering and checks
427
+
428
+ `prepare()` topologically sorts all rules once (Kahn's algorithm), giving a fixed execution order:
429
+
430
+ - Directed edge: rule writing key K -> rule reading key K; all writers of the same key are ordered before its readers;
431
+ - When a rule reads a key it also writes (read-modify-write, e.g. the rule containing `line_action_source &&= line.auto_stop_cmd`), that read forms no dependency edge;
432
+ - Keys in `reads_previous` form no dependency edges;
433
+ - Several writers of the same key, and rules without dependencies between them, are ordered by declaration order, so the result is repeatable.
434
+
435
+ Rules are declared after the whole object graph (all blocks, Bindings and variables) is built, because rules of upper levels reference blocks of lower levels, and rules of lower levels also reference blocks of upper levels (e.g. the section's `pre_stop_notice` reads the line's `pump_run`). The declaration order is actuators -> sections -> lines, objects of the same kind in configuration order, then the rule of the action record, and finally the command masking rule of each actuator (§14.1).
436
+
437
+ E.g. the section's `pre_stop_notice` reads the line's `pump_run`, the line's `pump_run` aggregates the `pump_run` of the sections, and the line's `pre_stop_notice` in turn aggregates the `pre_stop_notice` of the sections. Ordering by level (section -> line) cannot give a correct order; ordering by key gives:
438
+
439
+ ```
440
+ node.pump_run -> section.pump_run -> line.pump_run
441
+ -> section.pre_stop_notice -> line.pre_stop_notice
442
+ ```
443
+
444
+ which is computed right once within the same scan.
445
+
446
+ At startup the following errors are checked; when found, all errors are reported and the program refuses to start:
447
+
448
+ - A dependency cycle: the rules and keys on the cycle are reported, with the hint that `reads_previous` can break it;
449
+ - A key in `reads_previous` has no value of the previous scan: only tags, the `connected` / `read_ok` of Binding and registered variables have values of the previous scan;
450
+ - A key has a derive writer and also other rule writers;
451
+ - A rule writes a read-only Binding state;
452
+ - A rule writes a combined word;
453
+ - A rule declares a tag name or Binding state name that does not exist;
454
+ - A rule declares a variable not registered with `add_var`;
455
+ - A rule has no name, or two rules have the same name.
456
+
457
+ **Breaking cycles.** The dependencies between rules must be acyclic. When the business really needs a cycle, the rule author picks one place on the cycle and reads the value at the end of the previous scan there, i.e. puts this key into `reads_previous` in the declaration and reads it with `scheduler.previous()` in `run`. This is a unit delay in control systems: this quantity is always one scan period behind the others on the cycle, with fixed semantics. Copying the actuator parameters is an example (§7.3).
458
+
459
+ ```js
460
+ derive({
461
+ name: 'line B',
462
+ reads_previous: [[section.data, 'A']],
463
+ writes: [[line.data, 'B']],
464
+ run: () => { line.data.B = g(scheduler.previous(section.data, 'A')); },
465
+ });
466
+ ```
467
+
468
+ The scheduler neither picks the breaking point automatically nor evaluates repeatedly within a scan until stable: whether it converges depends on the functions in the rules, not on the structure of the dependency graph, and is generally undecidable; even when it converges, the result may differ with the breaking point or the initial values. Where to break is a business decision, left to the rule author to write explicitly, which makes it easy to review.
469
+
470
+ ### 6.5 Checking the dependency declarations
471
+
472
+ Dependencies rely on explicit declarations, and a missing read key leads to a wrong order without an error. So a check in test mode is provided:
473
+
474
+ - `trace_dependencies()` of the scheduler sets the access tracing hook of the data layer (§3.3) and records the accesses into the actual read and write sets of the "current rule"; after a test runs some scans, a tag actually accessed but not declared is an error; reads of combined words are compared by their expanded component bits (§6.1), and a write of a combined word is an error in itself;
475
+ - `scheduler.previous()` takes the values saved by the scheduler and does not go through the accessors, so a tag declared only in `reads_previous` that is read directly is reported as an error too (it reads the value of this scan);
476
+ - The hook can trace only tags; Binding states and variables do not go through accessors and are outside the check;
477
+ - Writes of a rule emit events during the execution of the rule, and accesses in event handlers are recorded under that rule; by the convention of §6.6, event handlers only log and take the values they need from the event arguments, causing no extra accesses;
478
+ - The fixture of the system tests turns the check on in every test and requires no undeclared accesses.
479
+
480
+ At run time the hook is not set. "Run once and infer the dependencies automatically" was not adopted, because the short-circuiting of `&&`, `||` and conditional branches mean one run cannot see all reads.
481
+
482
+ ### 6.6 Coding conventions for event handlers
483
+
484
+ This is a convention of the controller code, not a restriction of Ldata / Ltag: Ldata / Ltag prevent no writes.
485
+
486
+ - Derived logic such as interlocks and aggregations is written as rules, not in event handlers, so that a scan is based on one set of inputs and the result does not depend on the order of events;
487
+ - Event handlers are for logging; writing tags in handlers is allowed, and such a write requests a scan and is read by the rules in the next scan;
488
+ - Logic that needs asynchronous operations is written as act rules: the rule registers the request, Binding records the completion state and requests a scan, and the follow-up processing is done by the rule reading the completion state (§4.5).
489
+
490
+ ## 7. Actuator processing (`node_proc.js`)
491
+
492
+ ### 7.1 IO binding
493
+
494
+ The data and command of each actuator have a Binding each (§4.5), kept in `actuator.data_binding` / `actuator.command_binding`.
495
+
496
+ - data:
497
+ - binds the whole structure, with the remote start `driver_info.data.start`;
498
+ - `data_payload` contains the ID, the status bits, the measured values, `response_code` and the parameter block (not `comm_OK`, which the controller maintains itself);
499
+ - `data_parameters` contains only the parameter block.
500
+ - command:
501
+ - binds from local byte 16 (skipping the local area 0-15), with the remote start `driver_info.commands.start`;
502
+ - `commands_payload` contains the ID, commands and the parameter block.
503
+
504
+ ### 7.2 Reads and writes
505
+
506
+ - Reading the actuator data is done by the scan: the scan of a periodic tick starts the read in its output phase; when the data arrives, the `on_update` of Binding requests a scan, which loads `data_payload` in the input phase and detects the changes in the publish phase.
507
+ - The command Binding is write-only (§5.5): rules register writes, which are written out in the output phase of the scan; after a write completes, `on_update` requests a scan. While the driver is not connected, write requests are kept and written out once the connection recovers.
508
+ - Driver events are only logged; the connection and read results are recorded by Binding as `connected` / `read_ok`, for rules to read.
509
+
510
+ ### 7.3 Rules (`node_rules`)
511
+
512
+ | Rule | Processing |
513
+ | --- | --- |
514
+ | `comm_OK` (derive) | `off_delay(connected, delay_protect_time)`: true while connected, and kept for `delay_protect_time` after a disconnection before becoming false; when never connected, kept for the same time after startup |
515
+ | `work_OK` | Set to false when `off_delay(read_ok, delay_protect_time)` is false, i.e. when reads keep failing for longer than `delay_protect_time`; after a successful read, the loading restores the value reported by the actuator |
516
+ | Parameter refresh | The rising edge of `connected` starts timing, and after 2 s the parameters of the node block are copied to the command block; a disconnection in between stops it |
517
+ | Withdrawing `stop_pumps` (actuators with pumps) | On the falling edge of `pump_run`, clears `stop_pumps` of the command block |
518
+ | Acknowledgement handshake | When `response_code` changes and is not 0, for the bits set to 1 in `response_code`, the command bits of the same name in the command block are cleared bit by bit, and `executing` is cleared |
519
+ | `pressure_SD_F` | On change, clears the corresponding enable or disable command bit |
520
+ | `read_paras` | On the rising edge, copies the parameters of the node block to the command block and resets the bit |
521
+ | `write_paras` | On the rising edge, copies the parameters of the command block to the node block and registers a write of `data_parameters`; after the write completes (the sequence number of `write_done` is reached), resets the bit |
522
+ | `has_commands` (derive) | `commands` is not 0 |
523
+ | Sending | When `commands` changes, or when `response_code` changes and is not 0 (so the actuator sees the acknowledged bits cleared), registers a write of `commands_payload` |
524
+ | Resending | After `has_commands` has held for more than 3 ticks, registers a write again on every tick; timed per actuator |
525
+
526
+ - `write_paras` writes the parameters of the command block into the node block, while the parameter refresh and `read_paras` copy the parameters of the node block to the command block, and `comm_OK` / `work_OK` read `delay_protect_time` of the node block, which forms a cycle. The latter break this cycle by reading the node parameters at the end of the previous scan (`reads_previous`, §6.4): the node parameters come from the actuator, and being one scan late does no harm; `write_paras`, on the other hand, must read the command parameters of this scan, since the HMI often writes the parameters and then `write_paras` in the same request.
527
+ - Rules write only command bits, never the whole word `commands` (§6.1).
528
+ - `pump_run` follows the value reported by the actuator (the actuator already ORs the states of its pumps), and the controller does not compute it separately.
529
+ - State changes are only logged; the aggregation to the section is done by the rules of the section (§8).
530
+
531
+ ## 8. Section processing (`section_proc.js`)
532
+
533
+ ### 8.1 Event handling (`section_init`)
534
+
535
+ - Writes the section's ID, name and flow difference parameters (`flow_diff_WH` and the like, `action_time`).
536
+ - State changes (`action_F`, alarms, hang-on, `pre_stop_notice` and the like) are only logged.
537
+
538
+ ### 8.2 Rules (`section_rules`)
539
+
540
+ The variables and rules of a section are declared after the object graph is built (§6.4). The variables on the section object (not Tags, see spec §3.6) are registered with `add_var`:
541
+
542
+ - `flow_warning_trigger` / `flow_alarm_trigger`: the trigger bits of the flow difference warning and alarm;
543
+ - `press_SD_trigger`: the pressure interlock condition;
544
+ - `countdown_expired`: the countdown has expired;
545
+ - `press_action` / `flow_action`: the pressure action and the flow difference action;
546
+ - `stop_pumps`: this section executes a pump stop.
547
+
548
+ derive rules, run in every scan, ordered among themselves by the ordering:
549
+
550
+ | Rule | Computation |
551
+ | --- | --- |
552
+ | `comm_OK`, `work_OK` | AND over all begin and end actuators |
553
+ | `press_warning_F` / `press_alarm_F` | OR of `pressure_WH_F` / `pressure_AH_F` over the begin and end actuators |
554
+ | `pump_run`, `pump_change_F` | OR of the properties of the same name over the actuators with pumps |
555
+ | `flow_begin` / `flow_end` | Sum of `flowmeter` of the begin / end actuators |
556
+ | `flow_diff` | `flow_begin - flow_end` |
557
+ | Trigger bits | `flow_warning_trigger = flow_diff > flow_diff_WH`, `flow_alarm_trigger` likewise |
558
+ | `press_SD_trigger` | OR of `pressure_AH_F && pressure_SD_F` over the begin and end actuators, logged on change |
559
+ | Protection state | `protect_prereq = comm_OK && work_OK && !pump_change_F`; `protect_F = protect_prereq && !flow_override && !line.flow_override`, i.e. no protection when either the `flow_override` of this section or that of its line is true; `hangon_AF = !protect_prereq` |
560
+ | `flow_warning_F` / `flow_alarm_F` | One rule each: `on_delay(ticker, trigger bit, *_delay)` |
561
+ | `pre_stop_notice` | `flow_alarm_F && line.pump_run && protect_F`: the pump running condition takes the line's (spec §5.2), while `stop_pumps` and the pressure action still take this section's |
562
+ | Countdown | Timing while `pre_stop_notice` is true, `countdown = (action_time - elapsed) / 1000`; when the result is below 0, `countdown` is set to 0 and `countdown_expired` is true |
563
+ | `action_F` | `press_action \|\| flow_action` |
564
+ | `stop_pumps` | `(section auto/man \|\| line auto/man) && pump_run` |
565
+
566
+ `pre_stop_notice` reads the line's `pump_run`, which in turn aggregates the `pump_run` of the sections; after ordering, they are computed in turn within the same scan, and no recomputation through the change event of the line is needed any more.
567
+
568
+ ### 8.3 Interlock actions
569
+
570
+ act rules, run in every scan:
571
+
572
+ 1. Stop command reset: on the falling edge of `pump_run`, clears the section's `auto_stop_cmd` / `man_stop_cmd`. It is declared before the pressure action; both write `auto_stop_cmd` and are ordered by declaration order.
573
+ 2. Pressure action (variable `press_action`):
574
+ - set when `press_SD_trigger && pump_run`, together with the section's `auto_stop_cmd`. `protect_F` is not checked, so it is not restricted by hang-on;
575
+ - otherwise reset when `pump_run && !auto_stop_cmd`: a pump of this section is running (necessarily restarted after the stop), and the interlock condition has disappeared.
576
+ 3. Flow difference action (variable `flow_action`):
577
+ - set on `countdown_expired`, together with the line's `auto_stop_cmd` and this section's `line_action_source`;
578
+ - otherwise first runs `line_action_source &&= line.auto_stop_cmd`, then resets when `line.pump_run && !flow_alarm_F && !line_action_source`. The pump running condition takes the line's, as for the stop pump notice; otherwise a section without pumps could never reset.
579
+ 4. The reset conditions are evaluated in every scan and not latched; during the stop neither pump running condition holds, so the action state is kept until pumps run again.
580
+ 5. Action record: on a rising edge of either action variable, sets the line's `action_section_ID` to this section's ID and calls `add_action_record()` to create a record; when both happen in the same scan, only one record is created. When both action variables are false and the line's `action_section_ID` equals this section's ID, it is cleared, so as not to erase the action of another section.
581
+ 6. Pump commands: on changes of the section's `stop_pumps`, when true sets `command.stop_pumps = node.data.pump_run` for each actuator with pumps; when false sets `stop_pumps = false` and `cancel_stop = true`.
582
+
583
+ The section layout is planned to change in a future transitional version dedicated to layout adjustments: `press_action` / `flow_action` then become Tags, and the action record will be triggered by their change events instead of checking rising edges in the action record rule.
584
+
585
+ ## 9. Line processing (`line_proc.js`)
586
+
587
+ - Rules (`line_rules`, derive):
588
+ - `pump_run`, `pre_stop_notice`: the OR of the properties of the same name of the sections;
589
+ - `alarm_F`: the OR of `flow_alarm_F` and `press_alarm_F` of the sections.
590
+ - The line's `flow_override` is only logged and does not overwrite any section; its effect shows as an AND in the `protect_F` rule of the sections (see §8.2).
591
+ - act rule: on the falling edge of `pump_run`, clears the line's `auto_stop_cmd` / `man_stop_cmd`.
592
+
593
+ ## 10. Action records (`action_record.js`)
594
+
595
+ - The CSV columns are the Tags of RECORD except the Word types and `index`.
596
+ - At startup:
597
+ 1. writes the header when the file does not exist;
598
+ 2. reads all rows as a stream and keeps the latest `records_size` with `unshift`, the newest first;
599
+ 3. restores the types of the columns.
600
+ - `update_record(fields)`: writes the record fields by Tag name, then calls `add_record()`; the mapping between the fields and the section is not in the action record.
601
+ - `add_record()`:
602
+ 1. writes the current time;
603
+ 2. puts the record at the head of the in-memory list;
604
+ 3. sets `index = 0`;
605
+ 4. appends a row with `appendFile`.
606
+ - `index` is handled by an act rule (`action_record_rule` of `action_record_proc.js`), declared after the rules of all sections; the rule remembers the record currently shown in a closure:
607
+ - when `index` differs from the one shown: when -1, clears the time Tags; otherwise loads the corresponding record into data, and when out of range restores the previous value.
608
+ - The record content is filled in by the section's `add_action_record()` through `update_record()` when a pressure action or a flow difference action occurs (see §8.3); `press_action` / `flow_action` take the action variables of the section; the rule for actuator positions is in §13.
609
+
610
+ ## 11. Logging
611
+
612
+ - log4js has two categories:
613
+ - `default`: writes `logs/info.log` and `logs/error.log` with the date pattern `yyyy-MM-dd` of the file appender (`alwaysIncludePattern`, `keepFileExt`, `fileNameSep: "_"`), so the actual file names are `logs/info_<yyyy-MM-dd>.log` and `logs/error_<yyyy-MM-dd>.log` (rolled daily, each file limited to 10 MB, compressed); also writes to the console when `TLMS !== 'controller'`;
614
+ - `console`: writes only to the console.
615
+ - `logger` is a wrapper object that can switch categories.
616
+
617
+ ## 12. Runtime environment, dependencies and build
618
+
619
+ ### 12.1 Runtime environment and process management
620
+
621
+ - Runtime environment: Node.js; the sources are ES modules (using `import ... with { type: 'json' }` and `import.meta.dirname`).
622
+ - Background running uses pm2 (a peer dependency):
623
+ - `tlms start` first runs `pm2 delete tlms_esd`, then `pm2 start` with the fixed process name `tlms_esd`, so only one instance exists at a time;
624
+ - `stop`, `list`, `log`, `flush` correspond to `pm2 delete`, `pm2 list`, `pm2 log`, `pm2 flush`;
625
+ - pm2 starts with `TLMS=controller` set, and the logging module turns off the console output accordingly.
626
+
627
+ ### 12.2 Dependencies
628
+
629
+ | Library | Use |
630
+ | --- | --- |
631
+ | `es-modbus` | Modbus TCP client (to the actuators); the server to the HMI uses it through `modbus-emulator` |
632
+ | `modbus-emulator` | Creation of the data blocks and the upward Modbus TCP server (§4.4); forwards the API of `layout-data` (§3.1) |
633
+ | `layout-data` | Data layer (§3), used through `modbus-emulator`; this project uses directly only its type generation command (§3.3) |
634
+ | `@st-one-io/nodes7` | S7 client (to the actuators) |
635
+ | `yaml` | Configuration and layout parsing (YAML 1.2) |
636
+ | `csv-parser` | Reading the action record CSV |
637
+ | `log4js` | Logging |
638
+ | `mri` | Command-line argument parsing |
639
+
640
+ ### 12.3 Development tools
641
+
642
+ - Package manager: pnpm.
643
+ - Type generation: the `layout-types` command of layout-data (§3.3).
644
+ - Tests: `node --test`.
645
+ - Linting: ESLint with `@stylistic/eslint-plugin` (`eslint.config.js`, `pnpm lint`); JS is indented with tabs. ESLint finds code problems; @stylistic only regulates whitespace, quotes, semicolons and the like, without re-wrapping lines, so the hand-aligned layout tables are kept. Formatters that re-wrap lines (Biome, Prettier) are not used. In addition, the globals equivalent to the `Number` namespace (`isNaN`, `isFinite`, `parseInt`, `parseFloat`, `NaN`, `Infinity`) are forbidden; `Number.isNaN` and the like are used instead.
646
+
647
+ ### 12.4 Build and release
648
+
649
+ - `rolldown.config.js` produces two ES module bundles:
650
+ - `src/main.js` -> `./main.js`;
651
+ - `src/cli.js` -> `./cli.js`, with `./main.js` set as external, so `cli.js` imports the bundle in the same directory at run time.
652
+ - The `prepare` script of `package.json` triggers the build; `bin.tlms` points to `cli.js`.
653
+
654
+ ## 13. Unimplemented items
655
+
656
+ Requirements of the spec that the current code does not implement yet:
657
+
658
+ | Item | Spec requirement | Current code | Locations |
659
+ | --- | --- | --- | --- |
660
+ | ID uniqueness check | The IDs of lines, sections and actuators are all distinct (across types); several blocks of the same object share its ID (spec §4.1) | `config.js` only checks that an actuator `id` is a non-zero number; lines, sections and actuators are each indexed by `ID<id>`, and neither duplicates nor equal IDs across types are reported; a duplicate of the same type silently overwrites the earlier one | `add_conf` in `config.js` |
661
+ | Name uniqueness check | The `name`s of controllers and actuators are all distinct, both within the same type and across types (spec §4.2) | Not checked; `cfg_controllers` and `cfg_actuators` are indexed by `name`, a duplicate of the same type silently overwrites the earlier one, and a controller and an actuator with the same name are not reported | `add_conf` in `config.js` |
662
+ | Name format check | The `name`s of controllers, lines, sections and actuators are identifiers (spec §4.2) | Not checked by the configuration check; a line, section or actuator name that is not an identifier makes `emulator.load` report an invalid block name, which `main.js` logs before it exits | `add_conf` in `config.js` |
663
+ | ID as the upward unit id | The Modbus unit id of a line, section or actuator is its ID (at least 1), the action record is fixed at unit id 0, and the controller configuration no longer has `unit_id` (spec §4.1, 5.5) | `build_description` looks up the unit id by name in `controller.modbus_server.unit_id[name]` (the action record in `unit_id.action_records`), and every object must be listed in the controller configuration | `build_description` in `description.js` |
664
+ | Configuration check command | `tlms check` reads and validates the configuration and all layouts (§3.2), reports all errors, and does not start the controller (spec §3.6, §5.6) | No such command; configuration errors are found only at startup, and most of them exit or crash directly; the layout validation already runs at startup, when the emulator loads the description file (`init_controller`, §4.4), but is not yet wired into the command line | `cli.js`; `config.js` needs a separately callable validation function that collects all errors |
665
+ | Action record positions mapped to actuators (defect in the existing code) | Nodes 1-4 map to the actuators of the action section in order, begin actuators first, then end actuators; the pressure, ID and pump running state of each position come from the same actuator (spec §5.4) | Nodes 1-3 always take `begin_nodes[0..2]`, node 4 always takes `end_nodes[0]`; `node1..3_pump_run` come from `pump_nodes[0..2]` (actuators with pumps only, which may be misaligned with the node positions), and `node4_pump_run` is never assigned | `add_action_record` in `section_proc.js` |
666
+
667
+ ## 14. Command processing
668
+
669
+ All commands go through the common handshake of §7.3 (send the command word, clear the corresponding bits on receiving `response_code`); some commands also have local processing in the controller:
670
+
671
+ | Command | Command word bit | Controller processing |
672
+ | --- | --- | --- |
673
+ | `stop_pumps` | 0 | Set by the section's `stop_pumps`; withdrawn when the actuator's pump running state becomes false |
674
+ | `cancel_stop` | 1 | Set when the section's `stop_pumps` is withdrawn, so the actuator releases the stop pump output |
675
+ | `horn` / `reset_horn` | 2 / 3 | Common handshake |
676
+ | `enable_pressure_SD` / `disable_pressure_SD` | 4 / 5 | Common handshake, also cleared on changes of `pressure_SD_F` |
677
+ | `read_paras` | 6 | Local processing (actuator parameters copied to the command block), no need to send |
678
+ | `write_paras` | 7 | Local processing: writes the parameters directly to the actuator data area, resets after completion |
679
+ | `enable_pressure_alarm` / `disable_pressure_alarm` | 8 / 9 | Common handshake |
680
+ | `enable` / `disable` | 10 / 11 | Common handshake |
681
+ | `reset_CPU` / `reset_conn` | 12 / 13 | Common handshake |
682
+
683
+ ### 14.1 Command masking
684
+
685
+ Commands are masked by the `supported_commands` configured for each actuator (spec §5.1):
686
+
687
+ - Parsing: when `config.js` parses an actuator, it converts the `supported_commands` array into a 16-bit mask word `command_mask`. For each command name of the array, the command word bit k is looked up in the command enumeration (`node_commands`), and bit k of the mask is set to 1; the bit numbers are the register bits (see §3.2).
688
+ - Validation: a name outside the command enumeration in the array is a configuration error; the program reports it at startup and exits, in the same way as the validation of the actuator `id`.
689
+ - When the field is omitted, all commands are supported, and `command_mask` takes all bits 0-13 of the command enumeration, i.e. `0x3FFF`.
690
+ - Use: `command_mask` is carried into the runtime with the actuator object. Each actuator has a masking rule, which in every scan resets by name, bit by bit, the command bits that are 0 in `command_mask`; bit 14 (`reserve`) and bit 15 (`executing`) are not commands and are not affected.
691
+ - The masking rule is declared after all other rules: several writers of the same command bit are ordered by declaration order, so it comes after the other rules writing command bits; since it writes command bits, it comes before the sending rule that reads `commands`, so unsupported command bits are never sent.