Contents x
      Configuration
      • 16 Feb 2022
      • 11 Minutes to read
      • Print
      • PDF
      Contents

      Configuration

      • Updated on 16 Feb 2022
      • 11 Minutes to read
      • Print
      • PDF
      Article summary

      Upon selecting MqttClient, the following window will be shown: 

      Figure 3. MqttClient settings


      As shown in the above screenshot, MqttClient is configured by creating a list of named connections, where each Connection represents an MQTT connection to a specific MQTT broker. Many of the configuration options are MQTT terms, and although they are briefly explained here, a more in-depth explanation can be found at HiveMQ MQTT Essentials.

      Connection

      A Connection object represents an MQTT connection to a specific broker. Each connection object has the following settings: 

      Figure 4. Connection settings


      • Destination broker: This setting is used to select which broker to target. Valid options are Microsoft Azure, Amazon Web Services, Google IoT Core, and Custom. Depending on which broker is selected, some options will be locked to a certain value that is required for that broker. When set to Custom, all options will be available.
      • Authentication: Selects how the MQTT client will authenticate with the broker.
        • Authentication mode: Selects one of several authentication modes. Permitted values are None, Password, Certificate, Password – Certificate, and JSON Web Tokens. When JSON Web Tokens is selected, additional options will become available.
        • Username: Specifies the username used to authenticate with the broker.
        • Password: Specifies the password used to authenticate with the broker. 
        • Certificate: Selects the certificate used to authenticate with the broker. 
        • Private key: Selects the private key used to authenticate with the broker. 
        • Root CA certificate: Selects the root CA certificate used to authenticate with the broker. 
        • Reject unauthorized: If set to True, the connection will be rejected unless the server provides a certificate signed by a valid CA. Set to false for self-signed certificates.
      • Additional options: These options are shown when the selected authentication mode is JWT.
        • Token duration: Specifies how long a token will last until it needs refreshing. Some brokers, such as Google IoT Hub, have a maximum token duration. This value is displayed in milliseconds.
        • Header: 
          • Algorithm: Selects the algorithm used to generate the JWT. Valid options are RS256, RS384, RS512, HS256, HS384, HS512, ES256, ES384 and ES512.
          • Secret: Specifies a secret used to sign the JWT. Only used when the algorithm is HS256, HS384, or HS512.
          • Private key: Selects a private key used to sign the JWT. Used when the algorithm is either RSXXX or ESXXX.
        • Body:
          • Issuer: Sets the JWT issuer claim. 
          • Subject. Sets the JWT subject claim.
          • Audience: Sets the JWT audience claim. Required for Google IoT Core.
          • Not before: Sets the not before JWT claim.
          • JWT ID: Sets the JWT ID claim.
        • Additional claims: This list is only used if the broker requires additional claims in the body of the JWT.
      • Connection options: These options are used to connect to the broker:
        • Protocol: Selects either plain MQTT or secure MQTTS.
        • Broker URL: Selects the hostname or IP address of the target broker.
        • Port: Selects which port to use for connecting to the broker. Default ports are 1883 for MQTT and 8883 for MQTTS.
        • Client ID: Selects the client ID for this connection. Must be a unique ID for each connection, as the broker will drop any connections with duplicate client IDs.
        • Reconnect period: Selects the period between connection attempts when a connection drops, displayed in milliseconds.
        • Keep-alive interval: Selects the interval at which the client sends keep-alive packets to the broker, displayed in seconds.
      • Last will and testament: Sets a last will and testament for this connection, which will be sent by the broker when the connection disconnects unexpectedly (for example, in network failures).
        • Enable: Enables the last will and testament.
        • Topic: Selects the topic that the last will and testament will be sent to.
        • Payload: Selects the payload for the last will and testament.
        • Quality of service: Sets the quality of service level for the last will and testament. Valid values are 0, 1, or 2.
        • Retain flag: Enables the retain flag for the last will and testament.

      Agents: This is a list of all agents using this connection. Agents can be a Publisher, a Writer, or a Subscriber.


      Publisher

      A publisher is an object responsible for sending data to the MQTT broker. A connection can have multiple publishers, each of which is associated to a single topic. The below screenshot shows an example of the Publisher configuration settings.

      Figure 5. Publisher settings


      • Push interval: Sets the interval between each data push to the MQTT broker, or to the disk if the connection is offline and Store & Forward is enabled. This value is displayed in milliseconds. 
      • Topic: Specifies the topic for the published message. This can be any valid MQTT topic.
      • QoS: Specifies the QoS of the published message. Valid values are 0, 1, or 2.
      • Retain flag: Enables the retain flag on the published message.
      • Packet options: These options are used to control the behaviour of all packets generated by the publisher:
        • Max events per packet: Selects the maximum number of events permitted per packet. If this number is too high, some brokers may drop the packet. 
        • Send full packet: Determines publisher behaviour when a full packet (with the maximum number of events permitted) is created. Valid actions are either to send as soon as it has been created or wait until the push interval.
        • Max number of packets: Selects the maximum number of packets to store in the memory before saving to disk (or discarding, if S&F is not enabled). In general, users are recommended to keep this value as 1.
        • Interval between packets: Determines the time between sending one packet and the next. Some brokers only support a limited number of packets per second. Users can set this value to 0 to send each packet as soon as possible.
      • Store & Forward: These settings are used to configure the Store & Forward (S&F) mechanism, which is used to save packets to disk if they are unable to be sent (for example, due to connection loss). This ensures that no data is lost.
        • Enable: Enables or disables the S&F mechanism.
        • Path: Selects the path on the host machine’s hard drive to save data to. This path must be unique for each publisher. This path can either refer to the data folder of the current module instance (e.g. C:\Program Files (x86)\N3uron\data\MqttClientInstance\), or be an absolute path. The path can also be set to <null>, in which case the publisher will use the following default path: …/n3uron/data/MqttClientInstance/ConnectionInstance/ PublisherInstance/
        • Max packets in disk: Selects the maximum number of packets to be stored in the disk. If exceeded, older packets will be deleted to make room.
      • Payload options: These options control the format of the payload being sent to the MQTT broker.
        • Serialization: Selects the type of data serialization used. This can either be JSON or Protocol Buffers.
        • Data structure: Determines how the data is organized before serialization. Valid options are Compact or Extended. More information can be found in the appendix.
        • Date format: Determines how the timestamp of each event is formatted. Valid options are ISO (formatted according to ISO 8601), UNIX Epoch with milliseconds, or if the serialization is Protocol Buffer, Google Timestamp. 
        • Compression: Selects the payload compression (if desired). This can be set to None, Deflate, or GZip.
        • Compression level: If compression is enabled, this option determines the compression level. Valid values are Best speed, Default, and Best compression.
        • Encoding: Determines the encoding used when sending the payload to the broker. Valid encodings are UTF-8, Binary, Base64, and Hexadecimal. Some brokers don't accept binary encodings (such as those created from Protocol Buffers or where compression is involved), and as such, Base64 should be used to encode binary data into valid string characters.
      • Tag filters: In order for a Publisher to publish only a limited subset of the available tags in N3uron, one or various tag filters can be applied. More information about Tag Filters can be found here.

      Writer

      A writer is an object responsible for receiving write commands from the MQTT Broker. A connection can have multiple writers, each associated to a single topic. Writers are similar to Subscribers, although the main difference is that writers issue a write command to the underlying data provider for a specific tag, while a Subscriber acts directly as a data provider. See below screenshot for writer configuration settings:

      Figure 6. Writer settings


      • Topic: Selects the topic where Writer commands will be received. This topic will not accept wildcards.
      • QoS: Selects the Quality of Service of the MQTT subscription to the specified topic. Valid values are 0, 1, or 2.
      • Maximum write retries: Selects the maximum number of times a tag write will be attempted before being considered failed and subsequently ignored.
      • Retry interval: Selects the interval between tag write retries, displayed in milliseconds.
      • Payload options: These options are used to parse the message received from the broker. If the message is not parsed correctly, tag writes will not be issued.
        • Serialization: Determines the serialization format of incoming data. Valid options are either JSON or Protocol Buffers.
        • Data structure: Selects how the data is structured in the incoming message. This can either be Compact or Extended. More information can be found in the appendix. 
        • Compression: Selects the compression algorithm used to decompress the incoming message, if any. Valid values are None, GZip, or Inflate.
        • Encoding: Determines the encoding of the incoming message. Valid encodings are Binary, UTF8, Base64, and Hexadecimal.
      • Tag Filters: This list of tag filters can be used to filter which tags are allowed to receive write commands. By default, an empty list means that all writes commands will be issued. By defining one or more tag filters, only tags which match at least one of the filters will be allowed to be written by MqttClient. More information can be found in the Tag Filters section.


      Subscriber
      A subscriber is an object used to receive data from MQTT-enabled devices and save this data to tags. A Subscriber is similar to a Writer, although the main difference is that a Subscriber acts as a data provider for a tag, and as such, must provide a value, a quality, and a timestamp for each event. The following screenshot shows the configuration settings for a Subscriber:

      Figure 7. Subscriber settings


      • Topic: Selects the topic that will provide data for this Subscriber. Any valid MQTT topic is permitted, including wildcards.
      • QoS: Selects the Quality of Service level for the subscription to the broker. Valid values are 0, 1, or 2.
      • Keep-alive: These options are used to enable a keep-alive mechanism in order to check whether the device is still sending data, or, if the device has stopped sending data due to a possible device error.
        • Enable: Enables or disables the keep-alive mechanism.
        • Timeout: Determines the maximum delay between messages before the subscriber considers that the endpoint is experiencing a failure and has stopped sending data. If this delay is surpassed without any new messages, the quality of all tags associated with this subscriber will automatically be set to 64 (UNCERTAIN – LAST USABLE VALUE). If the subscriber receives a new message, the timer will be reset. 
      • Message format: Determines how the incoming message will be parsed.
        • Encoding: Determines the encoding of the incoming message. Valid values are Binary, UTF-8, Base64, and Hexadecimal.
        • Compression: Selects which algorithm to use to decompress the message. Valid values are None, GZip, and Inflate.
        • Serialization: Determines the serialization format of the incoming message. Valid values are None, JSON, and Protocol Buffers. If None is selected, the message will be passed to the Data parser as a binary buffer. Alternatively, it will be converted into a JS object, either by using JSON.parse or by de-serializing the Protocol Buffers message.
      • Serialization options: These options are only available when using Protocol Buffers deserialization. They are additional settings that must be configured in order for the deserialization to work.
        • Proto file type: Selects the protobuf file used to deserialize the message. This can be the embedded protobuf file, or a custom file.
        • Custom file: Selects the custom protobuf file when the file type is set to custom.
        • Message type: Selects the target message type when deserializing using Protocol Buffers. If an incoming message cannot be deserialized to the specified type, an error will be raised and the message will be ignored.
      • Data parser: After a message is deserialized, the resulting object from the deserialization is forwarded to the data parser, which is used to extract tag data from the input object.
        • Type: Determines the type of data parser used. Valid options are MqttClient JSON, MqttClient Protobuf (both of which are compatible with any MqttClient Publisher sending either JSON or protobuf), or custom, whereby a user defined script will be used to extract the tag data from the message. 
      • Parser options: When the data parser is set to custom, these additional options must be configured in order for the data parser to work correctly.
        • Script: Determines the script used to extract the tag data from the input object (or binary buffer, if no deserialization is applied). This must be valid JavaScript code that will consume the input and produce an array of tag data objects. More information about the utilities available to scripts can be found here. Or, see here for subscriber specific features.

      Tag Filters

      Tag Filters, as their name implies, are used to filter which tags are affected by a specific publisher or writer. For a publisher, all tags matching the active filter are sent to the broker, whilst for a writer, only tags matching a specified filter can be written to. The configuration settings for a tag filter are shown in the following screenshot.

      Figure 8. Tag Filter settings


      • RegEx pattern: Selects a Regular Expression to be used as a pattern for the tag filter. Most features of regular expressions are supported. Some of the unsupported features include lookbehinds or atomic groups.
      • Ignore case: Enables the //i (ignore case) flag for the regular expression.  

      Tag configuration

      When using MqttClient as a tag provider via one or more Subscribers, tags must be configured separately from the module. The below screenshot shows the MqttClient tag configuration settings:

      Figure 9. MqttClient tag settings


      • Subscriber: Selects the subscriber that will provide data to this tag. The format for this input is Connection/Subscriber. If either the connection or subscriber is incorrect, an error will be raised and the tag will not receive any updates.
      • Tag address: Determines an alias for this tag so that it can be referenced using this alias rather than having to use the full path. If provided, the tag can only be referenced using this alias. Alternatively, where an alias is not provided, the tag must be referenced using its full path.

      Was this article helpful?
      What's Next
      .
      Platform
      Company
      Resources
      Solutions
      Download N3uron
      FOLLOW US
      Sales and Support
      Copyright © N3uron Connectivity Systems. All Rights Reserved.