Staging:CC3220 MQTT Client (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. Key point of this protocol includes small code footprint and low network bandwidth requirement. Other features include faster response time, low power requirement, ease of scalability. All these advantages makes it an ideal candidate for communication protocol in embedded devices intended to implement IOT(internet of things) applications. More information regarding MQTT protocol can be obtained from the latest MQTT Protocol specification.

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.

Application
This application make use of the APIs from MQTT client library to communicate with an IBM web client using the IBM broker. Three LEDs on the CC3220 device can be controlled from a web client by publishing msg on appropriate topics. Similarly, message can be published on pre-configured topics(in the code) by pressing the switch buttons on the CC3220 device.



Configurations
Most the parameters user will need to modify are specified as MACROs /*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*/

/*Defining Broker IP address and port Number*/
 * 1) define SERVER_ADDRESS 			"messagesight.demos.ibm.com"
 * 2) define PORT_NUMBER 			1883


 * 1) define MAX_BROKER_CONN        1

/*Specifying Receive time out for the Receive task*/
 * 1) define SERVER_MODE				MQTT_3_1
 * 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_FOR_SW3 		"/cc32xx/ButtonPressEvtSw3"
 * 2) define PUB_TOPIC_FOR_SW2		"/cc32xx/ButtonPressEvtSw2"

/*Defining Number of topics*/
 * 1) define TOPIC_COUNT 			3

/*Defining Subscription Topic Values*/
 * 1) define TOPIC1 					"/cc32xx/ToggleLEDCmdL1"
 * 2) define TOPIC2 					"/cc32xx/ToggleLEDCmdL2"
 * 3) define TOPIC3 					"/cc32xx/ToggleLEDCmdL3"

which will eventually get populated in following structures containing connection configuration and library configuration respectively.

CC3200 MQTT library has the capability of connecting to multiple brokers simultaneously. So, if one wishes to do that, configuration for the new connection can be added as new element(on next index) in connect_config.

/* connection configuration */ connect_config usr_connect_config[] = {   {        {            {            	SL_MQTT_NETCONN_URL, SERVER_ADDRESS, PORT_NUMBER, 0,               0,                0,                NULL },           SERVER_MODE, true, },       NULL, "user1", NULL, NULL, true, KEEP_ALIVE_TIMER, {Mqtt_Recv, sl_MqttEvt, sl_MqttDisconnect}, TOPIC_COUNT, {TOPIC1, TOPIC2, TOPIC3}, {QOS2, QOS2, QOS2}, {WILL_TOPIC,WILL_MSG,WILL_QOS,WILL_RETAIN}, false } };

/* library configuration */ SlMqttClientLibCfg_t Mqtt_Client={ 1882,   TASK_PRIORITY, 30,   true, UART_PRINT };

Source Files briefly explained

 * main.c - The main file implementing the mqtt client.

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) Subscribe to the /cc32xx/ButtonPressEvtSw2 and /cc32xx/ButtonPressEvtSw3 topics from the web client.
 * 2) On a host PC, open a HyperTerminal/TeraTerm/Putty/Minicom with settings described in CC31xx & CC32xx Terminal Setting.
 * 3) Run the reference application (Flashing the bin/IAR/CCS).
 * 4) Application requires the AP to have the internet connectivity.
 * 5) On the Hyperterminal, in case the connection to this default AP is unsuccessful, the user is prompted to enter the AP details.
 * 6) 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.
 * 7) 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.
 * 8) Connect this web client to IBM broker by filling in the required fields(use below screenshot as reference for the field values).
 * 9) Publish on /cc32xx/ToggleLEDCmdL1, /cc3200/ToggleLEDCmdL2 or/cc32xx/ToggleLEDCmdL3 to control LED9, LED10 and LED11 respectively.
 * 10) Press the SW2 or SW3 switch on CC3220 device to publish message on /cc32xx/ButtonPressEvtSw2 or /cc32xx/ButtonPressEvtSw3 respectively.

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

 * 1) Client can connect to at most 4 brokers at a time