Required: DB Browser for SQLite or comparable SQLite database tool
The Canary MQTT collector utilizes a SQLite database for configuration settings. It is located at c:\programdata\canary labs\logger\storeandforward\mqttcollector\mqttcollector.sqlite (The base path can be modified by the system administrator and may vary from the default). The collector will automatically create the database configuration file upon first run.
To configure the collector:
- Open the database file with DB browser.
- Click on the “Browse Data” tab and select the “Servers” table in the drop down list
- Click on “New Record”
Enter information for each of the fields:
ID: Auto incremented field (leave default)
Host: (MQTT Server): IP address, machine name, or domain name (ex. Mqtttest.canarylabs.com or 192.168.0.1)
Port: (MQTT Server Port): Port number the mqtt server is listening on (standard ports are 1883 unsecure and 8883 for secure)
Secure: (Whether or not security is being used): 1 = true, 0 = false
SSL_Protocol: (type of security being used): 0 = none, 1 = SSLv3, 2 = TLSv1.0, 3 = TLSv1.1, 4 = TLSv1.2
Username: Username to use when connecting
Password: Password to use when connecting
Enabled: = 0 or 1. Set to 0. Controls whether the connection is enabled.
SenderSessionSessionKeepAliveInterval: Leave default (00:00:30) = 30 seconds. Canary sender session keep alive.
MQTTServerReconnectInterval: Leave default (00:01:00) = 1 minute
IgnoreSSLErrors: 0 or 1. Set to 1 if using security and a self-signed certificate on the mqtt server
CleanSession: 0 or 1: Set to 1 (default)
SessionKeepAlive: 0-65535 seconds: Leave set at 0.
MQTTClientId: This identifies the Canary collector within the MQTT broker (default = ‘Canary’)
IsPrimaryApplication: 0 or 1: Set to 1 to identify the Canary collector as the primary host to the MQTT devices. This is used to enable buffering of historical data at the device level if supported.
- Click File->Write Changes
Select the Subscriptions table
- Click ‘New Record’
Configure the subscription to the MQTT server
ID: Auto incremented field (leave default)
ServerID: This references the Servers table ID field of the record added to the servers table
TopicPath: This is the MQTT topic that you would like to subscribe to. All Sparkplug B topics start with spBv1.0/. The hash ‘#’ stands for multi-level wildcard whereas the ‘+’ is a single level wildcard. Sparkplug B topic names are in the format spBv1.0/<GroupName>/<MessageType>/<NodeName>/<DeviceName>.
Ex. spBv1.0/#subscribes to all tags on the MQTT server
spBv1.0/Group1/+/Node1/#subscribes to all tags under node ‘Node1’
spBv1.0/Group1/+/Node1/Device1 subscribes to all tags under device ‘Device1’
QOS_Level: 0,1,or2. Corresponds to the publish subscribe model in MQTT. Set this to 0.
Enabled: 0 (disabled), 1 (enabled and logging), or 2 (enabled and discover without logging). 0 and 1 are normal operating settings. 2 can be used upon initial startup to subscribe to the mqtt server, discover the tags, and preview what will be logged into Canary (via the SubscriptionTags table) before logging any data.
DatasetPrefix: The dataset that the subscribed tags will be written to. If the number of tags in the subscription exceeds the TagsPerDataset setting, then the discovered tags will be placed in additional datasets such as <DatasetPrefix>1, <DatasetPrefix>2, etc… If the SubscriptionSenderSession table AutoCreateDatasets setting = true, the datasets will be created automatically in the historian.
TagsPerDataset: Maximum number of tags to place in each dataset. Due to the dynamic nature of MQTT and the number of datapoints, this setting limits (for performance reasons) how many tags are placed in a dataset before creating more datasets.
RemoveFirstNBranchesFromTagName: Leave set to 0. This is used to truncate n levels from the beginning of the tag name to eliminate redundancy between tag name and dataset (shorter tag names). Use with caution as the more levels are removed, the more likely there will be for tag name conflicts and tags overwriting each other’s data.
- Click File->Write Changes
Select the SubscriptionSenderSessions table
- Click ‘New Record’
Configure the Canary target for the subscribed tag data
ID: Auto increment (leave default)
SubscriptionID: This references the Subscriptions table ID field of the subscription created
Historian: Canary historian machine. Ex. ‘localhost’
Dataset: Canary dataset into which the data will be logged. Ex. ‘MQTTData’
AutoGenerateHistorianTags: Not used (leave default). Current version always generates tags
Enabled: 0 (Disabled) or 1 (Enabled).
AutoCreateDatasets: 0 or 1. If = 1 the dataset will be created in the historian if it doesn’t exist.
ExternalPropertyStorage: 0 or 1. Leave default (0).
To log the same subscription data to multiple historians, add a record for each historian to the SubscriptionSenderSessions table that references the subscription.
- Click on File->Write Changes in DB Browser.
(Optional) Configure static properties (metadata) to assign to each tag in a particular subscription. Any configuration here will override any same name metadata coming from the mqtt subscription. Select the SubscriptionTagProperties table
- Click New Record
Configure the metadata for the subscription
ID: Auto increment (leave default)
SubscriptionID: This references the Subscriptions table ID field of the subscription created
PropertyName: Name of the metdata. Ex. ‘Eng Units’ or ‘Business Unit’
PropertyValue: Value to assign for all tags in the subscription. Ex. ‘psi’ or ‘1234’
- Click on File->Write Changes in DB Browser.
(Optional) Configure filters for the subscribed tags. This is helpful if you want to subscribe to the root of the MQTT broker (spBv1.0/#), but control which tags are logged into Canary. Filters utilize regular expressions for power and flexibility. There are many helpful tutorials online that can help in forming the correct expression filter. Open the SubscriptionFilters table
- Click New Record
Configure the filter for the subscription
ID: Auto increment (leave default)
SubscriptionID: This references the Subscriptions table ID field of the subscription created
MatchExpression: Regular expression to apply to the auto generated Canary tag name. The auto generated Canary tag name is formed by concatenating the Sparkplug B topic information (group id, node id, and device id) with the metric name. The concatenated string, which is delineated in Sparkplug B with forward slashes, is then modified by replacing the forward slashes with periods (which is what Canary uses as a hierarchy separator). Ex: Sparkplug B metric name ‘Compressor1/Tank/Pressure/PSI’ is published on Sparkplug B topic ‘spBv1.0/Texas/DBIRTH/West/PLC1’. The Canary tag name with this structure would be ‘Texas.West.PLC1.Compressor1.Tank.Pressure.PSI’. The configured filter would exclude any tags that end with ‘psi’.
Exclude: If true (default), the filter is exclusive. Otherwise, the filter is inclusive.
ExecOrder: For multiple filters, this controls which order the filter is executed in.
Rule filters are applied as such:
- Inclusive filters are applied first
If any inclusive filters are created, then none of the tags from the topic are included by default
If no inclusive filters are created, then all of the tags from the topic are logged by default
- If no inclusive filters are created, then all of the tags from the topic are logged by default
If no inclusive filters are created, then all of the tags from the topic are logged by default
- Rule filtering is applied to the auto generated Canary tag name minus the dataset.
- The auto generated name has some sanitation built into it for leading/trailing spaces in branch & tag names
- Click on File->Write Changes in DB Browser.
- Open the Canary Administrator
- Stop and Start the MQTT collector from the Canary Admin.
- Return to the home screen in the Administrator.
- Click on the MQTT collector tile:
- Click on the Enable button on the connection to connect to the server and start logging. If tag data is being published, the tags and TVQ/sec columns will reflect the activity. If errors are encountered, disable the connection and check the Messages for errors to diagnose the problem.
Comments
0 comments
Article is closed for comments.