This example program uses HiveMQ Broker to allow a user to both publish and subscribe to topics using the AT&T Cellular IoT Starter Kit from Avnet.

The example program subscribes to a topic and publishes keypress events to the broker by monitoring for button presses of switch #2 and #3 on the K64F board. Whenever either of these two buttons are pressed, it is reported to the broker. Any subscribers are then notified of those button presses.

To observer and interact more extensively with the example program, you can install MQTTBox and subscribe/publish to the same topics to obtain a good test experience.

If you need to learn more about MQTT and/or the MQTTBox application, documentation and supported systems are available at http://workswithweb.com/mqttbox.html.

NOTE: This doc is specific to using the AT&T Cellular IoT Starter Kit which contains a FRDM-K64F from NXP. Ensure that the online compiler has the platform set to FRDM-K64F.

MQTT HiveMQ Example Program¶

This example Program demonstrates subscribing and publishing to a public MQTT broker. Additionally, a MQTT utility is used to interact with the system.

1. Modify the source code so it interacts with your M2X device.

2. Install the PC based MQTTbox utility & configure.

3. Expected execution outcome.

Modify the source code¶

To modify the example code (main.cpp), please follow these steps so your device variables are properly configured. The variables you need to modify are pound defines (#define) in main.cpp and described below:

BROKER¶

It is unlikely will need to change this define, it is the URL of the broker service that is being used, HiveMQ

```
#define BROKER "broker.hivemq.com"   // MQTT broker URL
```

PORT¶

The port number to use is listed on the main page of HiveMQ Broker. It rarely changes so it will most likely not need to be changed.

```
#define PORT 1883                    // MQTT broker port number
```

CLIENTID¶

The CLIENTID (client identifier) is an identifier for each MQTT client connecting to a MQTT broker. It should be unique per broker so the broker can uses it for identifying the client and current state. The example program uses a fictional MAC without the ':'s of the device as its client ID.

```
#define CLIENTID "96430312d8f7"      // use K64F MAC address without colons
```

USERNAME/PASSWORD¶

MQTT allows to send a username and password to authenticate the client. This information is typically sent as plaintext. It is recommend to use username and password together with a secure transport if necessary. For this example program USERNAME and PASSWORD are not used.

```
#define USERNAME ""                  // not required for MQTT Dashboard public broker 
#define PASSWORD ""                  // not required for MQTT Dashboard public broker
```

TOPIC¶

A topic is a UTF-8 string, which is used by the broker to filter messages for each connected client. A topic consists of one or more topic levels. In the example, 'jmf/Test1' is used but this can be anything that is desired.

```
#define TOPIC "jmf/Test1"            // MQTT topic
```

Using the MQTT-JMF & MQTTPacket libraries¶

The MQTT-JMF library is used to create an MQTTwnc object. In turn, this library uses the MQTTPacket library and an underlying TCPSocket class created by WNCInterface. Explaining how each of these libraries interacts with the other is beyond the scope of this README, but it is important to know that the connection to the WNC hardware is performed when the 'ipstack.connect' call is made. All stdio occurs after the WNCInterface object is created.

Returned values¶

For all functions, the HTTP status code will be returned if the request can be fulfilled. For example, `200` will be returned upon success, `400` if a bad request was made.

The PC based MQTTbox utility¶

To interact with this MQTT example program, it is best to install MQTTBox from http://workswithweb.com/html/mqttbox/getstarted.html. Instructions are provided for Linux, Mac, and Windows. The Topic you subscribe to will be the same that you provided in the TOPIC define in your source code (described above).

Expected execution outcome¶

Once the necessary source code updates are made, the program compiled and downloaded to the IoT Kit, and run, the output will look similar to:

    ...    

License

This library is released under the Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License and may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.