Share this page

# MQTT protocol

VuGen's MQTT protocol supports testing for networks using machine-to-machine (M2M) and Internet of Things (IoT) communications.

In this topic:

## About MQTT

MQTT is a simple, lightweight, publish/subscribe messaging protocol designed for constrained devices and low-bandwidth, high-latency or unreliable networks.

MQTT is ideal for M2M and IoT communications, as well as for mobile applications where bandwidth and battery power are at a premium. MQTT focuses on minimizing network bandwidth and device resource requirements, while attempting to ensure reliability and some degree of assurance of delivery.

MQTT uses publisher-subscriber operations for communication between clients and the server. The MQTT server is the message broker that controls communication between clients.

Clients, or “things”, can be publishers or subscribers.

- The publisher is the client sending the message. The message goes to the message broker, specifying a topic.
- The subscriber is the client that receives the message. To receive a message on a topic, subscribers have to subscribe to it.

Back to top

## Create an MQTT script

You can use the MQTT Script Wizard to generate attributes for your script, or you can script it manually using the defined MQTT functions.

The client variables for your script are declared in the Extra Files > globals.h file, accessed from the Solution Explorer.

To create an MQTT script:

1. Create a new script by selecting New Script and Solution > MQTT protocol.

   A ready-to-use script opens in the Editor, using all of the available MQTT functions. In addition, the Script Wizard is opened automatically in a separate dialog box.

2. Design the script in one of the following ways:

   - Use the Script Wizard to generate the script. For details, see MQTT Script Wizard.
   - Click Cancel to close the Script Wizard, and modify the ready-to-use script template as needed. For a complete description of the MQTT functions and function calls, see the Function Reference.

   Note: If you are creating a multiple-protocol script, you can integrate MQTT steps into a recorded Web - HTTP/HTML script. For details, see Working with multi-protocol scripts.

3. Configure the runtime settings. These affect the way that a Vuser script runs.

   1. In the Solution Explorer, double-click Runtime Settings.

   2. In the <test name>:Runtime Settings view, configure the runtime settings as needed. To view descriptions of the individual runtime settings, hold your cursor over a runtime setting field name.

   For general details, see Runtime settings and Configure runtime settings.

Back to top

## MQTT Script Wizard

The MQTT Script Wizard enables you to define settings that are then generated as code in your MQTT script.

The Script Wizard is displayed automatically (default setting) when you create a new MQTT script. You can also open it by clicking Design Script on the VuGen toolbar. (The Design Script button is available when an MQTT script is open in the Editor.)

Connection Settings tab

UI Element | Description
--- | ---
Broker URL | Address of the broker server in the format: tcp://host:port or ssl://host:port, where the host is the domain name, IPv4 address, or the IPv6 address, in square brackets. Example of IPv6 address: [2001:0db8:85a3:0000:0000:8a2e:0370:7334]. If the port is not specified, the following default ports are used: tcp://host:1883 ssl://host:8883
Client ID | Define the client ID for the connection. The string is a unique identifier for a client in the network. Leave the field blank to use an automatically generated ID. The client is identified as follows: If you create a new client (identified by the Client ID), then when the script is generated, a new client is appended to the existing script, using all the properties from the wizard. An automatically generated ID always creates a new client. If the Client ID already has a connection in the script, it is considered an existing client. In that case, only additional attributes are appended to the existing client. See Additional attributes for clients.
Authentication settings | If required, define the user name and password to log on to the broker server.
Enable TLS | Select if secure communication over TLS (SSL) is required, and select the relevant TLS version from the dropdown list. Default uses the version defined in the runtime settings.
Use client certificate | Select to use the client certificate, then define the path to the certificate file and private key, and the password for the key (leave the password field empty if the key is not encrypted).
Check Connection | Click to check that VuGen can connect successfully to the broker using the defined credentials. A tick is displayed if the connection succeeded, and a cross if it failed.
Show wizard for new scripts | Clear the check box if you do not want the Script Wizard to open automatically when creating new MQTT scripts. Tip: If the Script Wizard does not open automatically, you can open it by clicking Design Script in the VuGen toolbar.
Clear All | Click to clear all settings in all tabs.
Generate Code | If the button is enabled, click to add the relevant steps to the code for the script; Or continue to the next tabs to define optional settings.

Client Settings tab

UI Element | Description
--- | ---
Publisher/Subscriber | Define values for one of these options. Use the radio buttons to switch between them: Publisher: Define settings for publishing messages. Subscriber: Define the topic for the subscriber.
Topic to publish | The destination topic for publishing the message, for example: `myhome/kitchen/temperature/1`.
Payload | Set the message to be published, in byte format.
Retain message | When checked, this instructs the broker to store the last retained message in the topic together with its QoS. Only one message is stored per topic, so the last retained message always replaces any previously stored message. This is useful for providing the latest status to new subscribers when they subscribe to a topic, so they do not need to wait for the next status update.
Quality of Service | The required Quality of Service (QoS). For example, if the connection is lost where QoS = 0, the client will not try to publish again after reconnecting, and a warning is displayed in the script's output. Values are 0 to 2 and Default (as defined in the runtime settings).
Topic to subscribe | Use to subscribe the client to a topic, or a set of topics (by using wildcards). The broker automatically sends messages published on these topics. The topic can contain wildcards. Examples: `myhome/kitchen/temperature/1, region2/#` `region2/WeatherStation/+/temperature` The default QoS is used, as defined in the runtime settings.

Last Will and Testament tab

UI Element | Description
--- | ---
Topic | Define the destination topic to notify other clients about an ungracefully disconnected client.
Payload | Set the message the broker sends to subscribers for the specified topic, when the client disconnects unexpectedly.
Retain message | When checked, this instructs the broker to store the last retained message in this topic. Only one message is stored per topic, so the last retained message always replaces any previously stored message.

Additional attributes for clients

You can use the MQTT Script Wizard to define additional attributes for an existing client—a client that already has a connection in the script. The client is defined by the Client ID provided in the wizard.

Possible additional attributes are:

- Publisher. A client can have multiple publishers. If a publisher is created for an existing client, the new publisher is added in the Actions.c file, for the corresponding client.

- Subscriber. A client can only subscribe to one topic at a time. If a subscriber is created for an existing client, code generation verifies if the existing client has already subscribed. If it has a subscriber, the one from the wizard is ignored. Otherwise, the subscriber is added to the `client_settings()` function in the vuser_init.c file, and the corresponding unsubscribe is added before the corresponding client’s disconnect in the vuser_end.c file.

- Last Will and Testament. A client can have only one Last Will and Testament (LWT) message. If an LWT message is created for an existing client, the code generation verifies if the existing client already has an LWT. If so, the one from the wizard is ignored. If not, a new LWT function is added to the corresponding client in the `client_settings()` function in the vuser_init.c file.

Back to top

## Working with multi-protocol scripts

You can test scenarios in which your script uses both of the following:

- MQTT to communicate between the client and the broker

- Web - HTTP/HTML to communicate between the broker and the web application

You prepare your script by recording the steps on your web application. Then you manually add MQTT steps as needed. The pre-populated MQTT script is not included when working with a multiple protocol script, but you can copy/paste from the Ready-to-use MQTT script template.

To enable support:

1. Create a multiple-protocol script that includes MQTT and Web - HTTP/HTML. For details, see Create a New Script dialog box.

2. Record a web script.

   Note: Recording a web script overwrites globals.h, removing the default support for MQTT steps.

3. Restore support for MQTT steps:

   1. Open globals.h (located in the Solution Explorer under Extra Files).

   2. Add #include "MqttApi.h" to the Include Files section.

4. Add MQTT steps to the script.

