Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

There are two configuration pages "History" and "Settings".                                   

Anchor
Settings
Settings

Settings

...

The General Settings tab contains a single Main section.Image RemovedImage Added

Anchor
GeneralMain
GeneralMain
General - Main

  • Enabled
    • Whether or not to enable or disable MQTT Transmission from connecting to the configured MQTT Servers.
  • Audit Profile
    • Selection of a configured Ignition Audit Profile for Transmission to use.
    • Available in release 4.0.16 and limited to auditing tag writes from MQTT Engine to MQTT Transmission if Validate Security Context is enabled

Anchor
Servers
Servers
Servers

...

The configuration sections available are Main, TLS, Advanced and Advanced. RPC Client Connection

Anchor
ServerSettingsMain
ServerSettingsMain
Server Settings - Main

...

  • Name
    • This is the friendly name of the MQTT Server used to easily identify it
  • 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, IPaddress, 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 Set that this server is a member of.
  • Username
    • Optional MQTT username to use in the MQTT connect packet.  This is required if the MQTT Server to connect to requires it.
  • Change Password?

    • Check box to enable changing of the optional password
  • Password
    • Optional MQTT password to use in the MQTT connect packet.  This is required if the MQTT Server to connect to requires it.

...

Tip
See this document for TLS configuration: Configuring Secure MQTT Communication
  • CA Certification Certificate File
    • CA Certification Certificate file currently in use.
  • Client Certification Certificate File
    • Client Certification Certificate file currently in use.
  • Client Private Key File
    • Client Private Key file currently in use
  • Change Password?
    • Check box to enable changing of the optional password.
  • 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 to use with this connection

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 Transmission connect packet when connecting to the server.  If left blank, a random client ID will be create of the form 'IgnitionTargetMT-xxxxxxxx-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
    Keep Alive
  • The MQTT client keep alive time (in seconds).
  • Random Startup Delay
    • The Random Startup Delay in milliseconds of the form 'min-max' where min is the low end and max is the high end of the random range. e.g. '10-1000'. 
  • Reconnect Delay
    • The clients reconnect delay in millisecond.
  • Auto-reconnect RPC Client
    • Allow the RPC Client to auto connect and reconnect when publishing from Ignition Python scripts.
  • Data Format Type
    • The format of the data to send. Default is Sparkplug_B_v1_0_Protobuf with JSON as an option.

...

This tab provides a list of the certificate or private key files if loaded and available for TLS configuration.

Note

All certificate or private keys must be in PEM format. If using modules pre 4.0.9, any private key must also be in RSA PKCS1 format. If using modules 4.0.9 or greater, any private key must also be in either RSA PKCS1 or PKCS8 format. 

The Certificates tab contains a single Main section.

Image Removed

...

Image Removed

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

...

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 a Transmitter 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

The Sets tab contains a single Main section.

...

  • Name
    • This is the friendly name of the set used to easily identify it.
  • Description
    • This is a friendly description of the set.
  • Primary Host ID
    • The primary host ID to use for 'state' notifications.  These notifications are used to notify MQTT Transmission if the primary backend application loses connection with the MQTT Server, meaning it has gone 'offline'.  If MQTT Transmission is notified that the primary backend application has gone 'offline', it will close it's client connection with the MQTT server and walk to the next MQTT server defined in the set.  If the primary host ID is not set, MQTT Transmission will not subscribe on the notification topics and not receive any 'state' notifications.
    • This must contain only letters, numbers, or any of the following special characters: . $ % @ ! - _ ^ *

...

Transmitters are the agents within MQTT Transmission that monitor tags, convert them to Sparkplug Messages, and publish them to an MQTT Server. Each transmitter is configured with a server Set and will attempt to maintain an MQTT client connection with one server in that Set at all times.

Transmitters will monitor tags from a specific Tag Provider and, optionally, a specific Tag Path. If the tag folder hierarchy has been constructed as Group ID, Edge Node ID, and Device ID, then these will automatically be used when building up the MQTT message payload that will represent the Tags as follows:

[TagProvider]<TagPath>/<GroupID>/<EdgeNodeID>/<DeviceID>

If your tag folder hierarchy does not conform to this structure, you can explicitly define these required elements under the SparkPlug Settings section and the elements will be prepended to your tag string.Image Removed

