> 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-hivemq-edge.md). # Migrating from HiveMQ Edge This guide shows you how to migrate a HiveMQ Edge configuration to Connectware by extracting the protocol adapter configuration and translating it into a [service commissioning file](/2-4-2/data-flows/service-commissioning-files.md). HiveMQ Edge stores its complete configuration in a single `config.xml` file and serves the same information as JSON over its REST API, which makes the connectivity layer a good candidate for AI-assisted translation. In more detail, the following topics are covered: * Understanding how HiveMQ Edge concepts map to Connectware resources * Extracting the configuration from the `config.xml` file or the REST API * Translating the configuration 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 adapter configuration 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 HiveMQ Edge protocol adapters. * Access to the HiveMQ Edge installation: the `conf/config.xml` file (or the Helm values on Kubernetes), or credentials for the REST API. * Network access from Connectware to the devices that HiveMQ Edge currently polls. After the migration, Connectware connects to the devices directly. * An AI assistant to translate the configuration. 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 HiveMQ Edge Concepts Map to Connectware HiveMQ Edge combines a local MQTT broker with protocol adapters. An adapter connects to one device, adapter tags name the data points, northbound mappings publish tags to MQTT topics, and southbound mappings write MQTT data back to tags. Connectware organizes the same information in resources of a service commissioning file: | HiveMQ Edge concept | Connectware resource | Notes | | ----------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Protocol adapter | [Cybus::Connection](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md) | The adapter `config` block carries the host, port, authentication, and TLS settings. | | Adapter tag | [Cybus::Endpoint](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md) | The protocol-specific tag `definition` becomes the endpoint address. Polling intervals live at the adapter level in HiveMQ Edge and per endpoint in Connectware. | | Northbound mapping | [Cybus::Mapping](/2-4-2/data-flows/service-commissioning-files/resources/cybus-mapping.md) | The `tagName` to `topic` assignment becomes a mapping entry. Topics can be reused verbatim. | | Southbound mapping | Write endpoint + [Cybus::Mapping](/2-4-2/data-flows/service-commissioning-files/resources/cybus-mapping.md) | The `topicFilter` to `tagName` assignment becomes a mapping from a topic to a write endpoint. | | MQTT bridge | [MQTT connector](/2-4-2/connectors/enterprise-connectors/mqtt.md) | Bridges to remote brokers become MQTT connections with mappings. | | Data combiner | [Rule Engine](/2-4-2/data-flows/rule-engine.md) | Combining several tags into one message maps to `collect` and `transform` rules. | | ISA-95 UNS topic prefix | MQTT topic hierarchy | HiveMQ Edge prefixes topics globally; in Connectware the prefix becomes an explicit part of the mapping topics. | | Local MQTT broker | Integrated Connectware broker | MQTT clients that connect to HiveMQ Edge directly must be repointed to Connectware and receive credentials through [user management](/2-4-2/access/user-management.md). | ### Mapping Protocol Adapters to Connectors The following HiveMQ Edge protocol adapters have a native Connectware connector: | HiveMQ Edge adapter (`protocolId`) | Connectware connector | | ---------------------------------- | ----------------------------------------------------------------------------------- | | `modbus` | [Modbus/TCP](/2-4-2/connectors/shop-floor-connectors/modbus-tcp.md) | | `s7` (S7-300/400/1200/1500, LOGO) | [Siemens SIMATIC S7](/2-4-2/connectors/shop-floor-connectors/siemens-simatic-s7.md) | | `opcua` | [OPC UA Client](/2-4-2/connectors/shop-floor-connectors/opc-ua/opc-ua-client.md) | | `eip`, `etheripCipOdva` | [EtherNet/IP](/2-4-2/connectors/shop-floor-connectors/ethernet-ip.md) | | `ads` | [ADS](/2-4-2/connectors/shop-floor-connectors/ads.md) | | `http` | [HTTP/REST](/2-4-2/connectors/enterprise-connectors/http-rest.md) | | BACnet (commercial module) | [BACnet](/2-4-2/connectors/shop-floor-connectors/bacnet.md) | For adapters without a native connector, for example MTConnect or the file adapter, evaluate a [custom connector](/2-4-2/connectors/custom-connectors.md) or keep those sources on an intermediary system. ### What Does Not Migrate 1:1 | HiveMQ Edge feature | Connectware approach | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Broker client sessions and retained state | MQTT clients reconnect to the Connectware broker. Sessions and retained messages do not transfer; clients need Connectware credentials and permissions. | | Bridge topic rewriting and loop prevention | The placeholder-based topic rewriting (`{#}`, `{2-#}`) and hop-count loop prevention of bridges must be redesigned as explicit mapping topics. | | Data Hub policies and scripts | Schema validation, behavior policies, and JavaScript transformations have no direct counterpart. Rebuild transformations 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). | | Payload shape options | Northbound options such as `includeTagNames` and MQTT user properties change the payload shape. Connectware endpoints publish `{timestamp, value}` objects; downstream consumers may need a `transform` rule to receive the accustomed shape. | | Commercial modules and custom adapters | Adapters built on the HiveMQ Edge SDK must be re-implemented as [custom connectors](/2-4-2/connectors/custom-connectors.md). | ## Extracting the HiveMQ Edge Configuration There are two sources; the REST API is the more reliable one: * **Configuration file:** The complete configuration is the `conf/config.xml` file of the installation (on Kubernetes, the file passed to the Helm chart). Protocol adapters appear as `` elements with `adapterId`, `protocolId`, a protocol-specific `` block, ``, and ``/``. * **REST API:** The Admin API serves the same information as JSON. Authenticate against `POST /api/v1/auth/authenticate` (default port 8080) and read the adapter configuration: {% code lineNumbers="true" %} ```bash curl -s "http://${EDGE_HOST}:8080/api/v1/management/protocol-adapters/adapters" \ -H "Authorization: Bearer ${TOKEN}" -o hivemq-edge-adapters.json curl -s "http://${EDGE_HOST}:8080/api/v1/management/bridges" \ -H "Authorization: Bearer ${TOKEN}" -o hivemq-edge-bridges.json ``` {% endcode %} * `${EDGE_HOST}` is the hostname or IP address of the HiveMQ Edge installation. * `${TOKEN}` is the JWT returned by the authentication endpoint. For details, see the [HiveMQ Edge REST API documentation](https://docs.hivemq.com/hivemq-edge/api-configuration.html). {% hint style="info" %} HiveMQ Edge restructured its adapter configuration format in 2024.8: older installations may still use a legacy per-protocol XML layout. The REST API always returns the current model, which is one more reason to prefer it over parsing an old `config.xml`. State your HiveMQ Edge version when you hand the configuration to an AI assistant. {% endhint %} ## Translating the Configuration with an AI Assistant {% hint style="warning" %} The `config.xml` file contains credentials in plain text, for example OPC UA usernames and passwords in adapter `auth` blocks and bridge authentication settings. Remove all credentials before you paste the configuration 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 adapter configuration: {% code title="AI translation prompt" lineNumbers="true" expandable="true" %} ``` You are translating a HiveMQ Edge configuration (config.xml or the JSON from the REST API) 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 protocol-adapter. Read the protocol from "protocolId" and the connection settings from the "config" block (host, port, uri, auth, security). - Create one Cybus::Endpoint per adapter tag, referencing its connection with !ref. The tag "definition" carries the protocol-specific address. - Polling: HiveMQ Edge polls per adapter ("pollingIntervalMillis" inside the config, already in milliseconds). Apply it as the "interval" of every endpoint of that adapter. OPC UA adapters subscribe instead: use "publishingInterval" as samplingInterval and publishInterval. - If "publishChangedDataOnly" is true, add a Rule Engine cov rule with key "value" to the mapping entries of that adapter's endpoints. - Create one Cybus::Mapping from the northboundMappings: for each entry, map the endpoint of "tagName" to its "topic", reusing the topic verbatim. If the ISA-95 UNS prefix is enabled in the section, prepend it to every topic explicitly. Tags without a northbound mapping get a topic derived from the adapter and tag name, lowercase kebab-case. - southboundMappings become write endpoints plus mapping entries from the "topicFilter" to the write endpoint. Flag "fieldMapping" definitions for manual review. - MQTT bridges: do not translate them into connections by default. MQTT clients and remote brokers connect to the Connectware broker directly. If a bridge forwards data to a remote broker that must keep receiving data, create an Mqtt connection with mappings and flag it for review. - Define hosts and credentials as parameters, never hardcoded. Do not include any credentials in the output. Driver-specific rules for "modbus" adapters (protocol: Modbus): - Tag definitions carry "startIdx" (already a 0-based register offset), "readType" (HOLDING_REGISTERS -> fc 3, INPUT_REGISTERS -> fc 4, COILS -> fc 1, DISCRETE_INPUTS -> fc 2), "unitId", and "dataType". - Map dataType: INT_16 -> int16BE, UINT_16 -> uint16BE, INT_32 -> int32BE, UINT_32 -> uint32BE, FLOAT_32 -> floatBE, FLOAT_64 -> doubleBE, BOOL -> boolean. 16-bit types use length 1, 32-bit types length 2, 64-bit types length 4. If "flipRegisters" is true, flag the tag: the word order must be verified against live values. Driver-specific rules for "s7" adapters (protocol: S7): host, port 102, rack and slot from "remoteRack"/"remoteSlot". Translate tag addresses to the Connectware S7 syntax and flag any address you are not certain about. Driver-specific rules for "opcua" adapters (protocol: Opcua): parse host and port from the "uri", map the security policy, and use the tag definition "node" as the endpoint nodeId. For any adapter whose protocol has no Connectware connector, skip it and list it at the end under "Not migrated". After the YAML, output a migration report: number of adapters, tags, and mappings translated, all assumptions made, and every flagged item that needs manual review. [Attach the config.xml or the REST API JSON. State your HiveMQ Edge version.] ``` {% 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 adapter `config` block: host, port, security, and authentication settings. 3. Spot-check translated Modbus tags: `startIdx` is already 0-based, so no offset correction applies, and `flipRegisters` tags need live-value verification. 4. Check that adapter-level polling intervals were applied to every endpoint of the adapter. 5. Compare mapping topics with the original northbound mappings, including the ISA-95 prefix if it was enabled. 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 adapters. ## 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 HiveMQ Edge can usually poll the same device at the same time, which allows you to compare live values on both brokers before you repoint MQTT clients. Check the connection limits of your devices first. Plan the client cutover separately: every MQTT client that connected to HiveMQ Edge needs Connectware credentials and permissions. {% 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 HiveMQ Edge and Connectware for the same data point. * Consumers that depended on the HiveMQ Edge payload shape (tag names or user properties in the payload) receive the shape they expect, through a `transform` rule where needed. * Adapters migrated with a `cov` rule only publish on value changes. ## Worked Example The following `config.xml` excerpt describes a Modbus protocol adapter with one tag and a northbound mapping, in the current HiveMQ Edge configuration format: {% code title="config.xml (excerpt)" lineNumbers="true" expandable="true" %} ```xml line1-modbus modbus 192.168.1.100 502 5000 1000 true line1-temperature factory/line1/temperature 1 line1-temperature Temperature register on line 1 0 HOLDING_REGISTERS 1 INT_16 ``` {% endcode %} Applying the translation rules produces the following service commissioning file. The adapter becomes a Modbus connection, the tag becomes a holding register endpoint with `fc: 3`, `address: 0` (the `startIdx` is already 0-based), and `dataType: int16BE` polled at the adapter interval of 1,000 ms, and the northbound topic is reused verbatim. Because `publishChangedDataOnly` was enabled, the mapping gets a `cov` rule: {% file src="/files/ZEWWLhIDLvdkuLMWFqzf" %} {% code title="hivemq-edge-migration-example.yml" lineNumbers="true" expandable="true" %} ```yaml description: > Service commissioning file migrated from the HiveMQ Edge protocol adapter line1-modbus (Example) metadata: name: HiveMQ Edge Migration Example provider: cybus homepage: https://www.cybus.io version: 1.0.0 parameters: modbusHost: description: Host of the adapter line1-modbus type: string default: 192.168.1.100 modbusPort: description: Port of the adapter line1-modbus type: integer default: 502 resources: # HiveMQ Edge protocol adapter "line1-modbus" line1ModbusConnection: type: Cybus::Connection properties: protocol: Modbus targetState: connected connection: host: !ref modbusHost port: !ref modbusPort # Tag "line1-temperature": HOLDING_REGISTERS, startIdx 0, INT_16, unit 1 line1Temperature: type: Cybus::Endpoint properties: protocol: Modbus connection: !ref line1ModbusConnection subscribe: fc: 3 address: 0 length: 1 dataType: int16BE interval: 1000 # Northbound mapping: topic reused verbatim # publishChangedDataOnly was enabled: only publish on change of value mapping: type: Cybus::Mapping properties: mappings: - subscribe: endpoint: !ref line1Temperature publish: topic: factory/line1/temperature 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: HiveMQ and HiveMQ Edge are trademarks of HiveMQ GmbH. Cybus is not affiliated with, endorsed by, or sponsored by HiveMQ GmbH. {% 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-hivemq-edge.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.