Ignition Integration

overview the ignition integration is a module for inductive automation's ignition platform that provides read/write integration for all ignition tags into litmus edge, allowing you the leverage the power of litmus edge analytics, digital twins and integrations before you begin use version 2 2 2 of the module for ignition 8 1 use 3 x for ignition 8 3 prerequisites verify you have an ignition instance running version 8 1 x or 8 3 x running on a device with support for java 17 verify you have a litmus edge instance running version 3 22 0 or greater open network access between litmus edge and ignition on set port (defaults to 4778) installation/upgrading the process for upgrading the module is identical to installation installing the ignition module installing for ignition 8 1 x download version 2 x x modl module file from the litmus portal https //portal litmus io/accelerators/ignition integration open your ignition gateway with admin permissions navigate to config >modules >install or upgrade a module select choose file and select "litmus edge ignition integration modl" and press install read and accept the litmus eula the module should now be installed navigate to config >modules there should now be a new header labeled litmus automation, inc with a module labeled litmus edge ignition integration verify that the version listed matches the expected version to read more about version see releases docid\ sd1vldcr7jcngzmqzhos installing for ignition 8 3 x download version 3 x x of the modl file from the litmus portal https //portal litmus io/accelerators/ignition integration open you ignition gateway with admin permissions navigate to platform >system >modules >install or updgrade a module select choose file and select the litrmus edge ignition integration 3 x x module and press install module when prompted with the module certificate mark i accept the module certificate and press trust certificate note, this will only happen on your initial installation of the module i f you are prompted with an error reading "module certificate already accepted" this is a known ui bug with ignition to resolve manually restart your ignition gateway and after restart you should be prompted to accept the module certificate and eula again after doing so the module will be correctly installed read and accept the litmus eula wait a few seconds, or refresh the page and you will be prompted with a gateway restart required prompt at the bottom of your screen when ready restart the gateway after you restart the module should be installed and running verify by navigating to platform >system >modules and identifying the litmus edge ignition module is installed and marked as active configuring the ignition module must be done after installing the ignition module docid\ sd1vldcr7jcngzmqzhos configuring ignition 8 1 x open the ignition gateway with the module installed with admin or higher permissions navigate to config >litmus edge integration >settings opening the config panel (if this page is not present, ensure that the module is correctly installed) in the configuration panel, ensure the properties match those in the ignition driver on your litmus edge instance when you are done press save changes after any setting change, restart the module by navigating to config >modules and pressing the restart button next to the module any changes you make to the module configuration may not apply until you restart the module ignition config menu configuring ignition 8 3 x open the ignition gateway with the module installed with admin or higher permissions navigate to connections >litmus edge >configuration opening the config panel (if this page is not present, ensure that the module is correctly installed) in the configuration panel, ensure the properties match those in the ignition driver on your litmus edge instance when you are done press submit form after any changes, wait a few seconds until the connection status reads connected healthy this signals a correct connection configuring litmus edge in your litmus edge instance, navigate to devicehub >devices >connect a device in the device creation window, select device type >ignition >ignition module in the device creation window, configure the device properties ensure that the network port you enter is open for both the litmus edge and ignition instances if you use the default value of 4778 you do not need to reconfigure the firewall in litmus edge when all properties are correct, press create device configure your ignition module docid\ sd1vldcr7jcngzmqzhos to match the same properties as the device litmus edge device creation panel connecting ignition module to litmus edge once both the device and the module are correctly configured, they should automatically connect indicated by the device appearing as connected in litmus edge if the module fails to connect, verify the module configuration and restart the module give it approximately 1 minute to reconnect enabling and using tls transport layer security (tls) allows data to be encrypted when being sent between the module and driver the module uses tls v1 3 enabling tls in litmus edge in your litmus edge instance, navigate to your devicehub > devices > \[your ignition device] > enable tls ensure both tls cert and tls private key are generated if using your own certificate, you can upload your certificate and private key, overriding the existing values press update to save your changes configuring tls in the ignition gateway ensure the module is installed in the ignition gateway navigate to config > litmus edge integration > settings > security settings enable use tls copy the tls certificate from the driver in litmus edge and paste it into the corresponding text field press if the module does not connect, you may have to restart the module to refresh the connection usage once connected, ignition tags can be added to the device using hierarchical browse this can be done in either of the following ways navigate to devicehub >tags > add tag > browse tags and select the ignition device navigate to devicehub >browse select the ignition device and create a new browse session once a tag is added, it can be read via the tag alias topic see browse tags docid\ akkxnvv6edvzaz40shbwm for more details see manage tags https //docs litmus io/litmusedge/product features/devicehub/tags/manage tags for more additional configuration of added tags currently, tags must preserve the name that is auto assigned to them during browsing which matches their tag path exactly (eg \[system]/time/timestamp) changing this tag name will cause the litmus and ignition tags to be dissociated hierarchy components in hierarchical browse are either folders or items folders contain child elements, whilst items produce data and have corresponding tags currently, tags must preserve the name that is auto assigned to them during browsing which matches their tag path exactly (eg \[system]/time/timestamp) changing this tag name will cause the litmus and ignition tags to be dissociated the hierarchy generated when browsing along with the correspondence of ignition tag types to browsing elements is the following root (folder) tag provider (folder) folder (folder) atomic tag (item) property (item) udt instance (folder) atomic tag (item) udt type (folder) property (item) the root element will always be present as the highest level element and will have all accessible tag providers as children writing tags tags which have write enabled in the ignition gateway can be written to from litmus edge using the write topic of the tag ensure the data is formatted correctly whilst writing, as conversion will be handled ignition side see use the write topic to send data to a plc docid\ tydbsngd7m4bgrohp41vc for more details user defined types (udts) ignition allows users to create their own structures for bundling multiple types of data into a single tag, called a udt udts are broken down into a collection of individual tags when imported into ignition see the browsing hierarchy docid\ sd1vldcr7jcngzmqzhos for more details supported tag types ignition type litmus edge type conversion boolean bool byte sbyte short int16 integer int32 long int64 float float32 double float64 string string datetime int64 uses file times https //learn microsoft com/en us/windows/win32/sysinfo/file times timestamp (100 nanosecond intervals since january 1 text string booleanarray boolarray bytearray sbytearray shortarray int16array integerarray int32array longarray int64array floatarray float32array doublearray float64array stringarray stringarray datetimearray int64array uses file times https //learn microsoft com/en us/windows/win32/sysinfo/file times timestamp (100 nanosecond intervals since january 1st, 1601) binarydata bytearray document dataset see document docid\ sd1vldcr7jcngzmqzhos for exact structure dataset dataset see dataset docid\ sd1vldcr7jcngzmqzhos for exact structure document document data follows a key value pair convention for associating elements to their values document elements have 3 fundamental types document primitives individual values, can have number, string, boolean, or datetime types ( ex 63, "cat", 1 234 ) document arrays contain an array of document elements of any type with a fixed order (ex \[123, {"pressure" 10 0, "temperature" 10}, "litmus"]) documents contain key value pairs, with string only keys and document element values of any type ( ex {"pressure" 10 0, "temperature" 10} ) document payloads are converted to dataset types, which can be interpreted as json payloads, with the following conversions document primitives are represented by a simple json value document arrays are converted to a json object with the following elements isarray boolean always set to true for arrays value json object with with indices as keys and values as elements ex {"isarray" true, "value" {"0" 72 2, "1" 232 2, "2" 2}}}} documents are converted to json objects with the following elements isarray boolean always set to false for documents (can be omitted during writing) value json object with the payload of the document ex {"isarray" false, "value" {"temperature" 10 0, "pressure" 10}} dataset an ignition dataset type is a table with a fixed amount of columns and rows each column has a fixed type and name when a dataset is read into litmus edge it is converted to a json payload with the following structure each column is represented by a json object with the following elements name string set to the name of the column type string representation of the datatype of the column (eg integer ) see supported tags docid\ sd1vldcr7jcngzmqzhos for a list of the ignition type names note color types are converted to strings and are represented by the type "object" data json object of the columns which each key corresponding to the row of the entry ex {"data" {"0" 10 2, "1" 83 2 }} the dataset is represented by a json object with keys corresponding to the index of each column ex {"0" {"name" "temperatures", "type" "float", "data" {"0" 10 2, "1" 2 3, "2" 56 7}}} alarms & events ignition supports alarms & events to allow the user to be notified when tag values meet certain conditions an alarm is always associated with a tag, and has a corresponding condition that will trigger an event an alarm event is an occurence when an alarm's conditions were met, it acts as a snapshot of an alarm activation alarms for each alarm in ignition, there is a corresponding alarm tag accessible in devicehub alongside the corresponding tag alarm tag browse alarm tags produce dataset json payloads with the following elements source simple path to the ignition alarm displaypath human readable path to the alarm if one is set, otherwise "" eventtime timestamp of the last instance of the last state change (triggering of an event) of the alarm state current state of the alarm from 0 3 0 clear and unacked (unacknowledged) 1 clear and acked (acknowledged) 2 active and unacked 3 active and acked eventid id of most recent corresponding event for the alarm priority integer from 0 4 indicating the set priority of the alarm 0 diagnostic 1 low 2 medium 3 high 4 critical alarm events alongside reading of tags, the ignition module allows you to read the status of alarms and events in real time into litmus edge via the static\ alarmeventrecords tag which will be present at the root of all ignition module devices which stores all active and unacked events in the ignition gateway alarm events record the alarm events record tag produces a dataset payload with a row column format with the following schema each row corresponds to an individual event in chronological order of most recently triggered first each row has the following columns eventid , source , displaypath , eventtime , state , priority see alarms for more details on the values of each colum writeback & acknowledgment the ignition module also allows event acknowledgement from directly within litmus edge using tag writeback writing a payload of {key0 event id0, key1 event id1, } to the static\ alarmeventrecords tag will acknowledge all events with ids \[event id0, event id1, ] with arbitrary keys (keys must be distinct, the use of sequential keys 0,1,2, etc is encouraged as best practice) ex "{"value" {"0" "34d3ce8f 5010 4d94 a6ca b9e9bd022f22", "1" "21b8c2da 3fc9 4067 bbf5 78fb0a444191"}}" writing to an invalid or non unacked event will cause the writeback to fail errors below are known errors that you may encounter when using the module and associated fixes tag failed mismatched data types the received value has the wrong type {"regid" registerid} the litmus edge device logs show the above error whenever the tag value type is incompatible with the source ignition tag data type (ex if the ignition tag has a type of double, but the le tag has a type of int64) this may occur whenever the user manually changes a tag value/data type in litmus edge or ignition to fix, verify the data type for the corresponding ignition tag and update value type of the litmus edge tag accordingly missing register can't find the register for the topic {"topic"" "devicehub module data (registerid)"}} the litmus edge device logs show the above error whenever the device is receiving data for a register which does not exist this may occur briefly whenever a litmus edge tag is deleted the issue should automatically be resolved after a few seconds when the module publish task stops if the issue persists, either restart the litmus edge device, or the ignition module registeradded failed to track if in the ignition gateway diagnostic logs you see the error registeradded event failed to track error message for controllerinstance this indicates that the ignition gateway failed to track a tag when it was added in le tag does not exist if you are seeing io litmus edgeintegration controller tagtracking tagtrackingexception tag does not exist \[tagprovider]/tagpath in the message trace this indicates that no tag has a matching provider and path validate the following the tag provider and path match exactly those from the target tag (ex \[sample tag]/folder1/folder2/tagname ) there is no trailing whitespace after the tag name while ignition tags support trailing whitespace in tag names, this is not supported by le tags and will be automatically trimmed missing data type if you are seeing io litmus edgeintegration controller tagtracking tagtrackingexception tag has no datatype \[tagprovider]/tagpath in the message trace this indicates that the ignition tag was found but is missing the datatype property validate that the tag has an associated data type if it is missing please assign one if there is a datatype present, unassign then reassign the datatype occasionally during bulk tag importing some properties are incorrectly registered to reconnect an le tag, select that tag and press update this will trigger another tag register event limitations data throughput as of v3 1 0 the module now safely supports up to 75k messages/second any messages above this threshold may result in data loss and increased latency release notes v3 1 0 fixed automatic reconnection after driver disconnect substantial performance and stability improvements now support up to 75k messages/sec improved connection status ui v3 0 1 updated to use free license for module v3 0 0 added support to ignition 8 3 rewrite of configuration menu with dynamic components substantial stability improvements to connection service v2 2 2 support millisecond precision for publishing interval support litmus edge version 3 27 0 and above v2 2 1 updated ignition sdk and java version v2 2 0 added read support for alarm and events allow acknowledgement of events via tag writeback add support for pollonce topics fix to timestamp reporting for tag payloads v2 1 0 added tls support tag subscribtion events are now tracked in the execution engine https //www docs inductiveautomation com/docs/8 1/platform/gateway/status/diagnostics execution v2 0 3 added read/write support for document and dataset types automatic reconnecting of ignition module to litmus edge devicehub after temporary device outage graceful recovery of module upon ignition gateway interruption