Staging:CC3220 MQTT Server (Texas Instruments NDA restrictions applicable)

Overview
MQTT(Message Queue Telemetry Transport) protocol is an extremely light weight machine to machine connectivity protocol. It is based on publish/subscribe messaging model and is designed to be used on the top of TCP/IP protocol. A small footprint implementation, low bandwidth requirement and ease of scalability makes it a popular choice for data transport for embedded systems in the realm of Internet-of-Things (IoT).

MQTT uses a client-server topology for data transactions. Multiple clients can communicate with a single server. More information about MQTT protocol can be obtained from the latest MQTT Protocol specification. Subsequent sections outline the support for tiny MQTT server that have been made available as part of the CC32xx SDK.

MQTT Network
A simple MQTT network contains a server / broker (like a central hub) that can handle connections from multiple clients. Each of the connected client can publish data for any topic (token). Whereas, the server / broker is responsible for forwarding the data published for a topic by a client to all the other clients who have subscribed for that particular topic. This is a very simplistic description of a MQTT network to set the tone for the sample application provided in SDK.

MQTT Library
MQTT library abstracts out the underlying intricacies of MQTT network and provide you with an intuitive and easy to use APIs to implement the MQTT protocol on CC3220 device. The server library makes provisions to manage multiple clients and topics.

Application
This application implements a MQTT bridge that utilizes the services of the MQTT server and MQTT client running in parallel (on the same launchpad). The MQTT server manages the local MQTT network whereas, the MQTT client connects to a cloud server / broker. The bridge application enables data exchange between local-server and the cloud server. To receive data from the cloud server, the MQTT bridge, through the MQTT client, subscribes to certain topics. It also forwards the data / topics received from the local MQTT server to the cloud-server. The local MQTT server handles the connections from the multiple MQTT clients (also shown as Launchpads in the following figure, but can be running on another platform) in the local network.



Use Case
The motivation behind this application is to showcase a working setup where Two local MQTT clients can communicate with each other as well as talk to a remote client via an external broker. For the sake of simplicity following abbreviations are used:
 * 1) LC1 - First local MQTT client
 * 2) LC2 - Second local MQTT client
 * 3) RC - Remote MQTT client
 * 4) AS(Application Server) - MQTT server running on CC32xx device
 * 5) AC(Application Client) - MQTT clint running on CC32xx device
 * 6) BR - External broker/ cloud server
 * 7) AP - Access Point

The use-case consists of two Local MQTT client LC1 and LC2, which could be running on a PC or Smartphone or even can be CC32xx clients(as shown in the above figure), communicating with each other using the MQTT server(AS). These Local clients can also communicate with a Remote MQTT client(RC) through an external broker(BR). Both these cases are explained below. Please refer to the following diagrams for more clarification.

Local Communication
 * 1) LC1 connects to AS
 * 2) LC2 connects to AS
 * 3) LC1 subscribes on a particular topic.
 * 4) LC2 publish message on the same topic.
 * 5) LC1 should get the message published by LC2. This will conclude the Local MQTT Network.

Remote Communication
 * 1) RC and AC should be connected to the same external broker(BR)
 * 2) AC has already subscribed to the topic SUB_TOPIC
 * 3) RC will publish a message on SUB_TOPIC
 * 4) Whatever message is received by AC will be passed to the AS.
 * 5) If any of the local client has subscribed to the SUB_TOPIC, it will receive the message published by RC.
 * 6) AC has also enrolled for the topic ENROLLED_TOPIC, which means if AS receives any message on ENROLLED_TOPIC from any local client, it will be passed to the AC. Which in turn will published to the BR.
 * 7) If RC has subscribed on ENROLLED_TOPIC, it will receive the message published by the Local Client.

Configurations
Following highlights most of the parameters that the user will want to configure /*Operate Lib in MQTT 3.1 mode.*/
 * 1) define MQTT_3_1_1 				false /*MQTT 3.1.1 */
 * 2) define MQTT_3_1 				true /*MQTT 3.1*/


 * 1) define WILL_TOPIC 				"Client"
 * 2) define WILL_MSG 				"Client Stopped"
 * 3) define WILL_QOS 				QOS2
 * 4) define WILL_RETAIN 			false

/*Defining Broker IP address and port Number*/


 * 1) define SERVER_ADDRESS 			"messagesight.demos.ibm.com"


 * 1) define PORT_NUMBER 			1883


 * 1) define LOOPBACK_PORT  		1882

/*Specifying Receive time out for the Receive task*/
 * 1) define RCV_TIMEOUT 			30

/*Background receive task priority*/
 * 1) define TASK_PRIORITY 			3

/* Keep Alive Timer value*/
 * 1) define KEEP_ALIVE_TIMER 		25

/*Clean session flag*/
 * 1) define CLEAN_SESSION 			true

/*Retain Flag. Used in publish message. */
 * 1) define RETAIN 			       1

/*Defining Publish Topic*/
 * 1) define PUB_TOPIC 		       "/cc32xx/ButtonPressEvtSw2"

/*Defining Number of topics*/
 * 1) define SUB_TOPIC_COUNT 		1

/*Defining Subscription Topic Values*/
 * 1) define SUB_TOPIC 			"/Broker/To/cc32xx"

/*Defining Enrolled Topic Values*/
 * 1) define ENROLLED_TOPIC		       "/cc32xx/To/Broker"

Apart from the MACROs shown above, the following structure can be configured as per requirement and use case. /*Initialization structure to be used with sl_ExtMqtt_Init API*/ SlMqttClientCtxCfg_t Mqtt_ClientCtx ={ {	SL_MQTT_NETCONN_URL, SERVER_ADDRESS, PORT_NUMBER, 0,   0,    0,    NULL },   MQTT_3_1_1, true };

SlMqttClientLibCfg_t Mqtt_ClientCfg ={ 0,   TASK_PRIORITY, RCV_TIMEOUT, true, UART_PRINT };

SlMqttServerCfg_t Mqtt_Server={ {		0,		NULL, PORT_NUMBER, 0,		0,		0,		NULL },   LOOPBACK_PORT, TASK_PRIORITY, KEEP_ALIVE_TIMER, true, UART_PRINT };

SlMqttWill_t will_param={ WILL_TOPIC, WILL_MSG, WILL_QOS, WILL_RETAIN };

Source Files briefly explained

 * main.c - The main file implementing the mqtt client server bridge.
 * cc_launchpad: - Contains mandatory board specific initialization. Also initializes the peripherals exercised.

Supporting Files
 * pinmux.c - Generated by the PinMUX utility.

Common Files
 * network_if.c - Common functions to handle connection to AP and FreeRTOS hook functions.
 * startup_*.c - IDE specific startup functions (not required when working with TI-RTOS)
 * timer_if.c - Wrapper functions for timer module driver
 * uart_if.c - To display status information over the UART

Usage

 * 1) On a host PC, open a HyperTerminal/TeraTerm/Putty/Minicom with settings described in CC31xx & CC32xx Terminal Setting.
 * 2) Run the reference application (Flashing the bin/IAR/CCS).
 * 3) Application requires the AP to have the internet connectivity.
 * 4) On the Hyperterminal, in case the connection to this default AP is unsuccessful, the user is prompted to enter the AP details.
 * 5) The GREEN LED denotes that the network processor has come up successfully, RED LED continuously blinks as long as a connection with AP is not established. Once established, the RED LED stays continuously ON for one second and then all the LEDs will be turned off.
 * 6) From another machine, open a web browser and type http://m2m.demos.ibm.com/mqttclient/ in the url box. You will reach the web client from IBM.
 * 7) Connect this web client to IBM broker by filling in the required fields(use below screenshot as reference for the field values).
 * 8) Connect one ore multiple local MQTT client to the MQTT server, it can be a PC or another CC3220 device. A local functional MQTT network can now be used to communicate between multiple local clients.
 * 9) At the same time, if a local client publishes on a topic enrolled by the on-board client, it will be published to the external broker and made available for remote clients.
 * 10) Any message from the broker to the on-board client will be passed on to the MQTT server, which will take responsibility of distributing the message to the local client(if subscribed to the same topic).

Suggestion
Client name is unique for every client. It is recommended to change the client ID for CC3220 device to avoid connection issues.

Additional Info
If anyone wishes to have prints(on serial comm port) about the packet level details of MQTT packets, just define DEBUG_NET_DEV as the predefined symbol while building the mqtt library.

Limitations/Known Issues
None.