Publisher Overview (version 23)

The Publisher service provides four methods with which a user can provide real-time data to third party systems:

1. JSON payload over MQTT 3.1.1
2. SparkplugB 2.2 payload over MQTT 3.1.1
3. SparkplugB 3.0 payload over MQTT 3.1.1
4. JSON payload over a Websocket connection

Like other Canary services and clients, the Publisher requests data through the Views service; therefore, any virtual view is available in addition to the raw historian archive.

Status

The 'Status' screen will display any publishing sessions that are configured.

• NAME - a unique name identifying the publishing session
• TYPE - the type of publishing session, JSONMQTT, SparkplugMQTT, or Websocket
• ENDPOINT - the URI of the server and port number of where the data is being published to
  • MQTT (Unsecure) - tcp://machineName:1883/
  • MQTT (Secure) - tcp://machineName:8883/
  • Websocket (Unsecure) - ws://machineName:portNumber/
  • Websocket (Secure) - wss://machineName:portNumber/
• ENABLED - True or False, if the session is running
• STATE - the current state of the session
  • None - the session is disabled
  • Connected - the session is enabled and connected to the host server
  • Disconnected - the session is enabled but not connected to the host server
• CONNECTED SINCE - the date/time of when the session last connected to the endpoint
• DATA SENT - the amount of data that has been sent since the start of the session
• TAGS - the total number of tags that have been published since the start of the session
• ASSETS * - the total number of assets that have been published since the start of the session

*This column is only applicable when using the Websocket method.

Configuration

The 'Configuration' screen is where the user can configure a publishing session to send data via MQTT or Websocket. All sessions will appear in the 'CONNECTIONS' panel with their given name and type.

Settings (JSONMQTT)

• Name - a unique name identifying the publisher session
• Type - JSONMQTT
• Client Id - a name given to the publisher client that must be unique in the MQTT broker it is connecting to. If two clients with the same ID connect to the broker, the last one in wins. The client ID can be edited so that it is more user-friendly.
• MQTT Topic - the topic path to publish data to in the broker. This topic is open-ended and does not require a specific structure (unlike SparkplugB).
• Max Tags Per Message - a throttling mechanism that controls the amount of tags that are sent in a single message. This setting does not affect the birth message. (1≤ value ≤ 1 million)
• Durable Stream - if false, only the most recent value is published. If true, all value changes since the last publish are sent. Not recommended for high throughput streams where updates exceed 10,000 updates/sec.
• Publish QoS (Quality of Service) - the level of agreement between the Publisher and MQTT broker that a particular message has been received
  • AT MOST ONCE (QoS = 0) - also known as "fire and forget", there is no guarantee the broker received the message
  • At LEAST ONCE (QoS = 1) - guarantees the message has been sent at least once to the broker. Can be sent multiple times until the broker confirms it has received the message.
  • EXACTLY ONCE (QoS = 2) - the highest and slowest level of security that guarantees the message is sent exactly once

For more information on QoS, visit https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/

• Views Host - the server name of the Views service to which the Publisher is reading data from. Default value is 'LOCALHOST'.
• Views Path - the source view and path of the data the Publisher will send. This can be the raw historian view or any virtual view that has been created within the Canary Views service.
• Servers - the URI of the MQTT server to which the Publisher will send data to. The default setting is 'tcp://localhost:1883/' indicating an unsecure connection to a local broker. Servers can be added to support a high availability MQTT infrastructure. If the Publisher cannot connect to the first configured broker, it will try the next configured one. The Publisher connects to only one broker at a time.
• URI - allows the user to edit the server name and port number
• Username/Password - the credentials used to connect securely to the broker when SSL/TLS is enabled
• Reconnect Interval - the frequency at which the Publisher attempts to connect to the broker if there is a disconnect
• Keep Alive - the frequency at which the Publisher will call the broker to ensure the connection is still active. If the connection is very reliable, this can be set to 00:00:00.
• Clean Session - when checked, updates the broker with the Publisher's settings such as client ID, QoS, and primary host ID when it connects. This should almost always be checked.
• Enable SSL/TLS - used in conjunction with a username and password when connecting securely (8883) to a broker

Settings (SparkplugMQTT 2.2 and 3.0)

• Name - a unique name identifying the publisher session

• Type - SparkplugMQTT

• SparkplugB Version - 2.2 or 3.0. As of v23, Canary supports SparkplugB 3.0. (See SparkplugB 3.0 Compliance for more details.)

• Client Id - a name given to the publisher client that must be unique in the MQTT broker it is connecting to. If two clients with the same ID connect to the broker, the last one in wins. The client ID can be edited so that it is more user-friendly.
• SparkplugB Group Id - the group topic name in the SparkplugB structure
• SparkplugB Node Id - the node topic name in the SparkplugB structure
• SparkplugB Device Id - the device topic name in the SparkplugB structure
• SparkplugB Primary Id - (optional) a unique ID that must be configured on both the publisher and subscriber side so that the Publisher is aware when a subscriber is online or offline. If a subscriber using the same primary host ID disconnects from the broker, the Publisher is notified and will stop sending data. (Note: If using a primary ID, the Publisher will not send data to a broker until a subscriber connects using the same primary ID.)
• Alias tags - allows the Publisher to alias tag names using an integer index; therein, reducing the amount of data being sent
• Compression - compression options when sending data
  • NONE
  • GZIP
  • DEFLATE
