Litmus Unify

10 min

The Litmus Unify connector connects Litmus Edge (LE) to Litmus Unify through the Litmus Unify MQTT broker. It publishes LE data to Litmus Unify, under the namespace hierarchy that Litmus Unify assigns to the edge. It can also subscribe to Litmus Unify topics and publish the data to a local topic.

The connector registers with Litmus Unify by using a token. When you save the connector, it exchanges the token for the broker address, credentials, and namespace hierarchy, and then publishes through that broker.

Supported communication

Outbound (publish data from LE to Litmus Unify): Yes

Inbound (subscribe to data from Litmus Unify and publish it to a local topic): Yes

Compatibility

The connector supports MQTT protocol versions 3.1.0 and 3.1.1.

Registration

Registration runs when you save the connector:

The connector exchanges the Litmus Unify Token once with Litmus Unify.

Litmus Unify returns the broker address, credentials, CA certificate, client certificate, and namespace hierarchy for this edge.

The connector stores these values in its configuration, fills in Connection Type, Port, CA Certificate, Unify Client ID, and Unify Hierarchy, and clears the token.

When the connector restarts, it reuses the stored values and doesn't contact Litmus Unify again. To register again, for example after you move the edge in Litmus Unify, enter a new token and save the connector.

The connector sends the registration request over HTTPS to the Litmus Unify endpoint named in the token. It doesn't verify that endpoint's certificate, because Litmus Unify deployments often use a private or self-signed CA. Skip Certificate Verification and CA Certificate apply only to the broker connection.

Connector configuration

Field	Type	Description	Required	Default
Name	String	Name of this connector instance.	Yes	-
Litmus Unify Token	String (Secret)	Registration token from Litmus Unify. The connector exchanges it once, when you save the connector, and then clears it. Enter a new token to register again.	Yes, to register	-
Skip Certificate Verification	Boolean	Skip verification of the broker's certificate. Use it only for test brokers with a self-signed certificate.	No	Disabled
Connection Type	Dropdown	Broker transport. mqtt and ws are unencrypted. mqtts and wss use TLS. Registration sets this field to the transport that Litmus Unify reports. You can change it afterward.	No	mqtt
Port	Integer	Broker port for the selected transport. Registration sets this field. A value of 0 keeps the registered port. Change it only if the broker serves the selected transport on another port. Range is 0 to 65535.	No	0
WebSocket Path	String	URL path that the broker serves MQTT on, such as /mqtt. The path must start with /. Applies only when Connection Type is ws or wss.	Conditional	-
CA Certificate	String (Secret)	PEM CA certificate that the connector uses to verify the broker. Registration sets this field to the CA that Litmus Unify supplies. Replace it to verify against a different CA, or clear it to use the supplied CA or the system certificate store. Applies only when Connection Type is mqtts or wss.	No	-
Unify Client ID	String	Identifier that Litmus Unify assigned to this edge at registration. Filled in automatically.	No	-
Unify Hierarchy	String	Slash-separated namespace levels that this edge publishes under, such as site/area/line. Filled in automatically at registration. Read-only.	No	-
Parallel Publish Count	Integer	Number of messages the connector publishes at the same time. Higher values increase throughput and resource usage. Range is 1 to 4000.	No	100

Advanced parameters

These parameters appear in the advanced section of the connector form.

Field	Type	Description	Required	Default
Connection Timeout	Integer	Maximum time in seconds for one connection attempt. Over ws and wss, this also limits the WebSocket handshake. Range is 1 to 60.	No	30
Ping Timeout	Integer	Time in seconds to wait for the broker's keep-alive reply before the connector treats the connection as lost. The connector checks every five seconds, so it rounds the value up to the next multiple of 5. Range is 5 to 60.	No	10
Reconnect Interval	Integer	Time in seconds to wait after a lost or failed connection before the next attempt. Range is 1 to 60.	No	5
Publish Wait Timeout	Integer	Maximum time in seconds for a single publish before the connector gives up on it. Range is 1 to 60.	No	10

Additional attributes

Field	Type	Description	Required	Default
Throttling limit	Integer	Maximum outbound messages per second. A value of 0 disables throttling. Minimum is 0.	No	0
Persistent storage	Boolean	Store outbound queue messages on disk. If the connection drops or the system loses power, the messages are retained and sent once the connection is restored.	No	Enabled
Persistent storage size limit	Integer	Maximum disk space in GB used for persisted data. Applies only when Persistent storage is enabled. Minimum is 1.	Conditional	1
Queue Mode	Dropdown	Order in which the connector sends buffered messages. fifo sends the earliest message first. lifo sends the latest message first. Applies only when Persistent storage is enabled.	No	lifo
Enable Logging	Boolean	Write connection and publish error messages to the connector log. Logging can increase CPU usage, so enable it only for debugging.	No	Disabled

Topic parameters

Outbound and inbound topics have one extra parameter.

Field	Type	Description	Default
Qos	Dropdown	MQTT quality of service level for the topic: default, 0, 1, or 2.	default

Topic addressing

When Litmus Unify assigns a hierarchy, the connector builds each outbound topic from the payload, not from the topic's Remote Data Topic. It matches each level in Unify Hierarchy against the keys in the payload's metadata object, without regard to case:

A key with the same name as the level supplies the value. For example, site matches the level site.

A key that ends in the level name after a -, _, or . separator also matches. For example, litmus-unify-site and unify_site match the level site, but campsite doesn't.

For example, with the hierarchy site/area/line and this payload, the connector publishes to plant1/assembly/l3:

{"metadata": {"litmus-unify-site": "plant1", "area": "assembly", "unify_line": "l3"}, "value": 42}

The connector rejects a message, and retries it through persistent storage, in the following cases:

The payload doesn't have a value for every level in the hierarchy.

Two matching keys have different values.

A value contains /, +, #, whitespace, or another character that isn't allowed in a topic name.

When no hierarchy is assigned, the connector publishes to the topic's Remote Data Topic as entered.

Transport and proxies

ws and wss use the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables. mqtt and mqtts ignore them and use only a SOCKS all_proxy setting. On an LE system with an HTTP proxy, the broker can therefore be reachable over one transport and not the other.

For mutual TLS, the connector uses the client certificate and key that Litmus Unify returns at registration. The form has no fields for them.

Connector status

If the Litmus Unify user account linked to the token is disabled or deleted, the connector status changes to Failed. When the account is enabled again, the status returns to Connected without any action in LE.

Add a ConnectorAdd a Connector

Manage ConnectorsManage Connectors

Organize Device and Tag Data by Using MetadataOrganize Device and Tag Data by Using Metadata