ezeio2:apiref:sparkplugb

SparkplugB MQTT service

SparkplugB MQTT service

The eze System MQTT service publishes data from your ezeio controllers using the Sparkplug B specification. Any Sparkplug B host application can connect to it. Examples are the Cirrus Link MQTT Engine module for Ignition, or your own client built on one of the open source Sparkplug libraries.

You log in with the same API credentials you use for the eze.io API. Each set of credentials gives access only to the devices in the group it belongs to. Devices belonging to other customers are never visible.

Please note that using this service requires some familiarity with MQTT and Sparkplug B. Links to the specification and other resources are at the end of this section.

Creating API credentials

API credentials are created for a group in eze.io under Groups → Group Settings → Manage API Keys. The credentials consist of a Key ID (a number) and a 24 character Key.

When creating or editing a key, note the following settings:

Inherit to subgroups	When checked, the key gives access to devices in the group and in all of its subgroups. When unchecked, only devices placed directly in the group are visible.
Privileges → Control	Required only if your host application will write values to the ezeio (see “Sending commands to the ezeio (DCMD)” below). Reading data does not require it.
Key expires	Once a key has expired, it can no longer log in to the MQTT service.

A new key can take up to 10 minutes to become active on the MQTT service. Changes to an existing key can also take a few minutes to take effect.

Please keep the API credentials secret. Anyone holding them can read the data from your devices and potentially send commands to your devices.

Connection settings

Server	mqtt.eze.io
Port	8883
Protocol	MQTT over TLS (MQTTS)
Username	apisession-<Key ID> (for example: apisession-10123)
Password	the 24 character Key
Client ID	any value, but it must be unique for each connection

The server uses a standard publicly trusted certificate, so no special certificate needs to be installed on the client. Unencrypted connections on port 1883 are not available.

In the Cirrus Link MQTT Engine module for Ignition, add a server under MQTT Engine → Settings → Servers, enter the URL as ssl://mqtt.eze.io:8883 and fill in the username and password as above.

Topics and naming

The service follows the standard Sparkplug B topic layout:

spBv1.0/<Group ID>/<Message type>/ezesys/<Serial>

Group ID	The numeric ID of the eze.io group the device belongs to. With “Inherit to subgroups” enabled, devices in different subgroups appear under different Group IDs.
Edge Node	Always “ezesys”
Device	The ezeio serial number, without the dash (for example BBF240)

To receive data, subscribe to:

spBv1.0/#	all devices the key has access to
spBv1.0/<Group ID>/#	only the devices in one group

The MQTT Engine default subscription (spBv1.0/#) works as is. You may also use the Group ID Filter in MQTT Engine to limit which groups are shown.

Only subscribe to topics in the Sparkplug namespace (spBv1.0/…) and to groups the key has access to. The server refuses any other subscription, and some clients (including MQTT Engine) respond to a refused subscription by disconnecting and reconnecting repeatedly.

What you will receive

When your application subscribes, the service sends an NBIRTH for each group and a DBIRTH for each device that is currently online. After that, DDATA messages are sent as the ezeio reports new values. When an ezeio goes offline a DDEATH is sent, and when it comes back a new DBIRTH follows.

Each device carries the following metrics:

Configured fields

Each field configured on the ezeio, named with its two digit field number followed by the field name (or asset tag, if one is set). For example: 01:Battery Voltage. Units, number of decimals and min/max limits are included where they are configured.

exStatus/…

System status of the ezeio, such as signal strength, network link state, GPS position, uptime, active alarm count, and the analog inputs and outputs. exStatus/SystemName and exStatus/SystemNotes hold the device name and notes from eze.io.

Event/…

Details of alarms and restores. These are only sent when alarms are set up to report to Sparkplug, as described in “Report by exception” below.

Data is only published while a host application is connected. The service does not store messages for clients that are offline.

Your application can request a fresh set of NBIRTH and DBIRTH messages at any time by sending the standard Node Control/Rebirth command (NCMD) to spBv1.0/<Group ID>/NCMD/ezesys. Host applications may also publish their own STATE messages (spBv1.0/STATE/<host id>) as described in the specification.

Report by exception (alarms)

IMPORTANT: Alarms and other exceptions are NOT sent to Sparkplug automatically. Report by exception must be set up in eze.io for each alarm you want to receive.

To set it up:

1. In the group's Destination Lists, create a list that contains the "Sparkplug B broker" destination.
2. On the device's configuration page, set up the Alarm.
3. Add an Alarm action of type "Send Message", and select the destination list from step 1.
4. Add a Restore action of type "Send Message" to the same destination list.

Step 4 is required. An alarm and its restore are two separate messages. Without a Restore action, your host application is told when the alarm occurs, but is never told that it has cleared.

Each alarm and restore is sent to your host application as a DDATA message for the device, with the details in the Event/… metrics:

Event/type	ALARM, REALARM or RESTORE
Event/subject	The message subject
Event/message	The message body
Event/text	The alarm text
Event/eventid	The event number
Event/source, Event/sourceid, Event/sourceindex, Event/sourcename	What raised the event
Event/actionname	The alarm action that sent the message

The timestamp is the time the ezeio recorded the event. If the device has not yet sent its DBIRTH in the current session when an alarm occurs, the event details are included in the DBIRTH instead of a separate DDATA.

A destination list that contains only the Sparkplug B broker destination does not count against message flood limits. If the Sparkplug B broker destination is not available on your account, please contact eze System.

Sending commands to the ezeio (DCMD)

DCMD is the way to send commands from a Sparkplug B client into the eze system. A host application writes a value to an ezeio field by publishing a Sparkplug B DCMD message to:

spBv1.0/<Group ID>/DCMD/ezesys/<Serial>

The DCMD payload holds one or more metrics, each with the new value. Identify each metric by the alias or the name given in the device's DBIRTH (for example 05:Pump Setpoint). In Ignition, writing to a writable tag under MQTT Engine sends the DCMD for you.

A command is only carried out when:

The API key used to log in has the Control privilege. DCMD messages from any other key are refused by the server.
The field is writable. Fields marked read only in the DBIRTH cannot be written.
The value is within the field's min/max limits, if limits are configured.

The value is passed to the ezeio, and the new value appears in the next DDATA from the device. If the ezeio is offline when the command arrives, the value is held and sent to the device when it reconnects (requires recent firmware). Every command is logged with the Key ID that sent it.

DCMD is the only way to write values to devices. The node-level NCMD message is used only for the Rebirth request described above.

Troubleshooting

Connection refused, not authorized

Check the username format (apisession- followed by the Key ID) and the Key. Make sure the key has not expired. A newly created key can take up to 10 minutes to become active.

Connected, but no devices appear

Check that the devices are in the key's group, or that “Inherit to subgroups” is enabled if they are in a subgroup. Check that the devices are online in eze.io.

Alarms are not received

Check that the alarm has a “Send Message” action to a destination list containing the Sparkplug B broker destination. Check also that the Restore action does the same, or the alarm will never be shown as cleared.

Writes to a tag have no effect

Check that the API key has the Control privilege, and that the field is not read only.

The connection drops and reconnects every few seconds

Check the subscriptions in your client. A subscription outside the Sparkplug namespace, or to a group the key does not have access to, will be refused.