Migrating from Litmus Edge

How to export DeviceHub devices and tags from Litmus Edge and translate them into a Connectware service commissioning file with the help of an AI assistant.

This guide shows you how to migrate the connectivity layer of a Litmus Edge instance to Connectware by exporting the DeviceHub configuration and translating it into a service commissioning file. In more detail, the following topics are covered:

• Understanding how Litmus Edge concepts map to Connectware resources

• Exporting tags as CSV and device configurations as a template JSON

• Translating the exports 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 tag 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 DeviceHub drivers.

• Access to the Litmus Edge web interface with permissions for DeviceHub and System > Device Management.

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

• An AI assistant to translate the exports. 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 Litmus Edge Concepts Map to Connectware

Litmus Edge collects data through DeviceHub: a device represents one asset behind a protocol driver, tags map the registers of the device, and every tag publishes to the internal broker on devicehub.raw.<deviceId>.<tagId> and, if enabled, devicehub.alias.<deviceName>.<tagName> topics. Connectware organizes the same information in resources of a service commissioning file:

Litmus Edge concept	Connectware resource	Notes
DeviceHub device	Cybus::Connection	One connection per device, carrying the driver choice and network address.
Tag	Cybus::Endpoint	Register address, value type, and polling interval become the endpoint properties. Litmus polling intervals are in seconds; Connectware intervals in milliseconds.
Internal broker topics	MQTT topic hierarchy	The devicehub.alias.<deviceName>.<tagName> structure translates to <device-name>/<tag-name> topics in a Cybus::Mapping.
Publish on change of value	Rule Engine cov rule	Tags with publishcov enabled get a cov rule on their mapping.
Tag formula	Rule Engine transform rule	Simple formulas translate to JSONata expressions; review each one.
Flows (Node-RED)	Node-RED Workbench	Litmus flows are standard Node-RED. Generic nodes move almost 1:1; Litmus-specific nodes must be replaced with MQTT nodes on Connectware topics.
Integration connectors	Enterprise connectors	Kafka, MQTT, MSSQL, SQL, InfluxDB, and HTTP/REST have direct counterparts.

Mapping Drivers to Connectors

The following DeviceHub driver families have a native Connectware connector:

Litmus Edge driver	Connectware connector
OPC UA	OPC UA Client
Modbus TCP	Modbus/TCP
Siemens S7	Siemens SIMATIC S7
Siemens S7CommPlus	Siemens SIMATIC S7+
Allen-Bradley (EtherNet/IP)	EtherNet/IP
Fanuc (FOCAS)	FOCAS
BACnet	BACnet
Beckhoff	ADS
Heidenhain	Heidenhain DNC
SICK	SOPAS
MQTT	MQTT

For drivers without a native connector, for example PROFINET, MTConnect, DNP3, or EUROMAP63, evaluate a custom connector or keep those devices on an intermediary system.

What Does Not Migrate 1:1

Litmus Edge feature	Connectware approach
Analytics and KPI processors	No equivalent. Rebuild transformations with Rule Engine rules; KPI logic moves to a consuming system.
Digital Twins models	No equivalent in the connectivity layer.
Marketplace applications	Run containerized workloads outside Connectware and connect them over MQTT or the HTTP Server.
Litmus Edge Manager	Fleet management is handled differently: Connectware uses agents and infrastructure-as-code deployment.
OPC UA server exposure	Re-implement with the Connectware OPC UA Server resources.
Local data store history	Historical values do not transfer. Store time-series data in an external database through the enterprise connectors.

Exporting the Litmus Edge Configuration

The migration needs two exports: the tag list as CSV and the device connection parameters from a template.

Exporting Tags as CSV

1. Open DeviceHub and select the Tags pane.

2. Click the download icon and choose whether to download all tags from all connected devices or only the tags of the selected device.

The CSV contains one row per tag with the columns deviceid, devicename, drivername, name (the register type), tagname, description, valuetype, registerid (the address), publishcov, tagformula, metadata, and pollinginterval (in seconds). For details, see Manage Tags in the Litmus documentation.

