Node-RED Implementation Spec

MQTT-to-OPC-UA Protocol Bridge

SYS Real-Time Steel Product Tracking

Project: Siam Yamato Steel Vision Tracking

Prepared by: Appomax Engineering

Version: 1.0 | April 2026

Classification: Internal – Engineering

1. Purpose & Scope

This document is the implementation specification for the Node-RED component in the SYS Real-Time Steel Product Tracking system. It provides everything an engineer needs to build, test, and deploy the Node-RED flows that bridge Tapway SamurAI Copilot (MQTT) to Ignition Edge (OPC-UA).

1.1 Role of Node-RED

Node-RED acts as a stateless protocol bridge between the raw MQTT event stream from SamurAI Copilot and the OPC-UA tag tree hosted by Ignition Edge. Its responsibilities are strictly limited to:

•       Subscribe to MQTT topics from SamurAI Copilot

•       Parse and validate incoming JSON payloads

•       Flatten nested structures into canonical event records

•       Write normalized values to Ignition Edge OPC-UA tags (as an OPC-UA client)

•       Maintain diagnostics counters for observability

1.2 What Node-RED Must NOT Do

To keep the architecture clean and maintainable, Node-RED must not take on responsibilities that belong to Ignition:

•       No long-term data persistence — Ignition owns all historical data

•       No tracking logic or state machine — Ignition handles product lifecycle

•       No enterprise reporting or alerting

•       No OPC-UA server hosting — Node-RED is an OPC-UA client only

•       No raw JSON dynamic shape forwarding — always normalize first

1.3 Architecture Overview

The data flow is unidirectional:

Tapway SamurAI Copilot

        |

   [MQTT Broker]

        |

   [Node-RED]  ---- OPC-UA Client Write ---->  [Ignition Edge OPC-UA Server]

   (parse,                                      (tag storage, historian,

    validate,                                    state machine, HMI,

    normalize)                                   reporting)

INFO: Node-RED does NOT host an OPC-UA server. Ignition Edge runs the OPC-UA server natively, and Node-RED connects to it as a client to write tag values.

2. Prerequisites & Key Concepts

2.1 Technology Stack

2.2 Key Terminology

3. Processing Flow

The Node-RED flow processes each incoming MQTT message through a linear pipeline of 6 steps. Each step is a distinct function node (or group of nodes) in the flow.

3.1 Step 1: MQTT Subscribe

Subscribe to the SamurAI Copilot MQTT topic(s). The exact topic pattern will be provided by Tapway during integration setup.

3.2 Step 2: JSON Parse + Validation

Parse the raw MQTT payload as JSON. If parsing fails, the message is dropped and diagnostics are updated.

3.2.1 Required Fields

Every valid message must contain the following fields. If any are missing, the message is treated as invalid:

•       cameraID — identifies which camera sent the event

•       uniqueEventID — globally unique identifier for deduplication

•       eventTimeStamp — ISO 8601 timestamp from SamurAI

•       inout — event direction (IN or OUT)

•       At least one zone event object

3.2.2 Validation Failure Behavior

Be lenient. When validation fails:

•       Log the raw payload to Diagnostics/LastRawPayload and the error to Diagnostics/LastParseError

•       Increment InvalidPayloadCounter in System diagnostics

•       Increment per-camera ParseErrorCount in camera diagnostics

•       Continue processing the next message — never crash or stop the flow

NOTE: Validation failures should be rare if Tapway implements their schema correctly. These diagnostics are safety nets for debugging during integration, not expected runtime paths.

3.3 Step 3: Flatten / Normalize

The raw MQTT payload from SamurAI Copilot contains nested structures (e.g., inout.zone5.event_direction, model-1.className[], model-1.trackID[]). Node-RED must flatten these into a canonical event structure.

Do not forward nested JSON to Ignition. The OPC-UA tag tree expects flat, typed values.

3.3.1 Canonical Event Structure

For each normalized event, Node-RED should produce an object with the following fields:

3.4 Step 4: Deduplication

Before writing to OPC-UA, check if this event_id has already been processed. Duplicate events must be silently dropped — they should not be logged to Ignition or update any OPC-UA tags.