The configuration sections available are Tag Settings, Command Settings, History Settings, Sparkplug Settings and Advanced Settings.

...

Image Removed

  • Name
    • Unique name for the Transmitter
  • Enabled
    • Checkbox to enable/disable the Transmitter. Selected by default.
  • Tag Provider
    • The name of the tag provider that Transmission will monitor.  By default this is the Ignition 'default' provider.
  • Tag Path
    • Optional path to the root folder where the tag tree starts.
    • Transmitters also support a multi-tag path configuration. Reference the Transmitters with Multi-Tag Paths tutorial for configuration assistance.
  • Tag Pacing Period
    • The buffer period for outgoing Transmission messages in milliseconds.  The default is 1000ms.  This means when a tag change event is detected 1000ms will elapse before an MQTT message is sent.  This allows additional tag change events to be buffered and put into the message and in turn reduce the number of generated MQTT messages.
  • Set
    • The Set that the default MQTT Transmission client will connect to.
  • Discovery Delay
    • An optional startup delay, in milliseconds, to wait before scanning for Tags to monitor. This is useful when Tags are dynamically created on initial startup, as is the case when using the MQTT Engine module.
  • Aliased Tags
    • Checkbox to enable/disable using aliases for tag names when published data messages as tag values change in order to optimize payload size when publishing data. Not selected by default.
  • Compression
    • The algorithm to use to compress payloads before they are published to the MQTT Server.  If 'NONE' is selected then compression is disabled.
  • Convert UDTs
    • Checkbox to enable/disable converting UDT members to normal Tags before publishing. If enabled the Tags representing the UDT member will retain their member path prefixed by the UDT Instance name. Selected by default.
  • Device level UDTs as Devices
    • Treat 'device level UDTs as Sparkplug devices'. Not selected by default and 'Convert UDTs' must be selected
  • Publish UDT Definitions
    • Checkbox to enable/disable publishing UDT Definitions in BIRTH. Selected by default and not editable.
  • Optimize UDTs
    • Checkbox to enable/disable optimizing UDT payload sizes in NDATA and DDATA payloads. Selected by default and not editable.

...

Image Removed

  • Block Commands
    • Checkbox to enable/disable the ability to block commands and tag writes received as messages from the MQTT server. Not selected by default.
  • Validate Security Context
    • Checkbox to enable/disable the ability to validate the Security Context in write commands. Not selected by default.
    • Reference the Ignition MQTT Security Context HowTo for additional details on how to use this configuration.
  • Security Context Hashing Algorithm
    • The hashing algorithm to use when decrypting the Security Context. Available if "Validate Security Context" is enabled.
  • Change Password?
    • Checkbox to allow existing password to be changed
  • Password
    • The hashing password to use when decrypting the Security Context. Available if "Validate Security Context" is enabled.

...

Image Removed

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.

...

  • The MQTT Transmission History Store to use with the Default Transmitter.

...

  • Keep Alive
    Keep Alive
    • The maximum interval in seconds (5-65,535) between any two MQTT protocol control packets sent by the client to the server.
    • The minimum Keep Alive for MQTT Transmission 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 if it has been defined.

    • For MQTT Transmission, this is an DEATH message.

  • Random Startup Delay
    • A clients variable reconnect delay in milliseconds - not configured by default
    • Entered in the format of 'min-max' where min is the low end and max is the high end of the random range. e.g. '10-1000'
    • Used to minimise "NBIRTH message storms" on reconnect from Edge nodes with many clients 
  • Reconnect Delay
    • A clients fixed reconnect delay in milliseconds with a default of 1000
  • Subscribe to Legacy STATE Topic
  • Data Format Type
    • The format of the data to send
    • Default is Sparkplug_B_v1_0_Protobuf and should be used when the subscribing client is Sparkplug aware such as MQTT Engine 
    • Sparkplug_B_v1_0_JSON should only be used when the subscribing client is not Sparkplug aware and requires the payload in a JSON format. For example some AWS IoT Core consumers.


Note

If both the Random Startup Delay and the Reconnect Delay are configured, the startup delay for any one client will be the aggregate of the two configured values. For example, with the Random Startup Delay = 10-1000ms and the Reconnect Delay = 1000ms, the startup delay for any one client will be between 1010 and 2000ms


Anchor
ServerSettingsRPCClient
ServerSettingsRPCClient
Server Settings - RPC Client Connection

This section was added in release 4.0.18 - previously configuration for the Auto-reconnect RPC Client property was under the Advanced section 

This section was updated in 4.0.23 to move the Enable/disable RPC Client and Auto-reconnect RPC Client to the Sets RPC Client configuration

Image Added

  • RPC Client ID
    • A manually configured MQTT Client ID for this RPC connection
    • Do not use this setting unless it is an absolute requirement that a specific Client ID be used for the connection to the MQTT Server. If left blank, one will be auto-generated. 
  • Username
    • Optional username for this RPC connection if required by the MQTT Server
  • Password
    • Optional password for this RPC connection if required by the MQTT Server
  • CA Certification File
    • CA Certificate file currently in use
  • Client Certificate File
    • Client certificate file currently in use
  • Client Private Key File
    • Client private key file currently in use
  • Password
    • Optional password associated with the certificates private key
  • Hostname Verification
    • Enable hostname verification. Enabled by default
  • TLS ALPN Extensions
    • Optional TLS ALPN Extensions to use with this connection

Anchor
ServerCertificates
ServerCertificates
Servers - Certificates

This tab provides a list of the certificate or private key files if loaded and available for TLS configuration.

Note

All certificate or private keys must be in PEM format. If using modules pre 4.0.9, any private key must also be in RSA PKCS1 format. If using modules 4.0.9 or greater, any private key must also be in either RSA PKCS1 or PKCS8 format. 

The Certificates tab contains a single Main section.

Image Added

Anchor
ServerCertificatesMain
ServerCertificatesMain
Server Certificates - Main

Image Added

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

Anchor
Sets
Sets

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 a Transmitter 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 Added

The Sets tab contains Main and RPC Client sections.

Anchor
SetsMain
SetsMain
Sets - MainImage Added

  • Name
    • This is the friendly name of the set used to easily identify it.
  • Description
    • This is a friendly description of the set.
  • Anchor
    PrimaryHost
    PrimaryHost
    Primary Host ID
    • The primary host ID to use for 'state' notifications.
    • If configured, MQTT Transmission will subscribe on 'state' notification topics. If MQTT Transmission is notified that the primary backend application has gone 'offline', it will close it's client connection with the MQTT server and walk to the next MQTT server defined in the set.  If the primary host ID is not set, MQTT Transmission will not subscribe on the notification topics and not receive any 'state' notifications.
    • This must contain only letters, numbers, or any of the following special characters: . $ % @ ! - _ ^ *

Anchor
SetsRPCClient
SetsRPCClient
Sets - RPC Client

Image Added

  • Enable/disable RPC Client
  • Auto-reconnect RPC Client
    • If checked, the RPC client will automatically reconnect to the server.
    • If unchecked, the RPC client will try to connect at publish time

Anchor
Transmitters
Transmitters
Transmitters

Transmitters are the agents within MQTT Transmission that monitor tags, convert them to Sparkplug Messages, and publish them to an MQTT Server. Each transmitter is configured with a server Set and will attempt to maintain an MQTT client connection with one server in that Set at all times.

Transmitters will monitor tags from a specific Tag Provider and, optionally, a specific Tag Path. If the tag folder hierarchy has been constructed as Group ID, Edge Node ID, and Device ID, then these will automatically be used when building up the MQTT message payload that will represent the Tags as follows:

[TagProvider]<TagPath>/<GroupID>/<EdgeNodeID>/<DeviceID>

Tip
Review the MQTT Transmitters and Tag Trees describing how Transmitter configurations interact with Ignition tag trees 

If your tag folder hierarchy does not conform to this structure, you can explicitly define these required elements under theSparkPlug Settings section and the elements will be prepended to your tag string.Image Added

The configuration sections available are Tag Settings, Command Settings, History Settings, Alarm Settings, Sparkplug Settings and Advanced Settings.

Anchor
TransmittersTagSettings
TransmittersTagSettings
Transmitters - Tag Settings

