node-red-contrib-event-calc 3.3.3 → 3.3.15

package/README.md

@@ -1,17 +1,19 @@
 # node-red-contrib-event-calc
 
-Node-RED nodes for event caching and streaming calculations with a local pub/sub event hub.
+Node-RED nodes for event caching, streaming calculations, alarm management, and event framing.
 
 ## Overview
 
 This package provides a local in-memory event hub with topic-based publish/subscribe and latest-value caching for reactive data flows within Node-RED. Stream data from MQTT, OPC-UA, or any source, then perform calculations that trigger automatically when values update.
 
+Also includes ISA-88 batch structure tracking, ISA-18.2 alarm lifecycle management, and simple event recording.
+
 ## Architecture
 
 ```
 ┌──────────────────────────────────────────────────────────────┐
 │  event-cache (config node)                                   │
-│  • Stores: Map<topic, {value, ts, metadata}>                │
+│  • Stores: Map<topic, {value, ts, metadata, previous}>      │
 │  • Event emitter for topic updates                           │
 │  • LRU eviction, optional TTL                                │
 └──────────────────────────────────────────────────────────────┘
@@ -34,14 +36,16 @@ Or install directly from the Node-RED palette manager.
 
 ## Nodes
 
-### event-cache (Config Node)
+### Core Nodes
+
+#### event-cache (Config Node)
 
 Central cache that stores topic values and manages subscriptions. Configure:
 
 - **Max Entries**: Maximum topics to cache (default: 10000). Oldest entries removed when exceeded.
 - **TTL**: Time-to-live in milliseconds. Set to 0 for no expiry.
 
-### event-in
+#### event-in
 
 Receives messages from any upstream node and pushes values to the cache.
 
@@ -51,7 +55,7 @@ Receives messages from any upstream node and pushes values to the cache.
 
 The original message passes through, allowing insertion into existing flows.
 
-### event-topic
+#### event-topic
 
 Subscribes to a topic and outputs when that topic updates.
 
@@ -66,7 +70,7 @@ Subscribes to a topic and outputs when that topic updates.
 - `msg.topic`: Change subscription topic
 - `msg.payload = 'refresh'`: Output current cached value
 
-### event-calc
+#### event-calc
 
 Subscribes to multiple topics and evaluates an expression when values update.
 
@@ -92,71 +96,113 @@ Subscribes to multiple topics and evaluates an expression when values update.
 }
 ```
 
-### event-json
+### Event Frame Nodes
 
-Bidirectional JSON envelope converter for MQTT messaging.
+#### event-frame (ISA-88 Batch Structure)
 
-**Behavior:**
-- **Unwrap**: If payload is `{value, topic?, timestamp?}`, extracts to msg properties
-- **Wrap**: If payload is any other value, wraps as `{timestamp, topic, value}`
+Creates ISA-88 procedural model records with hierarchical parent-child linking.
 
