How to connect an ESP8266 to Xively

What you will learn

This tutorial will teach you how to connect an ESP8266 device to Xively.

Scan this tutorial to get familiar with it. Then complete each step in a sequential manner. Each step builds upon the previous one.


Be a good sport!

Help us make this tutorial a breeze! If you hit rough spots, please take a moment to contribute by clicking on the link titled SUGGEST EDITS at the top right-hand region of this page. We absolutely :hearts: suggestions from you!


Consider using ESP32

This tutorial is a very simple Arduino-based demo that you can easily use to test Xively platform. It is not intended to be efficient or robust in any way, so we strongly recommend using it only for early rapid prototyping and demo purposes.

For production systems, please consider using ESP32, check Xi reference. For greater efficiency and control, consider using LibXively or other MQTT+TLS client implementation, and avoid using Arduino's built in one.

Hardware you will need

  • Adafruit Feather HUZZAH with ESP8266 Wi-Fi
  • Micro USB cable
  • Optional: Lithium Ion Polymer Battery 3.7v 500mAh, needed only if you want the ESP8266 to be portable (not connected to your computer)

Adafruit Feather HUZZAH with ESP8266 WiFi

Alternatively, you can try running this code on any ESP8266-based module. As long as there's enough flash to fit the binary, the application should work. If you do use a different module, you may need to connect an LED for the demo and a UART-USB bridge for programming. Refer to the code and your module's documentation for more details.

Software you will install during the tutorial

  • Arduino IDE - the official Arduino Software IDE that makes it easy to write code and upload it to the board
  • USB driver for the CP2104 USB-to-Serial chip - this driver will enable interfacing with the Feather HUZZAH board

Step 1 of 6: Install the Arduino Software (IDE)

  1. Download the Arduino Software appropriate for your operating system (Windows, Linux or macOS): Download the Arduino Software.

  2. Follow the step-by-step installation instructions for your computer, according to its operating system. Specific installation steps can bee: Install the Arduino Software (IDE).

Step 2 of 6: Install the Feather HUZZAH driver

  1. Download the CP210x USB to UART Bridge VCP drivers appropriate for your operating system (Windows, Linux or macOS): CP210x USB to UART Bridge VCP Drivers.

  2. Extract/unzip the downloaded ZIP file and conduct the installation process appropriate for your operating system (Windows, Linux or macOS).


Did you know? Your device lives in two worlds!

In the Internet of Things (IoT), every physical thing has a matching digital representation. Accordingly, Xively keeps data structures that capture the digital life of your physical device. While the physical device (ESP8266 hardware) is in your hands, the digital device lives on the Xively infrastructure, ready to provide valuable information about its present, past and, soon enough, its future through predictive analytics.

Step 3 of 6: Prepare your physical device

  1. Start the Arduino IDE.
  2. Go to Preferences and, toward the bottom of the window, copy this URL into the Additional Board Manager URLs text box:
3. Click
4. Go to `Tools` > `Boards` > `Boards Manager` and search for "esp8266".
5. Select the entry titled "esp8266 by ESP8266 Community", then click
6. Click
7. Go back to `Tools` > `Boards` and select `Adafruit HUZZAH ESP8266`.
8. Return to
9. Connect your hardware to your computer using the Micro USB cable.
10. Go to `Tools` > `Port` and select
11. Clone or download the [esp8266/Arduino]( repository.
12. Install the `esp8266/Arduino` using the steps [documented in its readme](
cd $ARDUINO_DIR #Your system's $ARDUINO_DIR is the "Sketchbook location" in the Arduino IDE's preferences
cd hardware #If this directory doesn't exist, create it with "mkdir hardware"
mkdir esp8266com
cd esp8266com
git clone esp8266
  1. Restart your Arduino IDE so it loads the new libraries.
  2. In the Arduino IDE Tools > Board menu, select the ESP8266 board we just installed


Installing ESP8266 support manually vs using Board Manager

The ESP8266 implementation currently available via Arduino's Boards Manager is outdated. It does not support TLS certificate chain validation, and it uses TLSv1.1 instead of the 1.2 required by Xively.

If you used the Boards Manager instead of following the instructions above, your code won't compile. If you have installed the Arduino port both manually and using the Board's manager, you'll see duplicate entries in the IDE's board selector. Make sure you pick the option you installed manually.

Step 4 of 6: Set up your digital device

Make sure your account has at least one group created (All groups > + Add new).

Before connecting a physical device to Xively, create its digital representation in the system. Log into the Xively management app to complete the following steps.

Create an ESP8266 device template

  1. Click on Devices > Device templates.
  2. Click on Create new device template.
  3. Enter the template name (for example: "My ESP8266")`.

Add a channel to the template

This operation will create a channel that the device will communicate over (talk and listen).

  1. In the Channels section, click on the + button.
  1. Enter "redled" as the channel name.
  2. Leave the other options as their default and click Save Channel.

Create an individual device

This individual device will represent the specific ESP8266 that you have physically connected for this example.

  1. On the device template page, click Create new device.
  1. In the pop-up window, do the following:
    • Select the device template you have just created (it is selected by default).
    • Select "Single" as the mode of creating devices (it is selected by default).
    • Enter any serial number (for example: "My ESP8266").
    • Associate device with a group (optionally).

3.Click Create.

You created a device template and a digital device instance inside Xively to represent your physical ESP8266 device.

Step 5 of 6: Prepare the ESP8266 client application

In this step you will prepare an example application that will subscribe to Xively.

Prepare the application code

  1. Copy and paste the following code into your Arduino IDE:
  Adafruit MQTT Library ESP8266 Adafruit IO SSL/TLS example
  Must use the latest version of ESP8266 Arduino from:
  Works great with Adafruit's Huzzah ESP board & Feather
  Adafruit invests time and resources providing this open source code,
  please support Adafruit and open-source hardware by purchasing
  products from Adafruit!
  Written by Tony DiCola for Adafruit Industries.
  SSL/TLS additions by Todd Treece for Adafruit Industries.
  MIT license, all text above must be included in any redistribution
#include <time.h>

#include <ESP8266WiFi.h>
#include <Adafruit_MQTT.h>
#include <Adafruit_MQTT_Client.h>

#define XIVELY_BROKER      ""

// Enter your WiFi credentials

// Enter your Xively credentials and topic
#define LED_TOPIC          "YOUR redled TOPIC ADDRESS"

// This string contains globalsign's Root Certificate for TLS validation
const unsigned char globalsignRootCert[888] = {
  0x30, 0x82, 0x03, 0x75, 0x30, 0x82, 0x02, 0x5d, 0xa0, 0x03, 0x02, 0x01, 0x02, 0x02, 0x0b, 0x04, 0x00, 0x00, 0x00, 0x00, 0x01, 0x15, 0x4b, 0x5a,
  0xc3, 0x94, 0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x05, 0x05, 0x00, 0x30, 0x57, 0x31, 0x0b, 0x30, 0x09, 0x06,
  0x03, 0x55, 0x04, 0x06, 0x13, 0x02, 0x42, 0x45, 0x31, 0x19, 0x30, 0x17, 0x06, 0x03, 0x55, 0x04, 0x0a, 0x13, 0x10, 0x47, 0x6c, 0x6f, 0x62, 0x61,
  0x6c, 0x53, 0x69, 0x67, 0x6e, 0x20, 0x6e, 0x76, 0x2d, 0x73, 0x61, 0x31, 0x10, 0x30, 0x0e, 0x06, 0x03, 0x55, 0x04, 0x0b, 0x13, 0x07, 0x52, 0x6f,
  0x6f, 0x74, 0x20, 0x43, 0x41, 0x31, 0x1b, 0x30, 0x19, 0x06, 0x03, 0x55, 0x04, 0x03, 0x13, 0x12, 0x47, 0x6c, 0x6f, 0x62, 0x61, 0x6c, 0x53, 0x69,
  0x67, 0x6e, 0x20, 0x52, 0x6f, 0x6f, 0x74, 0x20, 0x43, 0x41, 0x30, 0x1e, 0x17, 0x0d, 0x39, 0x38, 0x30, 0x39, 0x30, 0x31, 0x31, 0x32, 0x30, 0x30,
  0x30, 0x30, 0x5a, 0x17, 0x0d, 0x32, 0x38, 0x30, 0x31, 0x32, 0x38, 0x31, 0x32, 0x30, 0x30, 0x30, 0x30, 0x5a, 0x30, 0x57, 0x31, 0x0b, 0x30, 0x09,
  0x06, 0x03, 0x55, 0x04, 0x06, 0x13, 0x02, 0x42, 0x45, 0x31, 0x19, 0x30, 0x17, 0x06, 0x03, 0x55, 0x04, 0x0a, 0x13, 0x10, 0x47, 0x6c, 0x6f, 0x62,
  0x61, 0x6c, 0x53, 0x69, 0x67, 0x6e, 0x20, 0x6e, 0x76, 0x2d, 0x73, 0x61, 0x31, 0x10, 0x30, 0x0e, 0x06, 0x03, 0x55, 0x04, 0x0b, 0x13, 0x07, 0x52,
  0x6f, 0x6f, 0x74, 0x20, 0x43, 0x41, 0x31, 0x1b, 0x30, 0x19, 0x06, 0x03, 0x55, 0x04, 0x03, 0x13, 0x12, 0x47, 0x6c, 0x6f, 0x62, 0x61, 0x6c, 0x53,
  0x69, 0x67, 0x6e, 0x20, 0x52, 0x6f, 0x6f, 0x74, 0x20, 0x43, 0x41, 0x30, 0x82, 0x01, 0x22, 0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7,
  0x0d, 0x01, 0x01, 0x01, 0x05, 0x00, 0x03, 0x82, 0x01, 0x0f, 0x00, 0x30, 0x82, 0x01, 0x0a, 0x02, 0x82, 0x01, 0x01, 0x00, 0xda, 0x0e, 0xe6, 0x99,
  0x8d, 0xce, 0xa3, 0xe3, 0x4f, 0x8a, 0x7e, 0xfb, 0xf1, 0x8b, 0x83, 0x25, 0x6b, 0xea, 0x48, 0x1f, 0xf1, 0x2a, 0xb0, 0xb9, 0x95, 0x11, 0x04, 0xbd,
  0xf0, 0x63, 0xd1, 0xe2, 0x67, 0x66, 0xcf, 0x1c, 0xdd, 0xcf, 0x1b, 0x48, 0x2b, 0xee, 0x8d, 0x89, 0x8e, 0x9a, 0xaf, 0x29, 0x80, 0x65, 0xab, 0xe9,
  0xc7, 0x2d, 0x12, 0xcb, 0xab, 0x1c, 0x4c, 0x70, 0x07, 0xa1, 0x3d, 0x0a, 0x30, 0xcd, 0x15, 0x8d, 0x4f, 0xf8, 0xdd, 0xd4, 0x8c, 0x50, 0x15, 0x1c,
  0xef, 0x50, 0xee, 0xc4, 0x2e, 0xf7, 0xfc, 0xe9, 0x52, 0xf2, 0x91, 0x7d, 0xe0, 0x6d, 0xd5, 0x35, 0x30, 0x8e, 0x5e, 0x43, 0x73, 0xf2, 0x41, 0xe9,
  0xd5, 0x6a, 0xe3, 0xb2, 0x89, 0x3a, 0x56, 0x39, 0x38, 0x6f, 0x06, 0x3c, 0x88, 0x69, 0x5b, 0x2a, 0x4d, 0xc5, 0xa7, 0x54, 0xb8, 0x6c, 0x89, 0xcc,
  0x9b, 0xf9, 0x3c, 0xca, 0xe5, 0xfd, 0x89, 0xf5, 0x12, 0x3c, 0x92, 0x78, 0x96, 0xd6, 0xdc, 0x74, 0x6e, 0x93, 0x44, 0x61, 0xd1, 0x8d, 0xc7, 0x46,
  0xb2, 0x75, 0x0e, 0x86, 0xe8, 0x19, 0x8a, 0xd5, 0x6d, 0x6c, 0xd5, 0x78, 0x16, 0x95, 0xa2, 0xe9, 0xc8, 0x0a, 0x38, 0xeb, 0xf2, 0x24, 0x13, 0x4f,
  0x73, 0x54, 0x93, 0x13, 0x85, 0x3a, 0x1b, 0xbc, 0x1e, 0x34, 0xb5, 0x8b, 0x05, 0x8c, 0xb9, 0x77, 0x8b, 0xb1, 0xdb, 0x1f, 0x20, 0x91, 0xab, 0x09,
  0x53, 0x6e, 0x90, 0xce, 0x7b, 0x37, 0x74, 0xb9, 0x70, 0x47, 0x91, 0x22, 0x51, 0x63, 0x16, 0x79, 0xae, 0xb1, 0xae, 0x41, 0x26, 0x08, 0xc8, 0x19,
  0x2b, 0xd1, 0x46, 0xaa, 0x48, 0xd6, 0x64, 0x2a, 0xd7, 0x83, 0x34, 0xff, 0x2c, 0x2a, 0xc1, 0x6c, 0x19, 0x43, 0x4a, 0x07, 0x85, 0xe7, 0xd3, 0x7c,
  0xf6, 0x21, 0x68, 0xef, 0xea, 0xf2, 0x52, 0x9f, 0x7f, 0x93, 0x90, 0xcf, 0x02, 0x03, 0x01, 0x00, 0x01, 0xa3, 0x42, 0x30, 0x40, 0x30, 0x0e, 0x06,
  0x03, 0x55, 0x1d, 0x0f, 0x01, 0x01, 0xff, 0x04, 0x04, 0x03, 0x02, 0x01, 0x06, 0x30, 0x0f, 0x06, 0x03, 0x55, 0x1d, 0x13, 0x01, 0x01, 0xff, 0x04,
  0x05, 0x30, 0x03, 0x01, 0x01, 0xff, 0x30, 0x1d, 0x06, 0x03, 0x55, 0x1d, 0x0e, 0x04, 0x16, 0x04, 0x14, 0x60, 0x7b, 0x66, 0x1a, 0x45, 0x0d, 0x97,
  0xca, 0x89, 0x50, 0x2f, 0x7d, 0x04, 0xcd, 0x34, 0xa8, 0xff, 0xfc, 0xfd, 0x4b, 0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01,
  0x01, 0x05, 0x05, 0x00, 0x03, 0x82, 0x01, 0x01, 0x00, 0xd6, 0x73, 0xe7, 0x7c, 0x4f, 0x76, 0xd0, 0x8d, 0xbf, 0xec, 0xba, 0xa2, 0xbe, 0x34, 0xc5,
  0x28, 0x32, 0xb5, 0x7c, 0xfc, 0x6c, 0x9c, 0x2c, 0x2b, 0xbd, 0x09, 0x9e, 0x53, 0xbf, 0x6b, 0x5e, 0xaa, 0x11, 0x48, 0xb6, 0xe5, 0x08, 0xa3, 0xb3,
  0xca, 0x3d, 0x61, 0x4d, 0xd3, 0x46, 0x09, 0xb3, 0x3e, 0xc3, 0xa0, 0xe3, 0x63, 0x55, 0x1b, 0xf2, 0xba, 0xef, 0xad, 0x39, 0xe1, 0x43, 0xb9, 0x38,
  0xa3, 0xe6, 0x2f, 0x8a, 0x26, 0x3b, 0xef, 0xa0, 0x50, 0x56, 0xf9, 0xc6, 0x0a, 0xfd, 0x38, 0xcd, 0xc4, 0x0b, 0x70, 0x51, 0x94, 0x97, 0x98, 0x04,
  0xdf, 0xc3, 0x5f, 0x94, 0xd5, 0x15, 0xc9, 0x14, 0x41, 0x9c, 0xc4, 0x5d, 0x75, 0x64, 0x15, 0x0d, 0xff, 0x55, 0x30, 0xec, 0x86, 0x8f, 0xff, 0x0d,
  0xef, 0x2c, 0xb9, 0x63, 0x46, 0xf6, 0xaa, 0xfc, 0xdf, 0xbc, 0x69, 0xfd, 0x2e, 0x12, 0x48, 0x64, 0x9a, 0xe0, 0x95, 0xf0, 0xa6, 0xef, 0x29, 0x8f,
  0x01, 0xb1, 0x15, 0xb5, 0x0c, 0x1d, 0xa5, 0xfe, 0x69, 0x2c, 0x69, 0x24, 0x78, 0x1e, 0xb3, 0xa7, 0x1c, 0x71, 0x62, 0xee, 0xca, 0xc8, 0x97, 0xac,
  0x17, 0x5d, 0x8a, 0xc2, 0xf8, 0x47, 0x86, 0x6e, 0x2a, 0xc4, 0x56, 0x31, 0x95, 0xd0, 0x67, 0x89, 0x85, 0x2b, 0xf9, 0x6c, 0xa6, 0x5d, 0x46, 0x9d,
  0x0c, 0xaa, 0x82, 0xe4, 0x99, 0x51, 0xdd, 0x70, 0xb7, 0xdb, 0x56, 0x3d, 0x61, 0xe4, 0x6a, 0xe1, 0x5c, 0xd6, 0xf6, 0xfe, 0x3d, 0xde, 0x41, 0xcc,
  0x07, 0xae, 0x63, 0x52, 0xbf, 0x53, 0x53, 0xf4, 0x2b, 0xe9, 0xc7, 0xfd, 0xb6, 0xf7, 0x82, 0x5f, 0x85, 0xd2, 0x41, 0x18, 0xdb, 0x81, 0xb3, 0x04,
  0x1c, 0xc5, 0x1f, 0xa4, 0x80, 0x6f, 0x15, 0x20, 0xc9, 0xde, 0x0c, 0x88, 0x0a, 0x1d, 0xd6, 0x66, 0x55, 0xe2, 0xfc, 0x48, 0xc9, 0x29, 0x26, 0x69
const unsigned int globalsignRootCertLen = 888;

// Setup the MQTT secure client class by passing in the WiFi client and MQTT server and login details.
WiFiClientSecure client;

// Setup Channel
Adafruit_MQTT_Subscribe led = Adafruit_MQTT_Subscribe(&mqtt, LED_TOPIC);

void MQTT_connect();
void verifySecure();
void sntpUpdateDatetime();
void blink(int times);

void setup() {

  // Finds the onboard LED and sets it to off
  digitalWrite(LED_BUILTIN, HIGH);

  Serial.println(F("Xively MQTTS (SSL/TLS) Example"));

  // Connect to WiFi access point
  Serial.println(); Serial.println();
  Serial.print("Connecting to ");



  while (WiFi.status() != WL_CONNECTED) {

  Serial.println("WiFi connected");
  Serial.println("IP address: "); Serial.println(WiFi.localIP());

  // Update the device's date and time so we can verify the status of the TLS
  // certificate

  // Connect to the server and verify its TLS certificate origin

void loop() {
  // Ensure the connection to the MQTT server is alive

  // Subscribe to channel and apply changes.
  // Messages in the channel should be 0 or 1
  Adafruit_MQTT_Subscribe *subscription;
  while ((subscription = mqtt.readSubscription(5000))) {
    if (subscription == &led) {
      Serial.print(F("led: "));
      Serial.println((char *)led.lastread);

    if (strcmp((char *)led.lastread, "1") == 0) {
      digitalWrite(LED_BUILTIN, LOW);
      Serial.println("swithing on");
    if (strcmp((char *)led.lastread, "0") == 0) {
      digitalWrite(LED_BUILTIN, HIGH);
      Serial.println("switching off");

void verifySecure() {
  const char* host = XIVELY_BROKER;

  // Load root certificate in DER format into WiFiClientSecure object
  bool res = client.setCACert(globalsignRootCert, globalsignRootCertLen);
  if (!res) {
    Serial.println("Failed to load root CA certificate!");
    while (true) {

  // Connect to remote server
  Serial.print("Connecting to ");
  if (!client.connect(host, XIVELY_BROKER_PORT)) {
    Serial.println("Connection failed. Halting execution");
    while (1)

  // Verify validity of server's certificate
  if (client.verifyCertChain(host)) {
    Serial.println("Server certificate verified");
  } else {
    Serial.println("ERROR: certificate verification failed! Halting execution");
    while (1)

void sntpUpdateDatetime() {
  // Synchronize time useing SNTP. This is necessary to verify that
  // the TLS certificates offered by the server are currently valid.
  time_t now = time(nullptr);

  Serial.print("Setting time using SNTP");
  configTime(3600, 0, "", "");
  while (now < 1000) {
    now = time(nullptr);
  struct tm timeinfo;
  gmtime_r(&now, &timeinfo);
  Serial.print("Current time: ");

void blink(int times) {
  int count = 0;
  while (count < times) {
    digitalWrite(LED_BUILTIN, LOW);
    digitalWrite(LED_BUILTIN, HIGH);

// Function to connect and reconnect as necessary to the MQTT server.
// Should be called in the loop function and it will take care if connecting.
void MQTT_connect() {
  int8_t ret;
  // Stop if already connected.
  if (mqtt.connected()) {

  Serial.print("Connecting to MQTT... ");

  uint8_t retries = 3;
  while ((ret = mqtt.connect()) != 0) { // connect will return 0 for connected
    Serial.println("Retrying MQTT connection in 5 seconds...");
    delay(5000);  // wait 5 seconds
    if (retries == 0) {
      // basically die and wait for WDT to reset me
      while (1);

  Serial.println("MQTT Connected!");


Root Certificates stored in your Firmware

The example above includes only 1 Root Certificate: GlobalSign's.
That's the CA currently used by the Xively broker, but including only this certificate is not a good idea for a production environment.

For production, you should include at least the 3 extra roots we include in
libxively. If GlobalSign is ever compromised and their certificates are invalidated, the Xively broker would move to one of the other CAs, allowing all devices with its Root Cert to connect as usual

  1. Set your Wi-Fi credentials:
// Enter your WiFi credentials 
#define WLAN_SSID                 "<wifi network>"
#define WLAN_PASS                 "<wifi password>"

Add credentials and topic for this device

In order for your device to securely talk to Xively it needs credentials that it will use to authenticate itself as a valid device within your account. Your application need to contain the device credentials and the topic path.

  1. In the Xively management app, go to Devices > All devices and look for your ESP8266 device. Click on its name.

  2. Click on Get password.

  1. In the pop-up window, click Download.

A file named MQTTCredentials.txt gets downloaded. It contains the device credentials that will be used in the next step. The file contains two data items:

  • The first line is the Xively Device Secret.
  • The second line is the Xively Device Id.
  1. Go back to the Arduino IDE code and set your Xively credentials acquired in the previous step.
    Copy and paste device Secret and ID from the MQTTCredentials.txt file:
// Enter your Xively credentials and topic
#define XIVELY_DEVICE_ID   "<Xively Device Id>" 
#define XIVELY_DEVICE_PASS "<Xively Device Secret>"
  1. To get the device topic path, go to the Xively management app.

  2. On the page with your device details, click on the Messaging tab.

  3. In the drop-down list labeled PUBLISH TO, select the redled channel.

  4. To copy the topic to clipboard, click on the blue area next to the drop-down list.
    The topic format looks as follows:

  1. Go back to the Arduino IDE code and paste your device topic path acquired in the previous step:
// Enter your Xively credentials and topic
#define LED_TOPIC                 "<redled topic>"

Upload your application code

  1. Keep your physical device connected to the computer.
  2. In the Arduino IDE, click on the Upload button.
  1. When prompted to save the sketch, click on Save.
    After a few seconds, you should see the messages Compiling sketch, Uploading, then finally Done uploading.

Step 6 of 6: Let's play!

  1. Disconnect your ESP8266 from the Micro USB.
  2. Plug in the battery.
  3. Return to the digital device's MQTT tab in the Xively management app.
  4. To turn the light on, publish the message 1.
    The red LED turns on.
  1. Publish the message 0.
    The red LED turns off.


YES! You did it! Now you have an ESP8266 connected to Xively.

Updated 2 years ago


How to connect an ESP8266 to Xively

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.