Migrating from EMQX Neuron

How to export southbound drivers, groups, and tags from EMQX Neuron and translate them into a Connectware service commissioning file with the help of an AI assistant.

This guide shows you how to migrate an EMQX Neuron configuration to Connectware by exporting the southbound driver configuration and translating it into a service commissioning file. Neuron's REST API serves the complete southbound configuration, including all drivers, groups, and tags, as one JSON document, which makes the translation a good task for an AI assistant. The steps apply to the open-source Neuron as well as to the commercial product, formerly named NeuronEX. In more detail, the following topics are covered:

• Understanding how Neuron concepts map to Connectware resources

• Exporting drivers, groups, and tags via the REST API, the UI, or Excel

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

• Reviewing the generated service commissioning file

• Verifying the migrated data points in the Data Explorer

A complete worked example, from JSON 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 Neuron drivers.

• Access to the Neuron web interface or REST API. The open-source Neuron listens on port 7000, the commercial product on port 8085.

• Network access from Connectware to the devices that Neuron currently polls. After the migration, Connectware connects to the devices directly.

• 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 Neuron Concepts Map to Connectware

Neuron organizes data collection in southbound nodes (driver instances), groups (tag sets sharing one polling interval), and tags (address, data type, and access attribute). Northbound apps publish the collected groups to MQTT. Connectware organizes the same information in resources of a service commissioning file:

Neuron concept	Connectware resource	Notes
Southbound node	Cybus::Connection	One connection per driver instance, carrying the connection parameters from the node settings.
Group	Polling interval	The group interval (milliseconds) becomes the interval of every endpoint translated from that group.
Tag	Cybus::Endpoint	Address, data type, and attribute become the endpoint definition. The attribute is a bitmask: read (1), write (2), and subscribe (4).
Tag attribute subscribe	Rule Engine cov rule	Subscribe tags only report on change; the matching mapping entry gets a cov rule.
Northbound MQTT app	Cybus::Mapping	Neuron publishes one bundled message per group; Connectware publishes one topic per endpoint. See the payload note in this guide.
Tag decimal, bias	Rule Engine transform rule	Scaling factors translate to JSONata expressions; review each one.

Mapping Drivers to Connectors

The following Neuron drivers have a native Connectware connector:

Neuron driver	Connectware connector
Modbus TCP	Modbus/TCP
Siemens S7 ISOTCP	Siemens SIMATIC S7
OPC UA	OPC UA Client
EtherNet/IP	EtherNet/IP
Fanuc FOCAS	FOCAS
BACnet/IP	BACnet
Beckhoff ADS	ADS
Heidenhain CNC	Heidenhain DNC
OPC DA	OPC DA

For drivers without a native connector, for example IEC 60870-5-104, IEC 61850, DNP3, Mitsubishi, Omron FINS, KNXnet/IP, or PROFINET, evaluate a custom connector or keep those devices on an intermediary system.

What Does Not Migrate 1:1

Neuron feature	Connectware approach
Data stream processing (eKuiper)	Streaming SQL rules have no automated conversion. Rebuild the logic with Rule Engine rules or in the Node-RED Workbench.
Group-bundled MQTT payloads	Neuron publishes one JSON message per group with all tag values; Connectware publishes one topic per endpoint. Repoint consumers to per-endpoint topics, or recreate the bundled shape with collect and transform rules.
EMQX platform integrations	Platform-specific northbound apps are out of scope. Route data through the Kafka or MQTT connector instead.
Offline caching settings	Handled differently: Connectware agents buffer data during connection loss.

Exporting the Neuron Configuration

The REST API is the most complete export path and works on the open-source and commercial editions alike:

TOKEN=$(curl -s -X POST "http://${NEURON_HOST}:${NEURON_PORT}/api/v2/login" \
  -H "Content-Type: application/json" \
  -d '{"name": "${NEURON_USER}", "pass": "${NEURON_PASSWORD}"}' | jq -r .token)

curl -s "http://${NEURON_HOST}:${NEURON_PORT}/api/v2/global/drivers" \
  -H "Authorization: Bearer ${TOKEN}" -o neuron-drivers.json

• ${NEURON_HOST} is the hostname or IP address of the Neuron installation.

• ${NEURON_PORT} is 7000 for open-source Neuron and 8085 for the commercial product.

• ${NEURON_USER} and ${NEURON_PASSWORD} are the Neuron credentials.

The response contains every southbound driver with its settings, groups, and tags in one JSON document. For details, see the Neuron Configuration API documentation.

Two UI alternatives exist on the commercial product: Data Collection > South Devices > Export downloads the same driver configuration as JSON, and the Group List of a device exports tags as an Excel file with the columns group, name, address, attribute, type, description, precision, and decimal. The Excel export does not contain the device connection parameters.

Translating the Export with an AI Assistant

The driver export contains connection details and can contain credentials, for example OPC UA usernames. Remove credentials from the JSON before you paste it into an AI tool, and check the data privacy terms of the tool you use. See also the privacy notes for Cybus Connectware GPT.

Copy the following prompt and attach the driver export:

AI translation prompt

You are translating an EMQX Neuron driver export (JSON from
GET /api/v2/global/drivers) into a Cybus Connectware service commissioning
file (YAML). Produce one complete, valid service commissioning file with
description, metadata, parameters, definitions, and resources.

Structural rules:
- Create one Cybus::Connection per southbound node. Read the driver from
  "plugin" and the connection settings from the node params (host, port,
  and driver-specific options).
- Create one Cybus::Endpoint per tag, referencing its connection with !ref.
  The group "interval" (already in milliseconds) becomes the endpoint
  interval for polling protocols.
- The tag "attribute" is a bitmask: 1 = read, 2 = write, 4 = subscribe.
  Read tags get a subscribe section, write tags an additional write
  endpoint, and subscribe tags get a Rule Engine cov rule (key "value") on
  their mapping entry.
- Tag "type" is an integer: 1=INT8, 2=UINT8, 3=INT16, 4=UINT16, 5=INT32,
  6=UINT32, 7=INT64, 8=UINT64, 9=FLOAT, 10=DOUBLE, 11=BIT, 12=BOOL,
  13=STRING, 14=BYTES.
- Tags with a non-zero "decimal" or "bias" need a JSONata transform rule
  reproducing the scaling; flag each one for review.
- Create one Cybus::Mapping publishing every endpoint to the topic
  "<node>/<group>/<tag>", lowercase kebab-case. If downstream consumers
  depend on Neuron's bundled group payload, flag this: recreating that
  shape needs collect and transform rules.
- Define hosts and credentials as parameters, never hardcoded. Do not
  include any credentials in the output.

Driver-specific rules for "Modbus TCP" nodes (protocol: Modbus):
- Tag addresses use the syntax "SLAVE!ADDRESS" with six-digit areas:
  0xxxxx -> fc 1 (coils), 1xxxxx -> fc 2 (discrete inputs),
  3xxxxx -> fc 4 (input registers), 4xxxxx -> fc 3 (holding registers).
  The register offset is the remainder minus 1 (e.g., "1!400001" -> fc 3,
  address 0). Check the node's start-address option: if it is set to
  0-based, do not subtract 1.
- Map types: INT16 -> int16BE, UINT16 -> uint16BE, INT32 -> int32BE,
  UINT32 -> uint32BE, FLOAT -> floatBE, DOUBLE -> doubleBE, BIT and
  BOOL -> boolean. 16-bit types use length 1, 32-bit types length 2,
  64-bit types length 4.
- Address suffixes: "#" endianness codes (e.g. "#BB", "#LL") change the
  byte and word order; choose the matching BE/LE dataType and flag the tag
  for live-value verification. ".<bit>" suffixes are bit access: flag them
  for manual review.

Driver-specific rules for "Siemens S7 ISOTCP" nodes (protocol: S7): host,
port 102, rack and slot from the node params. Neuron addresses like
"DB1.DBW10" or "I0.0" translate to the Connectware S7 syntax ("DB1,W10",
"I0.0"); flag any address you are not certain about.

Driver-specific rules for OPC UA nodes (protocol: Opcua): endpoint URL and
security from the node params. Neuron addresses use "namespace!identifier"
(e.g. "2!Device1.Module1.Tag1" -> nodeId "ns=2;s=Device1.Module1.Tag1",
"0!2258" -> "ns=0;i=2258").

For any node whose driver has no Connectware connector, skip it and list
it at the end under "Not migrated".

After the YAML, output a migration report: number of nodes, groups, and
tags translated, all assumptions made, and every flagged item that needs
manual review.

[Attach the neuron-drivers.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 the original node settings: host, port, and driver-specific options.

3. Spot-check translated Modbus addresses, including the six-digit area mapping, the start-address setting of the node, and every endianness suffix.

4. Check that group intervals were applied to the endpoints and that subscribe tags received cov rules.

5. Review every generated scaling transform (decimal, bias) against the original tag.

6. Confirm that no credentials ended up in the file and that all site-specific values are parameters.

7. Compare the endpoint count against the migration report of the AI assistant and the tag count of the export.

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 Neuron can usually poll the same device at the same time, which allows you to compare live values before you switch consumers over. Check the connection limits of your devices first. Plan the consumer cutover deliberately: Neuron consumers receive bundled group messages, Connectware consumers per-endpoint messages.

Verifying the Data

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

• Every migrated tag publishes on its topic with plausible values.

• Values match between Neuron and Connectware for the same data point.

• Implausible numbers on multi-register tags indicate a wrong endianness suffix translation.

• Subscribe tags with cov rules only publish on value changes.

Worked Example

The following driver export excerpt describes one Modbus TCP node with one group and three tags, in the format returned by GET /api/v2/global/drivers:

neuron-drivers.json (excerpt)

{
  "nodes": [
    {
      "name": "modbus-tcp-1",
      "plugin": "Modbus TCP",
      "params": {
        "connection_mode": 0,
        "host": "192.168.1.100",
        "port": 502,
        "timeout": 3000
      },
      "groups": [
        {
          "name": "group-1",
          "interval": 2000,
          "tags": [
            {
              "name": "temperature",
              "type": 3,
              "address": "1!400001",
              "attribute": 1
            },
            {
              "name": "setpoint",
              "type": 4,
              "address": "1!400002",
              "attribute": 3
            },
            {
              "name": "flow_rate",
              "type": 9,
              "address": "1!400010#LL",
              "attribute": 5
            }
          ]
        }
      ]
    }
  ]
}

Applying the translation rules produces the following service commissioning file. temperature (1!400001, INT16, read) becomes a holding register endpoint with fc: 3, address: 0, and dataType: int16BE; setpoint (attribute 3 = read + write) additionally gets a write endpoint; and flow_rate (1!400010#LL, FLOAT, attribute 5 = read + subscribe) becomes a two-register endpoint with dataType: floatLE (flagged for live-value verification because of the endianness suffix) and a cov rule on its mapping. All endpoints poll at the group interval of 2,000 ms:

emqx-neuron-migration-example.yml

3KB

Open

emqx-neuron-migration-example.yml

description: >
  Service commissioning file migrated from the Neuron southbound node
  modbus-tcp-1, group group-1 (Example)

metadata:
  name: EMQX Neuron Migration Example
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  plcHost:
    description: Host of the southbound node modbus-tcp-1
    type: string
    default: 192.168.1.100

  plcPort:
    description: Port of the southbound node modbus-tcp-1
    type: integer
    default: 502

definitions:
  # Topics mirror the Neuron structure <node>/<group>/<tag>
  MQTT_TOPIC_PREFIX: modbus-tcp-1/group-1

resources:
  # Southbound node "modbus-tcp-1" (Modbus TCP)
  modbusTcp1Connection:
    type: Cybus::Connection
    properties:
      protocol: Modbus
      targetState: connected
      connection:
        host: !ref plcHost
        port: !ref plcPort

  # Tag "temperature": 1!400001, INT16, read
  temperature:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref modbusTcp1Connection
      subscribe:
        fc: 3
        address: 0
        length: 1
        dataType: int16BE
        interval: 2000

  # Tag "setpoint": 1!400002, UINT16, read + write (attribute 3)
  setpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref modbusTcp1Connection
      subscribe:
        fc: 3
        address: 1
        length: 1
        dataType: uint16BE
        interval: 2000

  setpointWrite:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref modbusTcp1Connection
      write:
        fc: 6
        address: 1
        length: 1
        dataType: uint16BE

  # Tag "flow_rate": 1!400010#LL, FLOAT, read + subscribe (attribute 5)
  # Endianness suffix #LL translated to floatLE: verify against live values
  flowRate:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref modbusTcp1Connection
      subscribe:
        fc: 3
        address: 9
        length: 2
        dataType: floatLE
        interval: 2000

  mapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref temperature
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/temperature'
        - subscribe:
            endpoint: !ref setpoint
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/setpoint'
        - subscribe:
            topic: !sub '${MQTT_TOPIC_PREFIX}/setpoint/set'
          publish:
            endpoint: !ref setpointWrite
        # Subscribe attribute: only publish on change of value
        - subscribe:
            endpoint: !ref flowRate
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/flow-rate'
          rules:
            - cov:
                key: value

For all Modbus connection and endpoint properties, see Modbus Connection Properties and Modbus Endpoint Properties.

Disclaimer: EMQ, EMQX, Neuron, and NeuronEX are trademarks or registered trademarks of EMQ Technologies, Inc. Cybus is not affiliated with or endorsed by EMQ.