ESP32 Arduino: Serial communication over Bluetooth Hello World

The objective of this post is to explain how to get started with the BluetoothSerial ESP32 library, in order to send data to a emulated Serial connection, operating over Bluetooth classic. The tests of this ESP32 tutorial were performed using a DFRobot’s ESP-WROOM-32 device integrated in a ESP32 FireBeetle board.


The objective of this post is to explain how to get started with the BluetoothSerial ESP32 library, in order to send data to a emulated Serial connection, operating over Bluetooth classic.

At the time of writing, the mentioned library had just been added to the ESP32 Arduino core. So, you may need to update to the latest version of the Arduino core. You can check here how to do it.

One important thing to mentioned is that this is a very high level library that will hide from us most of the Bluetooth implementation details, which is why the code we are going to develop is very simple and small.

In terms of API, it will be very similar to the regular Serial communication functions we use on the Arduino environment.

Note that the example provided here is based on the library example available on the Arduino core, which I encourage you to try.

The tests of this ESP32 tutorial were performed using a DFRobot’s ESP-WROOM-32 device integrated in a ESP32 FireBeetle board.

If you prefer, you can check the video tutorial at my Youtube channel.

The code

The first thing we need to do is including the BluetoothSerial.h library, which will expose the functionalities needed to work with serial over Bluetooth.

#include "BluetoothSerial.h"

Next we will need an object of class BluetoothSerial, which is the one we will use to initialize the Bluetooth stack on the ESP32 and to send the data.

You can check the implementation file for this class here. Under the hood, this class makes use of IDF’s Bluetooth classic API, which we have been covering in previous posts.

BluetoothSerial SerialBT;

Now that we have our Bluetooth object, we need to initialize the Bluetooth stack, so other devices can see our ESP32 and pair with it, before initializing the serial communication.

To do so, we simply need to call the begin method of the BluetoothSerial object, which will handle all of the lower level initialization for us.

This method receives as input a string with the name we want to assign to the device, which will be seen by other Bluetooth enabled devices that will discover it.

As output, it returns a Boolean value indicating if the initialization was successful or not. For now we will not look into that value, but for a robust code you should always include error checks.

We will do the mentioned initialization in the Arduino Setup function.

