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 users using versions prior to version 2 2 1 are highly encouraged to upgrade to at least 2 2 1 of the module as previous versions rely on potentially vulnerable dependencies prerequisites verify you have an ignition instance running version 8 1 x or greater 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 installing the ignition module download the modl module file, either from the ignition module showcase or litmus central open your ignition gateway with admin or higher 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 agree to 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 ignition integration docid\ sd1vldcr7jcngzmqzhos configuring the ignition module must be done after ignition integration docid\ sd1vldcr7jcngzmqzhos 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 confiugration may not apply until you restart the module 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 ignition integration 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 save changes 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\ ml 1dnqkd6d zhzbe7qmw for more details see 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\ pzo1yg6enmdnkit hdxn6 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 ignition integration 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 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 timestamp (100 nanosecond intervals since january 1st, 1601) binarydata bytearray document dataset see ignition integration docid\ sd1vldcr7jcngzmqzhos for exact structure dataset dataset see ignition integration 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 ignition integration 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 release notes 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 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