Versions Compared

Old Version 74

changes.mady.by.user Gill Houghton

Saved on

compared with

New Version Current

changes.mady.by.user Gill Houghton

Saved on

Key

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

...

Note

MQTT Engine 4.0.23 and newer support the acknowledgements of alarm events propagated from the Edge to MQTT Engine on the Central Gateway and inserted in the Ignition Alarm Journal 

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

Image RemovedImage Added

  • 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.

  • H2 Database PortDirectory - added in 4.0.25
    • Directory to store the H2 Database in.
    • TCP Port to connect to internal H2 Database
    • The AlarmStore.mv file is located here: yourIgnitionInstance\data\modules\com.cirrus-link\com.cirruslink.mqtt.engine.gateway\h2
    • 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

Image Removed

  • 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.

      Note
      If upgrading from a pre 4.0.14 module with a "reorderingTimeout" custom property configured, the upgrade will migrate the value for the custom property to the Reordering Timeout property. 


...

  • 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
    • The amount of time in milliseconds before another Sparkplug Rebirth request can be sent to an Edge Node
    • Available in version 4.0.23 and newer. Older releases have a hardcoded 5 second Rebirth Debounce Delay.

Anchor
Servers
Servers
Servers

...

The connection status of each server can be seen in the 'Status' column .Image Removedwith options:

  • Connected
  • Disconnected
  • Not Licensed

Image Added

The The configuration sections available are Main, TLS, Advanced and Advanced Legacy State

...

Default namespaces are provided out of the box and can simply be enabled or disabled.  When when MQTT Engine is first installed, all non Sparkplug B default namespaces are disabled.

The Default tab has four parts Selecting Edit for Elecsys will bring up three tabs - General, Sets and Filters, Files and String Conversions

...

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

Selecting Edit for Sparkplug B will bring up five tabs - General, Sets, Filters, Files and String Conversions

Selecting Edit for Xirgo will bring up two tabs - General and Sets


Anchor
NamespacesDefaultGeneralNonSparkplugB
NamespacesDefaultGeneralNonSparkplugB
Namespaces Default Non Sparkplug B - General

Image Added

  • Name

      ...

      Image Removed

      • Name
        • A friendly name of the namespace to easily identify it.
      • Enabled
        • Whether or not the namespace is enabled. 
        • If enabled, MQTT Engine will subscribe to the topics necessary to provide support for devices and data associated with that namespace.  If disabled, MQTT Engine will unsubscribe from those topics and no longer support the devices and data associated with that namespace.

      Anchor

      ...

      NamespacesDefaultGeneralSparkplugB

      ...

      NamespacesDefaultGeneralSparkplugB
      Namespaces Default

      ...

      Namespace filters allows you to specify Group or Group/EdgeNode combinations which will be included in the MQTT Engine subscriptions for this specific namespace.

      From MQTT Engine 4.0.16 and newer, it also allows for the filters to be applied to specific MQTT Servers.

      Image Removed

      • Group ID
        • The Group ID to be included in the MQTT Engine subscriptions for this specific namespace. 
      • Edge Node ID
        • Edge Node ID to be included in the MQTT Engine subscriptions for this specific namespace.
      • MQTT Server List
        • A comma separated list of MQTT Server names to apply the filter to. If left blank, it will apply to all MQTT Servers

      Additional detail on the default namespaces is available here.

      ...

      Image Removed

      • Main
        • Ignore Files
          • Default: Unchecked.
          • If checked, all published files will be ignored
        • File Host Type
          • Default: ACTIVE. Host will send message ACKs back to MQTT Transmission acting as an Active Host
          • Options are ACTIVE and PASSIVE
      • Location
        • Base File Directory
          • The directory to store files when 'Ignore Files' is unchecked
        • Add Topic Tokens
          • Default: Checked. If selected, appends the Group ID, Edge Node Id and device ID to the Base File Directory when storing files
        • File Storing Policy
          • The file policy for storing incoming files. Options are REPLACE_EXISTING_FILE and KEEP_EXISTING_FILE
          • Default: REPLACE_EXISTING_FILE
        • File Attributes Policy
          • The policy for handling basic file attributes such as CreationTime, LastModifiedTime and LastAccessTime of incoming files. Options are IGNORE, APPEND_TO_FILENAME, UPDATE_FILE_ATTRIBUTES and APPEND_AND_UPDATE
          • Default is IGNORE

      ...

      Image Removed

      • Order Index
        • The order index which specifies the order in which to execute the replacement
      • Source String
        • Free form field for the source string or regular expression (regex) in the MQTT Topic or payload to be replaced
      • Replacement String
        • Free form field for the replacement string that will be used to replace the source string in Ignition tags
      • Regex
        • If checked, the source string will be treated as a 'regular expression'
        • If unchecked, the source string is an exact character string to match and replace
        • Default: unchecked

      Reference the MQTT Engine String Replacement HowTo tutorial for additional details

      ...

      Custom Namespaces are used to provide support for generic, non Sparkplug compliant MQTT messages with string based payloads. If a custom namespace is configured MQTT Engine will convert all messages received to tags where the topic of each message will translate directly to the tag's path and the payload will be the tag's value.

      Note
      We recommend disabling the Sparkplug B default namespace if defining a custom namespace.

      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 Removed

      ...

      Sparkplug B - General

      Image Added


      • Name
        • A friendly name of the namespace to easily identify it.
      • Enabled
        • Whether or not the namespace is enabled. 
        • If enabled, MQTT Engine will subscribe to the topics necessary to provide support for devices and data associated with that namespace.  If disabled, MQTT Engine will unsubscribe from those topics and no longer support the devices and data associated with that namespace.
      • Default Tags Enabled
        • Included in release 4.0.23 and newer
        • Enable MQTT Engine tags in the 'Edge Nodes' folder prefixed by the Sparkplug IDs
      • UNS Tags Enabled
        • Included in release 4.0.23 and newer
        • Enable MQTT Engine tags in a specified folder using the metric path as the tag path
      • UNS Folder Prefix
        • Included in release 4.0.23 and newer
        • The MQTT Engine folder prefix to use for UNS tags

      Anchor
      NamespacesDefaultSets
      NamespacesDefaultSets
      Namespaces Default - Sets

      From release 4.0.26, a specific Server Set(s) can be associated with the Namespace

      Image Added

      • Server Set
        • A dropdown list of the existing sets configured under MQTT Engine Settings > Sets


      Anchor
      NamespacesDefaultFilters
      NamespacesDefaultFilters
      Namespaces Default - Filters

      Namespace filters allows you to specify Group or Group/EdgeNode combinations which will be included in the MQTT Engine subscriptions for this specific namespace.

      From MQTT Engine 4.0.16 and newer, it also allows for the filters to be applied to specific MQTT Servers.Image Added

      • Group ID
        • The Group ID to be included in the MQTT Engine subscriptions for this specific namespace. 
      • Edge Node ID
        • Edge Node ID to be included in the MQTT Engine subscriptions for this specific namespace.
      • MQTT Server List
        • A comma separated list of MQTT Server names to apply the filter to. If left blank, it will apply to all MQTT Servers

      Additional detail on the default namespaces is available here.

      Anchor
      NamespacesDefaultFiles
      NamespacesDefaultFiles
      Namespaces Default - FilesImage Added

      • Main
        • Ignore Files
          • Default: Unchecked.
          • If checked, all published files will be ignored
        • File Host Type
          • Default: ACTIVE. Host will send message ACKs back to MQTT Transmission acting as an Active Host
          • Options are ACTIVE and PASSIVE

      Image Added

      • Location
        • Base File Directory
          • The directory to store files when 'Ignore Files' is unchecked
        • Add Topic Tokens
          • Default: Checked. If selected, appends the Group ID, Edge Node Id and device ID to the Base File Directory when storing files
        • File Storing Policy
          • The file policy for storing incoming files. Options are REPLACE_EXISTING_FILE and KEEP_EXISTING_FILE
          • Default: REPLACE_EXISTING_FILE
        • File Attributes Policy
          • The policy for handling basic file attributes such as CreationTime, LastModifiedTime and LastAccessTime of incoming files. Options are IGNORE, APPEND_TO_FILENAME, UPDATE_FILE_ATTRIBUTES and APPEND_AND_UPDATE
          • Default is IGNORE


      Anchor
      NamespacesDefaultStringConversion
      NamespacesDefaultStringConversion
      Namespaces Default - String Conversion

      Image Added

      • Order Index
        • The order index which specifies the order in which to execute the replacement
      • Source String
        • Free form field for the source string or regular expression (regex) in the MQTT Topic or payload to be replaced
      • Replacement String
        • Free form field for the replacement string that will be used to replace the source string in Ignition tags
      • Regex
        • If checked, the source string will be treated as a 'regular expression'
        • If unchecked, the source string is an exact character string to match and replace
        • Default: unchecked

      Reference the MQTT Engine String Replacement HowTo tutorial for additional details

      Anchor
      NamespacesCustom
      NamespacesCustom
      Namespaces Custom


      Custom Namespaces are used to provide support for generic, non Sparkplug compliant MQTT messages with string based payloads. If a custom namespace is configured MQTT Engine will convert all messages received to tags where the topic of each message will translate directly to the tag's path and the payload will be the tag's value.

      Note
      We recommend disabling the Sparkplug B default namespace if defining a custom namespace.

      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 Added

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


      Anchor
      NamespacesCustomGeneral
      NamespacesCustomGeneral
      Namespaces Custom General

      The configuration sections available are Main, Optional and Advanced.

      Anchor
      NamespacesCustomGeneralMain
      NamespacesCustomGeneralMain
      Namespaces Custom - General MainImage Added

      • Name
        • A friendly name of the namespace to easily identify it.
      • Subscriptions
        • A comma separated list of subscriptions and supports both the multi-level (#) and single level (+) wild card characters.

        • (+) is a a single level wildcard that matches any name for a specific topic level. This can be used instead of specifying a name for any topic level in the topic filter.

        • (#) is a multi level wildcard that can only be used at the end of the topic filter as the last level and matches any topic whose first levels are the same as the topic levels specified at the left-hand side of the # symbol.


      Warning

      Check your MQTT Topic subscriptions to verify if they contain valid Ignition tag path or tag name characters. View the Ignition Understand Tag Naming document for details on the tag name rules.

      While MQTT and Sparkplug both support characters such as . & % =, Ignition does not support these as valid characters in a tag path or tag name and as a result, it may be necessary to tell MQTT Engine to replace certain characters or strings of characters with something else so the tag path and tag names can be properly created in Ignition. Reference the MQTT Engine String Replacement HowTo for additional details on how to use this configuration.

      Anchor
      NamespacesCustomGeneralOptional
      NamespacesCustomGeneralOptional
      Namespaces Custom - General Optional

      Image Added

      • Root Tag Folder
        • A name of a folder where all tags will be stored.  If configured, this folder will be the base folder where all tag paths will start.
      • Tag Name
        • A tag name to be used for all tags.  If not configured, the last token in the topic will represent the tag.
      • JSON Payload
        • Optional flag to indicate that the content of the string based payload is a JSON object.
      • Encoding Charset
        • The encoding format to use when not parsing as JSON.

      Anchor
      NamespacesCustomGeneralAdvanced
      NamespacesCustomGeneralAdvanced
      Namespaces Custom - General Advanced

      Image Added

      • Writable Tags
        • Enables writes on tags created by the Custom Namespace.
        • This will only make the tags writable and does not result in outgoing MQTT messages. Review this tutorial for writing back to an Edge device from a custom namespace tag.
      • Numbers as Floats (added 4.0.28)
        • Treat all numbers as decimal numbers when creating tags. 


      Anchor
      NamespaceCustomSets
      NamespaceCustomSets
      Namespaces Custom - Sets

      From release 4.0.26 a specific Server Set(s) can be associated with the NamespaceImage Added

      • Server Set
        • A dropdown list of the existing sets configured under MQTT Engine Settings > Sets

      ...

      The configuration sections available are Main, Optional and Advanced.

      ...

      Image Removed

      • Name
        • A friendly name of the namespace to easily identify it.
      • Subscriptions
        • A comma separated list of subscriptions and supports both the multi-level (#) and single level (+) wild card characters.

        • (+) is a a single level wildcard that matches any name for a specific topic level. This can be used instead of specifying a name for any topic level in the topic filter.

        • (#) is a multi level wildcard that can only be used at the end of the topic filter as the last level and matches any topic whose first levels are the same as the topic levels specified at the left-hand side of the # symbol.

      Warning

      Check your MQTT Topic subscriptions to verify if they contain valid Ignition tag path or tag name characters. View the Ignition Understand Tag Naming document for details on the tag name rules.

      While MQTT and Sparkplug both support characters such as . & % =, Ignition does not support these as valid characters in a tag path or tag name and as a result, it may be necessary to tell MQTT Engine to replace certain characters or strings of characters with something else so the tag path and tag names can be properly created in Ignition. Reference the MQTT Engine String Replacement HowTo for additional details on how to use this configuration.

      ...

      Image Removed

      • Root Tag Folder
        • A name of a folder where all tags will be stored.  If configured, this folder will be the base folder where all tag paths will start.
      • Tag Name
        • A tag name to be used for all tags.  If not configured, the last token in the topic will represent the tag.
      • JSON Payload
        • Optional flag to indicate that the content of the string based payload is a JSON object.
      • Encoding Charset
        • The encoding format to use when not parsing as JSON.

      ...

      • Writable Tags
        • Enables writes on tags created by the Custom Namespace. Note: This will only make the tags writable; it will not result in outgoing MQTT messages.

      Anchor
      NamespacesCustomStringConversion
      NamespacesCustomStringConversion
      Namespaces Custom - String Conversion

      ...