Configuration

Connection

A Connection object represents an MQTT connection to a specific broker. Each connection object has the following 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.
• Client ID: Defines the client ID for this connection. There must be a unique ID for each connection as the broker will drop any connections with duplicate client IDs. 
  • Pressing the refresh button generates a random Client ID.
    
    Note:

    This feature is available from N3uron version 1.21.8.

    
    

• Authentication: Refers to how the MQTT client will authenticate with the broker.
  • Authentication mode: Select one of several authentication modes: None, Password, Certificate, Password – Certificate, and JSON Web Tokens(JWT). When selecting JSON Web Tokens, additional options will appear.
  • Username: This field is used to specify the username used to authenticate with the broker.
  • Password: This field is used to specify the password used to authenticate with the broker. 
  • Certificate type: Determines how certificates will be provided, either as Embedded or via File path.
    • Embedded: Select this option to embed the certificate files directly into N3uron by selecting the files.
    • File path: Select this option to provide the path to the certificate files, either as an absolute path or a path relative to the data/<instance name>/cert/ folder.
      
      Note:

      This feature is available from N3uron version 1.21.10.
  • Certificate/Certificate Path: Selects the certificate used for authentication with the broker. For the Embedded certificate type, select the certificate file to embed it directly into N3uron. For the File Path type, provide the path to the certificate file, either as an absolute path or relative to data/<instance name>/cert/ folder.
  • Private Key/Private Key Path: Selects the private key used for authentication with the broker. For the Embedded certificate type, select the private key file to embed it directly into N3uron. For the File Path type, provide the path to the private key file, either as an absolute path or relative to data/<instance name>/cert/ folder.
  • CA Certificate/CA Certificate Path: Selects the root CA certificate used for authentication with the broker. For the Embedded certificate type, select the CA certificate file to embed it directly into N3uron. For the File Path type, provide the path to the CA certificate file, either as an absolute path or relative to data/<instance name>/cert/ folder.
  • Reject unauthorized: If the value is set to True, the server must provide a certificate signed by a valid CA, which will be used to establish the connection. Set it to False for self-signed certificates.
• Additional or Jwt options (referred to as Jwt from N3uron version 1.21.10) : If you have chosen JWT as your authentication mode, you will see the available options related to it.
  • Token duration: This field is used to specify the duration of a token until it needs refreshing, which may have a maximum limit set by some brokers. The token duration is displayed in milliseconds.
  • Header: 
    • Algorithm: It selects the algorithm used to generate the JWT. Valid options are RS256, RS384, RS512, HS256, HS384, HS512, ES256, ES384 and ES512.
    • Secret: This field is used to specify a secret used to sign the JWT. Only used when the algorithm is HS256, HS384, or HS512.
    • Private key: It 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.
    • 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: It can choose between using plain MQTT or secure MQTTS.
  • Broker URL: This field is used to specify the hostname or IP address of the target broker.
  • Port: It 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 set to 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.
  • Reconnect period: This field is used to specify the period between connection attempts when a connection drops, displayed in milliseconds.
  • Keep-alive interval: This field is used to specify the interval at which the client sends keep-alive packets to the broker, displayed in seconds.
  • Interval between messages: This field is used to specify 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: This field specifies the time interval in seconds for session expiry between connections. It determines how long the broker stores session information. 
    • 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.

      
      

      
• 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: This field specifies the topic to which the last will and testament will be sent.
  • Payload: This field specifies 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.
  • Properties:  This section is only available for MQTT 5.
    • Will Delay Interval: This field specifies the time delay when sending will messages, displayed in seconds. This parameter delays the sending of the will message during a brief connection interruption. Its default value is 0.
    • Message expiry interval: Specifies the message expiry interval, displayed in seconds. The default value is 0.  This interval defines the maximum period 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. 
• 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 associated with a single topic. 

Publisher MQTT 3.X

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

• Mode: This field specifies the publisher's 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. 
• Interval type (This section is only available for Snapshot mode):
  • Fixed time: The period starts counting when the module starts. For example, if the period is 30000 ms, and the module starts at 12:32:12, the transaction will execute on start, and every 30 seconds afterward, at 12:32:42. 
  • Fixed interval: The trigger becomes active at fixed points in time, depending on the given period. For example, if the period is 5 minutes, the trigger will activate at xx:00, xx:05, xx:10 etc. 
  • Cron: The action starts periodically based on a cron expression. If the script doesn't finish before the next scheduled time, that execution will be skipped.

• Max. Publishing interval: Sets the interval between each data push to the MQTT broker or 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 of Max. Publishing interval with Store & Forward enabled, may generate many files while the connection is offline.
• Max. events per message (This field is only available for Snapshot mode): 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.
  
• Override timestamps (This field is only available for Snapshot mode): If enabled, the timestamp will be updated to the current time as the data is sent.
• Events per message (This field is only available for Events mode): This field specifies the number of events ina a message. When this number of events is reached, a new message is generated and published. If the events per message are not reached within Max. Publishing interval, a message will be sent with the reached events.
  
• 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.
• 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/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.
    
    
    
    Note:

    From N3uron version 1.21.4, the possibility to remove the S&F data is available.
    

    
    

    
• 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 filters: Defines 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.