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 (select the relevant version).

   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.)

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 (select the relevant version).

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