Module Download and Installation Instructions (version 24)

Latest tested and supported version of Ignition: 8.1.43

If using 8.1.31 or 8.1.32, the provider name must match the collector name. A bug was introduced in 8.1.31 (and fixed in 8.1.33) that prevented the module from working properly without the names being the same.

The Canary Module for Ignition by Inductive Automation can be used to both write data from Ignition 8 projects to the Canary System as well as read historic and last known values from Canary and publish them to Ignition 8 projects. Versions of Ignition 7 are not supported.

As of version 8.1, Ignition will require the Tag Historian Module be licensed for the Canary Module to function.  This includes not only the logging of data but the reading of data as well.

Data Collection Installation

1. Download the latest module by clicking the button above.
2. Install the module on your Ignition Gateway server.
3. On the Gateway server, run the CanaryInstaller-*.*.*.exe and install the Admin Service, Identity (local or remote*), Store & Forward, and the Admin Client. Select Next.
   
   This documentation assumes your Canary Historian server is already configured.  If you need to install and configure the Canary Historian server, see this guide and refer to the Canary Historian Installation section.

   

   *If using best practices, the Identity service should be remote from the Ignition Gateway, installed along with the Historian. The user can specify the server location of the Identity service on the next screen if choosing the remote option. The Canary Historian should be installed on a separate server. Only the Admin Service, SaF, Admin Client, and Canary Module for Ignition should be installed local to the Ignition gateway. This ensures local data buffering should the Historian be disconnected from the network and will provide maximum resources to both the Historian as well as the Ignition Gateway.

4. Specify the server location of the Identity service if choosing the remote option, then choose where the software will get installed.

   

   Select Next then Install on the next screen to complete.
    
5. Navigate to the Ignition Gateway and launch the Gateway Configuration in the browser.  Towards the bottom of the left menu, select Configure Collectors under the CANARY subheading.

   

6. Select Create new Collector. Canary Collectors are responsible for logging data to the Canary Historian.  Here you can configure Ignition to send data to Canary as a tag Storage Provider by completing the following fields. Some fields are only applicable if running pre-v24 software that use the Sender service (as opposed to the Store and Forward service) and are indicated by an asterisk (*).

   

   • Name - The display name of the Collector. This name will appear when selecting a Tag History Provider in the Designer when history is enabled for a tag.
      
   • Canary Service - Assuming you are following best practices and your Ignition Gateway is running on a Windows platform, this should be 'localhost'; otherwise, enter the machine name or IP address of the Store and Forward (v24+)  or Sender (pre-v24) service.
      
   • Canary Service Port - 55293 if using v24+ of Canary software.

     55253 (anonymous) or 55254 (secure) if using anything prior to v24. 55254 is only needed if the Sender service is remote from the Ignition gateway and the user wants to make a secure connection to it. It is a best practice to have the Sender or SaF service installed locally to the Ignition gateway.

   • *Anonymous - Used to make an anonymous connection to the Sender service. Uncheck if using v24+.

   • *Username/Password - Only used if making a secure connection to the Sender service. Leave blank if using v24+.

   • API Token - Token used for secure access if Tag Security is enabled within the Identity service . This token can be used for both the Collector and Provider side of the module. The Canary user linked to the token should be given read/write permissions at the root View level within the Identity>Security>Tag Security screen.

     

     See How to Create an API Token.

   • Historian - The machine name or IP address of the Canary Historian. It is recommended this not be the same machine as your Ignition Gateway. You can send to multiple Historians by using a comma as a separator (e.g. Historian1, Historian2, etc.).

   • DataSet - The name of the DataSet you wish to log all tags from this Storage Provider. The DataSet will be part of a tag's name.

     As a best practice, keep each DataSet to less than 25,000 tags. If you think you will exceed this amount, edit the
     C:\ProgramData\Canary\StoreAndForward\store_and_forward.service.json file and set the DynamicDataSetIsEnabled parameter to True. This will create new DataSets as needed if you exceed 25,000 tags (e.g. DataSet, DataSet2, DataSet3, etc.).

   • Lower Case Tag Paths - By default Canary will copy the case structure of your Ignition tag names.  If you enable this field you will force all upper case to lower case and will result in your Canary tag names being entirely lower case.  Note, Canary is case sensitive and will create separate historical tags if case does not match.

   • Collector Enabled - Enables the Collector to send data to the Canary Historian.

   • Read/Connect/Write Timeout - Timeout settings the module uses to establish a connection with the SaF or Sender service. Do not change unless directed otherwise.

7. Click Create New CanaryCollectors when complete.  

You may create additional Collectors to enable additional logging to additional DataSets.  It is recommended you keep a 'one-to-one' relationship for your Collector sessions to DataSets, meaning do not create multiple Collectors logging to the same DataSet.  While this will work, it is not a best practice as you may later wish to individually manage your DataSets without interrupting the logging of data for your entire system.

Open your Ignition Project, and navigate to a tag you wish to enable history for.  Right-click on the tag and select Edit tag.

You may now enable history for your tag and select your newly created Canary Collector as the Storage Provider.  Since the module is built on top of Ignition's Tag History Module you can take advantage of all history settings including, deadbands, tag groups, and min/max times between samples.