Image Added

  • Name
    • Unique name for the Transmitter
  • Enabled
    • Checkbox to enable/disable the Transmitter. Selected by default.
  • Tag Provider
    • The name of the tag provider that Transmission will monitor.  By default this is the Ignition 'default' provider.
  • Tag Path
    • Optional path to the root folder where the tag tree starts.
    • Transmitters also support a multi-tag path configuration. Reference the Transmitters with Multi-Tag Paths tutorial for configuration assistance.
  • Tag Pacing Period
    • The buffer period for outgoing Transmission messages in milliseconds.  The default is 1000ms.  This means when a tag change event is detected 1000ms will elapse before an MQTT message is sent.  This allows additional tag change events to be buffered and put into the message and in turn reduce the number of generated MQTT messages.
  • Set
    • The Set that the default MQTT Transmission client will connect to.
  • Discovery Delay
    • An optional startup delay, in milliseconds, to wait before scanning for Tags to monitor. This is useful when Tags are dynamically created on initial startup, as is the case when using the MQTT Engine module.
  • Aliased Tags
    • Checkbox to enable/disable using aliases for tag names when published data messages as tag values change in order to optimize payload size when publishing data. Not selected by default.
  • Compression
    • The algorithm to use to compress payloads before they are published to the MQTT Server.  If 'NONE' is selected then compression is disabled.
  • Convert UDTs
    • Checkbox to enable/disable converting UDT members to normal Tags before publishing. If enabled the Tags representing the UDT member will retain their member path prefixed by the UDT Instance name. Selected by default.
  • Device level UDTs as Devices
    • Treat 'device level UDTs as Sparkplug devices'. Not selected by default and 'Convert UDTs' must be selected
  • Publish UDT Definitions
    • Checkbox to enable/disable publishing UDT Definitions in BIRTH. Selected by default and not editable.
  • Optimize UDTs
    • Checkbox to enable/disable optimizing UDT payload sizes in NDATA and DDATA payloads. Selected by default and not editable.

Anchor
TransmittersCommandSettings
TransmittersCommandSettings
Transmitters - Command Settings

Image Added

  • Block Commands
    • Checkbox to enable/disable the ability to block commands and tag writes received as messages from the MQTT server. Not selected by default.
  • Validate Security Context
    • Checkbox to enable/disable the ability to validate the Security Context in write commands. Not selected by default.
    • Reference the Ignition MQTT Security Context HowTo for additional details on how to use this configuration.
  • Security Context Hashing Algorithm
    • The hashing algorithm to use when decrypting the Security Context. Available if "Validate Security Context" is enabled.
  • Change Password?
    • Checkbox to allow existing password to be changed
  • Password
    • The hashing password to use when decrypting the Security Context. Available if "Validate Security Context" is enabled.

Anchor
TransmittersHistorySettings
TransmittersHistorySettings
Transmitters - History Settings

Image Added

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.

  • History Store
    • The MQTT Transmission History Store to use with the Default Transmitter.
  • Enable History Storage by Default
    • Checkbox to enable/disable store and forward for all tags. Selected by default. 
    • Store and forward controls whether or not a tag is stored in the configured History Store when Transmission is offline. To override the global setting,individual tags will require a custom tag property 'StoreAndForward' (type: boolean) to be created and set to the reverse state of the global setting.
  • In-Order History
    • Checkbox to enable/disable the flush history in-order (synchronously) before live data resumes. Not selected by default.

Anchor
TransmittersAlarmSettings
TransmittersAlarmSettings
Transmitters - Alarm Settings

Tip

MQTT Transmission 4.0.16 through 4.0.22 support the propagation of alarm events from the Edge to MQTT Engine on the Central Gateway to be inserted in the Ignition Alarm Journal but do not support the remote acknowledgment of those alarms

MQTT Transmission 4.0.23 and newer support the propagation of alarm events from the Edge to MQTT Engine on the Central Gateway to be inserted in the Ignition Alarm Journal along with acknowledgements from the Central Gateway back to the Edge

Review the Alarm Event Propagation document for system configuration details including the changes needed to the data/ignition.conf file and MQTT Engine

Image Added

  • Alarm Event Enable
    • When enabled and alarms are enabled on tags, the contents of the triggered alarms will be transmitted via Sparkplug to MQTT Engine and will be inserted into the Ignition Alarm Journal on the server where MQTT Engine is installed.

Anchor
TransmittersSparkplugSettings
TransmittersSparkplugSettings
Transmitters - Sparkplug Settings

Image Added

  • Group ID
    • An ID representing a logical grouping of MQTT Edge Of Network (EoN) 

...

  • Checkbox to enable/disable the flush history in-order (synchronously) before live data resumes. Not selected by default.

...

Image Removed

  • Group ID
    • An ID representing a logical grouping of MQTT Edge Of Network (EoN) Nodes and Devices into the infrastructure.
  • Edge Node ID
    • An ID that uniquely identifies the MQTT Edge Of Network (EoN) Node within the infrastructure.
  • Device ID
    • An optional ID that uniquely identifies a Device within the infrastructure.

Note that if a 'Device ID' is not specified, any folder within the folder specified by the Tag Path will be considered a device folder and any Tags within it will be published as device Tags. 

...

  • Filtered Properties
    • A semicolon delimited list of Tag properties to filter/block from being published
  • Rebirth Debounce Delay
    • The amount of time, in milliseconds, to delay before processing Rebirth NCMD requests after one has been processed. Default of 5000 milliseconds.

...

The 'Records' tab allows user to create a table of custom records. Each record defines a folder (under specified tag provider) in which user can create a number of tags that will be published as a record by clicking the 'Publish' checkbox. The 'Publish' tag will be created automatically in the folder specified.

Image Removed

The configuration sections available are Tag Settings, Sparkplug Settings and Advanced Settings.

...

  • Tag Provider
    • The name of the tag provider (i.e. default)
  • Tag Folder Path
    • The path to the tag folder under specified tag provider
  • Record Type
    • Type of Record

...

  • Group ID
    • An ID representing a logical grouping of MQTT Edge of Network (EoN) Nodes and Devices into the infrastructure.
  • Edge Node ID
    • An ID that uniquely identifies the MQTT Edge of Network (EoN) Node within the infrastructure.
  • Device ID
    • An Optional ID that uniquely identifies a Device within the infrastructure.

...

  • Override Publish Tag
    • Checkbox to override the default 'Publish Tag' in the Record defined folder path 
  • Publish Tag Path
    • Overrides the default 'Publish Tag' in the Record defined folder path 

...

The 'Files' tab allows for the configuration to publish files which are transferred using Sparkplug over MQTT.Image Removed

The configuration sections available are Tag Settings, File Settings, Sparkplug Settings and Advanced Settings.

...

Image Removed

  • Tag Name
    • A friendly name for File Records which must be unique. Name is prepopulated 
  • Tag Provider
    • The name of the tag provider (i.e. default)
  • Tag Folder Path
    • The path to the tag folder under specified tag provider

...

Image Removed

  • Enable Auto-Publish
    • Checkbox to enable/disable auto publish of files. Not selected by default.
  • File Scan Rate
    • The rate, in seconds, to scan the files directory specified in the 'Publish Files Path' tag for files to publish. Default is 60 seconds.
  • File Scan Rate Time Unit
    • Time unit for 'File Scan Rate' parameter. Default is SECONDS
    • Options are: MILLISECONDS, SECONDS, MINUTES, HOURS and DAYS

...

  • Group ID
    • An ID representing a logical grouping of MQTT Edge of Network (EoN) Nodes and Devices into the infrastructure.
  • Edge Node ID
    • An ID that uniquely identifies the MQTT Edge of Of Network (EoN) Node within the infrastructure.
  • Device ID
    • An Optional optional ID that uniquely identifies a Device within the infrastructure.

...

  • Message Size
    • Number of bytes to transfer in one message, Default 1000 bytes.
  • Message Pacing Period
    • Message Pacing Period is milliseconds. Default 1000 milliseconds.
  • Message ACK Timeout
    • Message acknowledgement timeout in seconds. Default 10 seconds.
  • Number Retries
    • Number of retries to publish a file or chunk or a file
  • Submit Basic File Attributes
    • Checkbox to enable/disable the basic file attributes to be included in the metrics. Not selected by default.

...

The "History" page allows for the configuration of MQTT Transmission History Stores.  In the event that a Transmitter loses its connection with the MQTT Server and is unable to reconnect, a History Store (if enabled) will store all messages corresponding to change events on the monitored tags.  Once a connection with an MQTT server is reestablished the History Store will publish the stored messages with a flag set to indicate that the messages are "historical" to prevent confusion with live data values.Image Removed

The History tab contains a single Main section.

...

Image Removed

...

  • The name of the History Store.

...

  • Checkbox to enable/disable the History Store. Not selected by default.

...

  • The type of History Store.

...

  • The maximum number of tag change events to store, from tags directly at the edge node level, before dropping the oldest stored tag change event for that edge node.
  • A tag change event is triggered by either a change in value or quality and results in the tag's Qualified Value (which has three attributes of value, quality and timestamp) being stored. 
  • This parameter is independent from the Device Tag Capacity

...

  • The maximum number of tag change events to store, for each device, before dropping the oldest stored tag change event for that device.
  • A tag change event is triggered by either a change in value or quality and results in the tag's Qualified Value (which has three attributes of value, quality and timestamp) being stored.
  • This parameter is independent from the Edge Node Tag Capacity

...

  • The maximum number of tags to publish in a single message upon reestablishing communication.

Note that if a 'Device ID' is not specified, any folder within the folder specified by the Tag Path will be considered a device folder and any Tags within it will be published as device Tags. 

Anchor
TransmittersAdvancedSettings
TransmittersAdvancedSettings
Transmitters - Advanced SettingsImage Added

  • Filtered Properties
    • A semicolon delimited list of Tag properties to filter/block from being published
    • By default the filtered properties list contains: 

      Code Block
      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 if different from the default Ignition tag property settings and are only published in BIRTH messages.
  • Rebirth Debounce Delay
    • The amount of time, in milliseconds, to delay before processing Rebirth NCMD requests after one has been processed. Default of 5000 milliseconds.
  • Include Sparkplug DataTypes
    • Whether or not to include Sparkplug DataTypes for Metrics in Sparkplug DATA payloads
    • Enabled by default

Anchor
Records
Records
Records

Within MQTT Transmission, a record is a collection of tags under an Ignition folder which are treated as a single entity and published on demand. They are usually used for, but not restricted to, sending flow computer records such as events, alarms and history data.

Each record will have an associated boolean tag that will trigger the record publish. The location of this boolean tag is defined in the Record - Advanced Settings section.

Records are published via an MQTT client using a Sparkplug-like format such as spBv1.0/Group/NRECORD/Edge or spBv1.0/Group/DRECORD/Edge/Device  

Image Added

The configuration sections available are Tag Settings, Sparkplug Settings, Records Signature and Advanced Settings.

Anchor
RecordsTagSettings
RecordsTagSettings
Records - Tag SettingsImage Added

  • Tag Provider
    • Free form field for the name of the tag provider where the record tags reside (i.e. default)
  • Tag Folder Path
    • Free form field for the path to the tag folder under specified tag provider where the record tags reside
    • Do not include the provider name. For a tag path of [default]Edge Nodes/G1/E1/MyRecord, enter Edge Nodes/G1/E1/MyRecord
  • Record Type
    • Free form field for the type of record represented by the tags in the folder path
    • This will be included in the NRECORD or DRECORD data and used by MQTT Recorder when creating DB tables or filtering the data inserted into the DB

Anchor
RecordsSparkplugSettings
RecordsSparkplugSettings
Records - Sparkplug Settings

Note

To publish records, MQTT Transmission uses a configured Transmitter. The properties entered into the Sparkplug settings for Group ID, Edge ID and Device ID (optional) must match an existing Sparkplug Edge Node based on a Transmitter and tag tree configuration.

. Image Added

  • Group ID
    • The Group ID that matches an existing Sparkplug Edge Node.
  • Edge Node ID
    • The Edge Node ID that matches an existing Sparkplug Edge Node.
  • Device ID
    • The Device ID that matches an existing Sparkplug Edge Node. (Optional)

Anchor
RecordsRecordsSignature
RecordsRecordsSignature
Records - Records Signature

Note
From version 4.0.19 added support for digital signatures/hashing of Records that are generated by MQTT Transmission so that they can be verified in the MQTT Recorder database.

Image Added

  • Enable Signature
    • Checkbox to enable a digital signature field on all Records. Default is de-selected
  • Algorithm
    • The hashing algorithm to use when generating the digital signature
    • Options are SHA_1,SHA_224,SHA_256,SHA_384 and SHA_512
  • Password
    • The password used to generate the PBE secret key for encrypting the digital signature 

Anchor
RecordsAdvancedSettings
RecordsAdvancedSettings
Records - Advanced Settings

Each record will have an associated boolean tag that is used to trigger the on demand publish of the record. The Advanced settings manage the location and naming of this boolean tag.Image Added

  • Override Publish Tag
    • When unchecked, the tag used to control the record publish will be created within the record defined folder path and named "Publish"
    • When checked, the tag used to control the record publish will be created using the Publish Tag Path property
  • Publish Tag Path
    • Defines the tag path for the boolean tag used to control the record publish
    • This can be used to create a tag in the record defined file folder with an alternate name to "Publish" or to have the tag located in a separate folder
    • The full tag path, including the tag provider, needs to be used for example: [default]Edge Nodes/G1/E1/RecordControl/PublishEvents or [default]Edge Nodes/G1/E1/D1/Alarm/PublishAlarms

Anchor
Files
Files
Files

The 'Files' tab allows for the configuration to publish files which are transferred using Sparkplug over MQTT.

The configuration for file record creates a set of control tags (which specify where to locate the file to publish and a manual trigger option) along with information tags publish status and history. 

Image Added

The configuration sections available are Tag Settings, File Settings, Sparkplug Settings and Advanced Settings.

Anchor
FilesTagSettings
FilesTagSettings
Files - Tag Settings

Image Added

  • Tag Name
    • A friendly name for File Records which must be unique. Name is prepopulated 
  • Tag Provider
    • Free form field for the path to the name of the tag provider where the file control and information tags will be created
  • Tag Folder Path
    • Free form field for the path to the tag folder under the specified tag provider where the file control and information tags will be created
    • Do not include the provider name. For a tag path of [default]MyFiles, enter MyFiles

Anchor
ControlandInfoTags
ControlandInfoTags
Files - Control and Information Tags

The control and information tags created in the tag folder are:

NameTypeDescription
Last Published FileStringName of last published file
Last Published Sequence NumberIntegerSequence number of last published file since last reset of metrics
Percent CompletedBytePublish completion percent for file being published
Publish FileBooleanManual trigger to publish file
Publish File CountLongNumber of files published since last reset of metrics
Publish File in TransitStringName of current file being published
Publish File PathStringFull path to the target file to publish over MQTT. Created if 'Enabled Auto-Publish' is disabled 
Publish Files FolderStringFull path to the target file folder to publish over MQTT. Created if 'Enabled Auto-Publish' is enabled
Publish Operation StatusStringStatus description of current publish operation
Publish Operation Status CodeIntegerStatus code for current publish operation
Remaining RetriesIntegerNumber of remaining retries for current publish operation
ResetBooleanTrigger to reset publish metrics


Anchor
FilesFileSettings
FilesFileSettings
Files - File Settings

Image Added

  • Enable Auto-Publish
    • Checkbox to enable/disable auto-publish of files. Not selected by default.
    • When set to enable, any new files identified in directory specified in the 'Publish File Path' tag will automatically be published 
    • If set to disabled for manual publish of files, Primary Host ID must be configured for MQTT Transmission and MQTT Engine
  • File Scan Rate
    • The rate to scan the files directory specified in the 'Publish Files Path' tag for files to publish. Default is 60 seconds.
  • File Scan Rate Time Unit
    • Time unit for 'File Scan Rate' parameter. Default is SECONDS
    • Options are: MILLISECONDS, SECONDS, MINUTES, HOURS and DAYS

Anchor
FilesSparkplugSettings
FilesSparkplugSettings
Files - Sparkplug Settings

Note

To publish files, MQTT Transmission uses a configured Transmitter. The properties entered into the Sparkplug settings for Group ID, Edge ID and Device ID (optional) must match an existing Sparkplug Edge Node based on a Transmitter and tag tree configuration.

Image Added

  • Group ID
    • The Group ID that matches an existing Sparkplug Edge Node. Cannot be NULL
  • Edge Node ID
    • The Edge Node ID that matches an existing Sparkplug Edge Node. Cannot be NULL
  • Device ID
    • The Device ID that matches an existing Sparkplug Edge Node. (Optional).

