How to Install and Configure the Canary Module for Ignition

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.

 

 

Installation

Begin by downloading the module above.

 

Install the module on your Ignition Gateway as well as the Canary Admin and 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 System 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 Writing Data To Canary

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

 

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

 

Next select 'Access' from 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.

 

Select 'Create new Collector' and configure Canary as a tag Storage Provider within Ignition 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', otherwise enter the machine name or IP address of where the Sender Service is located

 

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 your Canary Historian.  It is recommended this not be the same machine as your 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 automatically be corrected 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 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.

 

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 Writing Data To Canary

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

 

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

 

 

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.

 

Select 'Create new Provider' and configure Canary as a Tag History Provider within Ignition 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.

 

Anonymous:

Enabled by default.

 

Username, Change Password, and Password:

Blank by default.

 

 

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.

 

 

Canary Historian Integration To Ignition Components

The following Ignition Vision components work with the Canary Module.

• Table
• Power Table
• Easy Chart
• Chart
• Sparkline Chart
• Bar Chart
• Status Chart
• Pie Chart

The following Ignition Vision components have not been validated at this time to work with the Canary Module.

• Radar Chart
• Box & Whisker Chart
• Equipment Schedule
• Gantt Chart

The following Ignition Perspective components have been validated to work with the Canary Module but require tag path scripting.  Presently (Ignition v8.0.12) the Tag History Provider tag browser UI is not available within Perspectives.

• Time Series Chart
• Table
• Sparkline

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	Canary Aggregate Called
Time-weighted Average	TimeAverage2
Average	TimeAverage2
Min/Max	Currently not supported
Closest Value	EndBound
Last Value	EndBound
Basic Average	Average
Sum	Total2
Minimum	Minimum2
Maximum	Maximum2
Duration On	DurationInStateNonZero
Duration Off	DurationInStateZero
Count On	CountInStateNonZero
Count Off	CountInStateZero
Count	Count
Range	Range2
Variance	VariancePopulation
Standard Deviation	StandardDeviationPopulation
Percent Good	PercentGood
Percent Bad	PercentBad

 

Note: Canary does not currently provide a single aggregate that publishes two values.  As a result the Min/Max Ignition aggregate is not matched to a Canary aggregate and will return ‘null’ data.

 

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. Note, the Min/Max aggregate is not supported and will not return any values.

 

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.

 

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. Note, the Min/Max aggregate is not supported and will not return any values.

 

Table Settings And Resulting Canary Behavior

The Canary Module works in both Realtime and Historic Modes.  All aggregate modes except ‘Min/Max’ 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 a new data retrieval from Canary based on the Polling Rate.

 

Known Issues

Historical Data and Perspectives

 

Currently Canary can only function as a Tag History Provider for Perspective projects thru the scripting of tag paths.  The Tag History Provider U/I that was used for Vision has not yet been added to Perspectives limiting your ability to browse Canary tags.  To overcome this, prepend your Canary tag paths with the following:

[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. 

 

Deleting Tags

 

Deleting a tag currently does not pass a NoData value to the tag within Canary.  This means the tag will continue to have the timestamp extended and will appear to still be logging data.  This can be fixed with a module restart.

 

Releasing Tag Licenses

 

There is currently not a mechanism within the module to release a tag license.  This will be added to the next major release.  

 

Bug Report

Please report any bugs to info@canarylabs.com.