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!

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.

Attachments

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!

Attachments

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:

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:

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):

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:

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!

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!

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!

Yeah I've seen that post before, but with UART you dont have"AdvertisedDeviceCallbacks"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.

Hey, thank you for the great example. I try to play around to change some values. I try to send a second values/string from the esp32 to the app, but i didn't understand how can i send a second string or some int/float values and on the other hand if i use 2 times pCharacteristic->setValue(txString1);

Hi, I´m having the same issue, the esp32 is sending the values, but when the app is going to read them I can´t read them separately, i don´t know how can i organize the blocks in Thunkable to read each sensor in differents labels at the same time.

Hi there! The easiest way to send multiple values is to send them in CSV format. For example, if you need to send "21.5" and "331.2" then you can simply send the single string "21.5,331.2" then the app can parse it easily.

I haven't tried doing the setValue() twice but I'm assuming it will send two separate packets if you do it that way. The first time it sends txString1 and the second time it sends txString2.