Configuration
  • 31 Jan 2024
  • 14 Minutes to read
  • PDF

Configuration

  • PDF

Article Summary


Note:
Before starting the configuration, a new module instance must be created. Click here for more information about creating Module instances.

Each module has an API and Logger section that need to be configured separately. The default settings will be sufficient for this, but users will need to actively open the API and Logger configuration settings and save the default values to fully apply the settings. Click here for more information about API and Logger Configuration.
Note:
Please note that starting from N3uron version 1.21.5, the API section has been completely removed from the configuration options.


Upon selecting the MQTT Client instance, the following window will be shown: Figure - New Connection

Figure 1. MQTT Client settings


The MQTT Client module allows for unlimited connections to any number of brokers. As shown in the above screenshot, MQTT Client 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 1- ConfigFigure 2. Connection settings


  • Enable MQTT connection: Enable or disable the MQTT connection. When disabled it will not connect to the MQTT Server.
  • Version: Defines the MQTT version:
    • MQTT 3.X: The default version. Most commercial brokers use this version.
    • MQTT 5: The new version of MQTT. This version adds some new features. When MQTT 5.0 is selected, additional options will become available. 
  • 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 choice 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. 
    • 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.
    • Clean session: Sets the clean session flag of the MQTT connection:
      • If True, the connection will be made not persistent, which will make the server discard all data relevant to this connection after a disconnect.
      • If set to False, the connection will be made persistent, which means that subscriptions and messages with QoS >= 1 may be saved on the broker to be delivered when it reconnects.
    • 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.
    • Interval between messages: Specifies the time to wait between two successive messages while the buffer is emptying. Some brokers like Azure can only handle a limited number of published messages per second. Set to 0 to disable and send the next message immediately. 
    • Properties: This section is only available for MQTT 5. 
      • Session expiry interval: Specifies the session expiry interval between connections, displayed in seconds. This interval defines the period of time that the broker stores session information for.  
      • User properties: In MQTT 5, user properties are basic UTF-8 string key-value pairs that you canappend to virtually any sort of MQTT packet. As long as you don’t exceed the maximum message size, you'll use a limitless variety of user properties to feature information to MQTT messages and pass info between publisher, broker, and subscriber. It's possible to add as many properties as necessary. Figure 2 - Config


        Figure 3 - Config
  • Last will and testament: Sets a last will and testament for this connection, which will be sent by the broker when the connection falls 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.
    • Properties:  This section is only available for MQTT 5.
      • Will Delay Interval: Specifies the time delay when sending will messages, displayed in seconds. This prevents the will message from being sent during a short connection interruption. The default value is 0.
      • Message expiry interval: Specifies the message expiry interval, displayed in seconds. The default value is 0.  This interval defines the max period of time that the broker can store the PUBLISH message for any matching subscribers that are not currently connected. When no message expiry interval is set, the broker must store the message for matching subscribers indefinitely. When the retain=true option is set on the PUBLISH message, this interval also defines how long a message is retained on a topic.
      • User Properties: In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to virtually every sort of MQTT packet. As long as you don’t exceed the maximum message size, you'll use a limitless variety of user properties to feature information to MQTT messages and pass info between publisher, broker, and subscriber. It's possible to add as many properties as necessary. Figure - User properties 3
  • Agents: This is a list of all agents using this connection. Agents can be a Publisher 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. 

Publisher MQTT 3.X

The below screenshot shows an example of the Publisher configuration settings.Figure - Publisher settings 3X

Figure 3. 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. The default value is 60000ms. The valid range is 1000ms to 3600000ms.
    Note:
    Using small values with Store & Forward enabled may lead to a huge number of files generated while the connection is offline.
  • Mode: Selects the publisher operating mode. Available options are:
    • Events: Only new events will be published.
    • Snapshot: Tags are published regardless of whether or not they change, according to the value entered in the Push interval
      • Override timestamps: If enabled, the timestamp will be updated to the current time as the data is sent.
  • 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.
    • QoS 0 (at most once): The message is sent with no acknowledgment expected and it's as reliable as the underlying TCP connection. It's the fastest way of sending a message, but also the least secure.
    • QoS 1 (At least once): The message is sent and then acknowledged by the receiver. This guarantees the server receives the messages at least once, but it can cause repeated messages if the ACK is lost. Slower than QoS 0 but safer and the receiver needs to be able to deal with repeated messages.
    • QoS 2 (Once and exactly once): The safest way to send a message. It's guaranteed it will be delivered once and only once. It's also the slowest way to deliver a message. Some brokers, such as Microsoft Azure or AWS don't support this level of QoS.
  • Retain flag: Enables the retain flag on the published message. If True, the message will be retained by the broker and sent to all new clients who subscribe to that topic. Some brokers like AWS or Microsoft Azure don't support this feature.
  • Message options: These options are used to control the behavior of all packets generated by the publisher:
    • Max events per message: Specifies the maximum number of events to send or save in a single message. If this number is too high, some brokers might drop the message due to size limits. The minimum value is 10 events. The default value is 1,000.
  • 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. 
    Note:
    From N3uron version 1.21.4, the possibility to remove the S&F data is available.
    Figure - MQTT Trash


    Figure - MQTT Trash Message


    • 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/ConnectionName/ AgentName/
    • Max days in disk: Selects the maximum number of days to be stored in the disk. If exceeded, older packets will be deleted to make room.
  • Message format: These options control the format of the payload being sent to the MQTT broker.
    • Serialization: Selects the type of data serialization used. This can be JSON, Protocol Buffers, InfluxDB or Custom.
    • 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 filtersDefines and configures the filter for tags to be included in the message.
    Note:
    It is mandatory to add a filter even when the whole model is going to be published.
    • Mode: Selects whether the filter must include or exclude tags.  
      Note:
      Include filters are applied first and exclude filters are applied to the result of the include filters. 
    • Path: Specifies the path of the tag or group of tags to be filtered. 
    • Regex Pattern: This is a regular expression used to filter the tags that will be included. By default, it is set to .*, which means that no filter is applied. Readers can find further information about regular expressions at RegExr.

Publisher MQTT 5

The below screenshot shows an example of the Publisher configuration settings.

Figure - Publisher settings 5

Figure 4. Publisher settings


The configuration is the same as for MQTT 3.X, except that the following field is added: 

  • Properties:
    • Message expiry interval: Specifies the message expiry interval, displayed in seconds. When the retain=true option is set on the PUBLISH message, this interval also defines how long a message is retained on a topic.
    • User Properties: In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to virtually any sort of MQTT packet. As long as you don’t exceed the maximum message size, you'll use a limitless variety of user properties to feature information to MQTT messages and pass info between publisher, broker, and subscriber. It's possible to add as many properties as necessary.  Figure - User properties 4

Subscriber

A subscriber is an object used to receive data from MQTT-enabled devices and save this data to tags. 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. 

Subscriber MQTT 3.X

The following screenshot shows the configuration settings for a Subscriber:Figure - Subscriber 3X

Figure 5. 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.


Subscriber MQTT 5.0

The following screenshot shows the configuration settings for a Subscriber:

Figure - Subscriber 5

Figure 6. Subscriber settings


The configuration is the same as for MQTT 3.X except that the following field is added: 

  • Retain Handling: Specifies whether retained messages are sent when the subscription is established. This doesn't affect the sending of retained messages at any point after the subscription. This setting only applies whenever there are retained messages matching the Topic Filter.
    • At subscription time: Send retained messages at the time of the subscription.
    • If a subscription is new: Send retained messages at subscribe only if the subscription does not currently exist.
    • Never: Don't send retained messages at the time of the subscription.
  • Properties:
    • User Properties: In MQTT 5, user properties are basic UTF-8 string key-value pairs that you can append to virtually any sort of MQTT packet. As long as you don’t exceed the maximum message size, you'll use a limitless variety of user properties to feature information to MQTT messages and pass info between publisher, broker, and subscriber. It's possible to add as many properties as necessary.  Figure - User properties 5


Tag Configuration

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

Figure 8. MQTT Client 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.
    Note:
    For more information about using Alias, take a look at Parsing examples.

Was this article helpful?

What's Next