MQTT Protocol

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 machine-to-machine (M2M) and Internet of Things (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.

Create an MQTT script

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

    By default, a ready-to-use script opens using all of the available MQTT functions, as defined in the Function Reference.

    For general details on creating scripts, see Creating or Opening Vuser Scripts and Vuser Script Sections.

  2. Modify the ready-to-use script template as needed. For a complete description of each of the function calls, see the Function Reference.

    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 Overview and Runtime Settings Views.

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