Basic Operations

The following basic operations are available for the MQTT Engine Module and can be executed within any of the available Ignition scopes using the format system.cirruslink.engine.operation

  • createConfig(type, name, config, enabled, description)
    • enabled (boolean) and description (string) are optional calls
    • returns a dictionary that represents the config.json of the specified resource
  • deleteConfig(type, name)
    • returns a boolean
  • getConfigNames(type, enabled)
    • enabled is an optional call
    • returns a list strings
  • isConfigEnabled(type, name)
    • returns a boolean
  • readConfig(type, name)
    • returns a dictionary that represents the config.json of the specified resource
  • setConfigEnabled(type, name, enabled)
    • returns a boolean 
  • updateConfig(type, name, collisionPolicy, config)
    • returns a dictionary that represents the config.json of the specified resource

where:

  • type
    • string denoting the type of configuration to operate on
  • name
    • string denoting the unique name for the configuration resource to operate on
  • config
    • dictionary of properties making up the configuration resource to operate on
      • general
      • server
      • server-set
      • cert-file
      • namespace-file
      • default-namespace
      • namespace-server-set
      • default-namespace-convert
      • custom-namespace
      • custom-namespace-convert
      • topic-token-filter
  • enabled
    • boolean
  • collisionPolicy
    • string with options "MergeOverwrite" or "Overwrite"
      • "MergeOverwrite" will replace the existing properties in the resource name with only those included in the call
      • "Overwrite" will replace all properties in the resource name with those in the call



Configuration changes made through scripting do have the same validation as when made through the UI. 

For example, attempting to delete a Sets configuring that is being referenced by a Servers configuration will result in no action being performed.


Extended Operations

The following extended operations are available for the MQTT Engine Module and can be executed within any of the available Ignition scopes using the format system.cirruslink.engine.operation

  • readAlarms()
  • clearAlarm(id)
  • clearAllAlarms()

where:

  • id
    • string
    • The Id of the alarm to delete

Engine 'type' keys

  • general
  • server
  • server-set
  • cert-file
  • namespace-file
  • default-namespace
  • namespace-server-set
  • default-namespace-convert
  • custom-namespace
  • custom-namespace-convert
  • topic-token-filter

Engine 'general' keys

enabledboolean

Whether or not the configuration resource is enabled

namestring

The unique name for the configuration resource

enableEngineboolean

Whether to enable MQTT Engine

blockNodeCommandsboolean

Block outbound Edge Node Tag writes

blockDeviceCommandsboolean

Block outbound Device Tag writes

includeSecurityContextboolean

Whether or not to include the Security Context in write commands to be validated at the Edge Node

securityContextHashingAlgorithmstring

The hashing algorithm to use when encrypting the Security Context

securiyContextHashingPasswordstring

The hashing password to use when encrypting the Security Context

blockTagPropertyChangesboolean

Block incoming Tag property changes

storeHistoricalEventsboolean

Enable the writing of historical change events directly to the History provider instead of updating the Tag value

reorderingTimeoutlong

Sets the Sparkplug Reordering Timeout in milliseconds

enableLatchingboolean

Enable latching on tags to synchronize MQTT Engine tag updates with events in Ignition projects

latchTimeoutlong

The amount of time to wait for the latch to be released by the Ignition project component in milliseconds before timing out

latchTagListstring

A semicolon separated list of comma separated trigger tag/latch tag pairs

filteredPropertiesstring

A semicolon delimited list of Tag properties to filter/ignore on received Tags

enableBdSeqCheckingboolean

Enables/disables BIRTH/DEATH sequence number validation as required by the Sparkplug specification

metricTimestampValidationboolean

Enables/disables validation of metric timestamps against the current tag value timestamp before writing

customPropertiesstring

Custom properties to provide to MQTT Engine

primaryHostControlTagListstring

A semicolon separated list of comma separated Primary Host control tag triples

rebirthDebounceDelaylong

The amount of time to delay in milliseconds before another Sparkplug Rebirth request can be sent to an Edge Node

useCirrusEncoderboolean

Whether to use the Cirrus Link Encoder which will use special encoding for non-Sparkplug supported PropertyDataTypes

sparkplugMessageHandlerThreadCountinteger

The Sparkplug message handler thread count

enableAlarmEventPublishingboolean

Whether or not to support alarm events via MQTT

alarmDisplayPathTypestring

The format to use for the Alarm Display Path

h2dbDirectorystring

Directory to store the H2 Database in

h2dbPortinteger

TCP Port to connect to H2 Database

Engine 'server' keys

enabledboolean

Whether or not the configuration resource is enabled

namestringThe unique name for the configuration resource
urlstringThe URL of this MQTT Server
serverSetstringThe Server Set this MQTT Server is associated with
usernamestringThe username for this MQTT connection
passwordstringThe password for this MQTT connection
caCertFilestringCA certificate file
clientCertFilestringClient certificate file
clientPrivateKeyFilestringClient Private Key file
clientKeyPasswordstringClient Private Key password
hostnameVerificationbooleanEnable/Disable TLS Hostname Verification
tlsAlpnExtensionsstringThe TLS ALPN Extensions for this connection
clientIdstringThe MQTT Client ID for this MQTT connection
cleanSessionbooleanWhether or not this is a Clean MQTT Session
keepAliveintegerThe MQTT Client keep alive
filteredNamespacesstringComma separated list of namespaces to be disabled
includesparkplugDataTypesbooleanInclude Sparkplug DataType fields in DATA messages
enableLegacyStateMessagesbooleanWhether to support legacy (Sparkplug v2) Host State Messages
enablePrimaryHostSubscriptionsbooleanWhether to enable primary host subscriptions
legacyStateUsernamestring(Legacy) The username for this MQTT connection
legacyStatePasswordstring(Legacy) The password for this MQTT connection
legactClientIdstring(Legacy) The MQTT Client ID for this MQTT connection
legacyStateCaCertFilestring(Legacy) CA certificate file
legacyStateClientCertFilestring(Legacy) Client certificate file
legacyStateClientPrivateKeyFilestring(Legacy) Client Private Key file
legacyStateClientKeyPasswordstring(Legacy) Client Private Key password
legacyStateHostnameVerificationboolean(Legacy) Enable/Disable TLS Hostname Verification
legacyStateTlsAlpnExtensionsstring(Legacy) The TLS ALPN Extensions for this connection

Engine 'server-set' keys

enabledboolean

Whether or not the configuration resource is enabled

namestringThe unique name for the configuration resource
primaryHostEnabledbooleanWhether Primary Host ID is enabled
primaryHostIdstringThe Primary Host ID

Engine 'cert-file' keys

enabledboolean

Whether or not the configuration resource is enabled

namestringThe unique name for the configuration resource
fileContentsstringThe file contents
fileNamestringThe filename
fileDescriptionstringThe file description

Engine 'namespace-file' keys

enabledboolean

Whether or not the configuration resource is enabled

namestringThe unique name for the configuration resource
ignoreFilesbooleanWhether all published files will be ignored
fileHostTypestringDefines if file host sends message ACKs - 'Active' or 'Passive'
baseFileDirectorystringThe directory to store files in when using the 'Store' file policy
addTopicTokensbooleanWhether to add Group, EdgeNode, and Device IDs to the base file directory
fileStoringPolicystringThe policy for storing incoming files - 'Overwrite Existing File' or 'Keep Existing File'
basicFileAttriburesPolicystringThe policy for handling basic attributes - 'Ignore', 'Append To Filename', 'Update File Attributes', Append And Update'

Engine 'default-namespace' keys

enabledboolean

Whether or not the configuration resource is enabled

namestringThe unique name for the configuration resource
subscriptionstringComma separated list of topics the the MQTT server will subscribe on
qos1booleanUse QoS1 for all subscriptions
rootFolderstringThe root folder where all tags will be located
tagNamestringThe name of the tag
jsonPayloadbooleanParse the payload as a JSON string
charsetstringThe encoding format to use for Strings when not parsing as JSON
writeableTagsbooleanMakes created tags Writable
numbersAsFloatsbooleanTreat all numbers as decimal numbers when creating tags

Engine 'namespace-server-set' keys

enabledboolean

Whether or not the configuration resource is enabled

namestringThe unique name for the configuration resource
namespacestringThe Namespace this resource is associated with
serverSetstringThe Server Set this resource is associated with

Engine 'default-namespace-convert' keys

enabledboolean

Whether or not the configuration resource is enabled

namestringThe unique name for the configuration resource
defaultNamespacestringDefault Namespace reference
orderIndexintegerThe order index which specifies the order in which to execute the replacement
sourcestringThe source string or regular expression (regex) in the MQTT topic or payload to be replaced
replacementstringThe replacement string that will be used to replace the source string in Ignition tags
regexbooleanWhether the source string is a regular expression

Engine 'custom-namespace' keys

enabledboolean

Whether or not the configuration resource is enabled

namestringThe unique name for the configuration resource
subscriptionstringComma separated list of topics the the MQTT server will subscribe on
qos1booleanUse QoS1 for all subscriptions
rootFolderstringThe root folder where all tags will be located
tagNamestringThe name of the tag
jsonPayloadbooleanParse the payload as a JSON string
charsetstringThe encoding format to use for Strings when not parsing as JSON
writeableTagsbooleanMakes created tags Writable
numbersAsFloatsbooleanTreat all numbers as decimal numbers when creating tags

Engine 'custom-namespace-convert' keys

enabledboolean

Whether or not the configuration resource is enabled

namestringThe unique name for the configuration resource
defaultNamespacestringDefault Namespace reference
orderIndexintegerThe order index which specifies the order in which to execute the replacement
sourcestringThe source string or regular expression (regex) in the MQTT topic or payload to be replaced
replacementstringThe replacement string that will be used to replace the source string in Ignition tags
regexbooleanWhether the source string is a regular expression

Engine 'topic-token-filter' keys

enabledboolean

Whether or not the configuration resource is enabled

namestringThe unique name for the configuration resource
namespacestringNamespace reference
groupIDstringA Group ID to include in the subscription list
edgeNodeIdstringAn Edge Node ID to include in the subscription list
serverListstringA comma separated list of MQTT Server names to apply to the the filter to




Sample Scripts


Cirrus Link provides these scripts as examples only, they are not supported or guaranteed to meet any particular functionality. Cirrus Link cannot provide any assistance to modify these scripts to meet a particular need.
# Cirrus Link provides these scripts as examples only, they are not supported or guaranteed to meet any particular functionality. Cirrus Link cannot provide any assistance to modify these scripts to meet a particular need.

# Create new server set
serverProps = {}
serverProps["name"] = "Server Set 1"
serverProps["description"] = ""
serverProps["primaryHostEnabled"] = True
serverProps["primaryHostId"] = "MyPrimaryHost"
system.cirruslink.engine.createConfig("Sets", serverProps)

# Delete server
system.cirruslink.engine.deleteConfig("Servers", name)

# Read alarms
system.cirruslink.engine.readAlarms()
# Example list returned for 4 alarms
[{59ff123d-62af-4272-83c8-cbc444891982={"id":"59ff123d-62af-4272-83c8-cbc444891982","name":"Alarm4","alarmSource":"prot:MQTT:/src:Ignition-pi5:/prov:edge:/tag:Edge Nodes/G1/E1/D1/tag1:/alm:Alarm4","priority":"Critical","activeTime":1731373561034,"groupId":"G1","edgeNodeId":"E1","deviceId":"D1","state":"ActiveUnacked","ackedBy":null}, fa076e0f-bc37-4ce0-a7a3-709d2e2389b2={"id":"fa076e0f-bc37-4ce0-a7a3-709d2e2389b2","name":"Alarm1","alarmSource":"prot:MQTT:/src:Ignition-pi5:/prov:edge:/tag:Edge Nodes/G1/E1/D1/tag1:/alm:Alarm1","priority":"Low","activeTime":1731373531034,"groupId":"G1","edgeNodeId":"E1","deviceId":"D1","state":"ActiveUnacked","ackedBy":null}, 2ac2c263-b552-49fc-a969-98313ca107b6={"id":"2ac2c263-b552-49fc-a969-98313ca107b6","name":"Alarm2","alarmSource":"prot:MQTT:/src:Ignition-pi5:/prov:edge:/tag:Edge Nodes/G1/E1/D1/tag1:/alm:Alarm2","priority":"Medium","activeTime":1731373541033,"groupId":"G1","edgeNodeId":"E1","deviceId":"D1","state":"ActiveUnacked","ackedBy":null}, 74a19264-8672-4e5b-ab9b-420c6aae7877={"id":"74a19264-8672-4e5b-ab9b-420c6aae7877","name":"Alarm3","alarmSource":"prot:MQTT:/src:Ignition-pi5:/prov:edge:/tag:Edge Nodes/G1/E1/D1/tag1:/alm:Alarm3","priority":"High","activeTime":1731373551034,"groupId":"G1","edgeNodeId":"E1","deviceId":"D1","state":"ActiveUnacked","ackedBy":null}}]

# Clear alarm
system.cirruslink.engine.clearAlarm("59ff123d-62af-4272-83c8-cbc444891982")








  • No labels