3.4.1 Dedup Mechanism

•       Maintain an in-memory cache of recently processed uniqueEventIDs

•       Recommended: per-zone cache of the last 200 event IDs (covers ~20 seconds at peak load)

•       If an incoming event_id exists in the cache, drop the message silently

•       Increment DuplicateEventCounter in System diagnostics and per-camera DuplicateCount

NOTE: The dedup cache is in-memory only. On Node-RED restart, the cache is empty and a few duplicates may pass through. This is acceptable — Ignition's historian handles idempotent writes via the uniqueEventID.

3.5 Step 5: Write to Ignition Edge OPC-UA Tags

For each valid, non-duplicate canonical event, Node-RED writes the normalized values to the corresponding OPC-UA tags in Ignition Edge. Node-RED connects as an OPC-UA client.

3.5.1 OPC-UA Client Configuration

3.5.2 Write Targets per Event

Each canonical event triggers writes to multiple tag groups. The write order should be:

1.    Update Camera tags (e.g., Cameras/C05/LastEventID, LastEventTimestamp)

2.    Update Zone live-state tags (e.g., Zones/C05/C05_Z01/LastEventType, Occupancy, etc.)

3.    Read current EventSequence from Ignition, increment by 1, and write back

4.    Toggle EventPulse (read current value, write the inverse)

5.    Update Events branch if implemented (e.g., Events/C05/C05_Z01/EventID, etc.)

6.    Update Diagnostics counters

INFO: EventSequence and EventPulse require a read-before-write pattern. Node-RED reads the current value from Ignition's OPC-UA server, modifies it, and writes it back. This ensures continuity across Node-RED restarts since Ignition persists the tag values.

3.5.3 OPC-UA Write Failure Handling

If an OPC-UA write fails (Ignition down, network issue, tag path does not exist):

•       Log the error to Node-RED's internal log and to Diagnostics/LastErrorMessage

•       Do not buffer or retry indefinitely — Node-RED is stateless

•       Retry the write once after a short delay (1–2 seconds). If it fails again, drop the event and continue

•       Update System/Online to false if repeated failures indicate Ignition is unreachable

3.6 Step 6: Update Diagnostics

After every processed message (valid or invalid, duplicate or not), update the relevant diagnostics tags in Ignition. This provides real-time observability for the integration team.

4. OPC-UA Tag Contract

This section defines the OPC-UA tag paths and data types that must exist in Ignition Edge before Node-RED can write to them. This serves as the interface contract between the Node-RED spec and the Ignition Edge spec.

INFO: Tag creation and UDT definition are the responsibility of the Ignition Edge engineer. This section documents what Node-RED expects to write to.

4.1 Tag Tree Root

All tags live under a common root path:

Appomax/SteelTracking/SamurAI/

    System/

    Cameras/

    Zones/

    Events/        (recommended)

    Diagnostics/

4.2 System Tags

Global health and status indicators for the integration.

4.3 Camera Tags

Per-camera context and status. Path pattern: Cameras/{CameraID}/

4.4 Zone Tags

Per-zone live state and event detection signals. Path pattern: Zones/{CameraID}/{ZoneID}/

This is the most important tag group because it carries business meaning — each zone represents a detection point in the production line.

4.4.1 Zone Configuration Tags

4.4.2 Zone Live-State Tags

4.4.3 Zone Event Detection Tags (Critical)

These tags are how Ignition detects that a new event has occurred, even if the event values look identical to the previous event:

INFO: EventSequence is the primary mechanism for Ignition to detect new events. Because Node-RED reads the current value from Ignition and increments it, the counter survives Node-RED restarts without persistence.

4.5 Events Branch (Recommended)

An optional but recommended branch that stores the last normalized event per zone as individual tags. This makes it easier for Ignition to read full event details for historian logging and query.

Path pattern: Events/{CameraID}/{ZoneID}/

4.6 Diagnostics Tags

Diagnostics are split into global (under Diagnostics/) and per-camera (under Diagnostics/{CameraID}/).

4.6.1 Global Diagnostics

4.6.2 Per-Camera Diagnostics

Path pattern: Diagnostics/{CameraID}/

5. Camera Online/Offline Detection

NOTE: This section depends on Tapway's MQTT broker capabilities. The approach must be confirmed with Tapway during integration setup.

5.1 Preferred: MQTT Last Will / Death Certificate

If Tapway's MQTT broker supports Last Will and Testament (LWT), each camera can publish a "death certificate" message when it disconnects. Node-RED subscribes to the LWT topic and sets Cameras/{CameraID}/Online = false immediately.

5.2 Fallback: Heartbeat Timeout

If LWT is not available, Node-RED infers camera status from event flow:

•       Track the timestamp of the last received event per camera (Diagnostics/{CameraID}/LastReceiveTs)

•       If no event is received from a camera within the configurable timeout (default: 60 seconds), set Cameras/{CameraID}/Online = false

•       When a new event arrives from that camera, set Online = true

5.3 Decision Required

6. Zone Mapping Configuration

Node-RED must maintain a mapping between Tapway's zone names (SourceZoneName) and Appomax's business zone identifiers (ZoneID). This mapping determines which OPC-UA tag path to write to for each incoming event.

6.1 Mapping Table

Example mapping for Camera 05:

The full mapping table will be populated during integration setup with Tapway and the SYS plant operations team.

6.2 Naming Convention

•       Camera OPC-UA node path: use camera ID (e.g., C05)

•       Camera display/label: use descriptive name (e.g., CoolingBed_Entry_View)

•       Zone ID: {CameraID}_{ZoneSequence} (e.g., C05_Z01)

•       SourceZoneName: preserved exactly as Tapway sends it (e.g., zone5)

•       ZoneName: Appomax business name (e.g., CoolingBed_Entry)

6.3 Why Both SourceZoneName and ZoneID?

•       SourceZoneName = what Tapway sends. Preserves the upstream naming for debugging.

•       ZoneID = Appomax's business identifier. Decouples downstream tracking logic from Tapway's naming model.

This allows Tapway to rename their zones without breaking the Ignition tag tree or tracking logic.

6.4 Unknown Zone Handling

If Node-RED receives an event with a zone name that is not in the mapping table:

•       Log the unknown zone name to Diagnostics/LastParseError

•       Increment InvalidPayloadCounter

•       Drop the event — do not write to OPC-UA with an unmapped zone path

•       The engineering team should add the new mapping and redeploy

7. Startup & Restart Behavior

Node-RED is designed to be stateless. On startup or restart, it should:

1.    Connect to the MQTT broker and subscribe to SamurAI topics

2.    Connect to Ignition Edge's OPC-UA server as a client

3.    Write System/Online = true once both connections are established

4.    Write System/LastRestartTs with the current timestamp

5.    Write System/SchemaVersion with the spec version ("1.0")

6.    Begin processing incoming MQTT messages through the pipeline

There is no state recovery step. EventSequence values are read from Ignition on each event write, so continuity is automatic. The dedup cache starts empty, which means a few post-restart duplicates may pass through — this is acceptable since Ignition handles idempotency.

7.1 Connection Loss Scenarios

8. Deployment & Configuration

8.1 Deployment Target

Node-RED should run as a Docker container on the same network as Ignition Edge and the MQTT broker. This minimizes latency for OPC-UA writes.

8.2 Environment Configuration

All configurable parameters should be externalized as environment variables or a configuration file — not hardcoded in the flow:

8.3 Required Node-RED Nodes

The following community nodes are required in addition to the core Node-RED palette:

9. Testing & Acceptance Criteria

9.1 Unit Tests (Node-RED Flow)

9.2 Integration Tests (with Tapway)

•       Verify correct mapping of all camera + zone combinations

•       Verify EventSequence increments continuously under sustained event load

•       Verify EventPulse toggles on every event

•       Verify Diagnostics counters match expected values after a known test sequence

•       Verify camera Online status reflects actual camera connectivity

10. Open Items & Tapway Dependencies

End of Document — Node-RED Implementation Spec v1.0