• Publish Sub ms Time - if enabled, publishes the sub-milliseconds as a property of the metric value. This is only needed if wishing to consume the data back through using the Canary MQTT Collector for testing purposes.
• Max Tags Per Message - a throttling mechanism that controls the amount of tags that are sent in a single message. This setting does not affect the birth message. (1≤ value ≤ 1 million)
• Durable Stream - used in conjunction with the 'SparkplugB Primary Id', allows the Publisher to "buffer" data for subscribers that disconnect who are using the same primary ID. When the subscriber reconnects, the Publisher will start sending data from the time the subscriber disconnected so there is no data loss. Not recommended for high throughput streams where value updates exceed 10,000 updates/sec.
• Stream Flush Mode - visible when 'Durable Stream' is enabled
  • Synchronous - will flush historical data first until it gets to live data. Messages are flushed in order.
  • Asynchronous - live data will be published in parallel with historical data. Message are flushed out of order.
• Publish properties
  • DONT_INCLUDE - properties are never published
  • BIRTH_AND_CHANGE - properties are only published when a new tag comes online or the property of a tag changes
  • EVERY_TAG_VALUE_CHANGE - properties are published with each tag value change
• Publish QoS (Quality of Service) - the level of agreement between the Publisher and MQTT broker that a particular message has been received
  • AT MOST ONCE (QoS = 0) - also known as "fire and forget", there is no guarantee the broker received the message
  • At LEAST ONCE (QoS = 1) - guarantees the message has been sent at least once to the broker. Can be sent multiple times until the broker confirms it has received the message.
  • EXACTLY ONCE (QoS = 2) - the highest and slowest level of security that guarantees the message is sent exactly once

For more information on QoS, visit https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/

• Views Host - the server name of the Views service to which the Publisher is reading data from. Default value is 'LOCALHOST'.
• Views Path - the source view and path of the data the Publisher will send. This can be the raw historian view or any virtual view that has been created within the Canary Views service.
• Servers - the URI of the MQTT server to which the Publisher will send data to. The default setting is 'tcp://localhost:1883/' indicating an unsecure connection to a local broker. Servers can be added to support a high availability MQTT infrastructure. If the Publisher cannot connect to the first configured broker, it will try the next configured one. The Publisher connects to only one broker at a time.
• URI - allows the user to edit the server name and port number
• Username/Password - the credentials used to connect securely to the broker when SSL/TLS is enabled
• Reconnect Interval - the frequency at which the Publisher attempts to connect to the broker if there is a disconnect
• Keep Alive - the frequency at which the Publisher will call the broker to ensure the connection is still active. If the connection is very reliable, this can be set to 00:00:00.
• Clean Session - when checked, updates the broker with the Publisher's settings such as client ID, QoS, and primary host ID when it connects. This should almost always be checked.
• Enable SSL/TLS - used in conjunction with a username and password when connecting securely (8883) to a broker

Settings (WebSocket)

• Name - a unique name identifying the publisher session
• Type - WebSocket
• URI - server name and port number of where the Publisher is sending data to
• JSON Payload
  • Canary Defined
  • User Defined

                A 'Canary Defined' payload will use the following JSON structure:

                A 'User Defined' payload gives the user the option to create their own                 mappings.

• Views Host - the server name of the Views service to which the Publisher is reading data from. Default value is 'LOCALHOST'.
• Views Path - the source view and path of the data the Publisher will send. This can be the raw historian view or any virtual view that has been created within the Canary Views service.
• Asset - (optional) allows the user to publish an asset name and its tags according to the asset type selected. (Note: This option is only useful if assets are defined within a Virtual View that has been selected from the 'Views Path'.)
• Asset Filter - used in conjunction with 'Asset', filters out the asset names and their tags to be published
• Flush Interval - the frequency at which the Publisher pushes out updates. (Note: If the user desires to have every update published, the flush interval should be set lower than the rate at which a tag is logged. The Publisher only pushes the last value in the interval.)
• Keep Alive Interval - the frequency at which the Publisher will call the websocket host to ensure the connection is still active. If the connection is very reliable, this can be set to 00:00:00.
• Reconnect Interval - the frequency at which the Publisher attempts to connect to the websocket host if there is a disconnect
• Max Frame Size (bytes) - limits the amount of data that can be sent in each message
• Use Client Certificate - used when making a secure connection (wss://machineName:portNumber/). Certificates can be managed on the 'Settings' screen.

Settings

• Delayed Start Seconds - a general delay from when the service starts until data is actually published
• Views User - the client server name that will be used to connect to the  Views service. Used to control who has access to the data before being published.
• Views User GUID - a unique ID accompanied with the 'Views User' identifying the client connecting to the Views service
• Live Data Check Interval - the frequency at which the Publisher service checks for new data values within the Views service
• Views Change Check Interval - the frequency at which the Publisher service checks for changes in the Views service as it relates to new tags or assets
• Durable stream tag save interval - (MQTT only) the frequency at which the Publisher writes the status of the tags sent and their value to disk. If the connection is lost or a machine goes down, the Publisher can know where it left off when it resumes again. With an operation publishing 100k tags or more, the user must ask the question: How frequently do I want to save the status of the tags being published? The user must find the balance between duplicate data being published and system performance.
• Filter Views Time Extensions - if enabled, prevents the publisher from publishing the time-extended values that occur approximately once a minute within the historian for tags that are being actively logged, but have not received a new update within the last minute.

Client Certificate

The Publisher service will use this certificate when making a secure connection to an MQTT broker or websocket. To enable a secure connection, the user will need to ensure 'Enable SSL/TLS' or 'Use Client Certificate' is checked from the 'Configuration' screen.

• Store Name - the file location of the client certificate within the machine's certificate store
• Find Type - criteria by which the Publisher searches for the certificate
  • FindBySubjectName
  • FindByThumbprint
  • FindByTemplateName
• Subject Name - the value of the Subject Name or Thumbprint