-**Usage:**
-```
-[MQTT in] → [event-json] → [event-in]     (unwrap JSON from broker)
-[event-topic] → [event-json] → [MQTT out] (wrap for broker)
+**ISA-88 Levels:**
+- **Procedure** — top-level batch recipe
+- **Unit Procedure** — sequence within a unit
+- **Operation** — major processing step
+- **Phase** — lowest-level action
+
+**Features:**
+- Trigger-based: truthy starts, falsy ends
+- Auto-generated UUIDs
+- Parent-child linking via `parentLevel` config or `msg.frame_id` chaining
+- Cascade end: ending a parent auto-ends all children recursively
+- Shared global context tracker for cross-node coordination
+
+**Output Record:**
+```json
+{
+  "id": "auto-generated UUID",
+  "starttime": "2024-01-15T10:30:00.000Z",
+  "endtime": "9999-12-31T23:59:59.000Z",
+  "name": "Mixing",
+  "parent_id": "parent-uuid-or-empty",
+  "level": "operation",
+  "state": "running",
+  "batch_id": "BATCH-001",
+  "unit": "Reactor-1",
+  "metadata": ""
+}
 ```
 
-### event-simulator
+#### simple-frame (Simple Event Recorder)
 
-Generates simulated data for testing. Supports sine waves, random values, and ramps.
+A simplified event frame for tracking any event with start/end time — no hierarchy, no cascade.
 
-### event-chart
+**Properties:**
+- **Event Type**: Category label (str/msg/flow/global/env)
+- **Event Name**: Descriptive name (str/msg/flow/global/env)
+- **Metadata Field**: Optional msg property for extra data
+- **Two outputs**: start and end
 
-Real-time charting node for visualizing cached event data.
+**Output Record:**
+```json
+{
+  "id": "auto-generated UUID",
+  "starttime": "2024-01-15T10:30:00.000Z",
+  "endtime": "9999-12-31T23:59:59.000Z",
+  "type": "maintenance",
+  "name": "Oil Change",
+  "state": "running",
+  "metadata": ""
+}
+```
 
-## Examples
+### Alarm Management
 
-### Average Temperature
+#### event-alarm (ISA-18.2 Alarm Lifecycle)
 
-```
-[inject: room1/temp] → [event-in] → [cache]
-[inject: room2/temp] → [event-in] → [cache]
-
-[event-calc] → [debug]
-  inputs: a = sensors/room1/temp
-          b = sensors/room2/temp
-  expression: (a + b) / 2
-  trigger: all
-```
+Tracks alarms through the full ISA-18.2 lifecycle with four outputs.
 
-### Time-based Calculations (External Trigger)
+**Alarm States:**
+- **UNACK_ALM** — Active + Unacknowledged (just raised)
+- **ACK_ALM** — Active + Acknowledged (operator acked, condition still true)
+- **UNACK_RTN** — Inactive + Unacknowledged (condition cleared, not yet acked)
+- **NORM** — Normal (fully resolved)
 
+**Lifecycle Paths:**
 ```
-[inject: every 1 min] → [event-calc (external trigger)] → [MQTT out]
-  inputs: a = sensors/power
-          b = sensors/voltage
-  expression: a * b
+Path A: NORM → UNACK_ALM → ACK_ALM → NORM (ack first, then clear)
+Path B: NORM → UNACK_ALM → UNACK_RTN → NORM (clear first, then ack)
 ```
 
-### MQTT Round-trip with JSON Envelope
+**Properties:**
+- **Condition ID/Name**: Alarm identifier and description
+- **Input Mappings**: Map variable names to cache topics (like event-calc)
+- **Condition**: Expression that evaluates to true/false (e.g. `active == true`)
+- **Severity**: 0-1000 scale
+- **4 Outputs**: raised, acknowledged, cleared, resolved
+
+**Actions (via msg.payload):**
+- `{ action: "ack", source: "topic" }` — Acknowledge specific alarm
+- `{ action: "ack_all" }` — Acknowledge all active alarms
+- `{ action: "list" }` — List all active alarms
 
-```
-[MQTT in] → [event-json] → [event-in] → [cache]
+### Utility Nodes
 
-[event-calc] → [event-json] → [MQTT out]
-```
+#### event-flatten
 
-### Calculate Power (Voltage × Current)
+Flattens nested objects into individual topic/value pairs for the cache.
 
-```
-[event-calc]
-  inputs: v = power/voltage
-          i = power/current
-  expression: v * i
-  topic: power/watts
-```
+#### event-preview
+
+Preview cached values directly in the Node-RED editor.
+
+#### event-simulator
+
+Generates simulated data for testing. Supports sine waves, random values, and ramps.
 
-## Built-in Functions
+#### event-chart
+
+Real-time charting node for visualizing cached event data.
+
+## Built-in Functions (event-calc)
 
 ### Math
 | Function | Description |
@@ -190,6 +236,28 @@ Real-time charting node for visualizing cached event data.
 | `delta(current, previous)` | Difference |
 | `pctChange(current, previous)` | Percentage change |
 
+### Change Detection
+| Function | Description |
+|----------|-------------|
+| `now()` | Current timestamp in milliseconds |
+| `prev('varName')` | Previous value of a variable |
+| `hasChanged('varName')` | `true` if value differs from previous (false on first message) |
+| `timeSinceLastChange('varName')` | Milliseconds since the value last changed |
+
+### Date/Time
+| Function | Description |
+|----------|-------------|
+| `hour()` | Current hour (0-23) |
+| `minute()` | Current minute (0-59) |
+| `second()` | Current second (0-59) |
+| `day()` | Day of week (0=Sun, 1=Mon, ..., 6=Sat) |
+| `dayOfMonth()` | Day of month (1-31) |
+| `month()` | Month (1-12) |
+| `year()` | Full year (e.g. 2026) |
+| `isWeekday()` | `true` if Monday-Friday |
+| `isWeekend()` | `true` if Saturday or Sunday |
+| `hoursBetween(start, end)` | `true` if current hour is within range (wraps midnight) |
+
 ## Expression Examples
 
 | Expression | Description |
@@ -202,7 +270,9 @@ Real-time charting node for visualizing cached event data.
 | `clamp(a, 0, 100)` | Constrain 0-100 |
 | `map(a, 0, 1023, 0, 100)` | Scale ADC to % |
 | `ifelse(a > b, 'high', 'low')` | Conditional |
-| `pctChange(a, b)` | % change from b to a |
+| `hasChanged('temp')` | Did temperature just change? |
+| `temp - prev('temp')` | Delta from previous value |
+| `isWeekday() && hoursBetween(8, 18)` | During business hours? |
 
 ## API (for custom nodes)
 
@@ -216,7 +286,7 @@ cache.setValue('topic/path', 42, { source: 'sensor' });
 
 // Get a value
 const entry = cache.getValue('topic/path');
-// { value: 42, ts: 1704000000000, metadata: { source: 'sensor' } }
+// { value: 42, ts: 1704000000000, metadata: { source: 'sensor' }, previous: { value: 40, ts: ..., metadata: ... } }
 
 // Subscribe to updates
 const subId = cache.subscribe('sensors/room1/temp', (topic, entry) => {
@@ -236,9 +306,11 @@ cache.clear();
 ## HTTP Admin Endpoints
 
 ```
-GET  /event-cache/:id/stats   - Cache statistics
-GET  /event-cache/:id/topics  - List all topics
-POST /event-cache/:id/clear   - Clear cache
+GET  /event-cache/:id/stats    - Cache statistics
+GET  /event-cache/:id/topics   - List all topics
+POST /event-cache/:id/clear    - Clear cache
+GET  /event-frame/tracker      - Current batch tracker state
+GET  /event-alarm/:id/alarms   - Active alarms for a node
 ```
 
 ## License

package/examples/alarm-simulation-example.json

@@ -0,0 +1,288 @@
+[
+    {
+        "id": "alarm-sim-flow",
+        "type": "tab",
+        "label": "Alarm Lifecycle Simulation",
+        "disabled": false,
+        "info": "Self-running alarm lifecycle simulation.\n\nEvery few seconds a random alarm is raised. After a random delay it gets\nacknowledged, and after another random delay the condition clears.\nThe event-alarm nodes track the full ISA-18.2 lifecycle.\n\nBoth lifecycle paths are exercised:\n  Path A: Raised > Acked > Cleared (Resolved)\n  Path B: Raised > Cleared > Acked (Resolved)"
+    },
+    {
+        "id": "sim-cache",
+        "type": "event-cache",
+        "name": "Sim Cache",
+        "maxEntries": "10000",
+        "ttl": "0"
+    },
+    {
+        "id": "comment-sim-title",
+        "type": "comment",
+        "z": "alarm-sim-flow",
+        "name": "Alarm Lifecycle Simulation (self-running)",
+        "info": "Raises random alarms every N seconds, then auto-acks and auto-clears after random delays.\nWatch the debug sidebar to see the full lifecycle play out.",
+        "x": 230,
+        "y": 40,
+        "wires": []
+    },
+    {
+        "id": "sim-trigger",
+        "type": "inject",
+        "z": "alarm-sim-flow",
+        "name": "Every 5s: raise random alarm",
+        "props": [
+            { "p": "payload", "v": "", "vt": "date" }
+        ],
+        "repeat": "5",
+        "crontab": "",
+        "once": true,
+        "onceDelay": "2",
+        "x": 200,
+        "y": 120,
+        "wires": [["sim-raise-alarm"]]
+    },
+    {
+        "id": "sim-raise-alarm",
+        "type": "function",
+        "z": "alarm-sim-flow",
+        "name": "Raise Random Alarm",
+        "func": "const alarms = [\n    { topic: 'sim/plant/PumpTrip_P1A/active', name: 'PumpTrip_P1A' },\n    { topic: 'sim/plant/BreakerFault_MCC3/active', name: 'BreakerFault_MCC3' },\n    { topic: 'sim/plant/HighLevel_Thickener/active', name: 'HighLevel_Thickener' },\n    { topic: 'sim/plant/VibrationHigh_Screen2/active', name: 'VibrationHigh_Screen2' },\n    { topic: 'sim/plant/EStop_Conveyor7/active', name: 'EStop_Conveyor7' },\n    { topic: 'sim/plant/MagnetiteLevel_Low/active', name: 'MagnetiteLevel_Low' }\n];\n\n// Pick a random alarm\nconst alarm = alarms[Math.floor(Math.random() * alarms.length)];\n\n// Activate it\nconst activateMsg = {\n    topic: alarm.topic,\n    payload: true\n};\n\n// Schedule ack after 3-10s random delay\nconst ackDelay = 3000 + Math.floor(Math.random() * 7000);\n// Schedule clear after 5-15s random delay\nconst clearDelay = 5000 + Math.floor(Math.random() * 10000);\n\n// Randomly choose lifecycle path:\n//   Path A (60%): ack first, then clear\n//   Path B (40%): clear first, then ack\nconst ackFirst = Math.random() < 0.6;\n\nconst ackMsg = {\n    payload: { action: 'ack', source: alarm.topic },\n    _alarm: alarm.name,\n    _delay: ackFirst ? ackDelay : clearDelay + ackDelay\n};\n\nconst clearMsg = {\n    topic: alarm.topic,\n    payload: false,\n    _alarm: alarm.name,\n    _delay: ackFirst ? clearDelay + ackDelay : clearDelay\n};\n\n// Store scheduled actions in context for the delay nodes\nnode.status({ text: `${alarm.name} (${ackFirst ? 'ack-first' : 'clear-first'})` });\n\n// Output 1: activate now\n// Output 2: ack (with delay metadata)\n// Output 3: clear (with delay metadata)\nreturn [activateMsg, ackMsg, clearMsg];",
+        "outputs": 3,
+        "outputLabels": ["activate", "ack (delayed)", "clear (delayed)"],
+        "x": 480,
+        "y": 120,
+        "wires": [["sim-event-in"], ["sim-delay-ack"], ["sim-delay-clear"]]
+    },
+    {
+        "id": "sim-delay-ack",
+        "type": "function",
+        "z": "alarm-sim-flow",
+        "name": "Random Delay (ack)",
+        "func": "const delay = msg._delay || 5000;\nconst alarmName = msg._alarm || 'unknown';\n\nreturn new Promise(resolve => {\n    const timerId = setTimeout(() => {\n        node.status({ text: `ack ${alarmName} after ${(delay/1000).toFixed(1)}s` });\n        delete msg._delay;\n        delete msg._alarm;\n        resolve(msg);\n    }, delay);\n    \n    // Clean up on node close\n    node.on('close', () => clearTimeout(timerId));\n});",
+        "outputs": 1,
+        "x": 480,
+        "y": 200,
+        "wires": [["sim-ack-router"]]
+    },
+    {
+        "id": "sim-delay-clear",
+        "type": "function",
+        "z": "alarm-sim-flow",
+        "name": "Random Delay (clear)",
+        "func": "const delay = msg._delay || 8000;\nconst alarmName = msg._alarm || 'unknown';\n\nreturn new Promise(resolve => {\n    const timerId = setTimeout(() => {\n        node.status({ text: `clear ${alarmName} after ${(delay/1000).toFixed(1)}s` });\n        delete msg._delay;\n        delete msg._alarm;\n        resolve(msg);\n    }, delay);\n    \n    // Clean up on node close\n    node.on('close', () => clearTimeout(timerId));\n});",
+        "outputs": 1,
+        "x": 490,
+        "y": 280,
+        "wires": [["sim-event-in"]]
+    },
+    {
+        "id": "sim-event-in",
+        "type": "event-in",
+        "z": "alarm-sim-flow",
+        "name": "Push to Cache",
+        "cache": "sim-cache",
+        "topicSource": "msg",
+        "topicPattern": "",
+        "x": 710,
+        "y": 120,
+        "wires": [[]]
+    },
+    {
+        "id": "sim-ack-router",
+        "type": "function",
+        "z": "alarm-sim-flow",
+        "name": "Route ACK to alarm node",
+        "func": "// Route the ack to the correct alarm node based on source topic\nconst source = msg.payload.source;\nconst routes = {\n    'sim/plant/PumpTrip_P1A/active': 0,\n    'sim/plant/BreakerFault_MCC3/active': 1,\n    'sim/plant/HighLevel_Thickener/active': 2,\n    'sim/plant/VibrationHigh_Screen2/active': 3,\n    'sim/plant/EStop_Conveyor7/active': 4,\n    'sim/plant/MagnetiteLevel_Low/active': 5\n};\n\nconst outputs = [null, null, null, null, null, null];\nconst idx = routes[source];\nif (idx !== undefined) {\n    outputs[idx] = msg;\n}\nreturn outputs;",
+        "outputs": 6,
+        "outputLabels": ["Pump", "Breaker", "Thickener", "Vibration", "EStop", "Magnetite"],
+        "x": 720,
+        "y": 200,
+        "wires": [["sim-alarm-pump"], ["sim-alarm-breaker"], ["sim-alarm-thickener"], ["sim-alarm-vibration"], ["sim-alarm-estop"], ["sim-alarm-magnetite"]]
+    },
+    {
+        "id": "comment-alarm-nodes",
+        "type": "comment",
+        "z": "alarm-sim-flow",
+        "name": "--- Event Alarm Nodes ---",
+        "info": "",
+        "x": 940,
+        "y": 40,
+        "wires": []
+    },
+    {
+        "id": "sim-alarm-pump",
+        "type": "event-alarm",
+        "z": "alarm-sim-flow",
+        "name": "Pump P1A Trip",
+        "cache": "sim-cache",
+        "conditionId": "PumpTrip_P1A",
+        "conditionName": "Heavy Media Pump P1A Trip",
+        "inputMappings": [
+            { "name": "active", "topic": "sim/plant/PumpTrip_P1A/active" }
+        ],
+        "condition": "active == true",
+        "severity": "800",
+        "outputTopic": "alarm/PumpTrip_P1A",
+        "x": 960,
+        "y": 100,
+        "wires": [["debug-sim-raised"], ["debug-sim-acked"], ["debug-sim-cleared"], ["debug-sim-resolved"]]
+    },
+    {
+        "id": "sim-alarm-breaker",
+        "type": "event-alarm",
+        "z": "alarm-sim-flow",
+        "name": "Breaker MCC3 Fault",
+        "cache": "sim-cache",
+        "conditionId": "BreakerFault_MCC3",
+        "conditionName": "MCC3 Main Breaker Fault",
+        "inputMappings": [
+            { "name": "active", "topic": "sim/plant/BreakerFault_MCC3/active" }
+        ],
+        "condition": "active == true",
+        "severity": "900",
+        "outputTopic": "alarm/BreakerFault_MCC3",
+        "x": 970,
+        "y": 180,
+        "wires": [["debug-sim-raised"], ["debug-sim-acked"], ["debug-sim-cleared"], ["debug-sim-resolved"]]
+    },
+    {
+        "id": "sim-alarm-thickener",
+        "type": "event-alarm",
+        "z": "alarm-sim-flow",
+        "name": "Thickener Level High",
+        "cache": "sim-cache",
+        "conditionId": "HighLevel_Thickener",
+        "conditionName": "Thickener Overflow Level High",
+        "inputMappings": [
+            { "name": "active", "topic": "sim/plant/HighLevel_Thickener/active" }
+        ],
+        "condition": "active == true",
+        "severity": "600",
+        "outputTopic": "alarm/HighLevel_Thickener",
+        "x": 970,
+        "y": 260,
+        "wires": [["debug-sim-raised"], ["debug-sim-acked"], ["debug-sim-cleared"], ["debug-sim-resolved"]]
+    },
+    {
+        "id": "sim-alarm-vibration",
+        "type": "event-alarm",
+        "z": "alarm-sim-flow",
+        "name": "Screen 2 Vibration",
+        "cache": "sim-cache",
+        "conditionId": "VibrationHigh_Screen2",
+        "conditionName": "Screen 2 Vibration Alarm High",
+        "inputMappings": [
+            { "name": "active", "topic": "sim/plant/VibrationHigh_Screen2/active" }
+        ],
+        "condition": "active == true",
+        "severity": "500",
+        "outputTopic": "alarm/VibrationHigh_Screen2",
+        "x": 970,
+        "y": 340,
+        "wires": [["debug-sim-raised"], ["debug-sim-acked"], ["debug-sim-cleared"], ["debug-sim-resolved"]]
+    },
+    {
+        "id": "sim-alarm-estop",
+        "type": "event-alarm",
+        "z": "alarm-sim-flow",
+        "name": "Conveyor 7 EStop",
+        "cache": "sim-cache",
+        "conditionId": "EStop_Conveyor7",
+        "conditionName": "Conveyor 7 Emergency Stop",
+        "inputMappings": [
+            { "name": "active", "topic": "sim/plant/EStop_Conveyor7/active" }
+        ],
+        "condition": "active == true",
+        "severity": "1000",
+        "outputTopic": "alarm/EStop_Conveyor7",
+        "x": 970,
+        "y": 420,
+        "wires": [["debug-sim-raised"], ["debug-sim-acked"], ["debug-sim-cleared"], ["debug-sim-resolved"]]
+    },
+    {
+        "id": "sim-alarm-magnetite",
+        "type": "event-alarm",
+        "z": "alarm-sim-flow",
+        "name": "Magnetite Level Low",
+        "cache": "sim-cache",
+        "conditionId": "MagnetiteLevel_Low",
+        "conditionName": "Magnetite Storage Tank Level Low",
+        "inputMappings": [
+            { "name": "active", "topic": "sim/plant/MagnetiteLevel_Low/active" }
+        ],
+        "condition": "active == true",
+        "severity": "400",
+        "outputTopic": "alarm/MagnetiteLevel_Low",
+        "x": 970,
+        "y": 500,
+        "wires": [["debug-sim-raised"], ["debug-sim-acked"], ["debug-sim-cleared"], ["debug-sim-resolved"]]
+    },
+    {
+        "id": "comment-debug-outputs",
+        "type": "comment",
+        "z": "alarm-sim-flow",
+        "name": "--- Lifecycle Debug Outputs ---",
+        "info": "",
+        "x": 1270,
+        "y": 40,
+        "wires": []
+    },
+    {
+        "id": "debug-sim-raised",
+        "type": "debug",
+        "z": "alarm-sim-flow",
+        "name": "RAISED",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": true,
+        "statusVal": "payload.condition_name",
+        "statusType": "msg",
+        "x": 1240,
+        "y": 100,
+        "wires": []
+    },
+    {
+        "id": "debug-sim-acked",
+        "type": "debug",
+        "z": "alarm-sim-flow",
+        "name": "ACKNOWLEDGED",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": true,
+        "statusVal": "payload.condition_name",
+        "statusType": "msg",
+        "x": 1260,
+        "y": 180,
+        "wires": []
+    },
+    {
+        "id": "debug-sim-cleared",
+        "type": "debug",
+        "z": "alarm-sim-flow",
+        "name": "CLEARED",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": true,
+        "statusVal": "payload.condition_name",
+        "statusType": "msg",
+        "x": 1250,
+        "y": 260,
+        "wires": []
+    },
+    {
+        "id": "debug-sim-resolved",
+        "type": "debug",
+        "z": "alarm-sim-flow",
+        "name": "RESOLVED",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": true,
+        "statusVal": "payload.condition_name",
+        "statusType": "msg",
+        "x": 1250,
+        "y": 340,
+        "wires": []
+    }
+]