Page History

MQTT Engine provides a configuration section to the Ignition Gateway and this can be seen in the left side bar of the Ignition Gateway web UI.Image Added

Image Removed

The configuration options for each of the three tabs - General, Servers, Sets, and Namespaces - are detailed below.

...

The configuration sections available are Main, Command Settings, Alarm Settings, General Configuration, Miscellaneous and Advanced.

Anchor

...

GeneralConfiguration

...

GeneralConfiguration

General -

...

General Configuration

Image Added

...

Image Removed

• Enable the MQTT EngineEnabled

  • Whether or not the MQTT Engine module is enabled and connecting to configured MQTT Servers.

...

• Block Node Commands
  • Whether or not to block outgoing commands from MQTT Engine to Edge Nodes. This is true by default and provides a security mechanism for preventing accidental outgoing commands from MQTT Engine.
• Block Device Commands
  
  • Whether or not to block outgoing commands from MQTT Engine to Devices. This is true by default and provides a security mechanism for preventing accidental outgoing commands from MQTT Engine.
• Include Security Context
  • Whether or not to include the Security Context in write command to be validated at the Edge Node. This is deselected by default.
  • Reference the Ignition MQTT Security Context HowTo for additional details on how to use this configuration.
• Security Context Hashing Algorithm
  • Hashing algorithm to use when encrypting the Security Context. Options include SHA_1, SHA_224, SHA_256, SHA_384 and SHA_512
• Change Password?
  • Checkbox to allow existing password to be changed 
• Password
  • Password to be used when encrypting the Security Context

...

• Enable Alarm Event Publishing
  • When enabled and alarms are enabled on tags, MQTT Engine will receive the contents of the triggered alarms at the Edge and creates an alarm event where MQTT Engine is installed.
  • Review the Alarm Event Propagation document for system configuration details including the changes needed to the data/ignition.conf file and MQTT Transmission

Image Removed

• Alarm Event Enable

  • When enabled and alarms are enabled on tags, MQTT Engine will receive the contents of the triggered alarms at the Edge and creates an alarm event where MQTT Engine is installed.
    

• Alarm Display Path Type - added in 4.0.30
  • The format to use for the Alarm Display Path if the Display Path property is not configured at the Edge. If the Display Path is configured, it will be used by Engine.
    • EDGE - Sets the display path as the Edge tag path
      • Edge Nodes/Tag1/MyAlarm
    • ENGINE - Sets the display path as the Engine tag path which include the Sparkplug descriptors
      • Edge Nodes/GroupID/EdgeNodeID/DeviceID/Tag1/MyAlarm
    • IDS_AND_EDGE - Sets the display path to include the Sparkplug descriptors and the Edge tag path
      • GroupID/EdgeNodeID/DeviceID/Edge Nodes/Tag1/MyAlarm
• H2 Database Directory - added in 4.0.25
  • Directory to store the H2 Database in.
  • The AlarmStore is required to maintain the alarm events across MQTT Engine module disable/enable, module restart, or power loss.
  • The default base path for Linux is ~yourIgnitionInstance\data\modules and the database will be included in the Ignition GWBK
  • The default location for Windows Linux is ~yourIgnitionInstance\user-lib\modules and the database will not be included in the Ignition GWBK
  • The database file will be created in this directory under the base path com.cirrus-link\com.cirruslink.mqtt.engine.gateway\h2
• H2 Database Port
  • TCP Port to connect to internal H2 Database

...

Image Removed

...

• Whether or not to block incoming properties from modifying MQTT Engine tag properties. This is false by default so property changes will be applied if not included in the Filtered Property list under 'Advanced'.

...

• Whether or not to write historical change events directly to the Historian (if history is enabled on a Tag) instead of updating the live Tag value.
• Note: Store and Forward does not guarantee all data is stored and forwarded. There are some edge cases that are not currently handled with regard to data loss in the event of connection failures related to MQTT keep alive timeouts. This window of potential missed data can be reduced by decreasing MQTT Transmission and MQTT Engine configurable keep alive timeouts.

...

• H2 Database Directory 
  • Directory to store the H2 Database in.
  • The AlarmStore is required to maintain the alarm events across MQTT Engine module disable/enable, module restart, or power loss.
  • The default base path for Linux is ~yourIgnitionInstance\data\modules and the database will be included in the Ignition GWBK
  • The default location for Windows Linux is ~yourIgnitionInstance\user-lib\modules and the database will not be included in the Ignition GWBK
  • The database file will be created in this directory under the base path com.cirrus-link\com.cirruslink.mqtt.engine.gateway\h2
• H2 Database Port
  • TCP Port to connect to internal H2 Database

Anchor
GeneralMiscellaneous GeneralMiscellaneous

General - Miscellaneous

Image Added

• Block Property Changes
  • Whether or not to block incoming properties from modifying MQTT Engine tag properties. This is false by default so property changes will be applied if not included in the Filtered Property list under 'Advanced'.
• Store Historical Events
  • Whether or not to write historical change events directly to the Historian (if history is enabled on a Tag) instead of updating the live Tag value.
  • Note: Store and Forward does not guarantee all data is stored and forwarded. There are some edge cases that are not currently handled with regard to data loss in the event of connection failures related to MQTT keep alive timeouts. This window of potential missed data can be reduced by decreasing MQTT Transmission and MQTT Engine configurable keep alive timeouts.
• Reordering Timeout
  • Sets the Sparkplug Reordering Timeout in milliseconds.

  • When enabled (greater than zero), MQTT Engine will wait up to the specified number of milliseconds after receiving an out of order message for the expected message to arrive before considering it a failure.

Anchor
GeneralAdvanced GeneralAdvanced

General - Advanced

Image Added

• Enable Tag Latching
  • Whether or not to enable Tag latching to synchronize MQTT Tag updates with events in Ignition.

• Latch Timeout

  • The amount of time to wait for a Tag latch to be released before timing out.

• Latch Tags

  • A semicolon separated list comma separated list of Trigger Tag and Latch Tag pairs.
• Filtered Properties
  • A semicolon delimited list of Tag properties to filter/ignore on received Tags.
  • By default

When enabled (greater than zero), MQTT Engine will wait up to the specified number of milliseconds after receiving an out of order message for the expected message to arrive before considering it a failure.

...

Image Removed

• Enable Tag Latching
  • Whether or not to enable Tag latching to synchronize MQTT Tag updates with events in Ignition.

• Latch Timeout

  • The amount of time to wait for a Tag latch to be released before timing out.

• Latch Tags

  • A semicolon separated list comma separated list of Trigger Tag and Latch Tag pairs.
• Filtered Properties
  • A semicolon delimited list of Tag properties to filter/ignore on received Tags.
  • By default the filtered properties list contains:  accessRights;clampMode;deadband;deadbandMode;formatString;historicalDeadband;historicalDeadbandMode;historicalDeadbandStyle;historyEnabled;historyMaxAge;historyMaxAgeUnits;historyProvider;historySampleRate;historySampleRateUnits;historyTagGroup;historyTimeDeadband;historyTimeDeadbandUnits;opcItemPath;opcServer;permissionModel;rawHigh;rawLow;sampleMode;scaleFactor;scaleMode;scaledHigh;scaledLow;tagGroup;valueSource;expression;expressionType;ConfiguredTagPath;eventScripts;readPermissions;writePermissions;eventScripts;parentEnabled;sourceTagPath
  • Tag properties are only published from Transmission if different from the default Ignition tag property settings and are only published in BIRTH messages.

• Enable BD Sequence Validation

  • Whether or not to enable BIRTH/DEATH sequence number validation (required by Sparkplug specification).
• Enable Metric Timestamp Validation
  • Enables/disables validation of metric timestamps against the current tag value timestamp before writing. If enabled, tag writes will only occur if the new incoming metric timestamp is newer than the current tag timestamp.
• Custom Properties
  • Do not use unless instructed to by Cirrus Link personnel.
• Primary Host Control Tags
  • A semicolon separated list of comma separated Primary Host Control tags triples (e.g., tagPath1,tagDataType1,tagValue1;tagPath2,tagDataType2,tagValue2). Review MQTT Engine Primary Host Control for additional information.
  • Supported tag DataTypes are: Byte, Short, Integer, Long, Float, Double, Boolean and String
• Rebirth Debounce Delay - added in release 4.0.23Delay
  • The amount of time in milliseconds before another Sparkplug Rebirth request can be sent to an Edge Node
  • Releases prior to 4.0.23 have a hardcoded 5 second Rebirth Debounce Delay.
  Use Cirrus Link Encoder - added in release 4
  • .
  0.30
  • Whether or not to use the Cirrus Link encoder for Sparkplug payloads. This property is enabled by default.
  • This is not Sparkplug compliant but will properly encode Ignition properties such as Dataset, Document and Array types.

Anchor
Servers Servers

Servers

...

• Connected
• Disconnected
• Not Licensed

Image RemovedImage Added

The configuration sections available are Main, TLS, Advanced Server Settings, Certificate Configuration and Advanced Legacy State

Anchor

...

ServerSettingsServerSettings

...

ServerSettingsServerSettings

Server Settings -

...

Server Settings

Image Added

• Name
  • This is the friendly name of the MQTT Server used to easily identify it.
• Enabled
  • Whether or not connections to this MQTT Server are enabled.
• URL
  • This is the URL of the MQTT server.  Its format is as follows: [protocol]://[location]:[port].  Each of these are shown below.
    • protocol - Either tcp or ssl
    • location - The server location.  e.g. localhost, myserver.chariot.io, mydomain.com, etc
    • port - The port the MQTT Server is listening on.  Generally this is 1883 if using TCP or 8883 if using SSL
• Server Set
  • The Server Set this MQTT Server is associated with
• Username
  • Optional MQTT username to use in the MQTT connect packet.  This is required if the MQTT Server to connect to requires it.
• Password
  • Optional MQTT password to use in the MQTT connect packet.  This is required if the MQTT Server to connect to requires it.

...

• CA Certification File
  • CA Certification file currently in use.
• Client Certification File
  • Client Certification file currently in use.
• Client Private Key File
  • Client Private Key file currently in use
• Password
  • Optional password associated with the certificate's private key.
• Hostname Verification
  • Enable TLS Hostname Verification. This is true by default.
• TLS ALPN Extensions
  
  • Optional TLS ALPN Extensions, such as http/1.1, to use with this connection if supported by the MQTT Server.

...

...

• The maximum interval in seconds (5-65,535) between any two MQTT protocol control packets sent by the client to the server.
• Minimum Keep Alive for MQTT Engine is 5.
• If the client is idle and has no control packets to send, it will send PINGREQ protocol packet and the server is required to respond with a PINGRESP packet. If no response is received from the server within 1.5 times the Keep Alive, the client will close the connection.

• If the server does not receive, at minimum, a PINGREQ message from a client within 1.5 times the Keep Alive, it will terminate the connection and send the client's LWT message if defined.

• For MQTT Engine with Primary Host enabled, this is a message of format spBv1.0/STATE/primary_host_id with a payload {"online" : false, "timestamp" : 1668114759262}

• For MQTT Engine with Legacy Primary Host enabled, this is a message of format STATE/primary_host_id with a payload of OFFLINE

Anchor
ServerSettingsCertificateConfiguration ServerSettingsCertificateConfiguration

Server Settings - Certificate Configuration

Image Added

• TLS CA Certification File
  • CA Certification file currently in use.
• Client Certification File
  • Client Certification file currently in use.
• Client Private Key File
  • Client Private Key file currently in use
• Password
  • Optional password associated with the certificate's private key.
• Hostname Verification
  • Enable TLS Hostname Verification. This is true by default.
• TLS ALPN Extensions
  
  • Optional TLS ALPN Extensions, such as http/1.1, to use with this connection if supported by the MQTT Server.

Anchor
ServerSettingsAdvanced ServerSettingsAdvanced

Server Settings - Advanced

Image Added

• Client ID
  • Optional MQTT client ID to use.  If specified this will be used in the MQTT Engine connect packet when connecting to the server.  If left blank, a random client ID will be created of the form 'ME-xxxxxxxxx-xxxx-xxxx'.

    
    

    Warning
    Caution: MQTT Clients IDs must be unique and if two clients attempt to connect with the same client ID, one will be forcefully disconnected from the server to allow the other client to connect.

    
    

• Anchor
  KeepAlive KeepAlive

  Keep Alive
  • The maximum interval in seconds (5-65,535) between any two MQTT protocol control packets sent by the client to the server.
  • Minimum Keep Alive for MQTT Engine is 5.
  • If the client is idle and has no control packets to send, it will send PINGREQ protocol packet and the server is required to respond with a PINGRESP packet. If no response is received from the server within 1.5 times the Keep Alive, the client will close the connection.

  • If the server does not receive, at minimum, a PINGREQ message from a client within 1.5 times the Keep Alive, it will terminate the connection and send the client's LWT message if defined.

  • For MQTT Engine with Primary Host enabled, this is a message of format spBv1.0/STATE/primary_host_id with a payload {"online" : false, "timestamp" : 1668114759262}

  • For MQTT Engine with Legacy Primary Host enabled, this is a message of format STATE/primary_host_id with a payload of OFFLINE
• Filtered Namespaces
  • A comma separated list of namespaces that will be filtered/disabled for connections to this MQTT Server.
  • The default namespaces are Elecsys, Xirgo, Sparkplug A and Sparkplug B.
• Include Sparkplug DataTypes
  • Whether or not to include Sparkplug DataTypes for Metrics in Sparkplug CMD payloads
  • Enabled by default

...

• A comma separated list of namespaces that will be filtered/disabled for connections to this MQTT Server.
• The default namespaces are Elecsys, Xirgo, Sparkplug A and Sparkplug B.

...

• Whether or not to include Sparkplug DataTypes for Metrics in Sparkplug CMD payloads
• Enabled by default

...

From release 4.0.14 MQTT Engine will support the new STATE message format and be in compliance with MQTT Sparkplug™ B specification v3.0.0.

However as there will still be many existing clients which are only compatible with the MQTT Sparkplug™ B specification v2.2, we have made changes to MQTT Engine to establish a MQTT client whose only function is to publish the STATE message in its legacy format.

If you are updating from a previous version of MQTT Engine to v4.0.14, the configuration of the Legacy State template will be completed as part of the upgrade process and the Legacy Client enabled.

...

• Enable Legacy STATE messages
  • Whether or not connections to enable legacy STATE messages (e.g. STATE/[host_id]). This is false by default unless upgrading from a previous module version..

  • For use with MQTT clients only compatible with MQTT Sparkplug™ B specification v2.2

• Enable Primary Host Subscriptions

  • Whether or not to enable MQTT Engine subscriptions on legacy STATE/# and State/# topics.
  • Requires that Enable Legacy STATE messages is TRUE and Primary Host Enabled is FALSE and/or Primary Host ID is null.
  • This setting is for debugging purposes only.
• Legacy State Username
  • Optional MQTT username to use in the MQTT connect packet.  This is required if the MQTT Server to connect to requires it.
• Password
  • Optional MQTT password to use in the MQTT connect packet.  This is required if the MQTT Server to connect to requires it.
• Legacy State Client ID
  • The MQTT Client ID for connections to the MQTT Server. If left blank one will be auto-generated of the form ME-LS-xxxxxxxx-xxxx-xxxxxxxx
• Legacy State Password
  • Optional MQTT password to use in the MQTT connect packet.  This is required if the MQTT Server to connect to requires it.
• Legacy State CA Certification File
  • CA Certification file currently in use.
• Legacy State Client Certification File
  • Client Certification file currently in use.
• Legacy State Client Private Key File
  • Client Private Key file currently in use
• Password
  • Optional password associated with the certificate's private key.
• Legacy State Hostname Verification
  • Enable TLS Hostname Verification. This is true by default.
• Legacy State TLS ALPN Extensions
  
  • Optional TLS ALPN Extensions to use with this connection
• Legacy State Client Private Key File
  • Client Private Key file currently in use

Anchor
ServersCertificates ServersCertificates

Servers - Certificates

...

Image RemovedImage Added

The Certificates tab contains a single Main Certificate File Settings section.

Anchor

...

ServersCertificatesCertificateFileSettings

...

ServersCertificatesCertificateFileSettings

Servers Certificates -

...

Certificate File Settings

Image Added

• Friendly Certificate File UploadName
  • The friendly name of
  • Browse to the certificate file or private key to upload.
  Friendly Name
• File Description
  • The friendly name description of the certificate file or private key.
• Certificate File Description
  • Drag a file or browse to
  • The description of the certificate file or private key to upload.

Anchor
SetSettings SetSettings

Sets

The Sets tab contains a list of server sets.  Each set represents a logical grouping of MQTT servers.  When a set is referenced by an Engine configuration, a single connection to one of the servers in the set will be maintained. The other servers will act as failover in the case that a connection with the first is lost.  Server sets cannot have common elements meaning that a single MQTT server cannot be in more than one set.Image Removed

Image Added

Image Added

• Server Set Name
  • The friendly name of this MQTT Server Set
• Description
  • Description of this MQTT Server Set

• Anchor
  PrimaryHostEnabled PrimaryHostEnabled

  Primary Host Enabled
  • Whether or not primary host STATE message will be published. If true, the Primary Host ID must also be set.
  • When enabled, the MQTT Engine will publish it's connection state on a topic that contains the Primary Host ID.  In the event that MQTT Engine becomes disconnected from the server, a death certificate will be published on the same topic, setting the state to 'offline'.  Any connecting client that subscribes on the state topic will then be notified of the MQTT Engine state.

• Anchor
  PrimaryHost PrimaryHost

  Primary Host ID
  • The primary host ID to allow connecting clients to ensure they remain connected. 
  • This must contain only letters, numbers, or any of the following special characters: . $ % @ ! - _ ^ *

...

The third tab is used for configuring namespaces.  Each namespace configuration represents a family of devices and/or data that MQTT Engine will support.  A namespace defines the topics that each MQTT Engine client will subscribe on as well as indicates how the payload will be handled.Image Removed

The Namespace tab has two parts - Default and Custom.  

Anchor
NamespacesDefault NamespacesDefault

Namespaces Default

Image Added

Default namespaces are provided out of the box and when MQTT Engine is first installed, all non Sparkplug B default namespaces are disabled.Image Removed

Selecting Edit for Elecsys will bring up three tabs - General, Sets and Filters

...

MQTT Engine supports MQTT Engine String Replacement for both MQTT Topics and Payloads for character sequences that will become part of an Ignition tag path. 

Image RemovedImage Added

Each custom namespace configuration has three parts - General, Sets andString Conversion. 

...