• News
  • Cayenne MQTT and Standalone ESP8266 ESP-01

Cayenne MQTT and Standalone ESP8266 ESP-01

October 19, 2017

Contributing Cayenne Tribe member Eldon Tenorio demonstrates how to use the ESP8266 ESP-01 WiFi Module with Cayenne.


By Eldon Tenorio

Have you ever thought of using your ESP8266 ESP-01 WiFi Module as a standalone board for three (3) components namely DHT11 Sensor (for Temperature and Humidity), 1-Channel Relay Module and a Sound Sensor? Well, lucky for you, this is possible! Plus, there’s more: All these components are controlled and monitored via one of the IoT platforms available there: Cayenne IoT Platform.

Here is what we need:

  1. ESP8266 ESP-01 WiFi Module
  2. FTDI Breakout Board + Mini USB cable
  3. ESP8266 ESP-01 Breakout Board (Optional)
  4. 1-Channel Relay Module
  5. DHT11 Temperature and Humidity Sensor
  6. Sound Sensor
  7. Breadboards (I will be using 2 small breadboards)
  8. 5V to 3.3V Stepdown Buck Module (Optional)
  9. Plenty of jumper wires

Firstly, we need to study the pinouts for these components. Here are the main modules that we are going to use for this exercise. Please have time to study them, especially the pin assignments. You might have a different variant of the components as well, so please take note of the pin labels:


ESP8266 ESP-01 Wifie Module

ESP8266 ESP-01

We need to be careful since this board runs on a 3.3V logic. VCC (although I tried powering it with 5V and nothing happened) should be connected to 3.3V. Same goes to CH_PD. RX should be connected to TX of the FTDI breakout board, through a voltage divider. You can set the jumper in your FTDI Module to 3.3V if it has one. The FTDI module I am using gives you the option to choose between 5V and 3.3V. Just in case your power supply only provides 5V, refer to the voltage divider below. You may choose the correct resistors to provide ample power to your ESP8266 module.img_4636-1

1-Channel Relay Module

1-Channel Relay Module
The Relay Module that I am using is the one above. It has three different pins for power and signal. For power, pin labels are VCC and GND. To turn the relay on or off, the pin labeled IN is used. While I was doing the experiment, the relay works very well with a 3.3V power supply. I attached the signal. Study how the relay is used to control high-voltage devices as well (this is optional in this activity).


DHT11 Temperature and Humidity Sensor

This is the DHT11 sensors. It reads the temperature and humidity of the location where the sensor is. It has two pins for power (“-” for GND, the middle pin is VCC). Pin labeled “S” is the input pin. Readings are received thru this pin.

Sound Sensor

Sound Sensor
The sound sensor also has 3 pins: VCC, GND and OUT. The OUT pin sends the level of sound in the location where the sensor is. You may also control its sensitivity by turning the potentiometer on it (blue box with white “gear” inside).

FTDI USB to TTL Serial Converter

FTDI USB to TTL Serial Converter
This is the USB to TTL Serial Converter. We use this board to upload our sketches to the ESP8266 ESP-01 WiFi Module. It can also be used to program various microcontrollers. The board usually has 6 pins (although you can solder more header pins on both sides of the board): DTR, RX, TX, VCC, CTS, and GND. CTS isn’t usually used. For our activity, only 4 pins are needed: RX, TX, VCC and GND.

In the picture below, I have set the FTDI module to 3.3V by changing the set up of its jumper:

When the 1st and 2nd pins are connected, the FTDI module will provide a 5-volt power (same goes with TX pin as well). When the 2nd and 3rd pins are connected, it will provide 3.3-vols power (same with TX pin as well).

5V to 3.3V Stepdown Power Supply Buck Module (OPTIONAL)

5V to 3.3V Stepdown Power Supply Buck Module
This is OPTIONAL unless your FTDI breakout board does not give you the option to change voltage (usually between these two: 3.3V and 5V). The 5V to 3.3V Stepdown Power Supply Buck Module is used to “convert” 5V to 3.3V as its name implies. Very useful for modules using 3.3V logic.

Before proceeding with coding, we need to have the following set up in Arduino IDE. For the libraries, download them from the link provided for each library (see below) at Github.

  1. ESP8266 Boards – For step by step instructions, please see next section.
  2. SimpleDHT Libraries – SimpleDHT libraries can be downloaded here.
  3. SimpleTimer Libraries – Simple Libraries can be downloaded here.

ESP8266 Boards Set Up in Arduino IDE

Setting up the ESP8266 boards is quite easy. Please follow the steps below:

  1. Open your Arduino IDE.
  2. Go to File > Preferences.
  3. From the Additional Boards Manager URLs text field, place this URL: http://arduino.esp8266.com/stable/package_esp8266com_index.json. Click OK afterwards.
  4. Now, go to Tools > Board > Boards Manager.
  5. In Boards Manager, search for esp8266and install the esp8266 by ESP8266 Community Version x.x.x. The close the Boards Manager window.
  6. Go to Tools > Board then scroll through the list, until you find Generic ESP8266 Module.

Adding Required Libraries

  1. Go to the link provided above for the two (2) required libraries (SimpleDHT and SimpleTimer.
  2. For each link, click Clone or Download. A small window appears, then click Download Zip. Refer to the images shown below:SimpleDHTLibraryDownload.pngSimpleTimerLibraryDownload
  3. Save the ZIP file for each library.
  4. In the Arduino IDE, go to Sketch > Include Library > Add .Zip Library.
  5. Locate and add each library (one at a time).

Adding the Cayenne Libraries

Cayenne Libraries can be installed to the Arduino IDE via the Library Manager. To do this, follow the steps below:

  1. In the Arduino IDE, go to Sketch > Include Library. Click Manage Libraries.
  2. In the windows that will appear, type Cayenne in the search field. Install the Cayenne by myDevices Version x.x.x and CayenneMQTTby myDevices Version x.x.x. Close the window afterwards. These libraries are also available at Github (Cayenne and CayenneMQTT libraries).ArduinoIDE_LibraryManager

Programming Mode

Initially, we need to set up our ESP8266 ESP-01 to programming mode. We don’t need to connect our components yet, as connecting them might cause the uploading of the sketches to fail. The table below details what pins are connected to each other between the ESP8266 ESP-01 WiFi module and the FTDI USB to TTL Serial Converter:

Program Mode Connections

You need to set the jumper of the FTDI module to 3.3V. This way, we won’t be needing any voltage divider or the step down buck module. Your USB to Serial Converter might have different pin assignments. The above description is demonstrated in the schematic below:

ESP8266 Project 3v3 Program Mode_bb

That’s it! We are now ready to set up our dashboard and upload the sketches:
Upload the sketch


Create the Cayenne Dashboard

  1. Log on to your Cayenne account (register for FREE if you haven’t one yet at Cayenne Signup Page):
    Cayenne USB Serial - 01 Logon
  2. Once logged in, the next step would be to choose the device we are going to use. If this is your first device in your dashboard, choose All Devices:
    1 - All DevicesThen, choose Generic ESP8266 under Microcontrollers:
    2 - ESP8266If you already have existing devices added in previously, you need to add a device by clicking the Add Devices/Widget menu:
    Cayenne USB Serial - 02 Add New Device
    Then choose ESP8266 since this is our development board:
  3. In the succeeding page, you are shown with the MQTT Username, MQTT Password, and Client ID. We need these details in the sketch later. You will also see at the bottom portion of the page that it is waiting for the device to connect.
  4. Now, we proceed with the Sketch. Open the Arduino IDE. Go to File > Examples > Cayenne-MQTT-ESP8266 > ESP8266. This sketch will be our base sketch.MQTT Sketch
  5. Go back to the Cayenne Portal. Take note of the following, because we are going to use it in our sketch:
  6. Now, go back to the Arduino IDE. Paste the values in the section highlighted in the screenshot below:
    MQTT Creds Section
  7. Also, supply the WiFi name (SSID) and password in this section of the code:
    Wifi creds
  8. By the way, we need to include the needed libraries: SimpleDHT and SimpleTimer. The SimpleDHT will allow us to use the DHT Temperature. The SimpleTimer will allow us to execute methods outside the loop() method:
    Additional Libraries
  9. We now need to declare the pins to be used by the sensors.
    • DHT11 Pin = Pin 2 (GPIO2 of ESP8266 ESP-01)
    • Sound Pin = Pin 3 (GPIO3 of ESP8266 ESP-01)
    • Relay Pin = Pin 1 (GPIO1 of ESP8266 ESP-01)
      Sensor declaration
  10. Since we are going to send data to the Cayenne IoT platform using MQTT API, we need to pass the sensor value to the virtual pins. The virtual pins will be used by the widgets in our dashboard. We are not going to use V1, because we assigned this as an output (to control the relay – used in the Cayenne dashboard widgets):
    • V2 – Humidity (data from DHT11)
    • V3 – Temperature (data from DHT11)
    • V4 – Sound (data from Sound Sensor)
  11. Upload the sketch to the ESP8266 ESP-01 Board. Be sure that the chosen board is Generic ESP8266 Module:ESp8266 board on board

Complete Code

// This example shows how to connect to Cayenne using an ESP8266 and send/receive sample data.
// Make sure you install the ESP8266 Board Package via the Arduino IDE Board Manager and select the correct ESP8266 board before compiling.

#define CAYENNE_PRINT Serial
#include <CayenneMQTTESP8266.h>

#include <SimpleTimer.h> // Download from https://github.com/jfturcot/SimpleTimer
#include <SimpleDHT.h> // Download from https://github.com/adafruit/DHT-sensor-library

// WiFi network info.
char ssid[] = "<your ssid/wifi name>";
char wifiPassword[] = ""<your ssid/wifi password>"";

// Cayenne authentication info. This should be obtained from the Cayenne Dashboard.
char username[] = "<your MQTT Username>";
char password[] = "<your MQTT Password>";
char clientID[] = "<your client id>";

// DHT11 Pin
int pinDHT11 = 2;
SimpleDHT11 dht11;

// Sound Pin
int soundPin = 3;

// Relay Pin
int relayPin = 1;

// Timer
SimpleTimer timer;

void setup() {
 Cayenne.begin(username, password, clientID, ssid, wifiPassword);
 pinMode(relayPin, OUTPUT); // Relay
 digitalWrite(relayPin, HIGH);
 pinMode(soundPin, INPUT); // Sound
 timer.setInterval(200L, transmitData); // Method to execute every 200ms

void loop() {

CAYENNE_IN(relayPin) {
 if (getValue.asInt() == 1) { // NOTE: Channel = Virtual Pin
 digitalWrite(relayPin, LOW);
 else {
 digitalWrite(relayPin, HIGH);

void transmitData()
 byte temperature = 0;
 byte humidity = 0;
 int err = SimpleDHTErrSuccess;

if ((err = dht11.read(pinDHT11, &temperature, &humidity, NULL)) != SimpleDHTErrSuccess) {
 Cayenne.virtualWrite(V4, 0);
 Cayenne.virtualWrite(V2, 0);
 else {
 Cayenne.virtualWrite(V4, (int)temperature);
 Cayenne.virtualWrite(V2, (int)humidity);

if (digitalRead(soundPin) == HIGH) {
 Cayenne.virtualWrite(V3, HIGH);
 else {
 Cayenne.virtualWrite(V3, LOW);

Connecting the Sensors and Modules

At this stage, you should be able to upload your sketch successfully. Now, remove the board from power. Also, remove the connection GND from GPIO0. We don’t need GPIO0 connected to GND, unless we are going to update the sketch. Refer to the tables for each sensor and module below:

Sensor and Modules Connections

All these components’ power supplies are connected to the output voltage of the step down module, meaning they are powered via 3.3V. The main power supply is the FTDI breakout board. The schematic below shows the complete connections, after successfully uploading the sketch:

ESP8266 Project 3v3_ no rx and tx connection

NOTE: The RX and TX pins of the FTDI module aren’t connected to the TX and RX pins of the wifi module, and so is GPIO0 (from GND).

The image below is the actual set up of the schematics shown above:

That’s it! We’re done with these setups: Boards, Libraries, and Components. We are now ready to configure our project with Cayenne using MQTT. By the way, MQTT stands for MQ Telemetry Transport. Simply speaking, it is a messaging transport protocol between machines and Internet of Things! More on this at Cayenne Docs.

Power the board once again. The ESP8266 ESP-01 Wifi Module should be able to connect to your Wifi. Now, go back to the Cayenne portal. You should be able to see the dashboard with pre-populated initial widgets which you can add to the dashboard. You may now customize the dashboard.

Initially, this is how the dashboard looks like when the ESP8266 ESP-01 WiFi module starts to send data to the Cayenne Dashboard (under the configured device there):

Initial Dashboard - Cayenne


Add the initial widgets shown above, by clicking the “+” icon at the upper right hand corner of each initial widget:
Add widgets

Once added, we will now customize each widget. This is how it looks like when these initial widgets are added:
added widgets

To customize each widget, click on the right-most icon, then select Settings. Refer to screenshot below:
Customize Widget

A pop-up window appears and will allow us to change the Widget Name, Channel, Widget Icon, and Number of Decimal Places. We will leave Channel as it is. Don’t change the value of Channel, since the value here is the Virtual Pin (V0, V1, V2…) used in the code for this widget. Virtual Pin 4 (V4) is the temperature, Virtual Pin 2 (V2) is the humidity, and Virtual Pin 3 (V3) is the value of the sound sensor (0/1).

Below are the configuration/setting for each initial widget:

Config - HumidityConfig - Sound DetectedConfig - Temperature

Here is how they look afterward:
Config - Finished Initial

Now, we still need to add one more widget. This widget is for the relay, to turn it on/off. On the left side portion of the dashboard (upper-left), click Add New, then click Device/Widget:
Cayenne USB Serial - 02 Add New Device


Scroll down further down, and look for Custom Widgets. Select Button:
Custom Widgets - Button

We need to change the settings for the Button widget:

  • Name = Relay Switch
  • Device = Generic ESP8266 (or your named device if you have already)
  • Data = Digital Actuator
  • Unit = Digital (0/1)
  • Channel = 1 (this is GPIO1 of the ESP8266 ESP-01 WiFi Module – review code)
  • Choose Icon = Button (you may choose what icon you desire)

Below is the screenshot of the Button settings. Click Add Widget afterwards:
Add Button Widget

The final dashboard now looks like this:
Final Dashboard

And we’re DONE! Now, try to switch on/off the Relay Switch. The relay connected to the ESP8266 ESP-01 WiFi Module will turn on or off – you will hear clicking sounds. Try to make some noise. The sound widget will register 1 (if noise is detected, 0 if not). Try observing the Temperature and Humidity widgets – these values change according to what is “sensed” from where the DHT11 module is.

We’ve just used the Cayenne MQTT API to connect our device with components attached to it.




Article by Eldon Tenorio