MIMIC® Online Documentation

<< Previous Section    Next Section >>

MIMIC MQTT Protocol Module Guide

  1. Table of Contents

  2. Overview

    The MIMIC MQTT Protocol Module is an optional facility that simulates the Internet of Things (IoT) Message Queue Telemetry Transport (MQTT) standard version 3.1.1 as detailed on the OASIS site and ISO , as well as limited support for the new MQTT 5.0 . TLS v1.3 , 1.2 and 1.1 is supported.

    Each MIMIC agent instance configured with MQTT acts as a publisher client (eg. a sensor ) that connects to the broker (system under test) and publishes the configured messages for third-party subscriber clients to consume. In addition, it can act as a subscriber client, eg. for a control channel, or to do end-to-end latency testing.

    MIMIC supports both scenarios of a different IP address per simulated device instance (agent), as in a LAN at the edge, or same IP address for any number of them, as behind a NAT device.

    Any type of payload is supported, whether ASCII, JSON or binary, whether stateless or stateful. For example, we have implemented the widely used Sparkplug , SmartREST , LWM2M-MQTT and TR50 standards, as well as a variety of ad-hoc schemes.

    Compatibility with various on-site and cloud-based brokers is documented in the section below.

    Back to Top

  3. Installation

    MQTT support is made available in MIMIC as an optional dynamically loadable module. Starting with MIMIC 16.00, you can use the Protocol Wizard to install the MQTT module. If you prefer to enable MQTT by hand, you need to do the following:

    • Use File->Terminate to stop the any running MIMIC daemon.

    • Copy the MQTT shared library (mqtt.dll on Windows, mqtt.so on Unix) from "bin/dynamic/optional" to "bin/dynamic" in the install directory.

    • Install the license keys as detailed in the instructions e-mailed to you.

    • Restart MIMIC. You should see the following type of message in the MIMICLog that confirms that the MQTT module was properly loaded : 
      INFO  - MQTT : Loaded protocol from < path-to-DLL >
INFO  - MQTT v16.00

    Once MQTT is loaded, any agent instance configured to support the MQTT protocol will be able to publish MQTT messages to a MQTT broker.

    Back to Top

  4. Using MQTT from MIMICView

    If the MQTT module is enabled, then Agent->Add, Agent->Configure and Agent->Paste dialogs will display MQTT as an additional checkbox in the Advanced pane along with the SNMP protocols. On selecting the checkbox a new MQTT pane will appear.

    This MQTT configuration pane lets the user configure the parameters for a MQTT session:

    • Config file

      This mandatory parameter specifies the MQTT configuration file, to determine what MQTT packet is generated by the corresponding sensor. You will not be able to start the agent unless this parameter is set.

      The configuration file is detailed below. You can edit configuration files directly.

    • Broker Address

      This mandatory parameter specifies the address of the broker server.

    • Port

      This optional parameter specifies the broker port to use. The default port is 1883.

    • Client ID

      By default, the client identifier field in the CONNECT message will be a string like mimic/mqtt/00001, the last number indicating the agent instance number. You can override this string with this configurable. If the string ends with #, then this is meant to be a prefix, and the client identifier sent to the server will replace the # with the agent instance number.

    • Username

      This optional parameter specifies the username to use.

    • Password

      This optional parameter specifies the username to use.

    • Version

      This optional parameter specifies the MQTT version to use. You can set this to 3.1.1 or 5.0. By default, version 3.1.1 is used.

    • Use TLS

      This optional boolean parameter determines whether TLS security is enabled for this simulated sensor. The default is false.

    • TLS Config File

      If the sensor is configured to Use TLS security as above, then this parameter specifies the TLS configuration to use. If no configuration file specified, the agent's TLS client will not have a default certification. To use the sample certification included in MIMIC installation, you need to load the tls.cfg file.

    NOTE: if configuring a large number of agents at different IP addresses, and if SNMP access to the device is not required, there is a performance benefit in configuring non-privileged ports for the SNMP agent (reference 5377). After MIMIC 20.00, if SNMP is not needed, it's best to disable the SNMP protocol.

    Back to Top

  5. Using MQTT from MIMICShell

    A few new commands and some enhanced old commands can be used from the MIMICShell to control the MQTT functionality. Here is a synopsis:

    • mimic protocol msg MQTT get args

      This command lets the user gather the self-defining list of arguments required and their particulars. The parameters are detailed above. A sample exchange for this command would be: 

      mimicsh> mimic protocol msg MQTT get args
{{filename} {Config File} {file} {scripts/mqtt {{*.cfg {MQTT config files}
 {edit yes} {new yes}}} - both} {mandatory} {}}
{{broker} {Broker Address} {string} {} {mandatory} {}}
{{port} {Port} {integer} {} {optional} {1883}}
{{clientid} {Client ID} {string} {} {optional} {}}
{{username} {Username(blank for all-access)} {string} {} {optional} {}}
{{password} {Password(blank for all-access)} {string} {} {optional} {}} 
{{version} {Version} {string} {} {optional} {}} 
{{is_tls} {Use TLS} {boolean} {} {optional} {false}}
{{tls_conf_filename} {TLS Config (Optional)} {file} {config/mqtt
 {{*.cfg {TLS config files} {edit yes} {new yes}}} - both} {optional} {}}

    • mimic agent get protocol

      This command lets the user look at the protocols currently configured on the agent. A sample exchange for this command would be: 

        mimicsh> mimic agent get protocol
  snmpv1,snmpv2c,MQTT

    • mimic agent set protocol

      This command lets the user change the protocol setting for an agent. A sample exchange for this command would be: 

        mimicsh> mimic agent get protocol
  snmpv1
  mimicsh> mimic agent set protocol snmpv1,MQTT
  mimicsh> mimic agent get protocol
  snmpv1,MQTT

    • mimic agent protocol msg MQTT get config

      This command lets the user get the current argument settings. A sample exchange for this command would be: 

        mimicsh> mimic agent protocol msg MQTT get config
  {filename=mqtt1.cfg} {broker=2001:a18:1:10:d6be:d9ff:fecb:589f} {port=1883} {clientid=}
  {username=} {password=} {version=} {is_tls=false} {tls_conf_filename=}

    • mimic agent protocol msg MQTT set config [config]

      This command lets the user change the current argument settings of all MQTT sessions for an agent. A sample exchange for this command would be: 

        mimicsh> mimic agent protocol msg MQTT get config
  {filename=mqtt1.cfg} {broker=2001:a18:1:10:d6be:d9ff:fecb:589f} {port=1883} {clientid=}
  {username=} {password=} {version=} {is_tls=false} {tls_conf_filename=}

  mimicsh> mimic agent protocol msg MQTT set config \{broker=192.9.200.71\}

  mimicsh>  mimic agent protocol msg MQTT get config
  {filename=mqtt1.cfg} {broker=192.9.200.71} {port=1883} {clientid=}
  {username=} {password=} {version=} {is_tls=false} {tls_conf_filename=}

  mimicsh> mimic agent protocol msg MQTT set config \{filename=mqtt2.cfg\}

  mimicsh>  mimic agent protocol msg MQTT get config
  {filename=mqtt2.cfg} {broker=192.9.200.71} {port=1883} {clientid=}
  {username=} {password=} {version=} {is_tls=false} {tls_conf_filename=}

    • mimic agent protocol msg MQTT get trace
      mimic agent protocol msg MQTT set trace [0 or 1]

      This command lets the user change the MQTT tracing configuration for an agent. A sample exchange would be: 

        mimicsh> mimic agent assign 1

  mimicsh> mimic agent protocol msg MQTT get trace
  0
  mimicsh>  mimic agent protocol msg MQTT set trace 1

  mimicsh> mimic agent protocol msg MQTT get trace
  1
      and the log would show: 

      INFO  01/05.09:42:35 - agent 1 trace enabled for MQTT
INFO  01/05.09:42:51 - agent 1 loaded device
INFO  01/05.09:42:51 - MQTT[AGT=1] - sent CONNECT (30 bytes)
INFO  01/05.09:42:51 - MQTT[AGT=1]: client started
INFO  01/05.09:42:51 - MQTT[AGT=1] - rcvd CONNACK (4 bytes)
INFO  01/05.09:43:00 - MQTT[AGT=1] - sent PUBLISH (119 bytes)
INFO  01/05.09:43:00 - MQTT[AGT=1] - rcvd PUBACK (4 bytes)
...

    • mimic protocol msg MQTT get stats_hdr
      mimic agent protocol msg MQTT get statistics

      Returns MQTT statistics information:

      • a list of statistic headers, and
      • current statistics values for the specified client.

      In order, the statistic values are:

      • Total number of client TCP connections
      • Total number of client TCP disconnects
      • Total number of PUBLISH sent.
      • Total number of packets sent.
      • Total number of packets received.
      • Total number of packets discarded.
      • Total number of connections aborted.
      • Total number of CONNECT sent.
      • Total number of CONNACK received.
      • Total number of CONNACK errors.
      • Total number of PINGREQ sent.
      • Total number of PINGRESP received.
      • Total number of PUBLISH sent.
      • Total number of PUBLISH payload bytes sent.
      • Total number of PUBACK received.
      • Total number of PUBREC received.
      • Total number of PUBREL sent.
      • Total number of PUBCOMP received.
      • Total number of PUBLISH received.
      • Total number of PUBLISH payload bytes received.
      • Total number of PUBACK sent.
      • Total number of PUBREC sent.
      • Total number of PUBREL received.
      • Total number of PUBCOMP sent.
      • Total number of SUBSCRIBE sent.
      • Total number of SUBACK received.
      • Total number of UNSUBSCRIBE sent.
      • Total number of UNSUBACK received.
      • Total number of DISCONNECT sent.
      • Total number of DISCONNECT received.
      • Total number of CONNACK discarded.
      • Total number of PUBLISH discarded.
      • Total number of PUBACK discarded.
      • Total number of PUBREC discarded.
      • Total number of PUBCOMP discarded.
      • Total number of SUBACK discarded.
      • Total number of PINGRESP discarded.

      A sample exchange for these commands would be: 

        mimicsh> mimic protocol msg MQTT get stats_hdr
  {{connect} {Connect}} {{disconnect} {Disconnect}} {{published} {Published}}
  {{pktSnt} {PktSent}} {{pktRcv} {PktRcvd}} {{pktDisc} {PktDisc}}
  {{abort} {Abort}} {{CONNECTsent} {CONNECTsent}} {{CONNACKrcvd} {CONNACKrcvd}}
  {{CONNACKerr} {CONNACKerr}} {{PINGREQsent} {PINGREQsent}}
  {{PINGRESPrcvd} {PINGRESPrcvd}} {{PUBLISHsent} {PUBLISHsent}}
  {{PUBLISHsentbytes} {PUBLISHsentbytes}} {{PUBACKrcvd} {PUBACKrcvd}}
  {{PUBRECrcvd} {PUBRECrcvd}} {{PUBRELsent} {PUBRELsent}}
  {{PUBCOMPrcvd} {PUBCOMPrcvd}} {{PUBLISHrcvd} {PUBLISHrcvd}}
  {{PUBLISHrcvdbytes} {PUBLISHrcvdbytes}} {{PUBACKsent} {PUBACKsent}}
  {{PUBRECsent} {PUBRECsent}} {{PUBRELrcvd} {PUBRELrcvd}}
  {{PUBCOMPsent} {PUBCOMPsent}}
  {{SUBSCRIBEsent} {SUBSCRIBEsent}} {{SUBACKrcvd} {SUBACKrcvd}}
  {{UNSUBSCRIBEsent} {UNSUBSCRIBEsent}} {{UNSUBACKrcvd} {UNSUBACKrcvd}}
  {{DISCONNECTsent} {DISCONNECTsent}} {{DISCONNECTrcvd} {DISCONNECTrcvd}}
  {{CONNACKdisc} {CONNACKdisc}}
  {{PUBLISHdisc} {PUBLISHdisc}} {{PUBACKdisc} {PUBACKdisc}}
  {{PUBRECdisc} {PUBRECdisc}} {{PUBRELdisc} {PUBRELdisc}}
  {{PUBCOMPdisc} {PUBCOMPdisc}} {{SUBACKdisc} {SUBACKdisc}}
  {{UNSUBACKdisc} {UNSUBACKdisc}} {{PINGRESPdisc} {PINGRESPdisc}} 


  mimicsh> mimic agent protocol msg MQTT get statistics
  1 0 2 11 11 0 0 1 1 0 1 1 2 48 0 2 2 2 2 48 0 2 2 2 1 1 0 0 0 0 0 0 0 0 0 0

    • mimic agent protocol msg MQTT client get state

      This command lets the user query the state of the client. This is particularly useful at agent startup time to wait for MQTT client startup. A sample exchange for this command would be: 

        mimicsh> mimic agent protocol msg MQTT client get state
  0
  mimicsh> mimic agent start

  mimicsh> while { ! [mimic agent protocol msg MQTT client get state] } {
  	sleep 1
  }

    • mimic agent protocol msg MQTT client get protstate

      This command returns the protocol state of the client. The following are the values:

      • 0 - stopped

      • 2 - disconnected

      • 3 - connecting

      • 4 - connected

      • 5 - waiting for CONNACK

      • 6 - waiting for SUBACK

      • 7 - CONNACK received, in steady state

    • mimic agent protocol msg MQTT client set broker [BROKER-ADDR]
      mimic agent protocol msg MQTT client set port [PORT]
      mimic agent protocol msg MQTT client set clientid [CLIENTID]
      mimic agent protocol msg MQTT client set username [USERNAME]
      mimic agent protocol msg MQTT client set password [PASSWORD]
      mimic agent protocol msg MQTT client set willtopic [TOPIC]
      mimic agent protocol msg MQTT client set willmsg [MSG]
      mimic agent protocol msg MQTT client set willretain [RETAIN]
      mimic agent protocol msg MQTT client set willqos [QOS]
      mimic agent protocol msg MQTT client set cleansession [0 or 1]
      mimic agent protocol msg MQTT client set keepalive [KEEPALIVE]
      mimic agent protocol msg MQTT client set on_disconnect [ACTION]

      You can change these configurable parameters for the MQTT client after agent startup provided that the agent is HALTED and not connected to a broker (ie. mimic agent protocol msg MQTT client get protstate returns 2). For example: 

      mimicsh>  mimic agent protocol msg MQTT get config
{filename=mqtt2.cfg} {broker=192.9.200.71} {port=1883} {clientid=}
{username=} {password=} {version=} {is_tls=false} {tls_conf_filename=}

