IoT MQTT protocol tutorial: Control remote peripherals in IoT project

IoT MQTT protocol tutorial describes how to control a remote peripheral. We have already covered the MQTT protocol and how it works and we already know the IoT MQTT protocol is used to send data from remote sensors. Just to recap briefly MQTT is a lightweight protocol used in the telemetry. As you may already know IoT MQTT protocol is an IoT messaging system used to exchange data between a central server called MQTT broker and one or more clients (MQTT clients).

Several IoT platforms support MQTT as IoT messaging system to exchange data with remote IoT boards. Usually, IoT boards use MQTT to connect to the IoT platforms that acquire information. In this scenario, the IoT prototyping board is the MQTT client while the IoT platform acts as an MQTT broker. This is the main scenario where MQTT is mainly used. Anyway, it is possible to use MQTT IoT protocol in a slightly different way to send data from an MQTT client to another MQTT client through an MQTT broker. In this way, IoT MQTT protocol is exploited to control a remote device. Let us a see how to implement this.

Project description

In this project, we want to control a prototyping board (like MKR1000) using MQTT. In other words, the target of this project is controlling an RGB Led Matrix remotely using MQTT.
To build this project, we will use:

  • Arduino MKR1000
  • 4×4 RGB Led Matrix

The MKR1000 will connect to Ubidots cloud platform using MQTT. This project is divided into two steps:

  1. Configure the Ubidots to handle the RGB color components using the web interface
  2. Develop an MQTT client to connect to Ubidots and manage the RGB Led Matrix

At the end of this project, we control the RGB Led matrix remotely using Ubidots web interface.

Configure the IoT platform: Ubidots

In this first step, we will configure the Ubidots interface to handle the three color components. We will use sliders to control them. Let us begin.

Before continuing you have to create a free account using this link. Log into the application and click on the Device to create a new device. mqtt tutorial config

We used RGB Controller as the device name. A device acts as a data container where we can group variables that hold the data exchanged. Once the device is ready, we can start adding a new variable:

mqtt add variable

We create three variables called:

  • redColor
  • greenColor
  • blueColor

Now it is time to create the dashboard that we will use to control these variable values. Go to Dashboard and click on add. Give a name to your dashboard and start adding controls. In this project, we add sliders so click on add new widget and then on slider:

iot platform tutorial

Select the device (aka the datasource) previously configured:


Select the RGB Controller and you will see three variables:

Select one of them and repeat the process for all three variables. At the end, you will have a dashboard that looks like:

IoT mqtt protocol tutorial

How to build IoT projects using MQTT protocol #IoT #tutorial Click To Tweet

How to implement a client to handle the IoT MQTT protocol

Once the IoT platform is configured we can focus our attention on the IoT MQTT client. This client receives the data from the platform and manages the RGB Led matrix. To create the client, we use the following libraries:

The first step is initialized the Neomatrix providing a set of information like the matrix width and height and the pin number. In our case, the RGB Led matrix is connected using MKR PIN 5.

Adafruit_NeoMatrix matrix = Adafruit_NeoMatrix(4, 4, 5,
                           NEO_MATRIX_TOP     + NEO_MATRIX_RIGHT +
                          NEO_GRB + NEO_KHZ800);

Notice the first three parameters represent the number of LEDs in a row and in a column. Using matrix instance we can color the matrix.

If you are worried about MQTT security read this article explaining how to secure MQTT using SSL/TSL

Let us implement the MQTT client. This project uses MKR1000 so a WIFI connection:

WiFiClient net;
MQTTClient mqttClient;

void setup() {
  Serial.println("Configuring the net...");
  WiFi.begin("your WiFi SID", "your WiFi password");

  while (WiFi.status() != WL_CONNECTED) {
  mqttClient.begin("mqtt://", net);

In the setup() method, we simply initialize the WiFi connection and the mqttClient. To initialize the mqtt client we have to set the MQTT server (Ubidots server address) and the net.
The connect() method handles the connection and the MQTT topic subscription. According to the Ubidots docs, each variable defined in the datasource (aka device) has it is own topic:


Notice that the lv, at the end of the topic, stands for last value. In other words, we are interested only on the last variable value to control the RGB LED matrix. In this project, the application has to subscribe to the following topics:


So the connect() method is:

Once the application is connected to the MQTT server and subscribed to the variable topics, we have to implement the method that listens to the values coming from the MQTT server. To this purpose, we have to implement a method named:

messageReceived(String topic, String payload, char * bytes, unsigned int length)

In this method the application has to do the following tasks:

  • identify the topic that holds the message
  • convert the message to the color component value
  • control the RGB LED matrix setting the new color

This is the method implementation:

void messageReceived(String topic, String payload, 
                        char * bytes, unsigned int length) {
  if (topic.indexOf("redColor") >= 0) {
    red = atoi(bytes);
  else if (topic.indexOf("greenColor") >= 0) {
    green = atoi(bytes);
   else if (topic.indexOf("blueColor") >= 0) {
    blue = atoi(bytes);

That’s all. In the last two lines of the method, we use the instance of matrix to fill the RGB LED matrix with the color identified by red, green, blue component and we show it.

Now you can try to use the three sliders in the Ubidots IoT console to change the RGB LED matrix color.

This project can be further developed. You can use an Android MQTT client app that you can download from google play store and control the RGB LEDs from your smartphone.


At the end of this post, hopefully, you have gained the knowledge about IoT MQTT protocol and how to use it to control remote peripheral.

More posts...

By continuing to use the site, you agree to the use of cookies. more information

The cookie settings on this website are set to "allow cookies" to give you the best browsing experience possible. If you continue to use this website without changing your cookie settings or you click "Accept" below then you are consenting to this.