The CSV references devices by ID and name but does not contain their connection parameters.

Exporting Device Configurations as a Template

1. Open System > Device Management and select the Template tab.

2. Select the categories to export. Include the connected devices with their tags and configurations.

3. Click Download Template.

The template is an editable JSON file and is the only UI export that includes device connection parameters such as IP address, port, and station ID. For details, see Manage Templates in the Litmus documentation. Litmus does not publish a schema for the template format, so treat it as version-specific and record your Litmus Edge version alongside the export.

For large fleets, the Litmus Edge REST API lists devices and tags as JSON per component; see the Litmus API portal. The full system backup (backup.dat) is not machine-readable: use it as a safety net, not as a migration source.

Template exports can include passwords, either in plain text or encrypted, depending on the export options. Export with encrypted passwords or 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.

Translating the Exports with an AI Assistant

Copy the following prompt and attach the tag CSV and the template JSON:

AI translation prompt

You are translating a Litmus Edge DeviceHub configuration into a Cybus
Connectware service commissioning file (YAML). You receive two inputs: a tag
CSV export (columns: deviceid, devicename, drivername, name, tagname,
description, valuetype, registerid, publishcov, tagformula, metadata,
pollinginterval) and a template JSON export containing the device connection
parameters. Produce one complete, valid service commissioning file with
description, metadata, parameters, definitions, and resources.

Structural rules:
- Create one Cybus::Connection per device, joining the CSV rows to the
  template devices via deviceid/devicename. Read the driver from
  "drivername" and the network address, port, and station or unit ID from
  the template.
- Create one Cybus::Endpoint per CSV row, referencing its device connection
  with !ref.
- Polling: "pollinginterval" is in seconds; Connectware intervals are in
  milliseconds. Multiply by 1000.
- Create one Cybus::Mapping publishing every endpoint to the topic
  "<devicename>/<tagname>", lowercase kebab-case, mirroring the Litmus alias
  topic structure. For rows with "publishcov" true, add a Rule Engine cov
  rule to the mapping entry.
- Rows with a non-empty "tagformula" need a JSONata transform rule that
  reproduces the formula. Translate simple arithmetic directly and flag
  every formula for manual review.
- Define network addresses and credentials as parameters, never hardcoded.
  Do not include any credentials in the output.

Driver-specific rules for "Modbus TCP" devices (protocol: Modbus):
- "registerid" uses Modbus range addressing: 0xxxxx -> fc 1 (coils),
  1xxxxx -> fc 2 (discrete inputs), 3xxxxx -> fc 4 (input registers),
  4xxxxx -> fc 3 (holding registers). The register offset is the numeric
  remainder minus 1 (e.g., "400001" -> fc 3, address 0). Respect the
  station ID from the template and the zero-based addressing setting.
- Map "valuetype": bool -> boolean, int16 -> int16BE, uint16 -> uint16BE,
  int32 -> int32BE, uint32 -> uint32BE, float32 -> floatBE,
  float64/double -> doubleBE. 16-bit types use length 1, 32-bit types
  length 2, 64-bit types length 4. If the tag defines a non-default
  endianness (byte or word swap), flag it: the Connectware dataType
  variants (BE/LE) must be verified against live values.

Driver-specific rules for "Siemens S7" devices (protocol: S7): host, port
102, rack and slot from the template. Translate register addresses to the
Connectware S7 syntax (for example "DB10,INT4") and flag any address you
are not certain about.

For OPC UA devices (protocol: Opcua): endpoint URL, security settings, and
per-tag NodeIds from the template.

For any device whose driver has no Connectware connector (for example
PROFINET, MTConnect, DNP3), skip it and list it at the end under "Not
migrated".

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

[Attach: tag CSV export, template JSON export. State your Litmus 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 template: driver, host, port, station or unit ID, and rack and slot for S7 devices.

3. Spot-check translated register addresses, especially Modbus range addresses and endianness handling. Litmus supports byte and word swaps per tag; verify that the chosen Connectware dataType variant matches live values.

4. Check that every polling interval was converted from seconds to milliseconds.

5. Review every translated tag formula against the original.

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 row count of the tag CSV.

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 Litmus Edge 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. Remove the migrated devices from DeviceHub once the migration is verified.

Verifying the Data

Open the Data Explorer and subscribe to the topics of the migrated service. Compare live values with the DeviceHub tag view:

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

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

• Implausible numbers on multi-register tags indicate a wrong endianness or register offset.

• Tags migrated with a cov rule only publish on value changes.

Worked Example

The following tag CSV export describes three Modbus TCP tags on one device. The template export provides the connection parameters of the device plc_1: IP address 192.168.1.100, port 502, station ID 1:

litmus-tags.csv

deviceid,devicename,drivername,name,tagname,description,valuetype,registerid,publishcov,tagformula,metadata,pollinginterval
c9c3f3df-954f-4233-834c-4b381741357c,plc_1,Modbus TCP,HoldingRegister,motor_speed,Spindle speed,int16,400001,false,,{"line":"line_1"},1
c9c3f3df-954f-4233-834c-4b381741357c,plc_1,Modbus TCP,HoldingRegister,oil_temperature,Hydraulic oil temp,float32,400010,true,,{"line":"line_1"},5
c9c3f3df-954f-4233-834c-4b381741357c,plc_1,Modbus TCP,Coil,machine_running,Run state,bool,000017,true,,{"line":"line_1"},1

Applying the translation rules produces the following service commissioning file. motor_speed (400001, int16, one second) becomes a holding register endpoint with fc: 3, address: 0, and dataType: int16BE at 1,000 ms; oil_temperature (400010, float32, five seconds) occupies two registers starting at address 9; and machine_running (000017, bool) becomes a coil endpoint with fc: 1, address: 16. The two tags with publishcov enabled get a cov rule on their mapping:

litmus-edge-migration-example.yml

3KB

Open

litmus-edge-migration-example.yml

description: >
  Service commissioning file migrated from the Litmus Edge DeviceHub
  device plc_1 (Modbus TCP) with three tags (Example)

metadata:
  name: Litmus Edge Migration Example
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  plc1Host:
    description: IP address of the device plc_1 (from the template export)
    type: string
    default: 192.168.1.100

  plc1Port:
    description: Modbus/TCP port of the device plc_1
    type: integer
    default: 502

definitions:
  # Topics mirror the Litmus alias topic structure <deviceName>/<tagName>
  MQTT_TOPIC_PREFIX: plc-1

resources:
  # DeviceHub device "plc_1" (Modbus TCP, station ID 1)
  plc1Connection:
    type: Cybus::Connection
    properties:
      protocol: Modbus
      targetState: connected
      connection:
        host: !ref plc1Host
        port: !ref plc1Port

  # Tag "motor_speed": 400001, int16, polling interval 1 s
  motorSpeed:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref plc1Connection
      subscribe:
        fc: 3
        address: 0
        length: 1
        dataType: int16BE
        interval: 1000

  # Tag "oil_temperature": 400010, float32, polling interval 5 s
  oilTemperature:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref plc1Connection
      subscribe:
        fc: 3
        address: 9
        length: 2
        dataType: floatBE
        interval: 5000

  # Tag "machine_running": 000017, bool, polling interval 1 s
  machineRunning:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref plc1Connection
      subscribe:
        fc: 1
        address: 16
        length: 1
        dataType: boolean
        interval: 1000

  mapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref motorSpeed
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/motor-speed'
        # publishcov was enabled: only publish on change of value
        - subscribe:
            endpoint: !ref oilTemperature
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/oil-temperature'
          rules:
            - cov:
                key: value
        - subscribe:
            endpoint: !ref machineRunning
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/machine-running'
          rules:
            - cov:
                key: value

For all Modbus connection and endpoint properties, see Modbus Connection Properties and Modbus Endpoint Properties. For the cov rule, see Rule Engine.

Disclaimer: Litmus, Litmus Edge, and Litmus Edge Manager are trademarks or registered trademarks of Litmus Automation, Inc. Cybus is not affiliated with or endorsed by Litmus Automation.