How to Configure the MQTT Collector (version 20)

This version of the MQTT Collector runs as an SQLite database and, as such, requires a SQLite db tool to edit. It is recommended that you use DB Browser for SQLite (https://sqlitebrowser.org/) if you do not currently have another tool.

Create a New MQTT Collection Logging Session

The collector will automatically create the database configuration file upon first run.  To configure the collector, open the database file 'MQTTCollector.sqlite' with DB browser.  It is located in the Canary Labs ProgramData folder:

Canary Labs\Logger\StoreAndForward\MQTTCollector\MQTTCollector.sqlite

Configure ServerGroups


  1. Click on the 'Browse Data' tab and select the 'ServerGroups' table in the drop down list. New in v20.1 the collector now supports a group of mqtt brokers for high availability installations. Each group shares subscription and tag configuration across the list of servers configured.
  2. Click on 'New Record'.
  3. Enter information for each of the fields:
    1. ID: Auto incremented field (leave default)
    2. Name: Name of the group. Displayed in Canary Admin. Must be non-null
    3. Enabled: 0 or 1. Set to 0. Controls whether the group is enabled. This can be toggled from the Canary Admin
    4. MQTTClientId: This identifies the Canary collector within the MQTT broker and must be unique within the broker (default = Canary)
    5. 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.
    6. SendBirthRequests: 0 or 1: If set to 1, the collector will attempt to send node and device rebirth commands when it starts and wait for those birth messages from the device before logging. If set to 0, the collector will not send node and device rebirth commands when starting and will simply log any tag values published to the broker. If the nodes or devices publishing do not support rebirth commands, set this to false. Note: if the devices do not support rebirth commands, the collector may not discover all of the tags on the node or device until they rebirth at some point in the future.
  4. Click 'File' > 'Write Changes'.

Configure Servers

  1. Click on the 'Browse Data' tab and select the 'Servers' table in the drop down list.
  2. Click on 'New Record'.
  3. Enter information for each of the fields:
    1. ID: Auto incremented field (leave default)
    2. ServerGroupID: ID of the ServerGroups table record you want to associate this server to 
    3. Host (MQTT Server): IP address, machine name, or domain name (ex. Mqtttest.canarylabs.com or
    4. Port (MQTT Server Port): Port number the mqtt server is listening on (standard ports are 1883 unsecure and 8883 for secure)
    5. Secure (Whether or not security is being used): 1 = true, 0 = false
    6. SSL_Protocol (type of security being used): 0 = none, 1 = SSLv3, 2 = TLSv1.0, 3 = TLSv1.1, 4 = TLSv1.2
    7. Username: Username to use when connecting (if connecting anonymously put in a space)
    8. Password: Password to use when connecting (if connecting anonymously put in a space)
    9. MQTTServerReconnectInterval: Leave default (00:01:00) = 1 minute
    10. IgnoreSSLErrors: 0 or 1. Set to 1 if using security and a self-signed certificate on the mqtt server
    11. CleanSession: 0 or 1: Set to 1 (default)
    12. SessionKeepAlive: 0-65535 seconds: Leave set at 0.
  4. Click 'File' > 'Write Changes'.

Establish Subscriptions

  1. Click on the 'Browse Data' tab and select the 'Subscriptions' table in the drop down list.
  2. Click on 'New Record'.
  3. Configure the subscription to the MQTT server.
    1. ID: Auto incremented field (leave default)
    2. ServerGroupID: This references the ServerGroups table ID field of the record added to the ServerGroups table
    3. TopicPath: This is the MQTT topic that you would like to subscribe to. All Sparkplug B topics start with spBv1.0/  and are then followed by the topic namespace. The hash ‘#’ stands for multi-level wildcard whereas the ‘+’ is a single level wildcard.
      1. Sparkplug B topic names are in the format spBv1.0/<GroupName>/<MessageType>/<NodeName>/<DeviceName>.
      2. In order to ensure correct processing when ServerGroups.SendBirthRequests == true, please ensure that you do not subscribe to the device level. The collector needs contextual information from the node level to ensure correct template processing (e.g., spBv1.0/Group/+/Node/#).
      3. * In SparkplugB, the third level of the topic path refers to a specific command sent. Please ensure this is set to a ‘+’ so that the collector can receive all message types. Ex: spBv1.0/Group/+/Node/#.
      4. EXAMPLE: spBv1.0/# subscribes to all tags on the MQTT server where spBv1.0/Group1/+/Node1/# subscribes to all tags under node ‘Node1’
    4. QOS_Level: 0,1,or2. Corresponds to the publish subscribe model in MQTT. Set this to 0.
    5. 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.
    6. 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.
    7. 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.
    8. 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.
    9. AutoLogAllTags: 0 or 1. Set to 1. This setting determines whether tags discovered by the collector are automatically logged to the Canary historian. If set to 0, the user must set the Enabled status in the SubscriptionTags table after discovery to permit the tag to be logged. This setting permits the user to make a decision whether they want all tags in the historian or they want more control over those that are logged to it.
    10. Click 'File' > 'Write Changes'.

Configure the SubscriptionSenderSessions

  1. Click on the 'Browse Data' tab and select the 'SubscriptionSenderSessions' table in the drop down list.
  2. Click on 'New Record'.
  3. Configure the Canary target for the subscribed tag data.
    1. ID: Auto increment (leave default)
    2. SubscriptionID: This references the Subscriptions table ID field of the subscription created
    3. Historian: Canary historian machine server name or IP address
    4. AutoGenerateHistorianTags: Not used (leave default). Current version always generates tags
    5. Enabled: 0 (Disabled) or 1 (Enabled)
    6. AutoCreateDatasets: 0 or 1. If = 1 the DataSet will be created in the historian if it doesn’t exist
    7. ExternalPropertyStorage: 0 or 1. Leave default (0)
    8. Click 'File' > 'Write Changes'.

To log the same subscription data to multiple historians, add a record for each historian to the SubscriptionSenderSessions table that references the subscription.


Enabling the MQTT Collector

  1. Open the application Canary Admin
  2. Stop and restart the MQTT Collector service from the Services tile.
  3. Return to the home screen in the Administrator.
  4. Click on the MQTT Collector tile.
  5. Click on the 'Enable' button on the connection to connect to the server and start logging.
    1. If tag data is being published, the tags and TVQ/sec columns will reflect the activity.
    2. If errors are encountered, disable the connection and check the Messages tile for errors to diagnose the problem.
Reply Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular