Migrating from Node-RED

How to export Node-RED flows as JSON and translate industrial connectivity flows into a Connectware service commissioning file with the help of an AI assistant.

This guide shows you how to migrate industrial Node-RED flows to Connectware by exporting the flows as JSON and translating the connectivity portion into a service commissioning file. Node-RED is widely used as a low-cost glue layer that reads PLCs through contrib nodes and publishes to MQTT. Those flows translate well, because the entire flow configuration is a single, well-defined JSON document. In more detail, the following topics are covered:

• Understanding how Node-RED concepts map to Connectware resources

• Exporting flows from the editor, the flow file, or the Admin API

• Translating the flows into a service commissioning file with an AI assistant

• Deciding what happens to function nodes and other logic

• Verifying the migrated data points in the Data Explorer

A complete worked example, from flow export to service commissioning file, is available at the end of this guide.

Prerequisites

To follow this guide, you will need the following:

• A running instance of Cybus Connectware with licenses for the connectors that replace your contrib nodes.

• Access to the Node-RED editor, the flow file on disk, or the Admin API. The export format is the same across Node-RED 3.x and 4.x.

• Network access from Connectware to the devices that Node-RED currently polls.

• An AI assistant to translate the export. Any capable large language model (LLM) works. Cybus Connectware GPT is a ChatGPT assistant that already knows the service commissioning file format.

• Basic knowledge of the Connectware services concept (for example, service commissioning files, connections, and endpoints).

How Node-RED Concepts Map to Connectware

A Node-RED flow export is a flat JSON array of node objects. Nodes that talk to devices reference a configuration node by ID: the configuration node holds the connection settings, and the flow nodes hold the addresses and polling rates. Connectware separates the same concerns in resources of a service commissioning file:

Node-RED concept	Connectware resource	Notes
Configuration node (modbus-client, s7 endpoint, OpcUa-Endpoint)	Cybus::Connection	Holds host, port, and protocol-specific settings. One connection per configuration node.
Read and poll nodes (modbus-read, s7 in, OpcUa-Client)	Cybus::Endpoint	Address, quantity, and poll rate become the endpoint properties. The s7 endpoint variable table maps one-to-one to S7 endpoints.
mqtt out node topic	Cybus::Mapping	The topic can be reused verbatim on the integrated Connectware broker.
mqtt-broker configuration node	Integrated Connectware broker	External brokers that must keep receiving data become MQTT connector connections.
Simple function nodes	Rule Engine	Pure payload reshaping and scaling translate to JSONata transform rules.
Complex flows and logic	Node-RED Workbench or a Cybus::Container	Flows import into the Workbench largely unchanged for prototyping; production Node-RED runs as a containerized service.

Mapping Contrib Nodes to Connectors

The most common industrial contrib node families and their Connectware counterparts:

Contrib package	Configuration node	Connectware connector
node-red-contrib-modbus	modbus-client	Modbus/TCP
node-red-contrib-s7	s7 endpoint	Siemens SIMATIC S7
node-red-contrib-opcua	OpcUa-Endpoint	OPC UA Client
Core MQTT nodes	mqtt-broker	Integrated broker, or the MQTT connector
Core HTTP request node	—	HTTP/REST

What Does Not Migrate to Native Connectors

Node-RED is a general-purpose programming environment, so only the connectivity portion translates mechanically:

Node-RED feature	Connectware approach
function nodes with arbitrary JavaScript	Simple reshaping becomes a JSONata transform rule. Everything else moves to the Node-RED Workbench or a containerized Node-RED service.
Dashboards	Out of scope. Visualization consumes data from Connectware topics instead.
http in / http response endpoints	Re-implement with the HTTP Server, or keep them in a Node-RED instance.
Dynamic-address nodes (modbus-flex-getter)	Addresses computed at runtime cannot be translated statically. Redesign as fixed endpoints or keep the flow in Node-RED.
Context storage, timers, stateful logic	Keep in Node-RED (Workbench or container) and exchange data with Connectware over MQTT.

The Node-RED Workbench in Connectware is intended for prototyping and testing. For production workloads, run Node-RED as a dedicated service with a Cybus::Container resource, connected to the Connectware broker.

Exporting the Node-RED Flows

Any of the following gives you the same flat JSON array:

• Editor: Open the main menu and select Export (or press Ctrl+E / Cmd+E), select all flows, choose the formatted JSON, and download or copy it.

• Flow file: The runtime stores all flows in the flows.json file in the Node-RED user directory, ~/.node-red by default. Installations older than Node-RED 2.0 use a flows_<hostname>.json file name.

• Admin API: GET http://${NODE_RED_HOST}:1880/flows returns the active flow configuration (with a bearer token if adminAuth is enabled).

Credentials never appear in flow exports: Node-RED stores them encrypted in a separate flows_cred.json file. Collect broker and PLC credentials separately and pass them into the service as parameters. Before you paste an export into an AI tool, also check function node code for hardcoded secrets, and check the data privacy terms of the tool you use. See also the privacy notes for Cybus Connectware GPT.

Translating the Flows with an AI Assistant

Copy the following prompt and attach the flow export:

AI translation prompt

You are translating a Node-RED flow export (a flat JSON array of node
objects) into a Cybus Connectware service commissioning file (YAML). Produce
one complete, valid service commissioning file with description, metadata,
parameters, definitions, and resources.

Structural rules:
- Configuration nodes (no "x"/"y"/"wires" properties) hold connection
  settings and are referenced by ID from flow nodes ("server", "endpoint",
  "broker" properties). Create one Cybus::Connection per protocol
  configuration node that is actually referenced.
- Skip "tab" and "junction" nodes. Follow "wires" arrays to understand
  which read node feeds which mqtt out node.
- Create one Cybus::Endpoint per read/poll definition, referencing its
  connection with !ref.
- Topics of "mqtt out" nodes are reused verbatim as Cybus::Mapping publish
  topics on the integrated Connectware broker. The "mqtt-broker"
  configuration node itself needs no counterpart unless an external broker
  must keep receiving data; in that case create an Mqtt connection and flag
  it.
- "function" nodes between a read node and an mqtt out node: if the code
  only reshapes or scales the payload, translate it to a JSONata transform
  rule on the mapping entry and include the original JavaScript as a
  comment. Otherwise flag the flow for the Node-RED Workbench.
- Define hosts and credentials as parameters, never hardcoded. Credentials
  are not part of the export; list every configuration node that needs
  credentials re-entered.

Rules for node-red-contrib-modbus (protocol: Modbus):
- "modbus-client" configuration nodes: use "tcpHost" and "tcpPort".
  Flag "clienttype": "serial" nodes: Connectware Modbus supports TCP.
- "modbus-read" nodes: "dataType" encodes the function code (Coil -> fc 1,
  Input -> fc 2, HoldingRegister -> fc 3, InputRegister -> fc 4), "adr" is
  the 0-based address, "quantity" the register count, "unitid" the unit ID.
  Convert "rate" + "rateUnit" (ms/s/m/h) to a millisecond interval.
- The Modbus payload is a value array; the Connectware dataType must be
  inferred from how downstream nodes use the payload. Default 16-bit
  registers to int16BE with length 1 and flag every inference.
- Flag "modbus-getter" (triggered reads) and "modbus-flex-*" nodes
  (runtime-computed addresses) for manual redesign.

Rules for node-red-contrib-s7 (protocol: S7):
- "s7 endpoint" configuration nodes: "address" (host), "port" (102),
  "rack", "slot", and "cycletime" (poll interval in ms, use as the
  connection pollInterval). The "vartable" array of {name, addr} entries
  is the tag list: create one endpoint per entry; the address syntax
  ("DB5,REAL0", "MB10") matches the Connectware S7 syntax closely. Verify
  data type letters and flag uncertain addresses.
- "s7 in" nodes with "diff": true publish on change only: add a Rule
  Engine cov rule with key "value" to those mapping entries.

Rules for node-red-contrib-opcua (protocol: Opcua):
- "OpcUa-Endpoint" configuration nodes: parse host and port from the
  "endpoint" URL, map "secpol"/"secmode" to securityPolicy and
  messageSecurityMode.
- NodeIds usually come from "OpcUa-Item" nodes ("item" property, for
  example "ns=2;s=Machine.Temperature") wired into the client, or from
  inject node topics. Collect them into endpoints. Flag flows where the
  NodeId is computed at runtime.

After the YAML, output a migration report: number of connections and
endpoints translated, every function node and its disposition (transform
rule or Workbench), all assumptions made, and every flagged item.

[Attach the flows.json export.]

Reviewing the Generated Service Commissioning File

Work through this checklist before installing:

1. Validate the file structure. The Cybus Connectware Extension for VS Code validates service commissioning files against the official schemas as you edit.

2. Check every connection against its configuration node: host, port, rack and slot, and security settings.

3. Spot-check translated addresses and inferred Modbus data types against live values.

4. Review every generated JSONata transform against the original function node code.

5. Re-enter all credentials as parameters; they were not part of the export.

6. Compare the endpoint count against the migration report of the AI assistant.

Installing the Service

1. Install the service commissioning file. See Installing Services.

2. Enable the service. See Enabling Services.

Result: Connectware connects to the migrated devices directly and the connections reach the Connected state.

For read-only validation, Connectware and Node-RED can usually poll the same device at the same time, which allows you to compare live values before you retire the flows. Check the connection limits of your devices first. Disable the migrated flows in Node-RED once the migration is verified.

Verifying the Data

Open the Data Explorer and subscribe to the topics of the migrated service:

• Every migrated data point publishes on its topic with plausible values.

• Values match between Node-RED (for example, in a debug node) and Connectware.

• Payloads shaped by transform rules match what the original function nodes produced. Compare a sample message from each system side by side.

• Data arrives at the original poll rates.

Worked Example

The following flow export reads two holding registers from a PLC every second, scales the first register in a function node, and publishes the result to MQTT. It contains a tab, three flow nodes, and two configuration nodes:

flows.json

[
  {
    "id": "9a4f2c1e8b3d5a70",
    "type": "tab",
    "label": "Line 1 - Filling Machine"
  },
  {
    "id": "5e8d3a129c7f4b06",
    "type": "modbus-read",
    "z": "9a4f2c1e8b3d5a70",
    "name": "Read fill level",
    "unitid": "1",
    "dataType": "HoldingRegister",
    "adr": "0",
    "quantity": "2",
    "rate": "1",
    "rateUnit": "s",
    "server": "c2b7e9d04a1f6835",
    "wires": [["7f1c6b3e9d2a4580"], []]
  },
  {
    "id": "7f1c6b3e9d2a4580",
    "type": "function",
    "z": "9a4f2c1e8b3d5a70",
    "name": "Scale to liters",
    "func": "msg.payload = { fillLevel: msg.payload[0] / 10 };\nreturn msg;",
    "outputs": 1,
    "wires": [["3d9e5f2a8c4b1670"]]
  },
  {
    "id": "3d9e5f2a8c4b1670",
    "type": "mqtt out",
    "z": "9a4f2c1e8b3d5a70",
    "name": "Publish fill level",
    "topic": "factory/line1/filling/fill-level",
    "qos": "1",
    "broker": "a8c5d2f17e9b3460",
    "wires": []
  },
  {
    "id": "c2b7e9d04a1f6835",
    "type": "modbus-client",
    "name": "Filling Machine PLC",
    "clienttype": "tcp",
    "tcpHost": "192.168.1.100",
    "tcpPort": "502",
    "unit_id": "1"
  },
  {
    "id": "a8c5d2f17e9b3460",
    "type": "mqtt-broker",
    "name": "Plant broker",
    "broker": "broker.example.com",
    "port": "8883",
    "usetls": true
  }
]

Applying the translation rules produces the following service commissioning file. The modbus-client node becomes a Modbus connection; the modbus-read node becomes a holding register endpoint at address 0 with a one-second interval; the function node only uses the first register, so the endpoint reads one register as int16BE and the scaling becomes a JSONata transform rule; and the MQTT topic is reused verbatim:

node-red-migration-example.yml

2KB

Open

node-red-migration-example.yml

description: >
  Service commissioning file migrated from the Node-RED flow
  "Line 1 - Filling Machine" (Example)

metadata:
  name: Node-RED Migration Example
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  plcHost:
    description: Host of the modbus-client node "Filling Machine PLC"
    type: string
    default: 192.168.1.100

  plcPort:
    description: Port of the modbus-client node "Filling Machine PLC"
    type: integer
    default: 502

resources:
  # Configuration node "Filling Machine PLC" (modbus-client)
  fillingMachineConnection:
    type: Cybus::Connection
    properties:
      protocol: Modbus
      targetState: connected
      connection:
        host: !ref plcHost
        port: !ref plcPort

  # Node "Read fill level": HoldingRegister, adr 0, rate 1 s
  # The downstream function node only uses the first register.
  fillLevel:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref fillingMachineConnection
      subscribe:
        fc: 3
        address: 0
        length: 1
        dataType: int16BE
        interval: 1000

  # Function node "Scale to liters" became a JSONata transform rule:
  # msg.payload = { fillLevel: msg.payload[0] / 10 }
  mapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref fillLevel
          publish:
            topic: factory/line1/filling/fill-level
          rules:
            - transform:
                expression: |
                  {
                    "timestamp": timestamp,
                    "fillLevel": value / 10
                  }

The mqtt-broker node needs no counterpart: consumers subscribe to the topic on the integrated Connectware broker. If the external broker at broker.example.com must keep receiving the data, add an MQTT connector connection with a mapping.

For all Modbus connection and endpoint properties, see Modbus Connection Properties and Modbus Endpoint Properties. For the transform rule, see Data Processing Rules.

Disclaimer: Node-RED is a trademark of the OpenJS Foundation. Cybus is not affiliated with the OpenJS Foundation.