Configuration Of Querying History From Canary

1. Open the Ignition Gateway Configuration settings and select Configure Providers under the CANARY subheading.
   
2. Select Create new Provider. By completing the fields, the user will be able to read data from the Canary Historian back into Ignition. Some fields are only applicable if running pre-v24 software and are indicated by an asterisk (*).

   

   • History Provider Name - Name to be displayed as a Tag History Provider within the Ignition Designer
      
   • Hostname - Machine name or IP address of the Canary Historian
      
   • Port - Views endpoint the module will connect to. 55236 if using v24+ of Canary software. 55235 (anonymous) or 55236 (secure) if using anything prior to v24.
      
   • *Anonymous - Used to make an anonymous connection to the Views service with pre-v24 software. Uncheck if using v24 as there is no longer an anonymous endpoint.
      
   • *Username, Change Password, and Password - Only used if making a secure connection to the Views service with pre-v24 software. Leave blank if using v24+.
      
   • Verbose Logging Enabled - By default, this feature will be disabled.  Setting to true will provide additional data to the Ignition Logs which could be useful for debugging purposes.
      
   • Annotation Collector - Allows annotations to be written to the Historian using the Power Chart control. Must be the name of the configured Canary Collector.
      
   • API Token - Token used to read data from the Views service. This can be the same token that is used on the Canary Collector side of the module. The Canary user linked to the token should be given read/write permissions at the root View level within the Identity>Security>Tag Security screen if not already there.

     

     See How to Create an API Token.

3. Click Save Changes when complete.

You may now open your Ignition Designer and browse the Canary Historian referenced above as a Tag History Provider.  Note, not only will you able to browse the historian archive, but Canary will also expose any Virtual Views and Asset Models created on top of the historical record.

Linking Ignition And Canary Terminology

Ignition offers several aggregates for viewing data based on intervals of time.  These Ignition aggregates are linked to Canary aggregates as follows:

Easy Chart Tag History Resolution Modes And Drawing Behavior

You should adjust your pen’s draw style within the Edit Pen menu to Line.  By default, Canary writes null values whenever a tag has been disconnected from the logging session.  Using the Line drawing style will result in the most accurate representation of the raw historic data within Canary.  Leaving the style set to the default Line w/ gaps will not result in accurate data depictions of Canary data.

The Canary Module Works With Both Historic, Manual, And Realtime Easy Chart Modes.  

When invoking each of the following Easy Chart Tag History Resolution modes, the following behavior will result within Canary.

Fixed

Canary will pass the start and end times of the Easy Chart as well as the selected aggregate as indicated within the Edit Pen menu found in the Easy Chart Customizer.  Additionally, the interval for the aggregate is determined by the Tag History Resolution value.  Ignition recommends ensuring the duration of the chart is evenly divisible by the value within the Tag History Resolution.  Canary will return the selected aggregate with a time interval equal to chart duration divided by the Tag History Resolution value.

Raw

Canary will return raw data values from the start time to the end time of the Easy Chart.

Natural

Canary will return raw data values from the start time to the end time of the Easy Chart.  You should adjust your pen’s draw style within the ‘Edit Pen’ menu to ‘Line’.  By default, Canary writes ‘null’ values whenever a tag has been disconnected from the logging session.  Using the ‘Line’ drawing style will result in the most accurate representation of the raw historic data within Canary.  Leaving the style set to the default ‘Line w/ gaps’ will not result in accurate data depictions.

If an Easy Chart is not showing values update in 'Realtime' mode, set the Tag History Property Mode to Natural to fix the issue.

Chart Width

Assuming there are more values than pixels available, Canary will return aggregated values of all values associated with each available pixel.  The aggregate applied is based on the selected aggregate as indicated within the Edit Pen menu found in the Easy Chart Customizer.

Table Settings And Resulting Canary Behavior

The Canary Module works in both Realtime and Historic Modes.  All aggregate modes are supported when the Sample Size is set to Fixed or Interval. See the chart above in the Linking Ignition and Canary Terminology section for additional aggregate information. When the Sample Size is set to On Change or Natural, Canary returns raw data without an aggregate applied.

The Fixed Sample Size will result in the total duration of time as represented by the Table being divided by the Fixed sample size value.  This will then be used as the Canary aggregate interval.  Ignition recommends keeping the duration of time evenly divisible by the interval to avoid a remainder.

The Interval Sample Size will result in the total duration of time as represented by the Table being divided by the Interval sample size as entered.  This will then be used as the Canary aggregate interval.

Setting Polling Mode to Absolute or Relative will result in new data retrieval from Canary based on the Polling Rate.

Tag Path

When needing to use the Canary tag path in scripting, the following example can be used:

[CanaryHistorian/default:default]canaryhistorian/Ignition 1/Pump 1

The above example indicates 'CanaryHistorian' is the name of your Provider as configured within the History Provider Name field.  Keep the 'default:default' and '[ ]' part of the path the same.  'canaryhistorian/Ignition 1/Pump 1' indicates the name of the Canary Historian Server (canaryhistorian), the DataSet (Ignition 1), and the tag name (Pump 1).  Note, your tag name will likely be must longer as Canary respects the folder structure found within Ignition.  Add the '/' between each part of tag name hierarchy.