Introduction: Use MQTT to Upload and Listen to Ameba

MQTT (Message Queue Telemetry Transport) is a "lightweight" messaging protocol based on TCP/IP protocol proposed by IBM and Eurotech in 1999. It is designed for connections with remote locations where a "small code footprint" is required or the network bandwidth is limited. The design principles are to minimize network bandwidth and device resource requirements. These principles also turn out to make the protocol ideal for the emerging “machine-to-machine” (M2M) or “Internet of Things” world of connected devices.

The publish-subscribe messaging pattern requires a message broker. The broker is responsible for distributing messages to interested clients based on the topic of a message. We can even say MQTT is a protocol designed for IoT. All the current major IoT cloud player like Amazon, Apple, Microsoft, IBM, etc all supports MQTT. There are several roles of MQTT operation:

  • Publisher: Usually publishers are the devices equipped with sensors (ex. Ameba ). Publishers uploads the data of the sensors to MQTT-Broker, which serves as a database with MQTT service.
  • Subscriber: Subscribers are referred to the devices which receive and observe messages, such as a laptop or a mobile phone.
  • Topic: Topic is used to categorized the messages, for example the topic of a message can be "PM2.5 sensor", "temperature sensor" or "secure camera". Subscribers can choose messages of which topics they want to receive

The only equipment we need in this Instructables is RTL8195 based IoT Ameba board. We use this Arduino compatible board simply because of the build in wifi. You can search for "Seeedstudio Ameba" in Amazon for it.

Step 1: Code Preparation

In this example, we connect Ameba to MQTT-Broker. Then send messages as publisher and receive messages from MQTT-Broker as subscriber. Once you get your Ameba board and installed Arduino for it. Open file: “File” -> Examples -> AmebaMQTTClient -> mqtt_basic”. There are two highlighted code you need to pay attention to:

  • You need to fill in SSID and password of your wireless AP in order for this example to work.
  • There are five character string in second part of the code:

  1. The "mqttServer" refers to the MQTT-Broker, we use the MQTT sandbox "", it is provided by IBM eclipse for developers to test MQTT. Leave it unchanged.
  2. "clientId" is an identifier for MQTT-Broker to identify the connected device.
  3. "publishTopic" is the topic of the published message, we use "outTopic" in the example. The devices subscribe to "outTopic" will receive the message.
  4. "publishPayload" is the content to be published. You can change to whatever string you want.
  5. "subscribeTopic" is to tell MQTT-broker which topic we want to subscribe to. Next, compile the code and upload it to Ameba. Press the reset button, then open the serial monitor

Compile the code after your changes and upload it to Ameba. Press the reset button, then open the serial monitor. You'll see messages that it try to connect with AP and send "inTopic" message. All used libraries are standard Arduino library so any standard Arduino board should be able to run the code. The sketch is attached.

Step 2: MQTTLens Installation

We are going to use a chrome plugin called "MQTTLens" to be the MQTT client. Use Chrome to search for "MQTTLens" in Google and click on the link, MQTTLens popup will show on the scree, click on "Add to Chrome", then click on "Add app" on next popup. The plugin will then be downloaded and installed in your computer.

Step 3: Add Connections

After the installation of MQTTLens plugin, you can launch it now. Click on the plus sign "+" next to "Connections" on the left to add a new connection. We then need to fill in the required information:

  • Connection Name: Used to identify the connection, you can choose a name you like.
  • Hostname: The MQTT-Broker server, we use "" that needs to be matched with mqttServer[] as in the code
  • Client ID: Leave it unchanged and use the default randomly generated ID.

Click "CREATE CONNECTION" on lower right to create it.

Step 4: Run the Test

Since we have not registered the topic we want to listen to, we would not receive any messages now. Let's fill in "outTopic" in the subscribe field, and click "SUBSCRIBE" button. Now you should see the "hello world" message in Subscriptions filed in the lower half send from Ameba. Now we can experiment with the Publish. Fill in "inTopic" then type in any message in the Message file, then click on "PUBLISH" button, now you should see the message you just typed in showed up in Ameba/Arduino serial terminal.