Software apps and online services
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 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.
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
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 (see attachments), 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
11 Jan 2021 Update: Please see an updated Thunkable X app from a contributor who migrated the app to the new platform.
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!
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.
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, nice to meet you! Would you like to consider our special family Internet 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
Now in the example Arduino sketch we have some callback functions. These functions handle things like connecting/disconnecting as well as receiving data from the client. In the sketch I added an "if" statement that checks for an "A" or "B" being sent by the client and toggles the LED on or off accordingly. You will also notice that in the loop() function I use the "dtostrf" function to convert a number of type "float" into a char array so that the app can receive it properly.
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?
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 tutorial, please give it a thumbs up and share!
- If you're interested in building your own circuit boards at home, check out this tutorial on how to build your own reflow oven using an ESP32 via Bluetooth and Arduino IDE as well as an open-source ecosystem I invented called "Reflowduino".
- Feel free to check out my website here and my humble YouTube channel here for more cool projects like this!
- Follow me on Twitter!
- If you have any questions, comments, suggestions, or replicated this project, let me know in the comments section below!