cloud/mqtt_demo

This example shows how to use Gecko OS MQTT library to connect to different MQTT brokers, and subscribe to queue and publish data.

Requirements and Prerequisites

This app requires a Gecko OS evaluation board and Gecko OS 4.0+.

The example application default broker is set to test.mosquitto.org (publicly available Mosquitto MQTT server/broker over TCP non-secured link). For the example to work with AWS IoT (as documented below), you also need an account with Amazon IoT service and your client certificate/key files. Setup is different for different brokers.

Resources

You need to download the certificates to the device. Your certificate files may have different names and paths. Use the resources manifest.cfg file to manage this. See below for an example manifest:

[aws_ca_cert.pem]
name: aws_ca_cert.pem
path: resources/aws_ca_cert.pem

[aws_client_cert.pem]
name: aws_client_cert.pem
path: resources/aws_client_cert.pem

[aws_client_key.pem]
name: aws_client_key.pem
path: resources/aws_client_key.pem

Next, add the path of manifest.cfg to the makefile:

$(NAME)_RESOURCE_MANIFEST_PATH := resources/manifest.cfg

Setting Certificate Variables

In a Gecko OS terminal , use the following commands to set the values of variables to your AWS certificates and client key:

set network.tls.ca_cert aws_ca_cert.pem
set network.tls.client_cert aws_client_cert.pem
set network.tls.client_key aws_client_key.pem

Description

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

Usage Instructions

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

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

network_up -s
save

See the 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 Your_WiFiNetwork]
> 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                : set mqtt.<var> <val>
  - Connect to broker           : mqtt_connect
  - Disconnect from broker      : mqtt_disconnect
  - Subscribe to topic          : mqtt_subscribe <topic> [qos_level]
  - Unsubscribe from topic      : mqtt_unsubscribe <topic>
  - Publish to topic            : mqtt_publish <topic> <message> [qos_level] [retained]
  - Check if connected          : mqtt_is_connected

It also lists the different use of each MQTT custom variable:

MQTT variables description:
  - mqtt.auto_reconnect         : Automatically attempt to reconnect to the broker if the underlying network connection becomes disconnected
  - mqtt.broker_hostname        : Host or IP address of the broker
  - mqtt.broker_port            : Port to use for the broker connection (typically 1883, or 8883 for TLS)
  - mqtt.clean_session          : When true the broker deletes any previous undelivered messages and subscription information when connecting
  - mqtt.client_id              : A client ID for this connection (must be unique for the broker). Must be null terminated
  - mqtt.keep_alive_interval    : MQTT keep alive interval in seconds
  - mqtt.password               : Optional password for this connection. Must be null terminated
  - mqtt.username               : Optional username for this connection. Must be null terminated
  - mqtt.use_tls                : If the connection should use TLS instead of TCP
  - mqtt.version                : MQTT protocol to use for this connection, '3.1' or '3.1.1' are supported
  - mqtt.will.message           : MQTT will message to be sent. Must be null terminated
  - mqtt.will.qos_level         : MQTT QoS level for the will message
  - mqtt.will.retained          : If the will message should be retained by the broker
  - mqtt.will.topic             : Topic the will message should be published to

Ensure that the mqtt variables are set to the required values. As stated earlier, the default values are set to connect to Mosquitto server. In this example, we update the values to work for our AWS broker instance (A1NNFAKJYT1OHL). Use the following commands to set the mqtt variables:

> set mqtt.broker_hostname A1NNFAKJYT1OHL.iot.us-east-1.amazonaws.com
Set OK
> set mqtt.broker_port 8883
Set OK
> set mqtt.use_tls 1
Set OK
> set mqtt.will.qos_level 0
Set OK
> set mqtt.will.retained 0
Set OK
> get mqtt
mqtt.auto_reconnect: 1
mqtt.broker_hostname: A1NNFAKJYT1OHL.iot.us-east-1.amazonaws.com
mqtt.broker_port: 8883
mqtt.clean_session: 1
mqtt.client_id:
mqtt.keep_alive_interval: 30
mqtt.password:
mqtt.use_tls: 1
mqtt.username:
mqtt.version: 3.1.1
mqtt.will.message: offline
mqtt.will.qos_level: 0
mqtt.will.retained: 0
mqtt.will.topic: status

Note : for AWS IoT broker, the mqtt.will.retained variable needs to be set to 0 . Otherwise connection will fail. Set other variables to updated values as required.

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

> mqtt_connect
[2019-03-31 | 10:49:33: Opening: A1NNFAKJYT1OHL.iot.us-east-1.amazonaws.com:8883]
Resolving host: A1NNFAKJYT1OHL.iot.us-east-1.amazonaws.com
Connecting (TLS): 52.2.109.246:8883
Success
>

Now you can subscribe to an available message topic, assuming you have run mqtt_connect recently as above.

For example, subscribe to the state update of a thing (display):

> mqtt_subscribe $aws/things/display/shadow/update

For more information about AwS MQTT topics, please refer to the AWS IoT Developer Guide .

You can publish a message to the same topic you are subscribed to:

> mqtt_publish $aws/things/display/shadow/update "{\"state\":{\"desired\":{\"message\":\"Hello from Silicon Labs\"}}}"

You should receive the same message, as you are already subscribed to this topic. In the Gecko OS terminal, the response is similar to the following:

> [MQTT] Received from topic: '$aws/things/display/shadow/update', Message: '{"state":{"desired":{"message":"Hello from Silicon Labs"}}}'

Also, if you log into the AWS IoT console, you can see the thing state updated with the new value:

You can also update the state value in the AWS IoT console, and the device will receive a notification similarly. To do so, click Edit in the previous view ( thing > Shadow ). Enter the new value and click Save .

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

Implementation

main.c

The gos_app_init function initialises the MQTT connection object with gos_mqtt_init .

mqtt_cli_commands.c / mqtt_cli_variables.c

These source files set 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.

nvm_defaults.c

Default values for the MQTT variables. You can overwrite these values with your defaults.

Note: The MQTT component is based on Paho open source project, and code is accessible at components\gecko_os\cloud\mqtt\paho