ESP32 BLE + Android + Arduino IDE = AWESOME

Introduction

As you might know, the ESP32 is an incredibly feature-packed module that has not only WiFi but also Bluetooth Low Energy (BLE), touch sensors, tons of ADC pins, DAC pins, audio support, SD card support... did I mention enough to impress you?

In this tutorial we will be working with the Bluetooth Low Energy feature of this in Arduino IDE and create a custom Android app using Thunkable, a free and visual app building tool. What actually sparked me to do this tutorial was this YouTube video by Andreas Spiess in which he experiments with the BLE feature a little. What's really sweet is that some awesome dude has already done all the hard coding behind the BLE libraries for Arduino IDE (hats off to Neil Kolban!) and his contributions were recently added as part of the official ESP32 Arduino release.

Note: For using the ESP32's traditional Bluetooth as a serial device, please see the example Arduino sketch that is now included in the ESP32 Arduino package.

Goals for this Tutorial

First of all what are we making here? In this tutorial we'll be building an Android app that connects to the ESP32 via Bluetooth to establish two-way communication. We'll be able to control an LED on/off remotely and we'll also be able to see some arbitrary values that are sent from the ESP32 to the Android app. These values could be things like sensor readings, door states for a home security system, etc. The cool part about all this is that you don't need to have any crazy skills to do this! So with that, let's get started!

Step 1: Gather Parts

Fortunately this list is pretty simple!

• Android device with Bluetooth 4.0 or higher (most smartphones)
• ESP32 development board (note that there are many versions that would also work just fine)
• Micro USB to program the ESP32 dev board
• Optional: sensors, LED's, etc. to spice up the project!
• Depending on your setup and project you may want a breadboard and some jumper wires

Step 2: Arduino IDE Setup

This is pretty obvious, but the first thing you need to do is install Arduino IDE. Enough said.

ESP32 Package Installation

Luckily, now this process is really easy (as opposed to when the ESP32 first came out), and can be done all in the Arduino IDE. Simply copy and paste the following URL into File -> Preferences -> Additional Board Manager URLs: https://dl.espressif.com/dl/package_esp32_index.json

Then you can go into Tools -> Board -> Boards Manager and search for "esp32 by Espressif Systems" and install the package.

ESP32 BLE Example Sketch

In Arduino IDE the first thing you should do is go to Tools / Board and select the appropriate board. It doesn't really matter which one you choose, but some things might be board-specific. I chose "ESP32 Dev Module" for my board. Also go ahead and choose the correct COM port after connecting the board to your computer via the USB cable.

In order to check if the ESP32 installation went well, go to File / Examples / ESP32 BLE Arduino and you should see several example sketches, like "BLE_scan", "BLE_notify", etc. This means everything is set up properly in Arduino IDE!

Now that Arduino IDE is all set up, open the code I've provided for this tutorial (attached below), which is a slightly edited version of the "BLE_uart" example sketch. Since I've kept the file extension as ".ino" Arduino IDE will ask you if you want to create a folder around it with the same name, so click "yes" to open it.

Step 3: App Setup

UPDATE: Thunkable recently transitioned from Thunkable Classic to a completely new platform called ThunkableX which allows users to create apps for both Android and iOS from the same platform but requires a paid membership for making private apps. This tutorial was written using Thunkable Classic and unfortunately isn't accessible to ThunkableX users and there's no way to import from Classic into ThunkableX. However, a contributor has recreated the app in ThunkableX (you can find it here).

Setting up Thunkable

For the Android app we'll be using Thunkable, a fantastic visual app-building tool for Android and iOS. Here we'll just be making an Android app since their iOS support is still in the early stage and doesn't have Bluetooth stuff yet. (Not to mention Apple holds a tight grip on app distribution, etc.)

Go to the Thunkable site and set up an account or log in with a Google account. If you're new to Thunkable you won't see any existing projects, but that's about to change! Click "Apps" at the top left and click "Upload app project (.aia) from my computer". The "native" file type for Thunkable is ".aia" files and these files will allow you to view and edit code blocks within Thunkable. First download the attached file called "ESP32_BLE_Demo.aia" and then load this file in Thunkable. This should now bring you to the app's home screen where you can edit the user interface. To view and edit the code blocks, click "Blocks" sort of at the top left, next to "Designer". This tutorial isn't meant to teach you all the ins and outs of Thunkable, but I definitely recommend you explore it yourself and have fun with it!

Thunkable Companion App

You can also download the Thunkable companion app on your mobile device and do live testing with it, which is really darn cool because you can test the app without having to first compile and download it every time! Simply install it on your mobile device and under the "Test" tab at the top click "Thunkable Live" and it will bring up a QR code on the screen. Open the Thunkable app on your mobile device and scan the QR code to live test!

Now to actually get the app on your phone all you have to do is click "Export" and "App (provide QR code for .apk)" and scan the QR code with your phone using the Thunkable app. You can then install the app and open it! Alternatively, you can download the .apk file I've attached above and email it to yourself to get it on your phone.

When you first open the app it will ask you to turn on Bluetooth if you haven't already, and click "Yes". When the app is connected to your ESP32 it will print out arbitrary values that are sent to it from the ESP32 and the "LED" button allows you to toggle the LED on or off by sending "A" or "B" to the ESP32. But for now let's not jump the gun just yet!

Step 4: Code Explanation

First load the example sketch I attached a few steps ago and I'll try to give a brief explanation of what's happening. If you're using a different ESP32 dev board you should make sure that the LED pin is initialized correctly. Note that in Arduino IDE you should write the GPIO number, not necessarily the pin number shown on the board's pinout diagram.

BLE Intro

Bluetooth Low Energy (BLE) is a slightly different protocol than the traditional Bluetooth we might find in things like Bluetooth audio, for example. Instead of constantly streaming data, BLE "servers" (like the ESP32 reading sensor data) can "notify" clients (like your smartphone) periodically to send them bits of data. Therefore, BLE is more suitable for low-power IoT applications where large amounts of data aren't required.

Now in order to know which server and client to connect to, both the server and clients use a "service UUID" which describes the overarching service (kind of like a grocery store, Walmart for example). Inside this service there can be several "characteristics" which are defined by characteristic UUID's. This can be thought of kind of like the snack section in the Walmart, or the canned food section. Then we have "descriptors", which are attributes of the characteristics describing what it's being used for, and can be thought of like the brand of potato chips in the snack aisle of Walmart. This allows interoperability and standardization between various BLE devices so that you can, for example, connect your ESP32 with a heart rate monitor like what Andreas Spiess does in this YouTube video. You can view some example descriptors here.

So to summarize, when you (the client) check out Walmart (the service) you might be looking for potato chips (the characteristic) and pick up some Pringles (the descriptor). Because the product is labeled "Pringles" and not "Great Value" you know which product to choose from and what to expect. This is sort of how BLE devices operate. In our example, we use two different characteristics, TX and RX under the overarching "service" to send data to and receive data from a client (Android device) via these two channels. The ESP32 (acting as the server) "notifies" the client via the TX characteristic UUID and data is sent to the ESP32 and received via the RX characteristic UUID. However, since there is sending and receiving, TX on the ESP32 is actually RX on the Android app, so inside Thunkable you will notice that the UUID's are swapped from those in the Arduino sketch.

Arduino Code Explained

In this section I'll point out a few important things. At the top of the sketch we include the necessary libraries for the code to run:

#include <BLEDevice.h>
#include <BLEServer.h>
#include <BLEUtils.h>
#include <BLE2902.h>

Thankfully these libraries were bestowed upon us by Neil Kolban (thanks again!) and are now included in the ESP32 package distribution by default.

Also near the top of the sketch we define the analog read pin as well as the LED pin. Note that it's the GPIO pin number and not necessarily other pin numbers you see on Google.

const int readPin = 32; // Use GPIO number. See ESP32 board pinouts<br>const int LED = 2; // Could be different depending on the dev board. I used the DOIT ESP32 dev board.

Next, we define the service and characteristic UUID's for both TX and RX (two-way communication):

#define SERVICE_UUID           "6E400001-B5A3-F393-E0A9-E50E24DCCA9E" // UART service UUID<br>#define CHARACTERISTIC_UUID_RX "6E400002-B5A3-F393-E0A9-E50E24DCCA9E"
#define CHARACTERISTIC_UUID_TX "6E400003-B5A3-F393-E0A9-E50E24DCCA9E"

Because what's transmitted on one end is received on the other and vice versa, the RX UUID in the *app* is the TX UUID for the *ESP32* and vice versa. Next let's look at the callback function that handles the Bluetooth connection status:

class MyServerCallbacks: public BLEServerCallbacks {<br>    void onConnect(BLEServer* pServer) {
      deviceConnected = true;
    };
    void onDisconnect(BLEServer* pServer) {
      deviceConnected = false;
    }
};

All this does is set the "deviceConnected" flag true or false when you connect or disconnect from the ESP32. Similarly there's another callback function that handles receiving data being sent from the client (phone):

<p>class MyCallbacks: public BLECharacteristicCallbacks {<br>    void onWrite(BLECharacteristic *pCharacteristic) {
      std::string rxValue = pCharacteristic->getValue();</p><p>      if (rxValue.length() > 0) {
        Serial.println("*********");
        Serial.print("Received Value: ");</p><p>        for (int i = 0; i < rxValue.length(); i++) {
          Serial.print(rxValue[i]);
        }</p><p>        Serial.println();</p><p>        // Do stuff based on the command received from the app
        if (rxValue[0] == '1') {
          Serial.print("Turning ON!");
          digitalWrite(LED, HIGH);
        }
        else if (rxValue.find("B") != -1) {
          Serial.print("Turning OFF!");
          digitalWrite(LED, LOW);
        }</p><p>        Serial.println();
        Serial.println("*********");
      }
    }
};</p>

I've added an "if" statement at the end that toggles the LED on or off depending on what letter is sent by the app. Now let's have a look at the setup() function. As usual, we set up Serial and set the LED pin to OUTPUT but then we also initialize the ESP32 as a BLE device and set its name:

<p>// Create the BLE Device<br>BLEDevice::init("ESP32 UART Test"); // Give it a name</p>

Next, we create the BLE server,

// Create the BLE Server
BLEServer *pServer = BLEDevice::createServer();
pServer->setCallbacks(new MyServerCallbacks());

create a BLE service using the service UUID,

<p>// Create the BLE Service<br>BLEService *pService = pServer->createService(SERVICE_UUID);</p>

and add the characteristics

// Create a BLE CharacteristicpCharacteristic = pService->createCharacteristic(
                    CHARACTERISTIC_UUID_TX,
                    BLECharacteristic::PROPERTY_NOTIFY
                  );
pCharacteristic->addDescriptor(new BLE2902());
BLECharacteristic *pCharacteristic = pService->createCharacteristic(
                                       CHARACTERISTIC_UUID_RX,
                                       BLECharacteristic::PROPERTY_WRITE
                                     );
pCharacteristic->setCallbacks(new MyCallbacks());

According to Andreas Spiess' video, here the BLE2902 descriptor makes it so that the ESP32 won't notify the client unless the client wants to open its ears up to read the values to eliminate "talking to the air" and we also set the callback that handles receiving values via the RX channel. However, if you try uncommenting the BLE2902 line and even the BLE2902 #include line, the code still seems to run just as it did before! Maybe someone more knowledgeable can tell us what's going on here! Next, we start the BLE service and start advertising, but the ESP32 ain't gonna send nothin' until a client connects!

// Start the service<br>pService->start();

// Start advertising
pServer->getAdvertising()->start();
Serial.println("Waiting a client connection to notify...");

Now let's take a look at the loop() function. Here we check if the device is connected or not (handled by the callback function), and if so, we continue to read a sensor value (for now it's just a random analog reading), convert it to a char array using "dtostrf" so that the app can process it, set the value to send, and notify the client!

void loop() {
  if (deviceConnected) {
    // Fabricate some arbitrary junk for now...
    txValue = analogRead(readPin) / 3.456; // This could be an actual sensor reading!
    // Let's convert the value to a char array:
    char txString[8]; // make sure this is big enuffz
    dtostrf(txValue, 1, 2, txString); // float_val, min_width, digits_after_decimal, char_buffer
    
//    pCharacteristic->setValue(&txValue, 1); // To send the integer value
//    pCharacteristic->setValue("Hello!"); // Sending a test message
    pCharacteristic->setValue(txString);
    
    pCharacteristic->notify(); // Send the value to the app!
    Serial.print("*** Sent Value: ");
    Serial.print(txString);
    Serial.println(" ***");
  }
  delay(1000);
}

Upload the Sketch!

Now upload the sketch to your ESP32 board, making sure that you have the right board and COM port selected. When it's done, open the serial monitor under Tools / Serial Monitor and you should see "Waiting a client connection to notify..." Now open the Android app, click the "Connect" button at the top left, and you should see a list of available nearby devices. Select the ESP32 and you should see the button text change to "Connected!" and start seeing values on the screen. To toggle the LED on or off press the "LED" button and check the serial monitor to see how it sends "A" or "B" to the ESP32. Pretty neat stuff huh?

Sending Multiple Values

A lot of people have asked this question: "how do I send multiple values to and from the ESP32 and app?" That's a good question, and luckily it's not hard at all! The easiest way I've found is to simply send the values in comma-separated variable (CSV) format. For example, if you're measuring temperature and humidity and you measured 21 *C and 55% humidity and want to send it to the app, simply program the ESP32 to send "21,55" and the app can parse it easily.

Sending Lots of Data

Unfortunately BLE isn't really meant for large streams of data (that's more for traditional Bluetooth, like those used in audio-streaming devices). The max allowable data size per packet is 20 bytes for BLE specification, so if you want to send anything more you'll have to split it up into multiple packets. Fortunately this is not that hard to do either. Simply use a delimiter like "*" or "!" or something unique at the end of your entire message to let the app know the message is complete and to start listening for a new message. For example, if you want to send and and cumulatively + > 20 bytes, then what you can do is send then proceed with the next message if needed.

Step 5: Easy, Peasy, BL-Easy!

The ESP32 is literally exploding with features! In this tutorial we've just learned the basics of how to create a simple Android app for two-way communication between your mobile device and the ESP32 using Bluetooth Low Energy. With this knowledge combined with WiFi and sensors we can now make some really cool projects with this! Also feel free to experiment with the app and throw in extra features for things like voice recognition, color pickers for LED control, slide bars for motor speed, or use your phone's accelerometer for controlling a robot via Bluetooth!

• If you liked this Instructable, please give it a heart, vote for it, and share!
• Feel free to check out my website here and my humble YouTube channel here for more cool projects like this!
• You might also be interested in this follow-up tutorial I made about building your own circuit board reflow oven with a toaster oven and ESP32!
• If you have any questions, comments, suggestions, or replicated this project, let me know in the comments section below!