Sample multi-protocol script

    Action()
    {
      MQTT client;

      client = mqtt_create();

      mqtt_set_client_id(client, "myclientid");

      lr_start_transaction("connect_MQTT");

      mqtt_connect(client, "tcp://mymachine:1883");

      lr_end_transaction("connect_MQTT", LR_AUTO);

      lr_start_transaction("navigate_Web");

      // your recorded web code here

      lr_end_transaction("navigate_Web", LR_AUTO);

      mqtt_publish(client, "topic/subtopic", "payload", MQTT_AUTO, MQTT_DEFAULT, MQTT_NORETAIN);

      mqtt_disconnect(client);

      return 0;
    }

Back to top

## Ready-to-use MQTT script template

The default, single-protocol MQTT script includes actions that are pre-populated with commented out steps (shown below).

When working with multiple-protocol scripts, you first record steps on your web application. Then you add MQTT steps as needed. You can copy/paste the relevant steps from the template below.

For details on any of these functions, see the Function Reference.

vuser_init

    vuser_init()
    {
      /* Declared in "globals.h" */
      client = mqtt_create();

      /* Optional connection settings */
      // mqtt_set_client_id(client, "<insert Client ID>");
      // mqtt_set_credentials(client, "<username placeholder>", "<password placeholder>");
      // mqtt_set_lwt(client, "<topic>", "<sample lwt payload>", MQTT_AUTO, MQTT_DEFAULT, MQTT_RETAIN);

      /* Optional SSL/TLS settings, applicable for SSL/TLS connections only */
      // mqtt_set_tls_certificate(client, "<path to a certificate file, e.g. cert.pem>", "<path to a private key file, e.g. key.pem>", "<password for the private key>");
      // mqtt_set_tls_parameters(client, MQTT_TLS_DEFAULT, MQTT_DEFAULT_CIPHERS);

      /* Connect to an MQTT broker */
      mqtt_connect(client, "tcp://<enter an MQTT broker host name>");

      /* Uncomment the following if implementing the "subscriber" logic */
      // mqtt_subscribe(client, "<topic>");
      return 0;
    }

Action

    Action()
    {
      /* Uncomment the following if implementing the "subscriber" logic. Make sure to also uncomment subscribe/unsubscribe in vuser_init/end.c */
      //
      /* Option 1: Wait for messages, then handle their contents */
      // size_t messageCount = mqtt_await_messages(client, MQTT_DEFAULT);
      // size_t i = 0;
      // for ( ; i < messageCount; i++)

      // {
      // MQTT_MESSAGE m = mqtt_read_inbox(client);
      // const char* p = mqtt_get_payload(m);
      // const char* t = mqtt_get_topic(m);
      // size_t l = mqtt_get_length(m);
      // ... do something meaningful with the message
      // ... for instance, print received message information (assuming its payload is not binary data)
      // lr_message("received message with size %d from %s", l, t);
      // lr_message("payload %.*s", l, p);
      //
      // mqtt_free_message(m);
      // }

      /* Option 2: Wait for messages, then clear Inbox (if their handling is not needed) */
      // mqtt_await_messages(client, MQTT_DEFAULT);
      // mqtt_clear_inbox(client);

      /* Uncomment the following if implementing the "publisher" logic */
      // mqtt_publish(client, "<topic>", "<payload>", MQTT_AUTO, MQTT_DEFAULT, MQTT_RETAIN);

      return 0;
    }

vuser_end

    vuser_end()
    {
      /* Uncomment the following if implementing the "subscriber" logic */
      // mqtt_unsubscribe(client, "<topic>");

      /* Disconnect from the MQTT broker */
      mqtt_disconnect(client);

      return 0;
    }

Back to top

https://admhelp.microfocus.com VuGen,Professional Performance Engineering,Performance Engineering for Developers 8942
Tips to improve your search results... OpenText™ Virtual User Generator Help Center OpenText™ VuGen Help 26.1 All View Local Help Center View Online Help Center Version: