diff --git a/wiki/Home.md b/wiki/Home.md index 43ce3ea..7ee8ca2 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -1,13 +1,28 @@ # measurement -> **Reflects code as of `125f964` · regenerated `2026-05-11` via `npm run wiki:all`** -> If this banner is stale, the page may be out of date. Treat as informative, not authoritative. +![code-ref](https://img.shields.io/badge/code--ref-b884c0f-blue) ![s88](https://img.shields.io/badge/S88-Control_Module-a9daee) ![status](https://img.shields.io/badge/status-under--review-orange) -## 1. What this node is +A `measurement` turns a raw sensor signal into a validated, scaled, smoothed reading and re-emits it for any upstream parent. Two modes: **analog** (one channel built from the flat config — classic 4–20 mA / PLC style) and **digital** (one `Channel` per `config.channels[]` entry — MQTT / IoT JSON style). It is a leaf in the S88 hierarchy — no children of its own — and registers itself as a child of any parent that accepts measurements (`rotatingMachine`, `machineGroupControl`, `pumpingStation`, `reactor`, `monster`, …). -**measurement** is an S88 Control Module that turns a raw sensor signal into a validated, scaled, smoothed reading and re-emits it for any parent. Two modes: **analog** (one channel built from the flat config) and **digital** (one Channel per `config.channels[]` entry). It is a leaf in the hierarchy — no children of its own. +> [!NOTE] +> Pending full node review (2026-05). Content reflects `CONTRACT.md`, `src/commands/index.js`, and current source only. Some sections are best-effort placeholders pending the next pass. -## 2. Position in the platform +--- + +## At a glance + +| Thing | Value | +|:---|:---| +| What it represents | One sensor signal — pressure / flow / power / temperature / level / … | +| S88 level | Control Module | +| Use it when | You need to scale, offset, smooth, outlier-filter, or simulate a sensor reading before handing it to an equipment / unit / process-cell node | +| Don't use it for | Sensor fusion, threshold-trip alarms, or as a control output — this node is read-only signal conditioning | +| Children it accepts | None — leaf node | +| Parents it talks to | Any node that subscribes to `.measured.` events (`rotatingMachine`, `MGC`, `pumpingStation`, `reactor`, `monster`, …) | + +--- + +## How it fits ```mermaid flowchart LR @@ -18,12 +33,12 @@ flowchart LR p3[pumpingStation
Process Cell]:::pc raw -->|data.measurement| m - m -->|child.register| p1 + m -->|child.register
(Port 2 at startup)| p1 m -->|child.register| p2 m -->|child.register| p3 - m -..measured..-> p1 - m -..measured..-> p2 - m -..measured..-> p3 + m -.->|"<type>.measured.<position>"| p1 + m -.->|"<type>.measured.<position>"| p2 + m -.->|"<type>.measured.<position>"| p3 classDef pc fill:#0c99d9,color:#fff classDef unit fill:#50a8d9,color:#000 classDef equip fill:#86bbdd,color:#000 @@ -32,227 +47,117 @@ flowchart LR S88 colours: Control Module `#a9daee`, Equipment `#86bbdd`, Unit `#50a8d9`, Process Cell `#0c99d9`. Source of truth: `.claude/rules/node-red-flow-layout.md`. -## 3. Capability matrix +--- -| Capability | Status | Notes | -|---|---|---| -| Analog mode — single channel from flat config | ✅ | Default. `data.measurement` payload is numeric. | -| Digital mode — many channels from `config.channels[]` | ✅ | Payload is an object keyed by `channel.key`. | -| Outlier detection | ✅ | Median ± window check. Toggleable via `set.outlier-detection`. | -| Scaling (input range → process range + offset) | ✅ | `config.scaling.{inputMin,inputMax,absMin,absMax,offset}`. | -| Smoothing (moving window) | ✅ | `config.smoothing.{smoothWindow,smoothMethod}`. | -| Min/max tracking | ✅ | `totalMinValue`, `totalMaxValue`, smoothed variants. | -| Calibration (capture current as zero/reference) | ✅ | `cmd.calibrate`. Mutates `config.scaling.offset`. | -| Built-in simulator | ✅ | Sinusoidal/noise driver — `set.simulator` toggles. | -| Repeatability / stability metrics | ✅ | `evaluateRepeatability()`, `isStable()`. | -| Accepts children of its own | ❌ | Leaf node. | +## Try it — 1-minute demo -## 4. Code map +Import the basic example flow, deploy, and drive a single sensor through scaling + smoothing. -```mermaid -flowchart TB - subgraph nodeRED["nodeClass.js — adapter (BaseNodeAdapter)"] - nc["buildDomainConfig()
static DomainClass, commands
static tickInterval = 1000ms"] - end - subgraph domain["specificClass.js — orchestrator (BaseDomain)"] - sc["Measurement.configure()
mode = analog | digital
builds Channel(s)"] - end - subgraph concerns["src/ concern modules"] - channel["channel.js
outlier → offset → scaling →
smoothing → minMax pipeline"] - simulation["simulation/
built-in Simulator"] - calibration["calibration/
Calibrator + stability"] - commands["commands/
topic registry + handlers"] - end - nc --> sc - sc --> channel - sc --> simulation - sc --> calibration - nc --> commands +```bash +curl -X POST -H 'Content-Type: application/json' \ + --data @nodes/measurement/examples/basic.flow.json \ + http://localhost:1880/flows ``` -| Module | Owns | Read first if you're changing… | -|---|---|---| -| `channel.js` | Per-channel pipeline (outlier → offset → scaling → smoothing → emit) | Per-tick reading flow, unit semantics, emitted event name. | -| `simulation/` | Built-in signal generator for demos and offline tests | Sim behaviour, period / amplitude. | -| `calibration/` | Stability checks, repeatability, offset capture | `cmd.calibrate` behaviour, stable-window heuristic. | -| `commands/` | Input-topic registry and handlers | New input topics, payload validation. | +What to do after deploy: -The analog/digital branch is decided once in `configure()` based on `config.mode.current`. There is no FSM — `tick()` only pumps the simulator when enabled. +1. Click the `measurement 42` inject — sends `topic: 'measurement'` (legacy alias of `data.measurement`) with payload `42`. +2. Watch Port 0 in the debug pane: `mAbs` updates immediately. After a few injects `totalMinValue` / `totalMaxValue` start tracking the rolling min/max. +3. Toggle the simulator: send `topic: 'set.simulator'`. `tick()` (1000 ms) starts driving `inputValue` through `Simulator.step()`. +4. Trigger calibration: send `topic: 'cmd.calibrate'`. If the rolling window is stable (`stdDev <= config.calibration.stabilityThreshold`) the calibrator captures the current output as the new `config.scaling.offset`. -```mermaid -flowchart LR - cfg[config.mode.current] - cfg -->|"=== 'digital'"| dig[Build N Channels
from config.channels[]] - cfg -->|"=== 'analog' (default)"| ana[Build 1 Channel
from flat config] - dig --> emit_d[handleDigitalPayload
fan-out per channel] - ana --> emit_a[inputValue setter
single channel update] -``` +> [!IMPORTANT] +> **GIF needed.** Demo recording of steps 1–4 with the live status badge. Save as `wiki/_partial-gifs/measurement/01-basic-demo.gif`, target ≤ 1 MB after `gifsicle -O3 --lossy=80`. -## 5. Topic contract +--- -> **Auto-generated** from `src/commands/index.js`. Do NOT hand-edit between the markers. Re-run `npm run wiki:contract`. +## The four things you'll send - +| Topic | Aliases | Payload | What it does | +|:---|:---|:---|:---| +| `data.measurement` | `measurement` | analog: `number` (or numeric string); digital: `{: number, …}` | Push a raw reading into the pipeline. Wrong shape for the configured mode logs a hint suggesting the other mode. | +| `set.simulator` | `simulator` | (ignored) | Toggle the built-in `Simulator` random-walk on / off. Mutates `config.simulation.enabled`. | +| `set.outlier-detection` | `outlierDetection` | (ignored) | Toggle outlier detection on the analog pipeline. Mutates `config.outlierDetection.enabled`. | +| `cmd.calibrate` | `calibrate` | (ignored) | Run a one-shot calibration. Captures the current output as `config.scaling.offset`; aborts with a warn if the buffer is not stable. | -| Canonical topic | Aliases | Payload | Unit | Effect | -|---|---|---|---|---| -| `set.simulator` | `simulator` | `any` | — | Toggle the built-in simulator on / off. | -| `set.outlier-detection` | `outlierDetection` | `any` | — | Toggle / configure outlier detection on the measurement pipeline. | -| `cmd.calibrate` | `calibrate` | `any` | — | Trigger a one-shot calibration of the measurement. | -| `data.measurement` | `measurement` | `any` | — | Push a raw measurement (analog: number; digital: per-channel object). | +Aliases log a one-time deprecation warning the first time they fire. - +--- -## 6. Child registration +## What you'll see come out -`measurement` does **not accept children**. It only **registers itself** as a child on its upstream parent. +Sample Port 0 message (analog mode, after a few injects): -```mermaid -flowchart LR - m[measurement]:::ctrl -->|"child.register
(Port 2 at startup)"| parent[rotatingMachine /
MGC / pumpingStation /
reactor / monster] - m -.->|"<type>.measured.<position>
(measurements.emitter)"| parent - classDef ctrl fill:#a9daee,color:#000 -``` - -| What | softwareType payload | Side-effect on parent | -|---|---|---| -| Registration | `measurement` | Parent attaches listener for `.measured.`. | -| Subsequent updates | event on `child.measurements.emitter` | Parent mirrors value into its own `MeasurementContainer`. | - -Position labels are normalised to **lowercase** in the event name (`upstream`, `downstream`, `atequipment`). - -## 7. Lifecycle — what one event (or tick) does - -```mermaid -sequenceDiagram - participant ext as external sender - participant m as measurement - participant ch as Channel pipeline - participant emitter as measurements.emitter - participant parent as parent (e.g. rotatingMachine) - - ext->>m: data.measurement (12.4) - m->>m: command dispatch (analog branch) - m->>ch: update(12.4) - ch->>ch: outlier check → offset → scale → smooth → minMax - ch->>emitter: .measured. {value, ts, unit} - emitter-->>parent: child event (subscribed at register-time) - m->>m: notifyOutputChanged() - m-->>ext: Port 0 + Port 1 (delta-compressed) - Note over m: every 1000 ms: if simulation.enabled,
simulator.step() → inputValue -``` - -## 8. Data model — `getOutput()` - -Analog mode emits the legacy scalar shape. Digital mode emits a nested `{channels:{...}}` keyed by `channel.key`. - - - -| Key | Type | Unit | Sample | -|---|---|---|---| -| `mAbs` | number | — | `0` | -| `mPercent` | number | — | `0` | -| `totalMaxSmooth` | number | — | `0` | -| `totalMaxValue` | number | — | `0` | -| `totalMinSmooth` | number | — | `0` | -| `totalMinValue` | number | — | `0` | - - - -**Concrete digital sample** (when `mode='digital'`): - -~~~json +```json { - "channels": { - "level-a": { "mAbs": 1.84, "mPercent": 73.6, "totalMinValue": 0.1, "totalMaxValue": 2.4 }, - "temp-a": { "mAbs": 18.2, "mPercent": 36.4, "totalMinValue": 14.0, "totalMaxValue": 22.1 } + "topic": "measurement#sensor_a", + "payload": { + "mAbs": 0.42, + "mPercent": 42, + "totalMinValue": 0.12, + "totalMaxValue": 0.78, + "totalMinSmooth": 0.20, + "totalMaxSmooth": 0.65 } } -~~~ - -In addition, the legacy `source.emitter` fires `'mAbs'` (analog only) — kept for the editor status badge during the refactor window. - -## 9. Configuration — editor form ↔ config keys - -```mermaid -flowchart TB - subgraph editor["Node-RED editor form"] - f1[Mode: analog / digital] - f2[Asset type + unit] - f3[Position vs parent] - f4[Scaling: inputMin/Max, absMin/Max, offset] - f5[Smoothing: window + method] - f6[Outlier detection: enabled + window] - f7[Simulation: enabled + amplitude/period] - f8[Digital channels list] - end - subgraph cfg["Domain config slice"] - c1[mode.current] - c2[asset.type / asset.unit] - c3[functionality.positionVsParent] - c4[scaling.*] - c5[smoothing.*] - c6[outlierDetection.*] - c7[simulation.*] - c8[channels []] - end - f1 --> c1 - f2 --> c2 - f3 --> c3 - f4 --> c4 - f5 --> c5 - f6 --> c6 - f7 --> c7 - f8 --> c8 ``` -| Form field | Config key | Default | Range | Where used | -|---|---|---|---|---| -| Mode | `mode.current` | `analog` | enum (`analog`, `digital`) | `Measurement.configure` | -| Asset type | `asset.type` | `pressure` | enum | event name + unit policy | -| Position vs parent | `functionality.positionVsParent` | `atEquipment` | enum | event name suffix | -| Scaling enabled | `scaling.enabled` | `false` | bool | `Channel._applyScaling` | -| Input min/max | `scaling.inputMin/Max` | `0` / `1` | numeric | linear map foot/top | -| Output min/max | `scaling.absMin/absMax` | `50` / `100` | numeric | linear map foot/top | -| Offset | `scaling.offset` | `0` | numeric | calibration target | -| Smoothing window | `smoothing.smoothWindow` | `10` | ≥ 1 (samples) | moving window | -| Outlier detection | `outlierDetection.enabled` | varies | bool | `Channel._isOutlier` | -| Simulation enabled | `simulation.enabled` | `false` | bool | `tick()` step | +Sample Port 0 message (digital mode): -## 10. Examples +```json +{ + "topic": "measurement#multi", + "payload": { + "channels": { + "level-a": { "mAbs": 1.84, "mPercent": 73.6, "totalMinValue": 0.1, "totalMaxValue": 2.4 }, + "temp-a": { "mAbs": 18.2, "mPercent": 36.4, "totalMinValue": 14.0, "totalMaxValue": 22.1 } + } + } +} +``` -| Tier | File | What it shows | Status | -|---|---|---|---| -| Basic | `examples/basic.flow.json` | Inject + dashboard, no parent | ⚠️ legacy shape, pre-refactor | -| Integration | `examples/integration.flow.json` | measurement registered as child of a parent | ⚠️ legacy shape, pre-refactor | -| Edge | `examples/edge.flow.json` | Outlier / scaling / simulator edge cases | ⚠️ legacy shape, pre-refactor | +| Field | Meaning | +|:---|:---| +| `mAbs` | Latest output value in scaling-units (after offset + scaling + smoothing). | +| `mPercent` | Same value mapped to `interpolation.percentMin..percentMax` (default 0..100). | +| `totalMinValue` / `totalMaxValue` | Rolling min/max of **raw** (pre-scaling) values. `0` until first sample. | +| `totalMinSmooth` / `totalMaxSmooth` | Rolling min/max of the smoothed output. | -Tier 1/2/3 visual-first example flows are still TODO (see `MEMORY.md` "TODO: Example Flows"). Screenshots will land under `wiki/_partial-screenshots/measurement/` when the new flows ship. +Additionally the `source.measurements.emitter` fires `.measured.` on every accepted update — parents subscribe to that event through the `child.measurements.emitter` handshake established at register time. See [Architecture — Lifecycle](Reference-Architecture#lifecycle) for the full path. -## 11. Debug recipes +--- -| Symptom | First thing to check | Where to look | -|---|---|---| -| Parent never receives `.measured.` | `assetType` must match parent's filter exactly (e.g. `flow` — not `flow-electromagnetic`). | `config.asset.type` + `MEMORY.md` integration gotcha. | -| Position labels look uppercase to parent | Event name lowercases — but `functionality.positionVsParent` is sent as-is on `child.register`. | `_buildAnalogChannel` event-name composition. | -| Outliers seem to pass through | `outlierDetection.enabled` may be off (default varies by config). Toggle with `set.outlier-detection`. | `Channel._isOutlier`. | -| `cmd.calibrate` does nothing | Calibrator requires ≥ 2 stable samples — check `isStable()` first. | `calibration/calibrator.js`. | -| Digital payload silently dropped | Unknown channel keys land in the `unknown` log line only at debug level. | enable `logging.logLevel=debug` momentarily. | -| Simulator still running after toggle off | `tick()` reads `config.simulation.enabled` each tick — confirm the toggle actually mutated the config. | `toggleSimulation`. | +## How the pipeline behaves -> Never ship `enableLog: 'debug'` in a demo — fills the container log within seconds and obscures real errors. +```mermaid +flowchart LR + in[input value] --> out{outlierDetection.enabled?} + out -- yes --> oc[_isOutlier] + oc -- outlier --> drop[drop + warn] + oc -- ok --> off[apply scaling.offset] + out -- no --> off + off --> mm[update raw totalMin/Max] + mm --> sc{scaling.enabled?} + sc -- yes --> lin[linear map
input range → abs range] + sc -- no --> sm[pass-through] + lin --> sm + sm --> sw[push to storedValues
length capped by smoothWindow] + sw --> sf[smoothMethod:
mean / median / kalman / …] + sf --> sm2[update smooth totalMin/Max] + sm2 --> wo[round + write outputAbs
+ emit measurement event] +``` -## 12. When you would NOT use this node +The same pipeline runs per `Channel` instance — once in analog mode, N times in digital mode. -- Don't use measurement to **fuse** signals from multiple sensors — it's per-channel only. Aggregate at the parent. -- Don't use measurement for **control output** — it's read-only signal conditioning. Use `rotatingMachine` / `valve` for actuation. -- Don't use measurement for **alarm logic** — there is no threshold-trip output. Build that on top of the emitted reading at the parent or in a dashboard rule. +--- -## 13. Known limitations / current issues +## Need more? -| # | Issue | Tracked in | -|---|---|---| -| 1 | Legacy `source.emitter` 'mAbs' event still fired alongside `measurements.emitter` — slated for removal in Phase 7. | `OPEN_QUESTIONS.md` (2026-05-10) | -| 2 | Digital mode's per-channel scaling/smoothing falls back to the analog block's defaults when not specified per channel. | `_buildDigitalChannels`. | -| 3 | Tier 1/2/3 visual-first example flows not yet written; current `examples/` only contains pre-refactor flows. | P9 / P2.14 follow-up. | -| 4 | No automatic recalibration — `cmd.calibrate` is operator-triggered. | `calibration/calibrator.js`. | +| Page | What you'll find | +|:---|:---| +| [Reference — Contracts](Reference-Contracts) | Full topic contract, config schema, child-registration handshake | +| [Reference — Architecture](Reference-Architecture) | Code map, lifecycle, analog vs digital branching, per-Channel pipeline | +| [Reference — Examples](Reference-Examples) | Shipped example flows + debug recipes | +| [Reference — Limitations](Reference-Limitations) | When not to use, known limitations, open questions | + +[EVOLV master wiki](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Home) · [Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) · [Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions) diff --git a/wiki/Reference-Architecture.md b/wiki/Reference-Architecture.md new file mode 100644 index 0000000..9cd17c7 --- /dev/null +++ b/wiki/Reference-Architecture.md @@ -0,0 +1,244 @@ +# Reference — Architecture + +![code-ref](https://img.shields.io/badge/code--ref-b884c0f-blue) + +> [!NOTE] +> Code structure for `measurement`: the three-tier sandwich, the `src/` layout, the per-`Channel` pipeline, the analog vs digital branching, the lifecycle, and the output-port pipeline. For an intuitive overview, return to [Home](Home). +> +> Pending full node review (2026-05). Content reflects current source and `CONTRACT.md`; sections noted as TODO require a second pass. + +--- + +## Three-tier code layout + +``` +nodes/measurement/ +| ++-- measurement.js entry: RED.nodes.registerType('measurement', NodeClass) +| + admin endpoints (menu.js, configData.js, asset-reg) +| ++-- src/ +| nodeClass.js extends BaseNodeAdapter (Node-RED bridge) +| specificClass.js extends BaseDomain (orchestrates Channels + helpers) +| channel.js one scalar pipeline (outlier → offset → scale → smooth → emit) +| | +| +-- commands/ +| | index.js topic registry (set.simulator / set.outlier-detection / +| | cmd.calibrate / data.measurement) +| | handlers.js pure handler functions (mode-dispatching for data.measurement) +| | +| +-- simulation/ +| | simulator.js Simulator — random-walk driver for the analog input +| | +| +-- calibration/ +| calibrator.js Calibrator — stability check, offset capture, repeatability proxy +``` + +### Tier responsibilities + +| Tier | File | What it owns | Touches `RED.*` | +|:---|:---|:---|:---:| +| entry | `measurement.js` | Type registration; admin HTTP endpoints (`/menu.js`, `/configData.js`, `/asset-reg`) | Yes | +| nodeClass | `src/nodeClass.js` | Wraps `BaseNodeAdapter`; declares `DomainClass = Measurement`, `commands`, `tickInterval = 1000 ms`, `statusInterval = 1000 ms`; `buildDomainConfig()` reshapes the editor's flat `uiConfig` into the domain config slice | Yes (via base class) | +| specificClass | `src/specificClass.js` | Orchestrator. In `configure()` builds one `Channel` (analog) or N `Channels` (digital), wires up `Simulator` and `Calibrator`, installs legacy mirrors so pre-refactor tests keep passing | No | +| concern | `src/channel.js` | Pure per-channel pipeline: outlier → offset → scaling → smoothing → min/max → emit | No | +| concern | `src/simulation/simulator.js` | Random-walk driver used when `config.simulation.enabled` is true | No | +| concern | `src/calibration/calibrator.js` | Stability detection (`isStable`), calibration offset capture (`calibrate`), repeatability proxy (`evaluateRepeatability`) | No | + +`specificClass` is stitching. All real work lives in the concern modules. + +--- + +## No FSM — just modes + a pipeline + +Unlike `rotatingMachine` or `pumpingStation`, `measurement` has **no state machine**. The behavioural switch is a one-time decision made in `Measurement.configure()`: + +```mermaid +flowchart LR + cfg[config.mode.current] + cfg -->|"=== 'digital'"| dig[_buildDigitalChannels
one Channel per config.channels[i]] + cfg -->|"=== 'analog' (default)"| ana[_buildAnalogChannel
one Channel from flat config] + dig --> emit_d[handleDigitalPayload
fan-out per channel] + ana --> emit_a[inputValue setter
single channel update] + classDef ctrl fill:#a9daee,color:#000 +``` + +After `configure()`: + +- **analog mode** → `this.analogChannel` is set, `this.channels` is an empty `Map`. Setting `m.inputValue = v` runs the whole pipeline and `notifyOutputChanged()` fires Port 0. +- **digital mode** → `this.channels` is keyed by `channel.key`; `analogChannel` is `undefined`. `handleDigitalPayload(payload)` walks every key in the incoming object, dispatches to the matching `Channel`, and collects a per-channel `{ok, mAbs, mPercent}` summary. + +The 1000 ms `tick()` is **only** used to drive the built-in simulator when `config.simulation.enabled` is true; the rest of the node is event-driven (input msg arrives → pipeline runs → emit). + +--- + +## The per-`Channel` pipeline + +```mermaid +flowchart TB + in[update(value)] --> oe{outlierDetection
.enabled?} + oe -- no --> off[+= scaling.offset] + oe -- yes --> iso[_isOutlier(value)] + iso -- outlier --> drop[return false
warn + drop] + iso -- ok --> off + off --> rmm[update totalMinValue
/ totalMaxValue] + rmm --> sc{scaling.enabled?} + sc -- yes --> as[_applyScaling] + sc -- no --> sm[(unchanged)] + as --> sm + sm --> push[push to storedValues
cap at smoothWindow] + push --> meth[switch(smoothMethod)] + meth --> sms[update totalMinSmooth
/ totalMaxSmooth] + sms --> wo[round to 2dp
compare to outputAbs
(only emit on change)] + wo --> emit[measurements.emitter
fires <type>.measured.<position>] +``` + +Source: `src/channel.js` `update(value)`. + +### Outlier methods + +| `method` (config) | Implementation | Threshold default | +|:---|:---|:---:| +| `zScore` (default) | `_zScore`: `\|val - mean\| / stdDev > threshold` | `3` | +| `iqr` | `_iqr`: `val < q1 - 1.5*iqr` or `val > q3 + 1.5*iqr` | `3` | +| `modifiedZScore` | `_modifiedZScore`: `0.6745 * (val - median) / mad > threshold` | `3.5` | + +`_isOutlier` returns `false` when fewer than 2 samples are stored (warm-up). The `zScore` branch is intentionally **not** short-circuited at `stdDev === 0`: a perfectly flat baseline marks any deviation as an outlier. + +### Smoothing methods + +Each tick the smoother pushes the post-scaling value into `storedValues`, trims the buffer to `smoothing.smoothWindow`, then collapses it to a single scalar via `smoothing.smoothMethod`: + +| Method | Behaviour | +|:---|:---| +| `none` | Pass through the latest sample | +| `mean` (default) | Arithmetic mean of the window | +| `min` / `max` | Smallest / largest in the window | +| `sd` | Standard deviation | +| `median` | Middle value, robust to outliers | +| `weightedMovingAverage` | Linear weights `1..N` | +| `lowPass` | EWMA, `alpha = 0.2` | +| `highPass` | First-order high-pass, `alpha = 0.8` | +| `bandPass` | LP + HP combination | +| `kalman` | Simple 1-D Kalman with fixed gain | +| `savitzkyGolay` | 5-point cubic SG filter (`[-3, 12, 17, 12, -3] / 35`) | + +Unknown method names log an error and pass the raw value through. + +### Scaling and percent mapping + +`_applyScaling(value)` performs a linear map `[scaling.inputMin..inputMax]` → `[scaling.absMin..absMax]`, clamping the input to the source range first. An invalid input range (`inputMax <= inputMin`) self-heals to `[0, 1]` and logs a warn. + +`_computePercent(value)` then maps the **clamped** result into the percent range `[interpolation.percentMin..percentMax]` (defaults 0..100). When `scaling.enabled` is false and `absMax <= absMin` the percent uses the live `totalMinValue / totalMaxValue` instead. + +`_writeOutput` rounds to 2 decimal places and only emits a new measurement when `rounded !== outputAbs` — so a stable input does **not** retrigger downstream. + +--- + +## Lifecycle — what one event does + +### Analog mode + +```mermaid +sequenceDiagram + autonumber + participant ext as external sender + participant nc as nodeClass + participant m as Measurement + participant ch as Channel pipeline + participant emitter as measurements.emitter + participant parent as registered parent + + ext->>nc: msg {topic:'data.measurement', payload:42} + nc->>m: dispatch via commands.handlers.dataMeasurement + m->>m: set inputValue = 42 + m->>ch: analogChannel.update(42) + ch->>ch: outlier → offset → scale → smooth → minMax + ch->>emitter: pressure.measured.atequipment {value, ts, unit} + emitter-->>parent: child measurement event (subscribed at register-time) + m->>nc: notifyOutputChanged() + nc-->>ext: Port 0 + Port 1 (delta-compressed) + Note over nc: every 1000 ms: if simulation.enabled,
simulator.step() → m.inputValue +``` + +### Digital mode + +```mermaid +sequenceDiagram + autonumber + participant ext as external sender + participant nc as nodeClass + participant m as Measurement + participant chs as Channels (per key) + participant emitter as measurements.emitter + participant parent as registered parent + + ext->>nc: msg {topic:'data.measurement', payload:{level-a:1.8, temp-a:18}} + nc->>m: handlers.dataMeasurement (digital branch) + m->>m: handleDigitalPayload(payload) + loop for each key in payload + m->>chs: Channel.update(value) + chs->>emitter: <type>.measured.<position> per channel + emitter-->>parent: one event per channel that accepted a value + end + m-->>ext: Port 0 + Port 1 (nested {channels:{...}}) +``` + +> [!NOTE] +> Digital mode currently does **not** call `notifyOutputChanged()` from `handleDigitalPayload`. TODO: confirm whether Port 0 fan-out relies on the tick or on a follow-up notify; pending review of how `BaseNodeAdapter` schedules digital-mode output emission. + +--- + +## Output ports + +| Port | Carries | Sample shape | +|:---|:---|:---| +| 0 (process) | Delta-compressed snapshot of `getOutput()` — analog scalar fields or digital `{channels:{...}}` | `{topic: , payload: {mAbs, mPercent, totalMin/MaxValue, totalMin/MaxSmooth}}` (analog) | +| 1 (telemetry) | InfluxDB line-protocol payload, same fields as Port 0 | `measurement,id=sensor_a mAbs=0.42,mPercent=42,...` | +| 2 (registration) | One `{topic:'registerChild', payload:, positionVsParent, distance}` at startup | `{topic:'registerChild', payload:''}` | + +Port-0 / Port-1 use the standard `outputUtils.formatMsg(..., 'process' | 'influxdb')` formatters. Delta compression means consumers see only the keys that changed since the previous tick. + +See [EVOLV — Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry) for the platform InfluxDB layout. + +--- + +## Event sources + +| Source | Where it fires | What it triggers | +|:---|:---|:---| +| Inbound `msg.topic` | Node-RED input wire | `commands.handlers.` dispatch via `BaseNodeAdapter` | +| `setInterval(tickInterval = 1000)` | `BaseNodeAdapter` | `Measurement.tick()` — runs `Simulator.step()` only when `config.simulation.enabled` | +| `setInterval(statusInterval = 1000)` | `BaseNodeAdapter` | `Measurement.getStatusBadge()` re-rendered | +| `Channel._writeOutput` → `measurements.emitter` | Every accepted update where the rounded output changed | `.measured.` fires once per channel that produced a new value | +| `source.emitter` `'mAbs'` (legacy) | Analog `inputValue` setter | Editor status badge during the refactor window — deprecated, slated for removal in Phase 7 | + +No per-tick FSM. The only background work is the 1000 ms simulator pump. + +--- + +## Where to start reading + +| If you're changing... | Read first | +|:---|:---| +| The per-sample pipeline (outlier / scaling / smoothing) | `src/channel.js` `update`, `_isOutlier`, `_applyScaling`, `_applySmoothing` | +| Analog vs digital branching | `src/specificClass.js` `configure`, `_buildAnalogChannel`, `_buildDigitalChannels`, `handleDigitalPayload` | +| Top-level topic dispatch | `src/commands/{index, handlers}.js` | +| Simulator step / bounds | `src/simulation/simulator.js` `step` | +| Calibration stability / offset capture | `src/calibration/calibrator.js` `isStable`, `calibrate`, `evaluateRepeatability` | +| Editor → domain config reshape | `src/nodeClass.js` `buildDomainConfig` | +| Per-node status badge | `Measurement.getStatusBadge` | +| Output shape | `Measurement.getOutput` (analog) / `getDigitalOutput` (digital) | + +--- + +## Related pages + +| Page | Why | +|:---|:---| +| [Home](Home) | Intuitive overview | +| [Reference — Contracts](Reference-Contracts) | Topic + config + child registration | +| [Reference — Examples](Reference-Examples) | Shipped flows + debug recipes | +| [Reference — Limitations](Reference-Limitations) | Known issues and open questions | +| [rotatingMachine wiki](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Home) | The most common consumer of measurement | +| [EVOLV — Architecture](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Architecture) | Platform-wide three-tier pattern | diff --git a/wiki/Reference-Contracts.md b/wiki/Reference-Contracts.md new file mode 100644 index 0000000..4e30e66 --- /dev/null +++ b/wiki/Reference-Contracts.md @@ -0,0 +1,279 @@ +# Reference — Contracts + +![code-ref](https://img.shields.io/badge/code--ref-b884c0f-blue) + +> [!NOTE] +> Full topic contract, configuration schema, and child-registration handshake for `measurement`. Source of truth: `src/commands/index.js`, `src/commands/handlers.js`, `src/specificClass.js` `configure()`, and the schema at `generalFunctions/src/configs/measurement.json`. +> +> Pending full node review (2026-05). Hand-written best-effort placeholder where indicated. For an intuitive overview, return to [Home](Home). + +--- + +## Topic contract + +The registry lives in `src/commands/index.js`. Each descriptor maps a canonical `msg.topic` to a handler; aliases emit a one-time deprecation warning the first time they fire. + + + +| Canonical topic | Aliases | Payload | Unit | Effect | +|:---|:---|:---|:---|:---| +| `set.simulator` | `simulator` | (ignored) | — | Toggles `source.toggleSimulation()` — flips `config.simulation.enabled`. | +| `set.outlier-detection` | `outlierDetection` | (ignored) | — | Toggles `source.toggleOutlierDetection()` — flips `config.outlierDetection.enabled` and propagates the new value to `analogChannel.outlierDetection.enabled`. | +| `cmd.calibrate` | `calibrate` | (ignored) | — | Calls `source.calibrate()` — if the rolling window is stable, captures the current output as the new `config.scaling.offset`. Aborts with a warn when unstable or when the calibration baseline is missing. | +| `data.measurement` | `measurement` | mode-dependent (see below) | per channel (configured) | Push a raw sensor reading into the pipeline. Mode-dispatched in `handlers.dataMeasurement`: **analog** expects a number / numeric string → `source.inputValue = parsed`; **digital** expects an object keyed by channel name → `source.handleDigitalPayload(payload)`. Wrong shape for the configured mode logs a hint suggesting the other mode. | + + + +### Payload-shape rules + +| Mode | Accepted | Rejected (logs warn) | +|:---|:---|:---| +| `analog` | `number`; numeric string (trimmed, non-empty, parses with `Number`) | object payload (hint: "Switch Input Mode to 'digital' …"); non-numeric string | +| `digital` | object `{ key1: number, key2: number, … }` — keys must match `config.channels[*].key` | number (hint: "Switch Input Mode to 'analog' …"); array; any non-object | + +Unknown channel keys in a digital payload are collected and reported at `debug` level via `digital payload contained unmapped keys: `. + +### Source / mode allow-lists + +> [!NOTE] +> TODO: `measurement` does not appear to implement a `flowController`-style action/source allow-list (consult `src/specificClass.js`); it relies on the topic registry's typeof checks. If a future hardening pass adds mode-source gating, fold the table in here. + +--- + +## Data model — `getOutput()` shape + +Source: `src/specificClass.js` `getOutput()` / `getDigitalOutput()` and `src/channel.js` `getOutput()`. Delta-compressed by `outputUtils.formatMsg`: consumers see only the keys that changed. + + + +### Analog mode (`Measurement.getOutput()`) + +| Key | Type | Unit | Notes | +|:---|:---|:---|:---| +| `mAbs` | number | scaling units (`asset.unit` / `general.unit`) | Latest output value after offset + scaling + smoothing. Rounded to 2 dp. | +| `mPercent` | number | % | Output mapped to `interpolation.percentMin..percentMax`. Rounded to 2 dp. | +| `totalMinValue` | number | scaling units | Rolling minimum of the **post-offset, pre-smoothing** values. Reported as `0` until the first sample. | +| `totalMaxValue` | number | scaling units | Rolling maximum of the same. Reported as `0` until the first sample. | +| `totalMinSmooth` | number | scaling units | Rolling minimum of the smoothed output. Starts at `0`. | +| `totalMaxSmooth` | number | scaling units | Rolling maximum of the smoothed output. Starts at `0`. | + +### Digital mode (`Measurement.getDigitalOutput()`) + +```jsonc +{ + "channels": { + "": { + "key": "", + "type": "", + "position": "", + "unit": "", + "mAbs": , + "mPercent": , + "totalMinValue": , + "totalMaxValue": , + "totalMinSmooth": , + "totalMaxSmooth": + } + // ... one entry per channel that has produced output + } +} +``` + + + +### Status badge + +`Measurement.getStatusBadge()`: + +| Mode | Badge text | Fill / shape | +|:---|:---|:---| +| `analog` | ` ` (e.g. `0.42 bar`) | green / dot | +| `digital` | `digital · channel(s)` | blue / ring | + +The legacy `source.emitter` fires `'mAbs'` (analog only) and is kept for the editor status badge during the refactor window — see [Limitations](Reference-Limitations#legacy-source-emitter). + +--- + +## Events emitted on `source.measurements.emitter` + +The shared `MeasurementContainer` fires `.measured.` whenever a `Channel`'s rounded output changes. The type / position come from: + +- **analog**: `config.asset.type` and `config.functionality.positionVsParent`. +- **digital**: per-channel `config.channels[i].type` and `config.channels[i].position` (falls back to the node-level `positionVsParent` when missing). + +Position labels are normalised to **lowercase** in the event name (`upstream`, `downstream`, `atequipment`). Examples: + +- `pressure.measured.upstream` +- `flow.measured.atequipment` +- `level.measured.downstream` +- `temperature.measured.atequipment` + +Parents subscribe through the generic `child.measurements.emitter.on(eventName, …)` handshake established by `childRegistrationUtils` (in `generalFunctions`). + +In digital mode one input message can fan out into several events — one per channel that accepted a value on that tick. + +--- + +## Configuration schema — editor form to config keys + +Source of truth: `generalFunctions/src/configs/measurement.json` plus `nodeClass.buildDomainConfig`. Defaults below come from the schema. + +### General (`config.general`) + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Name | `general.name` | `Sensor` | Human-readable label. | +| (auto-assigned) | `general.id` | `null` | Node-RED node id. | +| Default unit | `general.unit` | `unitless` | Falls back to the asset unit. | +| Enable logging | `general.logging.enabled` | `true` | Master switch. | +| Log level | `general.logging.logLevel` | `info` | `debug` / `info` / `warn` / `error`. | + +### Functionality (`config.functionality`) + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Software type | `functionality.softwareType` | `measurement` | Constant. | +| Role | `functionality.role` | `Sensor` | Constant. | +| Position vs parent | `functionality.positionVsParent` | `atEquipment` | One of `atEquipment` / `upstream` / `downstream`. Used in the `child.register` payload and as the suffix of the measurement event name. | +| Distance offset | `functionality.distance` | `null` | Optional spatial offset; sent with `child.register`. | + +### Asset (`config.asset`) + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Asset UUID | `asset.uuid` | `null` | Globally-unique identifier. | +| Tag code / number | `asset.tagCode` / `asset.tagNumber` | `null` | Asset-registry identifiers. | +| Geolocation | `asset.geoLocation` | `{x:0, y:0, z:0}` | | +| Supplier | `asset.supplier` | `Unknown` | Free text. | +| Category | `asset.category` | `sensor` | `sensor` / `measurement`. | +| Asset type | `asset.type` | `pressure` | **Required.** Matches the type axis on `MeasurementContainer` and the parent's filter (e.g. `flow`, `power`, `temperature`). | +| Model | `asset.model` | `Unknown` | Free text. | +| Asset unit | `asset.unit` | `unitless` | Output unit label for the measurement event payload. | +| Accuracy | `asset.accuracy` | `null` | Optional sensor accuracy. | +| Repeatability | `asset.repeatability` | `null` | Optional repeatability metric. | + +> [!IMPORTANT] +> `asset.type` must match the **exact** string the parent listens for. The parent's filter is typically the bare type (`flow`, `pressure`, `power`, …) — a measurement configured as `flow-electromagnetic` will not register with a `flow`-only filter on its parent (see [Limitations](Reference-Limitations#asset-type-must-match-the-parents-filter-exactly)). + +### Scaling (`config.scaling`) + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Scaling enabled | `scaling.enabled` | `false` | When false, the input is passed through with only the offset applied. | +| Input min/max | `scaling.inputMin` / `scaling.inputMax` | `0` / `1` | Source range; clamps the input before mapping. | +| Output min/max | `scaling.absMin` / `scaling.absMax` | `50` / `100` | Target range. | +| Offset | `scaling.offset` | `0` | Added before scaling; mutated by `cmd.calibrate`. | + +### Smoothing (`config.smoothing`) + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Window size | `smoothing.smoothWindow` | `10` | `>= 1`. Rolling buffer length. | +| Method | `smoothing.smoothMethod` | `mean` | One of `none` / `mean` / `min` / `max` / `sd` / `median` / `weightedMovingAverage` / `lowPass` / `highPass` / `bandPass` / `kalman` / `savitzkyGolay`. | + +### Outlier detection (`config.outlierDetection`) + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Enabled | `outlierDetection.enabled` | `false` | Toggle with `set.outlier-detection`. | +| Method | `outlierDetection.method` | `zScore` | One of `zScore` / `iqr` / `modifiedZScore`. | +| Threshold | `outlierDetection.threshold` | `3` | Method-specific (e.g. z > 3, mz > 3.5). | + +### Simulation (`config.simulation`) + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Enabled | `simulation.enabled` | `false` | When true, `tick()` (1000 ms) drives `inputValue` via `Simulator.step()`. | +| Safe calibration time | `simulation.safeCalibrationTime` | `100` | ms before calibration is finalised in sim mode. | + +### Interpolation (`config.interpolation`) + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Percent min | `interpolation.percentMin` | `0` | Lower bound of the `mPercent` output. | +| Percent max | `interpolation.percentMax` | `100` | Upper bound. | + +### Calibration (`config.calibration`) + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Stability threshold | `calibration.stabilityThreshold` | `0.01` | Absolute stdDev ceiling (in scaling-units) below which the buffer is considered stable. Fits the default `[50,100]` range; tighten / relax for your sensor. | + +### Mode (`config.mode`) + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Input mode | `mode.current` | `analog` | `analog` (one channel, scalar payload) or `digital` (N channels, object payload). | + +### Channels (`config.channels[]` — digital only) + +In digital mode, each entry in `config.channels` defines its own pipeline: + +| Field | Required | Falls back to | +|:---|:---:|:---| +| `key` | yes | — (skipped if missing) | +| `type` | yes | — (skipped if missing) | +| `position` | no | `config.functionality.positionVsParent` → `atEquipment` | +| `unit` | no | `config.asset.unit` → `unitless` | +| `distance` | no | `config.functionality.distance` → `null` | +| `scaling` | no | `{enabled:false, inputMin:0, inputMax:1, absMin:0, absMax:1, offset:0}` | +| `smoothing` | no | `config.smoothing` | +| `outlierDetection` | no | `config.outlierDetection` | +| `interpolation` | no | `config.interpolation` | + +Invalid entries (missing `key` or `type`) are logged and skipped. An empty `config.channels[]` in digital mode logs `digital mode enabled but config.channels is empty; no channels will be emitted.` + +### Asset registration (`config.assetRegistration`) + +Used by the `/measurement/asset-reg` admin endpoint to register / sync the asset with the upstream asset registry. Not part of the runtime data path. + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Profile / location / process ids | `assetRegistration.{profileId, locationId, processId}` | `1` | Free integer ids in the asset registry. | +| Status | `assetRegistration.status` | `actief` | Lifecycle status. | +| Child assets | `assetRegistration.childAssets` | `[]` | List of child asset ids. | + +### Output (`config.output`) + +| Form field | Config key | Default | Notes | +|:---|:---|:---|:---| +| Process output | `output.process` | `process` | `process` / `json` / `csv`. Port-0 formatter. | +| Database output | `output.dbase` | `influxdb` | `influxdb` / `json` / `csv`. Port-1 formatter. | + +### Unit policy + +> [!NOTE] +> TODO: `measurement` does not currently declare a `unitPolicy` block on its `BaseDomain` configuration (unlike `rotatingMachine`). The per-channel `unit` is carried verbatim into the `MeasurementContainer` write at `_writeOutput`. If a future hardening pass adds a unit-policy enforcement, add the canonical / output / required-unit table here. See `CONTRACT.md` for the current invariants. + +--- + +## Child registration + +Source: `src/specificClass.js` `configure` (registers itself via the `BaseDomain` plumbing) and the standard `childRegistrationUtils` handshake in `generalFunctions`. + +`measurement` does **not accept children**. It only **registers itself** as a child on its upstream parent. + +| Layer | Direction | Topic / event | Payload | +|:---|:---|:---|:---| +| Startup (Port 2) | child → parent | `registerChild` | `{topic: 'registerChild', payload: , positionVsParent, distance}` | +| Runtime | child → parent | `.measured.` on `child.measurements.emitter` | `{value, timestamp, unit, distance?}` (per `MeasurementContainer.value()`) | + +| What | softwareType payload | Side-effect on parent | +|:---|:---|:---| +| Registration | `measurement` | Parent attaches a listener for `.measured.` on the child's `measurements.emitter`. | +| Subsequent updates | event on `child.measurements.emitter` | Parent mirrors the value into its own `MeasurementContainer` slot. | + +Position labels are normalised to **lowercase** in the event name (`upstream`, `downstream`, `atequipment`); the `positionVsParent` field in the register payload is sent as configured (preserves case). + +--- + +## Related pages + +| Page | Why | +|:---|:---| +| [Home](Home) | Intuitive overview | +| [Reference — Architecture](Reference-Architecture) | Code map + per-`Channel` pipeline + lifecycle | +| [Reference — Examples](Reference-Examples) | Shipped flows + debug recipes | +| [Reference — Limitations](Reference-Limitations) | Known issues and open questions | +| [EVOLV — Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions) | Platform-wide topic rules | +| [EVOLV — Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry) | Port 0 / 1 / 2 InfluxDB layout | diff --git a/wiki/Reference-Examples.md b/wiki/Reference-Examples.md new file mode 100644 index 0000000..5bb8205 --- /dev/null +++ b/wiki/Reference-Examples.md @@ -0,0 +1,148 @@ +# Reference — Examples + +![code-ref](https://img.shields.io/badge/code--ref-b884c0f-blue) + +> [!NOTE] +> Every example flow shipped under `nodes/measurement/examples/`, plus how to load them, what they show, and the debug recipes that go with them. Live source: `nodes/measurement/examples/`. +> +> Pending full node review (2026-05). Tier-1/2/3 visual-first example flows are still TODO (tracked in the superproject `MEMORY.md` "TODO: Example Flows"). The current shipped flows pre-date the refactor; treat them as smoke tests, not as production templates. + +--- + +## Shipped examples + +| File | Tier | Dependencies | What it shows | Status | +|:---|:---:|:---|:---|:---| +| `basic.flow.json` | 1 | EVOLV only | Single measurement node driven by inject buttons — analog scalar input, scaling enabled, three debug taps on Port 0/1/2. | Legacy pre-refactor shape, still imports. | +| `integration.flow.json` | 2 | EVOLV only | Parent-child wiring — measurement registers as a child of another node and emits its `.measured.` events. | Legacy pre-refactor shape. | +| `edge.flow.json` | 3 | EVOLV only | Invalid / edge payload driving for robustness checks (non-numeric strings, object in analog mode, …). | Legacy pre-refactor shape. | + +The three legacy files predate the AssetResolver refactor and the analog-vs-digital mode flag. They still deploy (the editor will accept the older shape and `nodeClass.buildDomainConfig` reshapes whatever it finds), but the recommended Tier-1/2/3 visual-first replacements are still to be written. + +> [!IMPORTANT] +> **TODO — Tier-1/2/3 visual-first flows.** Replace the three legacy files with: +> - `01 - Basic Analog.json` — one measurement, inject + scaling + smoothing + outlier-detection toggle + simulator. +> - `02 - Integration with rotatingMachine.json` — measurement registered as a pressure sensor on a `rotatingMachine`, Port 2 auto-register on deploy, parent's prediction updates as the measurement value moves. +> - `03 - Digital Multi-Channel.json` — one measurement in `digital` mode with 2–3 channels (e.g. `level-a`, `temp-a`, `flow-a`) fed by a single object-payload inject. + +--- + +## Loading a flow + +### Via the editor + +1. Open the Node-RED editor at `http://localhost:1880`. +2. Menu → Import → drag the JSON file. +3. Click Deploy. + +### Via the Admin API + +```bash +curl -X POST -H 'Content-Type: application/json' \ + --data @nodes/measurement/examples/basic.flow.json \ + http://localhost:1880/flows +``` + +--- + +## Example — `basic.flow.json` + +Single-measurement flow with the minimum kit to exercise scaling. + +### Nodes on the tab + +| Type | Purpose | +|:---|:---| +| `inject` | One-shot `topic: 'measurement', payload: 42` (legacy alias of `data.measurement`) | +| `measurement` | The unit under test — analog mode, scaling enabled (0..100 → 0..10), `mean` smoothing, window 5 | +| `debug` × 3 | Port 0 (process), Port 1 (InfluxDB), Port 2 (registration) | + +### What to do after deploy + +1. Click the inject. Port 0 fires with `mAbs ≈ 4.2` (42 scaled into 0..10), `mPercent ≈ 42`. +2. Send another value via the same inject (edit the inject payload to `60`). `totalMinValue` / `totalMaxValue` start tracking, `mAbs` jumps to ~6.0. +3. Send `topic: 'set.simulator'` (use a second inject). `tick()` starts driving `inputValue` through `Simulator.step()` every 1000 ms; Port 0 updates appear automatically. +4. Send `topic: 'cmd.calibrate'`. If `stdDev <= 0.01` (the default `stabilityThreshold`), `config.scaling.offset` jumps to `inputMin - currentOutput`; if not, a warn appears in the log. +5. Send `topic: 'set.outlier-detection'`, then inject a wildly out-of-band value (e.g. `9999`). With outlier detection on the value is dropped with `Outlier detected. Ignoring value=9999`. + +> [!IMPORTANT] +> **Screenshot needed.** Editor capture of `basic.flow.json` plus the Port 0 debug output. Save as `wiki/_partial-screenshots/measurement/basic-flow.png`. Replace this callout with the image link. + +--- + +## Example — `integration.flow.json` + +Demonstrates the parent-child handshake: the measurement node's Port 2 auto-fires `child.register` to its parent on deploy, and the parent then receives the `.measured.` event whenever a new reading lands. + +> [!IMPORTANT] +> **Screenshot needed.** Editor capture of `integration.flow.json` showing the wiring. Save as `wiki/_partial-screenshots/measurement/integration-flow.png`. + +> [!NOTE] +> TODO: confirm the integration flow targets a real EVOLV parent (e.g. `rotatingMachine`) versus a mock function node; if it's a mock, the Tier-2 replacement should use a real parent. + +--- + +## Example — `edge.flow.json` + +Drives the node with malformed inputs to verify the warn paths land cleanly: + +- Non-numeric string in analog mode → `Invalid numeric measurement payload: `. +- Object payload in analog mode → `analog mode received an object payload (keys: …). Switch Input Mode to 'digital' …`. +- Numeric scalar in digital mode → `digital mode received a number (…); expected an object …`. +- Outlier toggle on/off mid-stream → verifies `analogChannel.outlierDetection.enabled` mirrors `config.outlierDetection.enabled`. + +> [!IMPORTANT] +> **Screenshot needed.** Editor capture of `edge.flow.json` plus the log lines each inject triggers. Save as `wiki/_partial-screenshots/measurement/edge-flow.png`. + +--- + +## Debug recipes + +| Symptom | First thing to check | Where to look | +|:---|:---|:---| +| Parent never receives `.measured.` | `asset.type` must match the parent's filter exactly (e.g. `flow` — not `flow-electromagnetic`). Position labels lowercase in the event name. | `config.asset.type` + parent's `childRegistrationUtils` filter. | +| Outliers seem to pass through | `outlierDetection.enabled` may be off (default `false`). Toggle with `set.outlier-detection`. With `<2` samples in the buffer, `_isOutlier` returns `false` regardless. | `Channel._isOutlier`. | +| `cmd.calibrate` does nothing | Calibrator requires `stdDev <= calibration.stabilityThreshold` over `storedValues`. If `storedValues.length < 2`, `isStable()` returns `false` (legacy shape). | `src/calibration/calibrator.js` `isStable`, `calibrate`. | +| Digital payload silently dropped | Unknown channel keys are reported only at `debug` log level (`digital payload contained unmapped keys`). Numeric values that fail `Number.isFinite` warn at `warn`. | `Measurement.handleDigitalPayload`. | +| Simulator still running after toggle off | `tick()` reads `config.simulation.enabled` each tick. Confirm the toggle actually mutated the config (the `set.simulator` handler is idempotent — it just flips). | `Measurement.tick`, `toggleSimulation`. | +| Port 0 emits nothing after `data.measurement` | Analog: `_writeOutput` only emits when `rounded !== outputAbs`. A repeated identical value is silent by design. | `Channel._writeOutput`. | +| `mPercent` is stuck at `0` or unbounded | `processRange <= 0` (i.e. `absMax <= absMin`); percent falls back to `totalMinValue / totalMaxValue` which start at `0` / `0`. Configure `absMin < absMax`. | `Channel._computePercent`. | +| Scaling output looks clamped | `_applyScaling` clamps the input to `[inputMin, inputMax]` before mapping. Wide-band sensors need `inputMin / inputMax` set to the full physical range. | `Channel._applyScaling`. | +| `mAbs` jumps after `cmd.calibrate` | Expected. Calibration sets `config.scaling.offset = baseline - currentOutputAbs`, which makes the next reading land on the baseline (`inputMin` when scaling enabled, `absMin` otherwise). | `Calibrator.calibrate`. | +| Legacy `setpoint` / `simulator` topics work without warning | First fire emits a one-time deprecation warning via `BaseNodeAdapter`'s alias handling. Subsequent fires are silent — the topic still works. | `commands/index.js` `aliases`. | + +> Never ship `enableLog: 'debug'` in a demo — fills the container log within seconds and obscures real errors. + +--- + +## Docker compose snippet + +To bring up Node-RED + InfluxDB with EVOLV nodes pre-loaded: + +```yaml +# docker-compose.yml (extract) +services: + nodered: + build: ./docker/nodered + ports: ['1880:1880'] + volumes: + - ./docker/nodered/data:/data/evolv + influxdb: + image: influxdb:2.7 + ports: ['8086:8086'] +``` + +Full file: [EVOLV/docker-compose.yml](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/docker-compose.yml). + +--- + +## Related pages + +| Page | Why | +|:---|:---| +| [Home](Home) | Intuitive overview | +| [Reference — Contracts](Reference-Contracts) | Topic + config + child registration | +| [Reference — Architecture](Reference-Architecture) | Code map + per-`Channel` pipeline + lifecycle | +| [Reference — Limitations](Reference-Limitations) | Known issues and open questions | +| [rotatingMachine — Examples](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Reference-Examples) | Most common consumer of measurement | +| [EVOLV — Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) | Where measurement fits in a larger plant | diff --git a/wiki/Reference-Limitations.md b/wiki/Reference-Limitations.md new file mode 100644 index 0000000..eed130e --- /dev/null +++ b/wiki/Reference-Limitations.md @@ -0,0 +1,117 @@ +# Reference — Limitations + +![code-ref](https://img.shields.io/badge/code--ref-b884c0f-blue) + +> [!NOTE] +> What `measurement` does not do, current rough edges, and open questions. Open items live in `.agents/improvements/IMPROVEMENTS_BACKLOG.md` in the EVOLV superproject; node-local follow-ups are tracked in the superproject's `MEMORY.md` and `.claude/refactor/OPEN_QUESTIONS.md`. +> +> Pending full node review (2026-05). + +--- + +## When you would not use this node + +| Scenario | Use instead | +|:---|:---| +| Fusing signals from multiple sensors into one virtual measurement | This node is per-channel only. Aggregate at the parent (e.g. `rotatingMachine` already combines upstream + downstream into a differential). | +| Producing a control output / actuating something | This is read-only signal conditioning. Use `rotatingMachine`, `valve`, or another equipment-level node. | +| Threshold-trip alarms / latched state | There is no comparator / latch output. Build alarm logic on top of the emitted reading at the parent or in a dashboard rule. | +| A "passive" measurement that should not register with a parent | Registration is automatic at startup — not currently opt-out. TODO: confirm whether a "no-parent" mode exists; if not, leave the parent input unwired. | + +--- + +## Known limitations + +### Asset type must match the parent's filter exactly + +Parents subscribe to events by exact string match on `.measured.`. A measurement configured as `flow-electromagnetic` will not be picked up by a parent that filters on `flow`. The fix is mechanical — set `asset.type` to the bare type the parent expects. + +This is documented in the superproject `MEMORY.md` under "Key Integration Gotchas": + +> Measurement `assetType: "flow"` required (not "flow-electromagnetic") for pumpingStation/monster. + +### Position labels lowercase only in the event name + +The event name emits `.measured.` with `position` lowercased (`upstream`, `downstream`, `atequipment`). The `positionVsParent` field in the `child.register` payload, however, is sent **as configured** (preserves case). If a parent indexes children by the register-payload position string, mixed-case there will not match the lowercase position in subsequent events. Document the convention in any new parent that joins measurement. + +### Legacy `source.emitter` + +`source.emitter` fires `'mAbs'` on the analog `inputValue` setter alongside the canonical `measurements.emitter` path. It is kept for the editor status badge during the refactor window and is **slated for removal in Phase 7**. New consumers must use `measurements.emitter`. + +### Digital mode — `notifyOutputChanged()` not explicitly called + +`Measurement.handleDigitalPayload` collects a per-key summary but does not directly call `notifyOutputChanged()`. The analog `inputValue` setter does. TODO: confirm whether digital-mode Port 0 emissions rely on the next `tick()` or a follow-up notify path inside `BaseNodeAdapter`. Until verified, treat digital-mode Port 0 latency as "up to one tick" (1000 ms). + +### Digital mode — per-channel scaling / smoothing fall back to the analog block + +When a `config.channels[i]` entry omits a per-channel `scaling`, `smoothing`, `outlierDetection`, or `interpolation`, the missing fields fall back to the node-level config — **not** to a sensible per-type default. Setting `smoothing.smoothMethod = 'kalman'` at the node level applies that to every digital channel that does not override it. Operators should set every block per channel in production digital flows. + +### `data.measurement` accepts numeric strings — not arrays / NaN + +The analog handler parses with `Number(p)` and rejects `NaN`. Empty / whitespace strings are skipped silently. Arrays are not accepted in either mode and log a warn in digital mode. + +### Simulator does not respect outlier detection + +`Simulator.step()` writes directly into `m.inputValue`. The downstream `Channel.update` does run outlier detection if enabled — but the simulator's random walk is well-behaved enough that this is effectively a no-op. Don't expect the outlier path to be exercised by the simulator alone. + +### `cmd.calibrate` requires ≥ 2 stored values + +`Calibrator.isStable()` returns `{isStable:false}` when `storedValues.length < 2`. The legacy `Measurement.isStable()` wrapper returns a bare `false` in that case. A fresh calibration call before any data has arrived is silently rejected. + +### Calibration baseline depends on `scaling.enabled` + +When `scaling.enabled` is true, the calibration baseline is `scaling.inputMin`. When disabled, it is `scaling.absMin`. Toggling `scaling.enabled` after calibrating shifts the meaning of the captured offset; recalibrate after any scaling-toggle. + +### Smoothing buffer not cleared on config change + +Changing `smoothing.smoothMethod` or `smoothing.smoothWindow` at runtime does not clear `storedValues`. A previously-mean-smoothed buffer can produce a stale first sample after switching to `lowPass` until the window churns. The conservative workaround is to redeploy. + +### `outlierDetection.enabled` mirrored only into `analogChannel` + +`toggleOutlierDetection()` propagates the new boolean to `this.analogChannel.outlierDetection.enabled` only. In digital mode the per-channel `Channel.outlierDetection.enabled` is **not** updated by the toggle. TODO: digital-mode parity for `set.outlier-detection`. + +### Min/max counters never reset + +`totalMinValue` / `totalMaxValue` / `totalMinSmooth` / `totalMaxSmooth` are monotonic over the node's lifetime. There is no explicit reset command. The smooth-min/max additionally have a "first-write" rule that snaps both to the first value — before that, both read `0`, which can mislead downstream chart axes. + +--- + +## Open questions (tracked) + +| Question | Where it lives | +|:---|:---| +| Should digital-mode `notifyOutputChanged()` fire on every accepted update? | Internal — pending P9 review | +| Drop the legacy `source.emitter 'mAbs'` event | Phase 7 removal | +| Replace legacy `examples/{basic,integration,edge}.flow.json` with Tier-1/2/3 visual-first flows | Superproject `MEMORY.md` "TODO: Example Flows" | +| Add `data.clear-min-max` / `data.reset` topic for the rolling counters | Internal | +| Add per-channel `set.outlier-detection` for digital mode | Internal | +| Auto-recalibration heuristics (currently operator-triggered only) | Internal | +| Per-channel `smoothing` window-clear on config change | Internal | + +--- + +## Migration notes + +### From pre-refactor flat config + +Older flows used `assetType` / `supplier` / `category` at the top level of the editor config. `nodeClass.buildDomainConfig` reshapes the editor's flat `uiConfig` into the nested domain config slice (`scaling`, `smoothing`, `simulation`, `calibration`, `mode`, `channels`), so legacy flows continue to deploy. The migration is best-effort — re-saving each measurement node in the editor regenerates the canonical shape. + +### From analog-only + +Adding `config.mode.current` was additive. Flows that omit it default to `analog` and behave exactly as before. To switch to digital: set the editor's "Input Mode" to `digital` and define `config.channels`. + +### From legacy alias topics + +`simulator`, `outlierDetection`, `calibrate`, `measurement` continue to work; each emits a one-time deprecation warning on first fire. Prefer the canonical `set.simulator` / `set.outlier-detection` / `cmd.calibrate` / `data.measurement` for new flows. + +--- + +## Related pages + +| Page | Why | +|:---|:---| +| [Home](Home) | Intuitive overview | +| [Reference — Contracts](Reference-Contracts) | Topic + config + child registration (alias map at the end) | +| [Reference — Architecture](Reference-Architecture) | Code map + per-`Channel` pipeline + lifecycle | +| [Reference — Examples](Reference-Examples) | Shipped flows + debug recipes | +| [rotatingMachine — Limitations](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Reference-Limitations) | Where the most common consumer's caveats overlap | diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md new file mode 100644 index 0000000..b488340 --- /dev/null +++ b/wiki/_Sidebar.md @@ -0,0 +1,20 @@ +### measurement + +- [Home](Home) + +**Reference** + +- [Contracts](Reference-Contracts) +- [Architecture](Reference-Architecture) +- [Examples](Reference-Examples) +- [Limitations](Reference-Limitations) + +**Related** + +- [EVOLV master wiki](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Home) +- [rotatingMachine wiki](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Home) +- [machineGroupControl wiki](https://gitea.wbd-rd.nl/RnD/machineGroupControl/wiki/Home) +- [pumpingStation wiki](https://gitea.wbd-rd.nl/RnD/pumpingStation/wiki/Home) +- [Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) +- [Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions) +- [Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry)