Changelog: Litmus Edge 4.0.x to 4.4.x

You are at https://api.litmus.io/reference/changelog-le.md. Parent: https://api.litmus.io/agents.md (product router: /le/agents.md) What changed in the LE API between 4.0.x and 4.4.x. This tree documents 4.4.x only; 4.0.x endpoints live only in the full collection JSON.

This document describes the API differences between LitmusEdge 4.0.x and 4.4.x, for installations and integrations upgrading from 4.0.x. Every entry was checked against live 4.0.x and 4.4.x devices. Changes are grouped by service; anything not listed is unchanged.

Breaking changes at a glance

Fourteen classes of change can break an existing 4.0.x client. They are listed in the order you should act on them; the detail for each is in its service section below. Most of them are invisible to a GraphQL schema check: they live in the driver and provider catalogues, in REST routing, or in nullability, and no GraphQL type, field or enum value was removed outside Analytics.

Summary

Deprecations

Eight operations and fields are deprecated in 4.4.x that were not deprecated in 4.0.x. All still work and all have replacements. Two are scheduled for removal after 2027-09-01.

Integration

Breaking: every ProviderID changed

This is the largest breaking change on this upgrade path, and it affects every client that creates or inspects an Integration instance.

In 4.0.x a ProviderID was a readable slug. In 4.4.x it is a UUID, and most providers also have a new name. The table maps every provider present in both releases from its 4.0.x slug to its 4.4.x UUID and name.

48 providers in 4.0.x, 64 in 4.4.x, 43 present in both. None of those 43 kept its ProviderID.

The schema records the same change: Instance.ProviderID is retyped from String! to UUID!. CreateInstance takes a ProviderID, so every hard-coded ID fails. There is no alias or compatibility mapping: the old slug is simply not a valid ID.

Action required: migrate stored ProviderIDs with the table above, keyed on the 4.0.x slug, and treat the result as an opaque UUID.

Do not resolve by the 4.0.x name. The Gen 2 providers took the plain names and the originals became "(Gen 1)". A 4.0.x client that looks up MQTT - Generic on 4.4.x gets the Gen 2 provider 0e04a6f5-dc0c-4bd8-84b9-dc2b1b74b110, a different implementation from the generic-mqtt-tcp it used on 4.0.x, which is now MQTT - Generic (Gen 1). The same applies to NATS, REST API, Splunk, OSI PI Historian, AWS IoT SiteWise and the other renamed providers. The lookup succeeds, so nothing reports the mistake.

Five providers present in 4.0.x are gone in 4.4.x: Azure IoT Hub using SAS Key over SSL Gen 2, Kafka SSL Gen 2, Kafka TCP Gen 2, MQTT - v5 Generic over SSL Gen 2 and Snowpipe Streaming. The first four are covered by single Gen 2 providers that select the transport through a connectionType config property.

Breaking: AWS IoT Core QoS 2

AWS IoT Core (4.0.x MQTT - AWS IoT Core Gen 2) no longer offers QoS 2 for qos and willQoS. A config that sets either to 2 is invalid; use 0 or 1.

Deprecated

Config.Required is deprecated in favour of SchemaProperty.Required: GetProviderSchema now states on each property whether it is required.

Behaviour changes

On Databricks Zerobus Ingest, proxyValue is required when a proxy is configured, and on MQTT - Generic (the 4.0.x MQTT - Generic Gen 2), caCert is required for TLS connections. On Azure IoT Hub and MQTT - Generic, credentials that only apply to one connectionType are not required for the other.

New

Provider catalogue. 21 new providers: AMQP, AWS IoT SiteWise, Aveva DataHub, Azure Event Hubs, Azure IoT Hub, Cognite, Google Cloud Pub/Sub, Kafka, Litmus Unify (7c1f3a92-5b8e-4d6a-9f27-0a4c8e35b1d3), MQTT - IBM Watson over SSL, MaintainX API, Microsoft SQL Server, MongoDB v4+, MySQL, OSI PI Historian, PostgreSQL, REST API, SAP Hana Cloud, Snowflake Snowpipe Stream, Splunk and TimescaleDB.

Experimental providers. Provider, GroupedProvider and ProviderSchema gain IsExperimental: Boolean!, marking providers shipped for evaluation rather than production. It is independent of Hidden: an experimental provider is still listed and selectable unless separately hidden, so a production-only picker must filter on both. In 4.4.x, Aveva DataHub and OSI PI Historian are flagged.

Provider configuration. 37 optional properties were added across 9 providers, all with defaults, so existing configs are unaffected. They include connectTimeout, pingTimeout, reconnectInterval and publishWaitTimeout on the Gen 1 MQTT-family providers.

Instances. Instance gains ExecCommandEnabled: Boolean and ProviderName: String!. GetInstanceStatusResponse gains InstanceState: InstanceState!, backed by a new InstanceState enum.

DeviceHub

Breaking: the Mark and Space parity options are gone

Fourteen serial drivers dropped two values from their parity device property, and Generic Device, IND256x and Scale dropped them from the register-level parity as well.

Affected drivers: AB DF1 Serial, AB Logix Serial, Enron Modbus, Generic Device, IDEC Serial, IND256x, Mitsubishi A Series Serial, Modbus Multi-Station RTU to TCP Converter, Omron Fins Ethernet, Omron Fins Serial, Omron HostLink, Scale, Siemens S7-200 Serial, Toyopuc CMP-Link Serial.

The surviving options keep their value codes, so a device configured with 0, 1 or 2 needs no action. Action required: audit device and tag configurations for parity 3 or 4 on these drivers and re-point each to 0, 1 or 2. Mark and Space parity have no equivalent among the survivors, so this is a decision about what the physical device expects rather than a relabelling.

Breaking: IDEC Serial bit registers

The bit value type moved out of registers I, Q, M, R, C and T into six new registers, I_bit, Q_bit, M_bit, R_bit, C_bit and T_bit. A tag that reads a bit through, for example, I with value type bit must be re-created on I_bit. The address ranges also narrowed: I and Q from 0-37 to 0-20, M from 0-317 to 0-300, R from 0-63 to 0-48.

Breaking: removed driver properties and value types

Breaking: parity labels on five Modbus-family drivers

Cutler-Hammer ELC Serial, Modbus ASCII, Modbus ASCII Advanced, Modbus RTU and Modbus RTU Advanced changed their parity labels from none / even / odd to None / Even / Odd, and the property type from String to SignedInteger. The values 0, 1, 2 are unchanged, so this only affects a client that matches on the label string.

These five drivers do not use the same value mapping as the fourteen above: for them 1 is Even and 2 is Odd, the reverse of the fourteen. Always read the mapping from the driver's own ListValues.

Deprecated

UploadStatus.Warnings is deprecated in favour of UploadStatus.Stats and FailDetails.

Behaviour changes

Default values changed on these driver properties. Devices that set the property explicitly are unaffected; devices that relied on the default behave differently after the upgrade.

Sparkplug B Client Namespace is now required, with default spBv1.0. Generator widened the address range of registers M, S and Ssub from 1-32768 to 0-65535.

New

Driver catalogue. 153 drivers to 207. No driver was removed or renamed. The 54 new drivers are: AB ControlLogix Unsolicited, ABB Totalflow DB2, ABB Totalflow DB2 Serial, Beckhoff TwinCAT2/3 Ethernet Absolute, Beckhoff TwinCAT3 Ethernet Symbolic, Brother Ethernet, CAN Raw, CODESYS V2 Ethernet Absolute, CODESYS V2 Ethernet Symbolic, Delta DVP Ethernet, Excel, Fanuc CNC Ethernet, Fuji NB Serial, Fuji SPH2000 Ethernet, GE Fanuc 90-30 Ethernet, GE Fanuc RX3i Serial, GE Fanuc SNP Serial, GE Fanuc SNPX Serial, HID Device, Heidenhain 530 Ethernet, Heidenhain 640 Ethernet, Hitachi EH Serial, IEC60870-5-102 Ethernet, IEC60870-5-104 Ethernet, Keyence KV-10 Serial, Keyence Serial, Koyo Click Serial, Koyo Direct Serial, Koyo Ethernet, LS Serial, MTConnect Ethernet, Mitsubishi F Ethernet, Mitsubishi F Serial, Mitsubishi Q Serial, Mitsubishi iQ-F Serial (FX5U), Oemax Serial, Opto22 MMIO Protocol Ethernet, Panasonic FP Ethernet, Panasonic FP Serial, Panasonic FP7 Ethernet, Parker ACR9000 Ethernet, Ping, SEW Drive Ethernet, SICK Flexi Soft, Saia S-Bus Ethernet, Siemens Logo Ethernet, Siemens S7-300 Serial, Siemens Sinumerik 808D Serial, Siemens TI505 Ethernet, Siemens TI505 Serial, Toshiba Computer Link Ethernet, VIPA 300S Ethernet, Yaskawa MP2300 Ethernet, Yokogawa FA-M3 Ethernet.

Additions to existing drivers. Open Protocol Ethernet gains 50 register types and useGenericSubscribe; OPC UA Client Advanced can call OPC UA methods (value type Method, with DefaultInputArgumentsOPCUAMethod); AB Logix Ethernet gains array and unsigned value types on register R plus fwVersion and PLCProgramChangeAction; CIP Ethernet gains serviceType and register properties data, respDataOffset and respDataEndianness; Siemens S5 Ethernet gains value type sint; Fanuc CNC Ethernet (Gen1.3) gains register cnc_rdprgnum; Siemens S7CommPlus gains ReconnectInterval; AB Logix Serial gains readTimeout; Ignition Module gains publishStat.

GraphQL. The schema is additive: 125 types to 130, nothing removed. BrowseTask_CreateRegistersByFoldersSelection and Cart_AddItemsByFoldersSelection, both taking CreateRegistersByFoldersSelectionRequest, let a caller onboard tags by selecting folders rather than enumerating registers. UploadStatus gains Stats: UploadStats! and FailDetails: [UploadLineDetail], which report per-import counts and per-line failures; check Stats.Failed rather than trusting the absence of warnings. Smaller additions: BrowseTaskItem.DeviceID, Topic.Description, TableColumn.ReadOnly, TableColumn.AllowEmpty, FormatEnum values Call and CallResponse, ValueTypeEnum value RowFixedTable.

Digital Twins

Breaking: optional fields became required

Twelve input fields and one subscription argument went from optional to required. Nothing was removed, but any request that omitted these now fails GraphQL validation before it reaches the resolver.

Most of these were already semantically required: a delete without an ID could never succeed. What changes is where the failure happens: validation now rejects the document before execution, so the error shape differs. CreateModelRequest.Name and Assets are the two worth checking properly, since a model create that relied on a server-side default for either is now invalid.

New

Nested model attributes. DynamicAttributeType gains nestedModel, and CreateDynamicAttributeRequest, UpdateDynamicAttributeRequest and DynamicAttribute gain NestedModelID and NestedInstanceID. One model can now reference another instead of restating its attributes. Set one of the two, leave the other null. Nothing prevents a nesting cycle, and a cycle surfaces when the twin is resolved rather than when the attribute is saved.

Asset hierarchy. SetInstanceAssetHierarchy(input: SetInstanceAssetHierarchyRequest!) places instances in a hierarchy path with optional metadata, batch-first via an Items list. AttributeType gains AssetHierarchy, so it is now Regular | UNS | AssetHierarchy. An exhaustive match on AttributeType written against 4.0.x will meet a third member; check the default branch.

Instance source. Instance and CreateInstanceRequest gain Source: InstanceSource (local | external). There is no server-side filter by source; filter client-side.

Paging on attribute lists. ListStaticAttributeRequest and ListDynamicAttributeRequest gain Limit and Offset.

Counts and nested instances. Model gains InstanceCount, StaticAttributeCount, DynamicAttributeCount, ParameterCount and Instances. Instance gains the three attribute counts.

Playground. New PlaygroundMessages subscription for live topic inspection.

OPC UA

The schema grew from 62 types to 90, with 22 new operations and no breaking change.

Deprecated

GetNodes, UpdateNode and DeleteNode are deprecated in favour of GetNodesByRef, UpdateNodeByRef and DeleteNodeByRef, and UploadHierarchy in favour of UploadHierarchyWithResult. UpdateNode and DeleteNode are simultaneously extended: both gained originId, and DeleteNode gained expectedVersion, so callers who cannot move to the ByRef variants immediately still get versioning and origin tracking.

New

Hierarchy navigation and search. GetFolderItems, GetChildFolders, GetChildFoldersPage, GetFolderSkeleton and SearchNodes replace unpaged traversal with cursor-paged access. GetFolderItems returns a node's tag children only, and GetChildFolders returns its folder and device children; neither returns both.

Node versioning and unambiguous addressing. NodeItem gains Version, SyncState, SyncFailureReason, HasChildren and AccessControl. GetNodesByRef, UpdateNodeByRef and DeleteNodeByRef address nodes by reference rather than by an ID that can collide. DeleteNodeByRef and DeleteNode take expectedVersion for optimistic concurrency, and the mutations take originId for change attribution.

Staged bulk upload. StageHierarchy, CommitStagedHierarchy and CancelStagedHierarchy turn a bulk upload into a two-phase operation. UploadHierarchyWithResult returns applied counts where UploadHierarchy returned nothing.

Worker sync. SyncNodes, GetSyncStatus, GetCurrentSync and SubscribeSyncStatus. GetCurrentSync falls back to the most recent terminal sync, so a non-null result does not mean a sync is currently running; check the state.

Server settings and access control. GetServerSettings, UpdateServerSettings and BulkUpdateTagAccessControl.

Subscriptions. SubscribeNodeStateChanged, SubscribeTreeChanged and SubscribeSyncStatus.

Analytics

Analytics changes are stated against the operations in the LitmusEdge 4.0.x API documentation.

Breaking: global parameters removed

GetParameters and SetParameter no longer exist, and there are no global parameters in 4.4.x. Parameters now belong to individual processor instances: CreateProcessorInstanceRequest, UpdateProcessorInstanceRequest and ProcessorInstance carry Parameters. Global values that processors read and write are handled by variables (GetVariables, GetVariable, SetVariable). Action required: move each global parameter onto the processor instances that use it, or into a variable.

Deprecated

GetAnalyticsLogs and SubscribeToAnalyticsLogs are superseded by central logging (GET /logs/query) and scheduled for removal after 2027-09-01.

New

46 operations not in the 4.0.x documentation:

Applications

Breaking: five /apps routes became strict about the trailing slash

In 4.0.x both the slashed and unslashed form of these routes returned the list. In 4.4.x each route matches its path exactly, and the strictness runs in both directions.

Action required: do not apply a blanket rule. /apps/registries requires the absence of the trailing slash while the other four require its presence. The failure is a bare 404 page not found rather than an error payload, so a client that joins a base path without a separator fails silently.

New

GET /apps/overview/dashboard (query parameter cpuHistorySeconds) returns an application overview. GET /apps/registries/schemas gained schema.properties.region.minLength on the registry schema entries.

System

Breaking: the Configuration API rejects unknown request fields

