This article describes a typical day in the life of a simple and fictitious Lucid Field Device. The article aims to do this simply and in a more approachable form than the detail of the Lucid Protocol Specification. It is not going to cover how a Field Device comes into existence or is then managed by the Supervisory Application; we hope to write another article in the future which will deal with this.

Lucid is a protocol that defines how Field Devices (FDs) communicate with Supervisory Applications (SAs) via an MQTT broker. SAs are normally backend server applications which consume the data provided by the FDs and can make requests of the FDs. FDs are normally small devices installed within a company’s estate to monitor aspects of operation. They are comparable to today’s small IIoT or IoT devices.

The article has some simple JSON listings in to show messages sent over Lucid. These can be ignored without losing the gist of the article; they are provided to tie together with the examples on the Lucid website and provide further examples for the Lucid Protocol Specification.

I read the news today, oh boy – Our device’s backstory

So, to give some context to the day we will describe, here is some information about the simple device we are going to use.

• The device is small and powered by a battery, it is therefore trying to use as little power as possible to maximise the time before a battery change is required.
• The device can communicate with the MQTT server via an inbuilt cellular modem, but it only switches this on when it must, so that its power consumption is kept as low as possible.
• The device is monitoring liquid in a tank, it does this via:
  • A level sensor which provides a reading of the liquid depth. In Lucid this will be an analogue input.
  • A float switch which triggers if the level gets too high. In Lucid this will be a digital input.

The simple picture below gives an overview of what the situation may look like.

The user wants to keep record of the tank level throughout the day at a 10-minute interval for operational reasons. They also want to know quickly if the tank goes below 10% full or the float switch is triggered which will happen just before the liquid starts overflowing above the 100% level.

The device has already been set up and is working. It has previously published the following messages to the MQTT broker:

• A Last Will and Testament message
• A Status message
• An optional Profile message
• A configuration message

These messages are all types of messages defined in Lucid and are published as “retained” messages to the broker. This means that, even after being read by SAs which are currently subscribing, they are retained on the broker so that any new SAs can still read them and learn about the state of the device.

A simple example of the configuration message for our device may be as follows (we are including the configuration message example here because it, or at least part of it, will come into play when we discuss a configuration change. You can find examples of the other messages with the Protocol Specification):

{
  "cVer": 123,
  "full": true,

  "device": [
    {
      "nid": "RES01",
      "loc": "Ambleside",
      "ownr": "WR",
      "asst": "ASST123",
      "name": "Ambleside Main Tank",
      "serl": "1234567",
      "scan": true
    }
  ],

  "channel": [
    {
      "num": 1,
      "name": "Main IP Channel",
      "conn": "O2",
    }
  ],

  "connection": [
    {
      "num": 1,
      "name": "Broker 1",
      "channel": 1,
      "prot": 1,
      "type": 1,
      "net": "123.456.789.012:20100",
      "retries": 2,
      "backoff": 120
    }
  ],

  "connectionSchedule": [
    {
      "num": 1,
      "mode": 2,
      "start": 0,
      "repeat": 86400000
    }
  ],

  "deviceLink": [
    {
      "num": 1,
      "name": "Onboard IO"
    }
  ],

  "point": [
    {
      "deviceLink": 1,
      "num": 0,
      "type": "bi",
      "name": "Float Switch",
      "className": "Switch",
      "scan": true,
    },
    {
      "deviceLink": 1,
      "num": 0,
      "type": "ai",
      "name": "Tank Level",
      "className": "Level",
      "scan": true,
      "logRate": 600000,
      "logOffset": 0
    }
  ],

  "analogue": [
    {
      "parent": 0,
      "parentType": "ai",
      "rawsc1": 0,
      "rawsc2": 32768,
      "engsc1": 0.0,
      "engsc2": 100.0,
      "min": 0.0,
      "max": 100.0,
      "units": "%",
    }
  ],

  "binary": [
    {
      "parent": 0,
      "parentType": "bi",
      "bits": 1,
      "state0Action": 2,
      "state0Pers": 60000,
      "state1Action": 2,
      "state1Pers": 1000
    }
  ],

  "analogueLimit": [
    {
      "parent": 0,
      "parentType": "ai",
      "num": 0,
      "name": "Low",
      "action": 2,
      "dirctn": 1,
      "value": 10.0,
      "hyst": 1.0,
      "enter": 10000,
    }
  ],
}

A JSON configuration message representing our example device’s configuration

Further descriptions of all the messages presented in this article can be found on the example page of the Lucid website.

So, let’s get into what happens on the day.

I saw the photograph – Taking readings

During the day the device will normally be asleep trying to preserve as much power as it can. At intervals throughout the day it will wake to take readings and update the values of the points, when doing this it will also apply any necessary checks to the point to see if an event must be raised and / or the broker contacted. These intervals are normally set by the device but can be specified through the “Scan Rate” setting of a point by an SA. As a minimum (and even if that “Scan Rate” setting is larger than 10 minutes) our device will be waking every 10 minutes to read the analogue value, as the configuration shows that AI0 is to be logged at 600000 ms, or 10 minutes.

Often a digital point may be continuously monitored at no power cost and changes will cause the device to wake and record the new value. In other cases, a sensor may require power to be applied to some external circuit, which is then left to settle before a reading can be taken. In any case, the device will spend an amount of its day waking, taking values, checking them and recording them.

He didn’t notice that the lights had changed – Handling an alarm

When certain things happen on the device, events can be raised. For us, the events of interest would be a change of state of the digital signifying an overflow, and the value of the analogue passing below the 10% analogue limit. These events in turn, have actions associated with them; the actions can be: do nothing, raise an event, or raise an event and contact the broker. This last option (action 2) is equivalent to an alarm as it causes the event to be advertised to the broker as soon as possible.

If we assume for example that a digital reading of 1 means the float switch has been triggered, then as you can see from the configuration (state1Pers:1000) the digital state will change if the switch remains triggered for 1 second. It will then perform the associated action from the configuration (state1Action:2) which is to raise an event and contact the broker. On contacting the broker, the device will publish a status message like the one shown below.

{
	"pRef": "ACME_Device1_1-00",
	"cVer": 123,
	"time": 1728590330263
}

An example JSON status message

It will then automatically send on its current data values and stored events in a message like that shown below. This includes the fact that the float switch has been triggered.

{
	"p":
	[
		{
			"ai": 0,
			"v": [12],
			"q": [0],
			"ts": [1728590431263],
			"r": [1]
		},
		{
			"bi": 0,
			"v": [1, 1],
			"ts": [1728590431263, 1728590430263],
			"r": [1, 3]
		}
	]
}

 JSON data message showing the current point values and the digital state change event

 Likewise, if whilst reading the analogue level, the level causes a change of state to “Low”, then the action of 2 will cause the device to raise an event and contact the broker immediately. Once again, a status message, like that shown above, will be sent to the broker, followed by a data message like that shown below.

{
	"p":
	[
		{
			"ai": 0,
			"v": [8, 8],
			"q": [0, 0],
			"ts": [1728590531263, 1728590530263],
			"r": [1, 3]
		},
		{
			"bi": 0,
			"v": [1],
			"ts": [1728590531263],
			"r": [1]
		}
	]
}

 JSON data message showing the current point values and the analogue state change event caused after transgressing the associated analogue limit

Woke up, fell out of bed – A daily contact

During the day, events with action “1”, gathered by the Field Device, are stored only at the device. The logged values of data points, such as our analogue tank level, are also recorded as events. They are given a different “reason” code to reflect the fact that they are logged values rather than alarms.

If an event occurs which has an action of “2” (i.e. requires the broker to be contacted, also known as an alarm), then during that contact the Field Device will publish the event which caused the contact, all other stored events, and the current value of all points.

However, it is quite possible that no alarms may occur during any given day, and the device will continue to build up a store of events which do not require contact and therefore are not sent to the broker and made available to the SAs. To ensure events can be made available to SAs in a regular manner, Lucid uses scheduled connections. These are set to occur at regular intervals and cause the Field Device to contact the broker and publish the current values of points and any stored events.

In our example the device is scheduled to call in once per day, at midnight. At that time every day the device wakes up, connects to the mobile network and then to the broker. It then sends a status message and a data message or messages, containing the current values and events. The status message would look very much like the example shown above, whilst the data message would look something like the example below.

{
	"p":
	[
		{
			"ai": 0,
			"v": [8],
			"q": [0],
			"ts": [1728590631263],
			"r": [1]
		},
		{
			"bi": 0,
			"v": [1],
			"ts": [1728590631263],
			"r": [1]
		}
		{
			"ai": 0,
			"t":
			{
				"s": 1729710600000,
				"i": 600000
			}
			"v": [ 23.0, 23.1, 23.6, ... 19.2, 18.1, 15.1 ]
		}
	]
}

A JSON message showing the data that might be sent on a daily call

This example imagines there are no logged events and just shows the logged values of the analogue point and the current values of all points.

They had to count them all – Handling a config change

Whenever the Field Device connects to the broker, apart from sending information it has, it can also check for information that an SA has published to it to pick up. These can be things like requests for specific elements of data or requests to change configuration. In our example we will consider the situation where the user wishes to change the “Low” limit on the analogue level from 10% to 15%.

To do this the SA will have checked the device profile for the Field Device to ensure that it supports configuration download. If it does, then the SA will publish a “partial configuration change” message like that given below to the “down configuration” topic on the broker. Of course, the Field Device may not be connected at that time and so the message will sit on the MQTT broker awaiting pickup by the Field Device.

{
  "cVer": 124,
  "full": false,
  "source": "3cad5905-ea52-4d22-b862-a32fefe4e01e",

  "analogueLimit": [
    {
      "parent": 0,
      "parentType": "ai",
      "num": 0,
      "name": "Low",
      "action": 2,
      "dirctn": 1,
      "value": 15.0,
      "hyst": 1.0,
      "enter": 10000,
    }
  ],
}

The JSON message for a partial configuration change to the analogue limit

Eventually, either because of a scheduled connection or an alarm in the device, the Field Device will connect to the broker. As the Field Device supports configuration download, it will already be subscribed to the configuration download topic, and on connection the broker will send the message received from the SA to the Field Device.

Having received the message, the Field Device checks that the message is valid and, assuming it is, applies the configuration. It also increases its config version by one and publishes a status message, which includes that configuration version field, to show that the configuration change request has been applied. The Field Device will also republish its new configuration to the broker so that all SAs have access to the Field Devices latest configuration and can update their records accordingly.

The status message published would look like that below.

{
	"pRef": "ACME_Device1_1-00",
	"cVer": 124,
	"time": 1728590831263
}

JSON showing the updated status message after accepting a new configuration

The configuration message is not repeated in entirety here but would be the same as the original message with the configuration version and analogue limit objects changed as shown in the message fragment below.

{
  "cVer": 124,
  "full": true,

  "device": [
    {
      "nid": "RES01",

... data is the same

      "state0Pers": 60000,
      "state1Action": 2,
      "state1Pers": 1000
    }
  ],

  "analogueLimit": [
    {
      "parent": 0,
      "parentType": "ai",
      "num": 0,
      "name": "Low",
      "action": 2,
      "dirctn": 1,
      "value": 15.0,
      "hyst": 1.0,
      "enter": 10000,
    }
  ],
}

JSON excepts showing the updated parts of configuration after a change in the analogue alert level

As the configuration is applied to the device the state of the analogue level point will be re-evaluated. This is done without considering enter and exit time persistence. If the state has changed, then depending upon the action associated with that change, an event may be raised. Assuming the Field Device is still connected then that event would be published to the broker.

In our example let’s assume that the analogue level was actually 13% at the time the configuration change is applied. This would immediately mean the “Low” analogue limit is breached and the Field Device would raise an event and contact the broker. The new data message published by the Field Device would look like the following:

{
	"p":
	[
		{
			"ai": 0,
			"v": [13],
			"q": [0],
			"ts": [1728590831263],
			"r": [3]
		},
	]
}

JSON message representing a new data event at 13%

After the message is sent, the Field Device will drop the connection, and the day will continue as normal.

I’d love to turn you on – Summary

In this article we have been through a normal day for an example device. There is more information related to this on the example pages of the Lucid website. You may not have read the news today or found out how many holes fit in the Albert Hall, but you have hopefully seen how Lucid enables a simple field device to perform its normal daily chores. We hope we have done enough to turn you on to the simplicity and advantages of Lucid.

Mark Davison (Terzo Digital) and Dave Howarth (NWL)

March 2025