Anchor
FilesAdvancedSettings
FilesAdvancedSettings
Files - Advanced SettingsImage Added

  • Message Size
    • Number of bytes to transfer in one message, Default 1000 bytes.
  • Message Pacing Period
    • Message Pacing Period is milliseconds. Default 1000 milliseconds.
  • Message ACK Timeout
    • Message acknowledgement timeout in seconds. Default 10 seconds.
  • Number Retries
    • Number of retries to publish a file or chunk or a file
  • Submit Basic File Attributes
    • Checkbox to enable/disable the basic file attributes to be included in the metrics. Not selected by default.



Anchor
History
History
History

The "History" page allows for the configuration of MQTT Transmission History Stores.

When a Transmitter is configured to use an MQTT Transmission History Store, data is written to the History Store once MQTT Transmission has determined that there is a connection failure. Once a connection with an MQTT server is re-established the History Store will publish the stored messages with a flag set to indicate that the messages are "historical" to prevent confusion with live data values. Determination of a connection failure can be up to 1.5 times the configured keep alive. and, as such, any data published during this time can be lost.

Note
From release 4.0.17, in order to cover data loss during a keep alive timeout scenario, the MQTT Transmission History Store includes a Rolling History Buffer that can be configured in the Advanced Properties configuration section. When the Rolling History Buffer is enabled, all tag changes will be written to the History Store regardless of connection status.


Note
From release 4.0.19, major improvements have been made to the disk-backed History Store. Details on configuring pre 4.0.19 modules can be found here


Tip

Prior to release 4.0.22, Disk-Backed History stores are located here ~yourIgnitionInstance\user-lib\cls\data\h2

From release 4.0.22, Disk-Backed History store are located here ~yourIgnitionInstance\data\modules\com.cirrus-link\com.cirruslink.mqtt.transmission.gateway\h2

Image Added

The History tab contains a Main section and an Advanced section.

Anchor
HistoryMain
HistoryMain
History - Main

Image Added

  • Name
    • The name of the History Store.
  • Enabled
    • Checkbox to enable/disable the History Store. Not selected by default.
  • Type
    • The type of History Store.
    • Data stored in an In-Memory History Store will not be persisted across a module configuration change, module disable/enable, module restart or power loss. 
    • Data stored in a Disk-Backed History Store will persist across a module configuration change, module disable/enable, module restart or power loss.
  • History Max Size
    • Maximum number of megabytes history can use before dropping the data
    • An In-Memory History store will use the Ignition Java Heap memory
  • History Max Age
    • Maximum number of minutes to store history before dropping the data.
  • Flush Quantity
    • The maximum number of tags to publish in a single message upon reestablishing communication.
  • Flush Period
    • The period to wait in milliseconds between acquisition and publishing of the historical data when flushing messages upon re-establishing communication
    • MQTT Transmission queries the history store and builds up a publish, and publishes it, and then delays by the Flush Period.
      The actual message publish frequency is not deterministic as the time to gather the publish from the history store can vary depending on the frequency tag change events occurring, disk speed, CPU availability, etc. For example, if it takes 5s to gather up and publish that payload, the actual message publish frequency will be it will be 5s + the flush period

Anchor
HistoryAdvanced
HistoryAdvanced
History - Advanced

Image Added

Rolling History Settings

  • Enable Rolling History Buffer
    • Enable/disable storing data in a rolling buffer to cover data loss in Keep Alive timeout scenario
  • Rolling History Prune Interval
    • The interval, in seconds at which to attempt to prune the rolling history buffer
  • Rolling History Max Age
    • The maximum age allowed of data, in seconds, in the rolling history buffer
    • This should be at least 2 x the Keep Alive timeout
  • Rolling History Prune Quantity
    • The number of metrics to prune in a single block

Advanced Settings

  • H2 Database Port
    • TCP Port to connect to H2 Database for Disk-Backed History Store
Warning

If using multiple Disk-Back History Stores, the TCP Database Port must be unique for each one.

This requirement applies to all Disk-Backed History Stores (MQTT Transmission and all Injectors), MQTT Engine Alarm Stores and Chariot MQTT Server (uses TCP Port 9092) if co-located on the same platform 

...