void setup() {

Now that we have initialized the device, we will periodically send a “Hello World” message on the Arduino main loop.

As can be seen in the header file of the BluetoothSerial class, it inherits from the Stream class. The Stream class inherits from the Print class, which means that we can use the println method to write to the Bluetooth serial port.

SerialBT.println("Hello World");

Between each iteration of the main loop, we will do a small 1 second delay. The full source code can be seen below.

#include "BluetoothSerial.h"

BluetoothSerial SerialBT;

void setup() {

void loop() {

  SerialBT.println("Hello World");


Testing the code

To test the code, simply compile it and upload it to your ESP32 using the Arduino IDE. Once it finishes, go to your computer’s Bluetooth devices and start a scan. The ESP32 should get detected, as shown in figure 1.

ESP32 Bluetooth Classic Serial Communication Hello World.png

Figure 1 – ESP32 detected as Bluetooth device on Windows 8 (menus in Portuguese).

In my case, I already had the device paired. If you haven’t yet, pair with it. Once it is paired, you should get a new COM port available on your computer. On Windows 8, you can check it at the device manager, as can be seen in figure 2.

Windows 8 Serial over Bluetooth COM at device manager.png

Figure 2 – New Bluetooth over serial COM port detected in Windows 8.

You can now go back to the Arduino IDE and this COM port should be on the list of the available COM ports that we can connect to using the Serial Monitor. Choose it and open the Serial Monitor. You can check the expected result at figure 3, which shows the message we defined in the code getting printed.

ESP32 Arduino Bluetooth Classic Hello World Serial Monitor.png

Figure 3 – Output of the program on the Arduino IDE serial monitor.

Related posts

27 Replies to “ESP32 Arduino: Serial communication over Bluetooth Hello World”

  1. I love this. A couple years ago, I did something similar for a senior project. We basically wrote an Android app which would communicate with an Arduino via Bluetooth. Based on certain commands, the Arduino would drive a solenoid which would move a deadbolt in a door. Fun stuff!

    1. Hi!

      What Bluetooth module were you using? Let me guess, something like the HC-05 or HC-06? 🙂 Had a lot of fun with those in the past 🙂

      It’s amazing how nowadays we get Bluetooth, WiFi, 2 cores, Hardware encryption and so many other features in a device as cheap as the ESP32.

      Best regards,
      Nuno Santos

    1. You’re welcome 🙂 I’ve also stumbled on it by chance, I was looking at the Arduino core PRs to check if there was something new coming and there it was. Works very well, a great job by Copercini, the author of the PR.

      Best regards,
      Nuno Santos

      1. Yep just tried it for debugging on the phone screen and it worked like a charm! I’ve been eyeballing the bluetooth examples every now and then and they’ve seemed too much trouble to investigate. This API is a great abstraction to all that madness. 🙂

        Thank you also for the other posts on ESP32/Arduino! I came across your blog just today while looking for code examples for taking advantage of the second core. as I saw it being demostrated on Andreas Spies YouTube channel. I ended up reading all the other posts also, very useful and well written posts!

        I found the info I needed on the use of the second core. I’m planning to see if it would make sense on a NRF24L01 to wifi/MQTT gateway device I’m building to route traffic from AVR/STM32 based nodes. I’m also planning to try the queues you had another article about. Basic idea would be to run the wifi/MQTT code on the default core and the RF24/RF24Network/RF24Mesh library loop process on the other. There’d be a queue for each direction (MQTT->NRF24 and NRF->MQTT).

        1. Thank you very much for the feedback 🙂

          This is indeed a very nice abstraction, specially since most of the times we only want to exchange some data using the Bluetooth interface.

          Nonetheless, the IDF API brings some more flexibility, which may be needed for more advanced use cases.

          I’m trying to cover both on tutorials, to give a better understanding of what happens under the hood and which additional functionalities we can get from using it.

          I’m glad you are finding the other posts useful 🙂 I would like to go back to some more FreeRTOS stuff, there’s still plenty of functionalities I would like to explore.

          Andreas Spies has awesome videos, I’ve been following his Youtube channel for a while and really recommend it.

          Regarding your project, it seems a very interesting one. I have a couple of NRF24L01 here but never had the chance to test them. Are they reliable? I’ve heard some good stuff about them.

          It seems a good approach, using queues. A good thing about them is that you can have a FreeRTOS task waiting on them blocked while there is no data, leaving the CPU available for other tasks.

          Let us know if it works fine 🙂

          Best regards,
          Nuno Santos

  2. Hello
    I am using Arduino 1.8.4
    I downloaded and unzipped the Arduino-esp32 directory inside library folder of Arduino 1.8.4
    I restarted the Arduino IDE
    I keep getting the error message that BluetoothSerial.h not found. The files are present.
    Need some help.

    1. Hi!

      Sorry for the delay. Does the rest work? If you try to use another ESP32 library such as the HTTPClient, does it work?

      I never ran into that issue, but I’ve installed / updated my libraries always using the method indicated on the GitHub page of the Arduino core, or using git directly on the command line:

      My recommendation is that you try an installation following that procedure, it will most likely cause you less problems when updating, for example.

      Let me know if it solves the problem.

      Best regards,
      Nuno Santos

  3. Hi
    Could you confirm he number of bytes in a serial packet that can be sent with this simple arduino BT print command and the rate (no of times/second) that it could be sent through the ESP32.

    1. Hi!

      As far as I’m aware, at the time I was more actively working with Bluetooth, there was not yet any way of adding a pairing password or something similar.

      If you find some way of doing, please let us know since it would be very interesting 🙂

      Best regards,
      Nuno Santos

  4. Hey, I’ve been trying to use this and it works fine except for one weird issue. As soon as I call SerialBT.begin(), GPIO input stops working properly. Calling analogRead() on any pin gives me either 4095 or 0 depending on the pin. Have you seen anything like this? Do you know anywhere else I could ask to get more info? This is my code:

    void setup() {
    SerialBT.begin(“ESP32test”); //Bluetooth device name
    Serial.println(“The device started, now you can pair it with bluetooth!”);
    pinMode(C_ANALOG_PIN, INPUT);
    while (1)

    1. Hi,

      That’s an weird issue, I’ve never experienced it, but haven’t yet tried to work with analog input and Bluetooth at the same time.

      My suggestion is to ask around the Arduino core Github page, to check if someone has already faced the same issue:

      You can also try to pull the latest version of the Arduino core for the ESP32, since that may have been a bug in some commit that may already been solved.

      Nonetheless, that is most likely a lower level error (the Arduino core is built on top of IDF, the ESP32 official development framework), so you can eventually find more information at the Github page of that project:

      You can also try to check the documentation of IDF, since there may be some information regarding the problem you are experiencing:

      Hope this helps and let us know if you find the cause or get any answer, since it is an useful information for others 🙂

      Best regards,
      Nuno Santos

  5. I’m struggling on finding an example for Arduino where the ESP32 is the Serial client. I would like to use ESP32 to ESP32 over BT

    1. Hi!

      Unfortunately I haven’t yet had the chance to check if there is a way to make two ESPs talk over Bluetooth.

      My suggestion is to ask around the Arduino core GitHub page, since there someone may already succeeded.

      In case I came across some example code, I’ll make sure to share. Please let us know if you are able to make it work, since it will be useful for others 🙂

      Best regards,
      Nuno Santos

  6. Hi, excelent project, I tried to do it but when i compile the project there is an error, “fatal error: esp_spp_api.h: No such file or directory”. could you help me? please

Leave a Reply