> 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-litmus-edge.md). # Migrating from Litmus Edge 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](/2-4-2/data-flows/service-commissioning-files.md). 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](/2-4-2/monitoring/data-explorer.md) 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](/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 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..` and, if enabled, `devicehub.alias..` topics. Connectware organizes the same information in resources of a service commissioning file: | Litmus Edge concept | Connectware resource | Notes | | -------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DeviceHub device | [Cybus::Connection](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md) | One connection per device, carrying the driver choice and network address. | | Tag | [Cybus::Endpoint](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md) | 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..` structure translates to `/` topics in a [Cybus::Mapping](/2-4-2/data-flows/service-commissioning-files/resources/cybus-mapping.md). | | Publish on change of value | [Rule Engine](/2-4-2/data-flows/rule-engine.md) `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](/2-4-2/data-flows/node-red-workbench.md) | 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](/2-4-2/connectors/enterprise-connectors.md) | 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](/2-4-2/connectors/shop-floor-connectors/opc-ua/opc-ua-client.md) | | Modbus TCP | [Modbus/TCP](/2-4-2/connectors/shop-floor-connectors/modbus-tcp.md) | | Siemens S7 | [Siemens SIMATIC S7](/2-4-2/connectors/shop-floor-connectors/siemens-simatic-s7.md) | | Siemens S7CommPlus | [Siemens SIMATIC S7+](/2-4-2/connectors/shop-floor-connectors/siemens-simatic-s7-plus.md) | | Allen-Bradley (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 | [BACnet](/2-4-2/connectors/shop-floor-connectors/bacnet.md) | | Beckhoff | [ADS](/2-4-2/connectors/shop-floor-connectors/ads.md) | | Heidenhain | [Heidenhain DNC](/2-4-2/connectors/shop-floor-connectors/heidenhain-dnc.md) | | SICK | [SOPAS](/2-4-2/connectors/shop-floor-connectors/sopas.md) | | MQTT | [MQTT](/2-4-2/connectors/enterprise-connectors/mqtt.md) | For drivers without a native connector, for example PROFINET, MTConnect, DNP3, or EUROMAP63, 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 | Litmus Edge feature | Connectware approach | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Analytics and KPI processors | No equivalent. Rebuild transformations with [Rule Engine](/2-4-2/data-flows/rule-engine.md) 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](/2-4-2/connectors/servers/http-server.md). | | Litmus Edge Manager | Fleet management is handled differently: Connectware uses [agents](/2-4-2/data-flows/agents.md) and infrastructure-as-code deployment. | | OPC UA server exposure | Re-implement with the Connectware [OPC UA Server](/2-4-2/connectors/servers/opc-ua-server.md) 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](https://docs.litmus.io/litmusedge/product-features/devicehub/tags/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](https://docs.litmus.io/litmusedge/product-features/system/device-management/backup-restore/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](https://api.litmus.io/). The full system backup (`backup.dat`) is not machine-readable: use it as a safety net, not as a migration source. {% hint style="warning" %} 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](/2-4-2/tools/cybus-connectware-gpt.md#data-privacy). {% endhint %} ## Translating the Exports with an AI Assistant Copy the following prompt and attach the tag CSV and the template JSON: {% code title="AI translation prompt" lineNumbers="true" expandable="true" %} ``` 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 "/", 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.] ``` {% 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 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-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 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. {% endhint %} ## Verifying the Data Open the [Data Explorer](/2-4-2/monitoring/data-explorer.md) 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: {% code title="litmus-tags.csv" lineNumbers="true" %} ``` 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 ``` {% endcode %} 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: {% file src="/files/fCYVkPu4d9UsNAiXPis4" %} {% code title="litmus-edge-migration-example.yml" lineNumbers="true" expandable="true" %} ```yaml 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 / 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 ``` {% 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). For the `cov` rule, see [Rule Engine](/2-4-2/data-flows/rule-engine.md). {% hint style="info" %} 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. {% 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-litmus-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.