The Canary module
for Ignition 8

MODULE SUPPORTS 
VERSION 8.1.5 AND NEWER OF IGNITION.
Download Module

Current release - 23.0.1

Latest tested and supported version of ignition: 8.1.36
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.

For full functionality, this version requires Canary V23.0+ for getTagContext Views API endpoints but will function without it.

Features
- Annotations stored on a tag in the Canary Historian will now display in charts.

Bug Fixes
- Tags that have no history cause charts to stop functioning.
- All available API licenses are consumed when a screen containing many controls is opened.
- Annotations on virtual tags are failing to write to the Historian. The fix for this requires the getTagContext API endpoint added in Canary V23.0. Annotations made in Ignition on non-Virtual Views tags will write to the Historians as expected.

Module Documentation

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. The module supports version 8.1.5 and any newer version of Ignition.

As of version 8.1, Ignition will require the Tag Historian Module to be licensed for the Canary Module to function. This includes not only the logging of data but the reading of data as well. However, if you have been previously running Canary and Ignition together, Inductive Automation is willing to provide the license at no additional charge. Please contact your IA account representative to work out this compensation.

Installation

Begin by downloading the module above.
Install the module on your Ignition Gateway. If you are currently running a previous version of the module, simply install it over top of the existing one. In addition to the module, the following Canary Services must be installed on the Ignition Gateway using the Canary Installer if following the best practices:
- Admin Service
- Sender Service

This documentation assumes your Canary Historian Server is already configured. If you need to install and configure the Canary Historian Server, see this guide.

Note, as a best practice it is always recommended that the Canary Historian be installed separate from the Ignition Gateway, with only the Sender Service, Canary Admin, and Canary Module for Ignition installed local to the 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.

Configuration Of HistoriCAL Ignition Data To Canary

Open the Canary Admin application on your Ignition Gateway and navigate to the Sender tile.


Use the 'Configuration' menu (at the bottom) and then open the 'Endpoints' menu at the left. Ensure port 55253 is enabled and click 'Apply'.


Next, select 'Access' from the left menu and add 'ANONYMOUS LOGON' to the 'Allow' window and click 'Apply'.

Navigate to your Ignition Gateway and launch the Gateway Configuration in your browser.  Towards the bottom of the left menu, select 'Configure Collectors' under the 'CANARY' subheading.

Canary Collectors are responsible for logging data to the Canary Historian.  To create a new Canary Collector, select 'Create new Collector'.  Here you can configure Ignition to send data to Canary as a tag Storage Provider by completing the following fields:

Name:
The display name of the Storage Provider instance.

Sender Service:
Assuming you are following best practices and your Ignition Gateway is running on a Windows platform, this should be 'localhost'. If the Sender service is not installed locally on the gateway, specify the server name where the Sender service resides.

Sender Service Port:
55253 by default

Anonymous:
Enabled by default

Username, Change Password, and Password:
All unnecessary if Anonymous is enabled.  Leave blank.

Historian:
The machine name or IP address of the Canary Historian.  It is recommended this not be the same machine as the Ignition Gateway.

DataSet:
The name of the DataSet you wish to log all tags from this Storage Provider to.  As a best practice, it is recommended to keep each DataSet to less than 25,000 tags.  Additionally, the DataSet is part of a tag's name.  Logging the same tag to more than one DataSet will result in more than one historical record.  The DataSet will be automatically created for you within Canary as soon as you begin logging.

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 lowercase which will result in your Canary tag names being entirely lower case.  Note, that Canary is case-sensitive and will create separate historical tags if a case does not match.

Collector Enabled:
By default, this feature will be enabled.  Setting it to 'false' will suspend all tag logging for this Storage Provider.

Verbose Logging Enabled:
By default, this feature will be disabled.  Setting it to 'true' will provide additional data to the Ignition Logs which could be useful for debugging purposes.

Click 'Save Changes' 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

Open the Canary Admin application on your Canary Historian Server and navigate to the Views tile.

Use the 'Configuration' menu (at the bottom) and ensure port 55235 (Anonymous - Web API) is enabled and 'ANONYMOUS LOGON' is allowed within the 'Access' menu, clicking 'Apply' after each step.

*If needing to make a secure connection to the Views service, ensure port 55236 (Https - Username (Web API)) is enabled.
Navigate to your Ignition Gateway and launch the Gateway Configuration in your browser.  Towards the bottom of the left menu, select 'Configure Providers' under the 'CANARY' subheading.

To enable the reading of Canary History from Ignition, you will need to select 'Create new Provider' and configure Canary as a Tag History Provider within Ignition.  This can be done by completing the following fields:

History Provider Name:
The name you wish to be displayed as a Tag History Provider

Hostname:
Machine name or IP address of the Canary Historian.

Port:
Default to 55235.(*55236 if making a secure connection.)

Anonymous:
Enabled by default.

Username, Change Password, and Password:
Blank by default. If making a secure connection, a username/pw is required. The user specified here must have permission to the data within the Views service. These permissions are configured in the Views tile>Security tab (at the bottom)>Permissions tab (on the left).

Click "Save Changes" when complete.

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:

Ignition Aggregate Name
Time-weighted Average
Average
Min/Max
Closest Value
Last Value
Basic Average
Sum
Minimum
Maximum
Duration On
Duration Off
Count On
Count Off
Count
Range
Variance
Standard Deviation
Percent Good
Percent Bad

Canary Aggregate Called
TimeAverage2
TimeAverage2
Minimum2 and Maximum2
EndBound
End
Average
Sum
Minimum2
Maximum2
DurationInStateNonZero
DurationInStateZero
CountInStateNonZero
CountInStateZero
Count
Range2
VariancePopulation
StandardDeviationPopulation
PercentGood
PercentBad

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 indicated 'Canary Historian' as 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, that 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.

Vision - 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 historical data within Canary. Leaving the style set to 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 the 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 historical 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 the Polling Mode to Absolute or Relative will result in new data retrieval from Canary based on the Polling Rate.

Bug Report

Please report any bugs using the Canary Community Bugs or Issues section.