mimicsh> mimic agent start

# if the agent has a start action script that sets it's state to HALTED,
# then the MQTT client does not establish a connection

mimicsh> mimic agent get state
3
mimicsh> mimic agent protocol msg MQTT client get protstate
2
mimicsh> mimic agent protocol msg MQTT client set broker iot.eclipse.org

    • mimic agent protocol msg MQTT client runtime abort
      mimic agent protocol msg MQTT client runtime disconnect
      mimic agent protocol msg MQTT client runtime connect

      To control the client session at runtime, these commands allow you to abort the session (without sending a DISCONNECT command), disconnect gracefully from the server, and re-connect, respectively. For example: 

      mimicsh> mimic agent start

mimicsh> mimic agent protocol msg MQTT client get state
1
mimicsh> mimic agent protocol msg MQTT client get protstate
6
mimicsh> mimic agent protocol msg MQTT client runtime disconnect

mimicsh> mimic agent protocol msg MQTT client get state
1
mimicsh> mimic agent protocol msg MQTT client get protstate
2
mimicsh> mimic agent protocol msg MQTT client runtime connect

mimicsh> mimic agent protocol msg MQTT client get state
1
mimicsh> mimic agent protocol msg MQTT client get protstate
6
mimicsh>  mimic agent protocol msg MQTT client runtime abort

