Cloud MQTT Demo

MQTT client able to connect to the Amazon IoT broker and update messages, or subscribe to updates.

API Features Demonstrated

Platforms

This app works on:

Requirements and Prerequisites

This app requires a ZentriOS evaluation board and ZentriOS 3.1+.

You also need an account with Amazon IoT service and your user certificate file.

Memory Considerations

Because a TLS connection requires a considerable amount of memory, the MQTT demo requires some memory optimisations.

The MQTT demo works best when optimised for release, as the loadable Zap is 10K smaller.

Reducing the memory buffer size to 17K also saves some memory space. See the network.buffer.size variable:

> set network.buffer.size 17408

Resources

You need to download the certificates to the device. You can use the manifest.json file to manage this. See Development, Settings and Resources, Application Resources. See below for an example manifest:

{
   "files": [
      {
         "flags": 0, 
         "local_path": "resources/aws_ca_cert.pem", 
         "name": "aws_ca_cert.pem", 
         "remote_path": "aws_ca_cert.pem", 
         "type": 254, 
         "version": "1.0.0"
      },
      {
         "flags": 0, 
         "local_path": "resources/aws_client_cert.pem", 
         "name": "aws_client_cert.pem", 
         "remote_path": "aws_client_cert.pem", 
         "type": 254, 
         "version": "1.0.0"
      },
      {
         "flags": 0, 
         "local_path": "resources/aws_client_key.pem", 
         "name": "aws_client_key.pem", 
         "remote_path": "aws_client_key.pem", 
         "type": 254, 
         "version": "1.0.0"
      }
   ], 
   "search_paths": [
      ""
   ]
}

A number of settings can be managed with the settings.ini file. See Development, Settings and Resources, Application Settings. See below for an example settings file:


network.tls.ca_cert aws_ca_cert.pem
network.tls.client_cert aws_client_cert.pem
network.tls.client_key aws_client_key.pem
network.buffer.size 17408

bus.command.read_timeout 5000

mqtt.host A1NNFAKJYT1OHL.iot.us-east-1.amazonaws.com
mqtt.port 8883
mqtt.client Zentri
mqtt.user ""
mqtt.password ""
mqtt.security 1
mqtt.keepalive 60
mqtt.qos 0

Note that the variable values depend on your setup, and in particular values for the certificate files, mqtt.host, mqtt.client and mqtt.password must be changed to fit your AWS setup.

Description

This app demonstrates using the MQTT protocol to connect to the Amazon IoT broker and update messages, or subscribe to updates. The app creates custom commands for MQTT actions, such as connect, subscribe, publish, unsubscribe, and disconnect.

Usage Instructions

Open a ZentriOS serial terminal to the device. See Getting Started, Opening a ZentriOS Terminal.

This app assumes your ZentriOS device is set up with the credentials to join your local network. If you have not already set up network credentials, on the ZentriOS terminal, run the commands:

network_up -s
save

See the Wi-Fi Command API documentation for network_up and save.

Before starting, set up an AWS account. See http://aws.amazon.com. Adjust the variable values as required for your account values and certificate files. See Resources above. Compile and run the app.

Note that in the example output values for IP addresses, host and so on vary depending on your setup.

On starting the app displays a message similar to the following:

> Network is down, restarting...
[Associating to Zentri_Guest]
> Security type from probe: WPA2-AES
Obtaining IPv4 address via DHCP
IPv4 address: 192.168.6.113
[Associated]
> MQTT Demo Application Started:
  - List all variables                        : get mqtt
  - Set variable <mqtt.var> to value <val>    : set mqtt.var val
  - Connect to broker <mqtt.host:port>        : mqtt_connect
  - Subscribe to topic                        : mqtt_subscribe <topic>
  - Publish <mqtt.message> to topic           : mqtt_publish <topic>
  - Unsubscribe from topic                    : mqtt_unsubscribe <topic>
  - Disconnect from broker <mqtt.host>        : mqtt_disconnect

Ready

Ensure that the mqtt variables are set to the required values. You can do this with the settings file, as described above in Resources. For example:

> get mqtt
mqtt.client: Zentri
mqtt.host: A1NNFAKJYT1OHL.iot.us-east-1.amazonaws.com
mqtt.keepalive: 60
mqtt.message: Hello Zentri!
mqtt.password:
mqtt.port: 8883
mqtt.qos: 0
mqtt.security: 1
mqtt.user:

Set variables to updated values as required.

Now use the mqtt_connect command to connect to the specificed MQTT host. The command response is similar to the following:

> mqtt_connect
Success
> Opening connection with broker A1NNFAKJYT1OHL.iot.us-east-1.amazonaws.com:8883
[2016-03-03 | 06:36:02: Opening: A1NNFAKJYT1OHL.iot.us-east-1.amazonaws.com:8883]
> Resolving host: A1NNFAKJYT1OHL.iot.us-east-1.amazonaws.com
Connecting (TLS): 54.236.181.116:8883
[2016-03-03 | 06:36:05: Opened: 0]
> Connection established
Connecting...

Now you can subscribe to an available message topic. For example, subscribe to notifications of changes to the shadow state:

> mqtt_subscribe $aws/things/fridge/shadow/update/accepted

The response is similar to the following:

Success
BETA> Subscribing to topic '$aws/things/fridge/shadow/update/accepted'
Send SUBSCRIBE frame
Received SUBACK
TOPIC SUBSCRIBED

You can publish a message. This is a two-step process, assuming you have run mqtt_connect recently as above. First set the message, then publish it:

set mqtt.message {\"state\":{\"desired\":{\"color\":\"red\"}}}
mqtt_publish $aws/things/fridge/shadow/update

If you log into the AWS IoT console, you can see the shadow state update with the new value:

In the AWS IoT console, click Update shadow in the detail display at the right. Edit the shadow state json and click Update shadow.

The IoT cloud sends a message publishing the change in shadow state. Because you are subscribed to this topic, your device receives the notification.

In the ZentriOS terminal, the response is similar to the following:

Received PUBLISH
MESSAGE RECEIVED
----------------------------
Topic  : $aws/things/fridge/shadow/update/accepted
Message: {"state":{"reported":{"time":"2016-02-19T01:09:52+00:00","temp":"25.50"},"desired":{"color":"blue","time":"2016-02-19T02:16:11+00:00"}},"metadata":{"reported":{"time":{"timestamp":1457314176},"temp":{"timestamp":1457314176}},"desired":{"color":
----------------------------

Implementation

main.c

zn_app_init

commands.c

This source sets up the custom variables and commands.

Note that the initial settings of the variables are stored in read-only memory to save RAM.

This is a complete demonstration of the procedures for creating custom variables and commands. They all work by calls to the MQTT library.

Source

See: