ESP32 BLE + Android + Arduino IDE = AWESOME




About: I'm a young engineer with a passion for DIY and electronics! Learn to share, share to learn!


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!

Teacher Notes

Teachers! Did you use this instructable in your classroom?
Add a Teacher Note to share how you incorporated it into your lesson.

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

The next thing you need to do is install the ESP32 package for Arduino IDE by following the Windows instructions or the Mac instructions. I will say that for Windows when the instructions tell you to open "Git GUI" you have to download and set up "Git" from the link provided and if you have a hard time finding an application called "Git GUI" then all you need to do is search "Git GUI" in the start menu and you will see a little command prompt-ish looking icon (see attached screenshot above). It's also located in "C:\Program Files\Git\cmd\git-gui.exe" by default. From there, follow the instructions and you should be good to go!

Note: If you already have the ESP32 package installed in Arduino IDE but you didn't get it after BLE support was added to the package, I'd recommend going to "Documents/hardware/espressif" and deleting the "esp32" folder and re-doing the setup instructions above. I'm saying this because I ran into an issue where even after following the update procedure at the bottom of the instructions the BLE examples weren't appearing in the "Examples" under "Examples for ESP32 Dev Module" in Arduino IDE.

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

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.

You could also think about this like AT&T customer service:

  • Server --> Waiting for client to connect
  • Client --> Connects to service
  • Server --> Via Customer Support characteristic: "Hi, how may I help you? Would you like to consider our special family bundle?"
  • Client --> Via Raised Voice characteristic: "No thanks, I would just like to know why my bill went up this time"
  • Server --> Via Customer Support characteristic: "OK, no problem. Would you also like to upgrade your Internet speed for only $5 more per month?"
  • Client --> Disconnects

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.print("Received Value: ");</p><p>        for (int i = 0; i < rxValue.length(); 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();

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(
pCharacteristic->addDescriptor(new BLE2902());
BLECharacteristic *pCharacteristic = pService->createCharacteristic(
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
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->notify(); // Send the value to the app!
    Serial.print("*** Sent Value: ");
    Serial.println(" ***");

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!
Arduino Contest 2017

Participated in the
Arduino Contest 2017

Remote Control Contest 2017

Participated in the
Remote Control Contest 2017

Be the First to Share


    • Instrument Contest

      Instrument Contest
    • Make it Glow Contest

      Make it Glow Contest
    • STEM Contest

      STEM Contest

    84 Discussions


    Question 13 hours ago

    Very interesting project.
    I can't read your aia file since Thunkable classic is no longer accessible for new user.
    Is there a new version of the app with Thunkable X ?


    Question 4 weeks ago

    Hello, well done on your code! however, i seems to having trouble displaying the values of my mq-3 sensor onto the app itself.

    float BAC;
    float sensorValue;
    sensorValue = analogRead(AOUTpin);
    sensor_volt= sensorValue/4095*3.3;
    RS_gas = (3.3-sensor_volt)/sensor_volt;
    ratio = RS_gas/0.15;// ratio = RS/R0
    x= 0.4* ratio;
    eBAC = pow(x,-1.431); //BAC in mg/L
    BAC = (eBAC*0.21) - 0.02 ;
    char BACString[2];
    // pCharacteristic->setValue(&BACValue, 1); // To send the integer value
    // pCharacteristic->setValue("Hello!"); // Sending a test message
    pCharacteristic->notify(); // Send the value to the app!
    Serial.print("*** Sent Value: ");
    Serial.println(" ***");

    would you be able to assist me? thanks so much!


    Question 9 months ago

    At first, it was working smoothly. But now, when i am going to connect i'm getting this error & apk is going to close automatically. can u solve the problem? It's urgent.

    1 answer

    Answer 5 weeks ago

    I am getting the same error - Did you solve it? Thanks


    2 months ago

    Hello, I tried the .apk and when i click connect, there is a black screen, no BLE device. I'm on android 8.0


    Question 3 months ago

    Very interesting, but wondering if your ES)32 code is downloadable somewhere (or I read over it). The various code sections contain too many html codes to be reliable


    Question 5 months ago on Step 5

    Hi, when i click connect a black screan appear with no devices to choose ?!


    8 months ago on Introduction

    Hi, Your app is working well. I have a issue that when I use your .aia file and try to compile it using thunkable the app does not work. I am unable to pick bluetooth in the app after creating the apk file from you .aia file. Is the .aia file not correct? Please confirm. Thanks

    1 reply

    Reply 7 months ago

    I have the exact same problem! Did you by any chance find a solution??


    Question 7 months ago

    how to add buzzer in coding and how the connection with esp32?


    8 months ago

    Hi, Your app is working well. But if I need to control 4 LEDs , What we need to change ? in your .aia file and in your ESP32_BLE_UART_Demo file ? Please confirm. Thanks


    10 months ago

    Thanks for the tutorial.

    Can anyone confirm if in the current version of the web THUNKABLE (2019) projects * .aia can be uploaded?

    Thank you.

    1 reply

    Reply 9 months ago

    As far as I know, it's not possible.
    You can use the classic thunkable via, there it's definitely possible to upload .aia files.


    Question 11 months ago

    Super nice tutorial,
    I've everything I need except the RSSI, which I need to measure distance. Do u have any idea how I get the RSSI value of the connected phone?

    3 answers

    Reply 11 months ago

    Yeah I've seen that post before, but with UART you dont have
    So I don't know how I should call the RSSI in your code, do u have any ideas?
    Alot of people use it for a BLE Scanner, but I want to connect to my phone first.


    Reply 11 months ago

    Sorry I'm not sure and I don't have time to look into it. I know from the phone's side you can get the RSSI though.


    Tip 1 year ago

    Very useful tutorial! thanks.

    Just a note for WemosLolin32: LED pin is number 5


    Question 1 year ago

    Hello, very good tuto.

    you've made an esp32 server BLE + app inventor tuto

    i would like to know if it's possible to have

    esp32 server BLE + esp32 client BLE to exchange data in two way

    if i use you're sketch for esp32 server BLE is it possible to have a sketch for the esp32 client BLE (instead of the aia)

    thanks o you're tuto

    here a link to the .ino who work as ep32 BLE server to send and receive multi data

    here a link on a .aia

    to send and received multi data throught BLE to the esp32

    in fact if it's not to much i would like a .ino for esp32 who work as BLE client with you're .ino esp32 BLE server

    Thanks a lot