The Configuration service now decodes request bodies strictly: an unknown field fails with 400 and failed to decode request body: json: unknown field "<name>". Template option marketplaceV2 (datastruct.MarketplaceOptionsV2) was removed, so a template download or create that sends it now fails this way. Use marketplace.

New: saved templates and snapshots

The Configuration API grew from 6 paths to 14, with 14 new operations and nothing removed. In 4.0.x only the session-based /config/template flow existed; templates are now first-class saved objects.

Apply and preview take a mode: legacy (the default), use or merge-apply; any other value is 400. use hard-resets each section in the template to exactly the template's contents, deleting what is not in it. merge-apply restarts most services, and a merge that would overwrite existing configuration is refused with 409 confirm_required unless confirm_overwrite is set. Applying a snapshot with no mode or legacy rolls back to it. parameters is an object keyed by section, not an array. DELETE /config/snapshots keeps the most recent snapshot and deletes the rest, oldest first, bounded per call; repeat while truncated is true. The most recent snapshot cannot be deleted.

The session-based apply (Step 3: Apply Uploaded Template) accepts optional name, description, encryptionKey, failFast and saveOnly; a non-empty name also saves the template, and saveOnly saves it without applying. {} still applies the whole uploaded template.

New: log query service

GET /logs/query and GET /logs/version are new. GET /logs/query returns entries, count and cursor; each entry carries timestamp, level, message, component and a fields object with the underlying journald metadata. Query parameters: limit (default 100), level, component (the exact service name, such as loopedge-dh), search, start and cursor. The response cursor is the RFC3339 timestamp of the newest entry in the page: send it back as start to tail forward, or as cursor to page backwards. cursor=0 is rejected with 400, while start=0 and unrecognised parameters are silently ignored, so confirm a filter applied by inspecting the entries.

New: log forwarding

Five Device Management v2 operations: GET and PUT /dm/v2/log-forwarding/config, GET /dm/v2/log-forwarding/status, POST /dm/v2/log-forwarding/start and POST /dm/v2/log-forwarding/stop.

Other changes

GET /dm/ifconfig accepts an optional show_bridges query parameter. High availability (/dm/v2/ha/role), static routes (/dm/v2/routes) and the rest of Device Management are unchanged. Cloud storage sync (/cloudstorage/*) moved from service version 0.14.0 to 0.16.1 with no API difference.

Unchanged

Dashboard, DataHub and Flows Manager have no API changes between 4.0.x and 4.4.x.

Upgrade checklist

1. Replace every hard-coded Integration ProviderID using the slug-to-UUID table, and accept a UUID wherever you store one. Do not resolve by the 4.0.x provider name.
2. Audit device and tag configurations for parity 3 or 4 on the fourteen drivers listed under DeviceHub.
3. Use the exact trailing-slash form for the five /apps routes.
4. Move Analytics global parameters onto processor instances or variables.
5. Confirm your Digital Twins mutations always send the now-required IDs, and that CreateModelRequest sends Name and Assets.
6. Remove marketplaceV2 and any other undocumented field from Configuration API requests.
7. Re-create IDEC Serial bit tags on the *_bit registers and check their addresses; drop accessType from Toyopuc CMP-Link Serial tags; re-express pollPLCProgramChecksum on AB CompactLogix Ethernet Advanced; re-type byte / dword tags on AB Logix Ethernet register R.
8. Set QoS 0 or 1 on AWS IoT Core instances that used QoS 2.
9. Set driver properties explicitly where you relied on a default that changed (requestTimeoutMs, KeepAlive, accessMode, DefaultDataFile, the Modbus Multi-Station timeouts).
10. Find exhaustive matches on AttributeType and handle the third member.
11. Switch CSV-import checks from UploadStatus.Warnings to Stats and FailDetails.
12. Plan the move from GetAnalyticsLogs / SubscribeToAnalyticsLogs to GET /logs/query before 2027-09-01, and to the OPC UA ByRef operations when convenient.