> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-2/guides/migration/migrating-from-emqx-neuron.md). # Migrating from EMQX Neuron 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](/2-4-2/data-flows/service-commissioning-files.md). 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](/2-4-2/monitoring/data-explorer.md) 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](/2-4-2/tools/cybus-connectware-gpt.md) is a ChatGPT assistant that already knows the service commissioning file format. * Basic knowledge of the Connectware [services](/2-4-2/data-flows/services.md) concept (for example, [service commissioning files](/2-4-2/data-flows/service-commissioning-files.md), [connections](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md), and [endpoints](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md)). ## 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](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md) | 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](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md) | 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](/2-4-2/data-flows/rule-engine.md) `cov` rule | Subscribe tags only report on change; the matching mapping entry gets a `cov` rule. | | Northbound MQTT app | [Cybus::Mapping](/2-4-2/data-flows/service-commissioning-files/resources/cybus-mapping.md) | 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](/2-4-2/connectors/shop-floor-connectors/modbus-tcp.md) | | Siemens S7 ISOTCP | [Siemens SIMATIC S7](/2-4-2/connectors/shop-floor-connectors/siemens-simatic-s7.md) | | OPC UA | [OPC UA Client](/2-4-2/connectors/shop-floor-connectors/opc-ua/opc-ua-client.md) | | EtherNet/IP | [EtherNet/IP](/2-4-2/connectors/shop-floor-connectors/ethernet-ip.md) | | Fanuc FOCAS | [FOCAS](/2-4-2/connectors/shop-floor-connectors/focas.md) | | BACnet/IP | [BACnet](/2-4-2/connectors/shop-floor-connectors/bacnet.md) | | Beckhoff ADS | [ADS](/2-4-2/connectors/shop-floor-connectors/ads.md) | | Heidenhain CNC | [Heidenhain DNC](/2-4-2/connectors/shop-floor-connectors/heidenhain-dnc.md) | | OPC DA | [OPC DA](/2-4-2/connectors/shop-floor-connectors/opc-da.md) | 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](/2-4-2/connectors/custom-connectors.md) 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](/2-4-2/data-flows/rule-engine.md) rules or in the [Node-RED Workbench](/2-4-2/data-flows/node-red-workbench.md). | | 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](/2-4-2/connectors/enterprise-connectors/kafka.md) or [MQTT](/2-4-2/connectors/enterprise-connectors/mqtt.md) connector instead. | | Offline caching settings | Handled differently: Connectware [agents](/2-4-2/data-flows/agents.md) 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: {% code lineNumbers="true" %} ```bash 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 ``` {% endcode %} * `${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](https://docs.emqx.com/en/neuron/latest/api/configuration.html). 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 {% hint style="warning" %} 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](/2-4-2/tools/cybus-connectware-gpt.md#data-privacy). {% endhint %} Copy the following prompt and attach the driver export: {% code title="AI translation prompt" lineNumbers="true" expandable="true" %} ``` 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 "//", 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. "." 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.] ``` {% endcode %} ## Reviewing the Generated Service Commissioning File Work through this checklist before installing: 1. Validate the file structure. The [Cybus Connectware Extension for VS Code](/2-4-2/tools/cybus-connectware-extension-vs-code.md) 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-4-2/data-flows/services/managing/installing.md). 2. Enable the service. See [Enabling Services](/2-4-2/data-flows/services/managing/enabling.md). **Result:** Connectware connects to the migrated devices directly and the connections reach the **Connected** state. {% hint style="info" %} 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. {% endhint %} ## Verifying the Data Open the [Data Explorer](/2-4-2/monitoring/data-explorer.md) 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`: {% code title="neuron-drivers.json (excerpt)" lineNumbers="true" expandable="true" %} ```json { "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 } ] } ] } ] } ``` {% endcode %} 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: {% file src="/files/TgeYrC7EJwmVOqDs32ye" %} {% code title="emqx-neuron-migration-example.yml" lineNumbers="true" expandable="true" %} ```yaml 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 // 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 ``` {% endcode %} For all Modbus connection and endpoint properties, see [Modbus Connection Properties](/2-4-2/connectors/shop-floor-connectors/modbus-tcp/modbusconnection.md) and [Modbus Endpoint Properties](/2-4-2/connectors/shop-floor-connectors/modbus-tcp/modbusendpoint.md). {% hint style="info" %} Disclaimer: EMQ, EMQX, Neuron, and NeuronEX are trademarks or registered trademarks of EMQ Technologies, Inc. Cybus is not affiliated with or endorsed by EMQ. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cybus.io/2-4-2/guides/migration/migrating-from-emqx-neuron.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.