mimicsh>  mimic agent protocol msg MQTT client get protstate
2

    • mimic agent protocol msg MQTT client message card
      mimic agent protocol msg MQTT client message get [MSGNUM] [ATTR]
      mimic agent protocol msg MQTT client message set [MSGNUM] [ATTR] [VALUE]

      To control message generation by the client at runtime, these commands allow you to get and set message simulation parameters. The first parameter returns the cardinality of the messages, ie. 0 or more. You can then control each message (starting at 0) with the get and set commands.

      ATTR (defined in message configuration below can be one of the following:

      • topic
      • interval
      • count
      • sent (cannot set)
      • pre
      • post
      • properties (cannot set) - list of PUBLISH properties
      • properties.i - i-th PUBLISH property
      • properties.PROP-NAME - PUBLISH property with name PROP-NAME

      Eg. to PUBLISH exactly one of the first configured message on demand (where count was configured to 0): 

      mimicsh> mimic agent protocol msg MQTT client message card
1
mimicsh> mimic agent protocol msg MQTT client message get 0 count
0
mimicsh> set sent [mimic agent protocol msg MQTT client message get 0 sent]
0
mimicsh> incr sent
1
mimicsh> mimic agent protocol msg MQTT client message set 0 count $sent
# message is PUBLISHed at this moment
mimicsh> mimic agent protocol msg MQTT client message get 0 count
1
mimicsh> set sent [mimic agent protocol msg MQTT client message get 0 sent]
1

      Or, to set and clear the Message Expiry Interval for a message: 

      mimicsh> mimic agent protocol msg MQTT client message card
1
mimicsh> mimic agent protocol msg MQTT client message get 0 properties
User-Property User-Property
mimicsh> mimic agent protocol msg MQTT client message get 0 properties.0
prop1 = some value 1
mimicsh> mimic agent protocol msg MQTT client message get 0 properties.1
prop2 = some value 2
mimicsh> mimic agent protocol msg MQTT client message get 0 properties.2
{cannot get property 2}
mimicsh> mimic agent protocol msg MQTT client message set 0 properties.Message-Expiry-Interval 100

mimicsh> mimic agent protocol msg MQTT client message get 0 properties.2
100
mimicsh> mimic agent protocol msg MQTT client message set 0 properties.Message-Expiry-Interval {""}

mimicsh> mimic agent protocol msg MQTT client message get 0 properties
User-Property User-Property
mimicsh> mimic agent protocol msg MQTT client message get 0 properties.2
{cannot get property 2}

      Or, to change one of the user properties: 

      mimicsh> mimic agent protocol msg MQTT client message get 0 properties
User-Property User-Property
mimicsh> mimic agent protocol msg MQTT client message get 0 properties.0
prop3 = some value 3
mimicsh> mimic agent protocol msg MQTT client message get 0 properties.1
prop2 = some value 2
mimicsh> mimic agent protocol msg MQTT client message set 0 properties.1 {{prop3=some value 3}}

mimicsh> mimic agent protocol msg MQTT client message get 0 properties.0
prop3 = some value 3
mimicsh> mimic agent protocol msg MQTT client message get 0 properties.1
prop3 = some value 3

    • mimic agent protocol msg MQTT client subscribe card
      mimic agent protocol msg MQTT client subscribe get [SUBNUM] [ATTR]
      mimic agent protocol msg MQTT client subscribe unsubscribe [SUBNUM]
      mimic agent protocol msg MQTT client subscribe set [SUBNUM] [ATTR] [VALUE]
      mimic agent protocol msg MQTT client subscribe resubscribe [SUBNUM]

      To control subscriptions by the client at runtime, these commands allow you to get and set subscription simulation parameters. The first parameter returns the cardinality of the subscriptions, ie. 0 or more. You can then control each subscriptions (starting at 0) with the get and set commands. The unsubscribe command unsubscribes with an UNSUBSCRIBE message, and the resubscribe command resubscribes.

      ATTR (defined in subscription configuration below can be one of the following:

      • topic
      • properties (cannot set) - list of SUBSCRIBE properties
      • properties.i - i-th SUBSCRIBE property
      • properties.PROP-NAME - SUBSCRIBE property with name PROP-NAME

      For example, to unsubscribe to the current topic, and re-subscribe with a different one 

      mimicsh>  mimic agent protocol msg MQTT client subscribe unsubscribe 0

mimicsh> mimic agent protocol msg MQTT client subscribe get 0 topic
some-topic/#
mimicsh> mimic agent protocol msg MQTT client subscribe get 0 properties
Subscription-Identifier User-Property
mimicsh> mimic agent protocol msg MQTT client subscribe get 0 properties.Subscription-Identifier
123456
mimicsh> mimic agent protocol msg MQTT client subscribe set 0 properties.Subscription-Identifier 123457

mimicsh> mimic agent protocol msg MQTT client subscribe get 0 properties.Subscription-Identifier
123457
mimicsh> mimic agent protocol msg MQTT client subscribe set 0 topic some-topic/2

mimicsh>  mimic agent protocol msg MQTT client subscribe resubscribe 0

    Back to Top

  6. Recording MQTT

    7. The MIMIC mqttrec and mqttconv utilities work together to transform real-world MQTT client and broker network communications into customizable MIMIC MQTT simulations.

    To create a default MQTT simulation, you record MQTT sessions from real-world publisher or subscriber clients (eg. sensors) with the mqttrec utility. This tool works as a proxy between MQTT client and broker, and saves commands and responses in a temporary MQTT session file. Alternatively, you can record from a previously captured packet capture (PCAP) file..

    The usage is as below: 

    mqttrec --help
Usage: obj.Linux/mqttrec
  [--help, -h]               print this usage message
  or
  --out, -o output file      Recording output file
  --target, -t target        Target ip address or host name
  [--port, -p target port]   Target port
  [--start, -S start]        Packet number to start recording from
  [--stop, -E stop]          Ending packet number
  [--file, -f input file]    pcap input file
  [--directory, -D path]     default path combined with filenames
  [--localport, -l port]     Local port
  [--ipv4, -4]               ipv4 (default)
  [--ipv6, -6]               ipv6

    The MQTT client to be recorded (ie. the real sensor) should be configured to connect to the MIMIC host system, where mqttrec is running, as its MQTT broker. The mqttrec application will forward mqtt traffic to the broker and broker traffic back to the client.

    The MQTT session will be recorded and written to the output file specified. Recorded sessions can be converted by mqttconv into MIMIC MQTT simulations. 

    mqttconv --help
INFO  11/16.15:25:21 - MQTTCONV starting
Usage: mqttconv
  [--help, -h]                   print this usage message
  or
  [--out, -o output file name]    mqttconv base output name (no extension)
  [--in, -i input file]           mqttrec input
  [--path, -p directory path]     override default path
  [--single, -s single output stream] combine MQTT CONNECTs
  [--multiple, -m multiple output streams] MIMIC cfg file for each CONNECT

    mqttconv will generate two types of files, a MIMIC MQTT agent configuration file (.cfg) and script files as detailed below.

    mqttconv will process MQTT CONNECT, PUBLISH and SUBSCRIBE commands into a format that can be read by the MIMIC MQTT agent. The MQTT CONNECT information can be further customized using the MIMIC Configure Agents dialog tab.

    The stream of PUBLISH commands is evaluated for periodic repetitions that can be consolidated into a single MIMIC MQTT simulation configuration file message statement.

    For non-JSON mqtt payloads only identical payloads are consolidated. When a JSON payload is detected the schema is extracted and compared against the other JSON payload schema. If the schema match the timing is used to determine the period of messages.

    Currently the MQTT command times are averaged to create the interval value in the MIMIC MQTT configuration message statement.

    When a JSON payload is identified several support files are created to facilitate customizing the MIMIC MQTT simulation:

    • A unique JSON file, [output name]_[simulation number]_[mqtt command number].json, that contains the JSON schema and MIMIC actions to retrieve MIMIC agent store variable values for each element.

    • A unique MIMIC agent startup TCL script, start+[output name]_[simulation number]_[mqtt command number].mtcl, that initializes the values of the MIMIC agent store variables read by the JSON file specified in the MIMIC agent cfg message statement.

    Several general TCL scipts are generated to provide examples of how a MIMIC mqtt simulation can be customized using TCL scripting:

    • action-on-disconnect.mtcl prints a message when an agent is disconnected.

    • mqtt_subscribe_action.mtcl prints a message displaying the payload when an agent receives an mqtt publish message as a result of an mqtt subscribe command.
    Back to Top

  7. Simulation Configuration

    8. The behavior of the MQTT simulation (data to be published by the simulated sensor, as well as subscriptions) is specified by the MQTT configuration file(s) loaded into the agent instance. This configuration allows to control a simulated MQTT session from establishment until disconnect.

    Back to Top

    Globals

    This section documents the global parameters for this client. All of these are optional with specified defaults.
    Parameter Description
    init

    There can be zero or more initialization scripts for this simulation. Currently it supports

    • action

      The action script to run. These global variables are passed into the action script:

      • gCurrentAgent IN

    These can be used to initialize agent store variables, start timer scripts, etc.

    Back to Top

    Connect

    This section documents the connect-time parameters for this client. All of these are optional with specified defaults.
    Parameter Description
    will-topic

    The Will Topic as detailed in section 3.1.2.5 and 3.1.3.2 of the MQTT spec . If this option is not specified, no Will Message will be published.

    will-message

    The Will Message payload as detailed in section 3.1.2.5 and 3.1.3.3 of the MQTT spec . If this value is the name of an action script, then the payload will be dynamically generated.

    will-qos

    The Will QOS as detailed in section 3.1.2.5 and 3.1.2.6 of the MQTT spec . The default is 0.

    will-retain

    The Will Retain as detailed in section 3.1.2.5 and 3.1.2.7 of the MQTT spec . The default is 0.

    will-properties

    The will-properties block specifies MQTT 5 Will Properties to be sent with the CONNECT message (optional).

    This is an example of the properties block: 

    will-properties = {
                Will-Delay-Interval = 20
                Payload-Format-Indicator = 1
                Message-Expiry-Interval = 123
                Response-Topic = some-will-topic
                User-Property = {
                        name = willprop7
                        value = some value 7
                }
                User-Property = {
                        name = willprop8
                        value = some value 8
                }
}

    clean-session

    The Clean Session flag as detailed in section 3.1.2.4 of the MQTT spec . The default is 0.

    keepalive

    The Keep Alive time as detailed in section 3.1.2.10 of the MQTT spec . The default is 60.

    on-disconnect

    This parameter specifies the action script to invoke on receiving a DISCONNECT event on the connection. If absent, then no action is taken on disconnect.

    on-error

    This parameter specifies the action script to invoke on receiving an error event on the connection. If absent, then a default error message is printed in the log. These global variables are passed into the action script:

    • gCurrentAgent IN
    • gControl IN
      the MQTT control message that generated the error
    • gPacketId IN
      the packet identifier for the erroneous message
    • gCode IN
      the reason code in the MQTT control message that generated the error
    • gMsg IN
      message number (as defined for the mimic agent protocol msg MQTT client message above)
    • gData IN
      Payload with binary data represented as a string of hexadecimal bytes starting with \x
    • gAscii IN
      The same payload represented as a ASCII string. This handles the majority of payloads.
    properties

    The properties block specifies MQTT 5 CONNECT Properties to be sent with the CONNECT message (optional).

    This is an example of the properties block: 

    properties = {
       Session-Expiry-Interval = 0xFFFFFFFF
       Receive-Maximum = 10
       Maximum-Packet-Size = 100
       Topic-Alias-Maximum = 5
}

    Back to Top

    Message

    This section documents the PUBLISH message to be sent to the broker as detailed in section 3.3 of the MQTT spec . There can be multiple different messages published from this client. All parameters are mandatory unless specified. Most parameters can be changed at run-time as detailed below.

    Parameter Description
    topic

    The topic that all messages of this type are published to. If this value is the name of an action script, then the action script defines the topic, allowing to make the topic unique for the particular agent instance.

    interval

    The interval in msec that this message is generated.

    count

    The count of messages to be generated (optional). If this parameter is absent, then the message is generated indefinitely.

    qos

    The QOS that this message is sent at, as detailed in this section (optional). By default it is 0.

    data

    The data section specifies the payload of the message. These are the alternatives:

    • const

      The constant string that is sent in the payload.

    • action

      The action script that generates this payload. It is invoked each time a message needs to be published, and returns the content of the payload. These global variables are passed into the action script:

      • gCurrentAgent IN
      • gMsg IN
        message number (as defined for the mimic agent protocol msg MQTT client message above)
      • gSeq IN
      • gQos IN/OUT
      • gRetain IN/OUT
      • gTopic IN/OUT

      The IN/OUT variables override the message parameters on return, so you can change topic/QOS/retain flag for individual messages in addition to the payload.

    • json_file

      The native JSON that specifies the payload of this message. The JSON file defines the payload syntax PAYLOAD as follows:

      PAYLOAD ::= BLOCK
      BLOCK ::= { JSON-STMTS }
      JSON-STMTS ::= JSON-STMT | JSON-STMT, JSON-STMTS
      JSON-STMT ::= LABEL:BLOCK | LABEL:VALUE-STMT
      LABEL ::= "STRING"
      VALUE-STMT ::= STRING | VALUE-BLOCK
      VALUE-BLOCK ::= { "MIMIC_action": MIMIC-ACTION VALUE-TYPE }
      VALUE-TYPE ::= NULL | , "MIMIC_json_type": MIMIC-JSON-TYPE
      MIMIC-ACTION ::= "store_get" | "agent_get_host" | "agent_get_ipv6" | "range" | "seq" | "timeformat(now,format)"
      MIMIC-JSON-TYPE ::= "string" | "number" | "int" | "uint" | "int64" | "uint64" | "boolean" | "object" | "array" | "null"
      STRING is an arbitrary constant string
      NULL is the empty string

      For example this JSON PAYLOAD 

      {
	"d": {
		"host": {
			"MIMIC_action" : "agent_get_host()"
		},
		"mem": {
			"MIMIC_action" : "seq(20,60)",
			"MIMIC_json_type" : "number"
		}
	},
	"ts": {
		"MIMIC_action" : "timeformat(now)"
	}
}

      generates this payload for a sensor at address 10.0.0.2 if generated every 10 seconds: 

      {"d":{"host":"10.0.0.2","mem":20},"ts":"Tue, 02 Aug 2016 10:25:27"}
{"d":{"host":"10.0.0.2","mem":21},"ts":"Tue, 02 Aug 2016 10:25:37"}
{"d":{"host":"10.0.0.2","mem":22},"ts":"Tue, 02 Aug 2016 10:25:47"}

    properties

    The properties block specifies MQTT 5 PUBLISH Properties to be sent with each message (optional).

    This block must be defined after the data block.

    This is an example of the properties block: 

            properties = {
                Payload-Format-Indicator = 0
		Message-Expiry-Interval = 10
		Response-Topic = some-topic
		Topic-Alias = 1
		User-Property = {
			name = userprop1
			val = some value 1
		}
		User-Property = {
			name = userprop2
			value = some value 2
		}
	}

    Notice that all properties can only appear once, except for User-Property blocks. Properties can be changed at run-time with the mimic agent protocol msg MQTT client message command above .

    pre

    The pre block specifies a pre-processing action script that is executed before sending every payload and before any action script in the data block (optional).

    This block must be defined after the data block.

    These global variables are passed into the action script:

    • gCurrentAgent IN
    • gMsg IN
      message number (as defined for the mimic agent protocol msg MQTT client message command above )
    • gSeq IN

    For example, the pre-processing script can do calculations and set agent store variables to be retrieved in the json data action, or a C++ action script such as that for the Sparkplug standard. 

    pre = {
        action = action-some-preprocessing.mtcl
}

    post

    The post block specifies a post-processing action script that is executed after sending every payload (optional). It is executed only if the PUBLISH is sent successfully.

    This block must be defined after the data block.

    Same global variables are passed into the action script as for pre.

    For example, the post-processing script can be used to implement the MQTT 5 Topic Alias feature, by setting the topic name to empty after the first PUBLISH. 

    post = {
        action = action-some-postprocessing.mtcl
}

    Most of these configurables can be changed at runtime with the mimic agent protocol msg MQTT client message set command above .

    Back to Top

    Subscribe

    This section documents subscriber features of the MQTT client as detailed in section 3.8 of the MQTT spec .
    Parameter Description
    topic

    The topic that the subscriber wants to receive. If it is the name of an action script, then that topic is dynamically generated at agent startup time and can be unique for the agent.

    action

    The name of an action script to be invoked upon receipt of PUBLISH messages from the broker on the subscribed topic.

    These global variables are passed into the action script with information from the PUBLISH message:

    • gCurrentAgent IN
    • gPacketId IN
      the packet identifier for the PUBLISH message
    • gDup IN
    • gQos IN
    • gRetain IN
    • gData IN
      Payload with binary data represented as a string of hexadecimal bytes starting with \x
    • gAscii IN
      The same payload represented as a ASCII string. This handles the majority of payloads.
    • gTopic IN
    • gProps IN
      For MQTT 5, the Properties in the PUBLISH message.

    An error return, eg. with a "return -code error" statement from this script results in the PUBLISH to be discarded (and not acknowledged if QOS > 1).

    Most of these configurables can be changed at runtime with the mimic agent protocol msg MQTT client subscribe set command above .

    Back to Top

    TLS configuration

    This section documents the TLS configuration file.
    Parameter Description
    certificate

    The client certificate file. The sample command 

    openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes

    created the certificate and key file that is shipped in config/mqtt/client.crt . For details see this primer.

    This command diagnoses the SSL connection to a server at IP address IPADDR and port PORT (usually 8883) for a Certificate Authority specified in CAFILE: 

    openssl s_client -connect IPADDR:PORT -CAfile CAFILE
    key The client private key file.

    Back to Top

  8. Compatibility

    9. Click here for the compatibility document. If you get an error opening this URL, you need to download the optional MQTT Compatibility documentationupdate package with the Update Wizard.

    Back to Top
    << Previous Section    Next Section >>