ModusToolbox, with the release of the AnyCloud libraries, provides a great platform to seamlessly develop connectivity-based projects with the PSoC 6 MCU and CYW43xxx Wi-Fi + Bluetooth combo devices. Since it does not tie you to a specific cloud management solution, you can choose a cloud service that suits your application.
In this blog, we will look at an overview of the MQTT protocol and see how to configure PSoC 6 MCU as an MQTT client using the AnyCloud libraries.
MQTT is a light-weight Machine-to-Machine (M2M) connectivity protocol. It is based on the publish/subscribe messaging model and is usually run over the TCP/IP protocol. It is designed for connections with remote locations where a "small code footprint" is required or the network bandwidth is limited. Other features include faster response time, low power requirement, and ease of scalability. These characteristics make it ideal for use in embedded devices intended to implement IoT (Internet of Things) applications.
The MQTT protocol defines two types of network entities: a message broker (server) and a number of clients. An MQTT broker is a server that receives all messages from the clients and then routes the messages to the appropriate destination clients. An MQTT client is any device that runs an MQTT library and connects to an MQTT broker over a network.
As per the publish/subscribe model, the MQTT clients send messages (the publishers) to the server or receive the messages (the subscribers) from the server. The publishers and subscribers never contact each other directly. In fact, they are not even aware that the other exists. The connection between them is handled by the broker (server). The job of the broker is to filter all incoming messages and distribute them correctly to subscribers.
MQTT uses subject-based filtering of messages. Every message contains a topic (subject) that the broker can use to determine whether a subscribing client gets the message or not. Information is organized in a hierarchy of topics. When a publisher has a new item of data to distribute, it sends a control message with the data to the connected broker. The broker then distributes the information to any clients that have subscribed to that topic. This concept is better illustrated in the figure shown.
In the example shown in the figure, there are totally four MQTT clients (one publisher and three subscribers) that connect to an MQTT server. Two clients subscribe to ‘topic1’ and another to ‘topic2’. When the publisher publishes a ‘Message’ to the broker on the ‘topic1’, the broker distributes the ‘Message’ only to the clients that have subscribed to ‘topic1’. The client that subscribed to ‘topic2’ will not receive the ‘Message’. It is to be noted that the above diagram depicts only a logical separation between the publisher and the subscriber. In practice the publish and subscribe operations can be run on the same MQTT client (i.e. on the same device).
To learn more about the MQTT protocol, you can refer to the HiveMQ – MQTT essentials series.
The MQTT Client library simplifies the process of creating an MQTT client and connecting to an MQTT broker. It uses the AWS IoT Device SDK MQTT Client library. The library implements an MQTT 3.1.1 client that support MQTT connection over both secure and non-secure TCP connections. The APIs are multithreaded by default with support for asynchronous operation. The library is built on top of FreeRTOS, lwIP, and Mbed TLS. The MQTT client library handles all the underlying operations like socket creation which greatly simplifies the MQTT connection process with the server. The AnyCloud solution also offers a Wi-Fi Connection Manager which makes Wi-Fi connections easier and more reliable.
Developing applications with the AnyCloud MQTT client library
The following diagram illustrates the basic operations that must be performed by an MQTT publisher and a subscriber. These operations are independent of the MQTT broker being used. Note that this diagram only provides a basic set of operations to be performed. In a practical application, there will be additional code required to handle the MQTT connection like disconnect callbacks, cleanup code, etc.
We have developed the MQTT client code example to help you implement an MQTT client on your PSoC 6 MCU and CYW43xxx connectivity devices. In this example, the MQTT client establishes a connection with the configured MQTT Broker (AWS IoT Core in this example) and creates two tasks - publisher and subscriber. The publisher task publishes messages on a topic when the user button is pressed. The subscriber task subscribes to the same topic and controls the user LED based on the messages received. Both publish and subscribe operations are performed in a single code example so that you can observe the entire MQTT functionality with a single development kit.
To get started with AnyCloud and the MQTT client example, you can start exploring the examples in the GitHub repository. To try the code examples, you need to install the ModusToolbox software which can be downloaded from this link. Once installed, you can directly import and use the code examples from the Eclipse IDE for ModusToolbox. Refer to the code example README.md to know more about importing and using the MQTT Client code example.
The MQTT client example is developed and tested to work with the AWS IoT Core service which needs an active AWS account. Follow the steps given below to setup the MQTT device (also known as a ‘Thing’) in the AWS IoT Console.
- Sign in to the AWS IoT console. If you do not have an AWS account, follow these instructions to create one.
- Create a Thing in the AWS IoT Console:
- Click on Manage in the navigation page.
- Click on Create > Create a single thing.
- Enter a name for your thing in the Name field. Choose Next and proceed to register a thing.
- Register the Thing:
Create a device certificate
- On the ‘Add a certificate for your thing’ page, choose Create certificate.
- Click on Download links to download the certificate, private key, and root CA for AWS IoT Core, and then choose Activate to continue.
- Choose Done to return to the main page of the AWS IoT console.
Create an AWS IoT Core policy
- In the left navigation pane, choose Secure, and then click on Policies. Click on Create.
- Enter a name for the policy in the Name field.
- Under the Action field, enter iot:*. In the Resource ARN field, enter *. Select the Allow check box. This allows all clients to perform all IoT operations.
- Choose Create to continue.
Attach the AWS IoT Core policy to the device certificate
- Head over to Certificates page under Secure section on the left navigation page.
- In the box for the certificate you created, choose ... to open a drop-down menu, and then choose Attach policy.
- Select the check box next to the policy you created in the previous step, and then choose Attach.
Attach the certificate to the thing
- On the certificates page, in the box for the certificate you created, choose ... to open a drop-down menu, and then choose Attach thing.
- Select the check box next to the thing you registered, and then choose Attach.
- Follow the steps given in the README to configure the MQTT client example with the credentials for the Thing created and registered above.
The AnyCloud MQTT client library is designed to work with various MQTT brokers, not just limited to AWS IoT Core. The MQTT Client code example works with AWS IoT Core out-of-box. With few changes to the source code, the example can be configured to work with other MQTT brokers like Mosquitto. The AnyCloud OTA using MQTT example connects to the public MQTT broker test.mosquitto.org to perform over-the-air firmware update using MQTT. Refer to the source code of the OTA example to understand the changes to be made to connect to the Mosquitto broker.
Make sure to check out other AnyCloud code examples from the Cypress GitHub repository...