Migrating from HiveMQ Edge

How to read the HiveMQ Edge configuration from config.xml or the REST API and translate protocol adapters, tags, and mappings into a Connectware service commissioning file using an AI assistant.

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. 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

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 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 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	The adapter config block carries the host, port, authentication, and TLS settings.
Adapter tag	Cybus::Endpoint	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	The tagName to topic assignment becomes a mapping entry. Topics can be reused verbatim.
Southbound mapping	Write endpoint + Cybus::Mapping	The topicFilter to tagName assignment becomes a mapping from a topic to a write endpoint.
MQTT bridge	MQTT connector	Bridges to remote brokers become MQTT connections with mappings.
Data combiner	Rule Engine	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.

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
s7 (S7-300/400/1200/1500, LOGO)	Siemens SIMATIC S7
opcua	OPC UA Client
eip, etheripCipOdva	EtherNet/IP
ads	ADS
http	HTTP/REST
BACnet (commercial module)	BACnet

For adapters without a native connector, for example MTConnect or the file adapter, evaluate a custom connector 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 rules or in the Node-RED Workbench.
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.

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 <protocol-adapter> elements with adapterId, protocolId, a protocol-specific <config> block, <tags>, and <northboundMappings>/<southboundMappings>.

• 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:

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

• ${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.

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.

Translating the Configuration with an AI Assistant

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.

Copy the following prompt and attach the adapter configuration:

AI translation prompt

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 <uns> 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.]

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 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. 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 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.

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 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:

config.xml (excerpt)

<protocol-adapters>
  <protocol-adapter>
    <adapterId>line1-modbus</adapterId>
    <protocolId>modbus</protocolId>
    <config>
      <host>192.168.1.100</host>
      <port>502</port>
      <timeoutMillis>5000</timeoutMillis>
      <modbusToMqtt>
        <pollingIntervalMillis>1000</pollingIntervalMillis>
        <publishChangedDataOnly>true</publishChangedDataOnly>
      </modbusToMqtt>
    </config>
    <northboundMappings>
      <northboundMapping>
        <tagName>line1-temperature</tagName>
        <topic>factory/line1/temperature</topic>
        <maxQos>1</maxQos>
      </northboundMapping>
    </northboundMappings>
    <tags>
      <tag>
        <name>line1-temperature</name>
        <description>Temperature register on line 1</description>
        <definition>
          <startIdx>0</startIdx>
          <readType>HOLDING_REGISTERS</readType>
          <unitId>1</unitId>
          <dataType>INT_16</dataType>
        </definition>
      </tag>
    </tags>
  </protocol-adapter>
</protocol-adapters>

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:

hivemq-edge-migration-example.yml

2KB

Open

hivemq-edge-migration-example.yml

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

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

Disclaimer: HiveMQ and HiveMQ Edge are trademarks of HiveMQ GmbH. Cybus is not affiliated with, endorsed by, or sponsored by HiveMQ GmbH.