1.23 TCP/IP WolfSSL MQTT Application

The wolfMQTT application demonstrates a simple MQTT application using the 3rd party wolfMQTT library.

The application uses the console to implement a simple set of commands to start a MQTT connection to a selected broker.

The connection parameters can be adjusted using various MQTT related commands.

This demonstration uses the NET_PRES layer which supports encrypted communication through an external service provider for TLS support (usually wolfSSL).

TCP/IP WolfSSL MQTT Application MCC Configuration

The following Project Graph diagram shows the Harmony components included in the WolfSSL MQTT Application application demonstration.

• MCC is launched by selecting Tools > Embedded > MPLAB® Code Configurator from the MPLAB X IDE and after opening the project, TCP/IP demo project is ready to be configured and regenerated.

• TCP/IP Root Layer Project Graph

  The root layer project shows that UART2 peripheral is selected to do read and write operation for TCP/IP commands.

  This is the basic configuration with SYS_CONSOLE, SYS_DEBUG and SYS_COMMAND modules. These modules are required for TCP/IP command execution.

  

  NOTE - The above diagram contains FreeRTOS component and that is required for RTOS application. For bare-metal(non-RTOS) FreeRTOS component shouldn't be selected.

  TCP sockets calculate the ISN using the wolfSSL crypto library.

• TCP/IP WolfMQTT Configurations

  • The configuration options for the wolfMQTT are the standard ones supported by wolfMQTT (see wolfMQTT site). Note that the project has already selected the 3rd party wolfMQTT and wolfSSL libraries (for supporting encrypted connections).

  • The NET_PRES layer is also needed because the Harmony wolfMQTT NET glue layer uses the NET_PRES to handle the connections to the broker.

  • Use the github repositories for wolfMQTT and wolfSSL.

  • To configure the wolfMQTT and the wolfMWQTT NET glue layer, select the "wolfMQTT Library" module:

    

  • The configuration options for the wolfMQTT NET glue allow the application to:

    • force TLS mode

    • enable IPv6 operation

    • set the maximum length of the MQTT broker

    • enable the NET glue debug and debug strings

    • set the allocation functions

    • set the MQTT TX and RX buffer sizes

    • generate the custom MQTT application template:

    • the files app_mqtt_task.c, app_mqtt_task.h and app_mqtt_commands.c will be added to the project

• TCP/IP Configuration

  • PIC32MZ EF Starter Kit

    

• TCP/IP Required Application

  TCP/IP demo use these application module components for this demo.

  DHCP Client module to discover the IPv4 address from the nearest DHCP Server.

  DNS Client provides DNS resolution capabilities to the stack.

  SNTP Simple Network Time Protocol updates its internal time periodically using a pool of public global time servers.

• TCP/IP Data Link Layer

  Internal ethernet driver(ethmac) is enabled with the external LAN8740 PHY driver library for the starter kit. The MIIM Driver supports asynchronous read/write and scan operations for accessing the external PHY registers and notification when MIIM operations have completed.

TCP/IP WolfSSL MQTT Application Hardware Configuration

This section describes the hardware configuration for PIC32MZ EF Starter Kit and one can be used for the respective application demonstration.

1. This section describes the PIC32MZ EF Starter Kit default hardware configuration which uses the on-board debugger and programmer for this application demonstration.

   • Refer to the PIC32MZ EF Starter Kit User Guide for the programming/debugging options supported & setting up the hardware.

     

   • Connect the mini USB cable from the computer to the USB DEBUG connector on the PIC32MZ EF Starter Kit

   • Connect the mini USB cable from the computer to the USB-UART connector on the PIC32MZ EF Starter Kit

   • Establish a connection between the router/switch with the PIC32MZ EF Starter Kit through the RJ45 connector on PHY daughter board

TCP/IP WolfSSL MQTT Application Running Application

This table list the name and location of the MPLAB X IDE project folder for the demonstration.

Running Demonstration Steps

1. Build and download the demonstration project on the target board.

2. If the board has a UART connection:

   1. A virtual COM port will be detected on the computer, when the USB cable is connected to USB-UART connector.

   2. Open a standard terminal application on the computer (like Hyper-terminal or Tera Term) and configure the virtual COM port.

   3. Set the serial baud rate to 115200 baud in the terminal application.

   4. See that the initialization prints on the serial port terminal.

   5. When the DHCP client is enabled in the demonstration, wait for the DHCP server to assign an IP address for the development board. This will be printed on the serial port terminal.

      • Alternatively: Use the Announce service or ping to get the IP address of the board.

      • Run tcpip_discoverer.jar to discover the IPv4 and IPv6 address for the board.

3. Execution :

   The wolfMQTT demo is interactive, using a set of special MQTT commands that have been added to this demo.

   

   Pressing "mqtt help" at the command prompt displays the list of the available commands/options:

4. Most of the commands are self explanatory.

   All settings come with default values.

   A brief description of the most important settings/commands follows:

   

• "mqtt broker": sets the MQTT broker to connect to. The default value is "iot.eclipse.org"

• "mqtt port": sets the MQTT port to use. Default is 1883

• "mqtt qos": setd the QoS. Default is MQTT_QOS_0.

• "mqtt topi": sets the MQTT topic. Default is "MQTT_NET_Client topic"

• "mqtt tls": sets the force TLS flag. Default is 0.

• "mqtt user": sets the user name. Default is "MQTT_NET_User"

• "mqtt txbuf": sets the size of the TX buffer for the connection. Default is 1024

• "mqtt rxbuf": sets the size of the RX buffer for the connection. Default is 1024

  Note: The connection to the broker is normally done using the port number: 1883 for plain connections, 8883 for encrypted ones.

1. Wolf MQTT Connection:

   Using the "force TLS" will force an encrypted connection regardless of the port number.

   The wolfMQTT demo is based on the examples provided by wolfMQTT.

   To allow a simple usage of the wolfMQTT library, a wolfMQTT NET Glue layer has been added to the Harmony port,

   The NET glue layer takes care of all the connections to the broker, supporting both encrypted and plain connections.

   This way the application does not have to be concerned with the communication mechanisms and can use directly the wolfMQTT API on a Harmony platform without the need to add other supporting code.

   The configuration parameters for the wolfmqtt demonstration are defined in the app_mqtt_task.h file that's part of the project.

   The configuration parameters for the NET glue layer can be configured with MCC (see MCC Configuration).

   The demo starts with all parameters having default values (see above).

   If needed, parameters can be adjusted as the application requires.

   Then a connection to the broker can be started using the command: "mqtt start".

   A successful connection should render the following output:

   The "mqtt stop" command can be used to request the ongoing MQTT transaction to be aborted.

   The "mqtt stat" can be used to display the current state of the MQTT connection cycle.