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.


Introduction

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() {
  SerialBT.begin("ESP32");
}

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() {
  SerialBT.begin("ESP32");
}

void loop() {

  SerialBT.println("Hello World");
  delay(1000);
}

 

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

60 thoughts on “ESP32 Arduino: Serial communication over Bluetooth Hello World”

  1. David Agge Agnér

    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

  2. David Agge Agnér

    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

  3. 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

  4. 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

  5. Pingback: ESP32 Arduino Serial over Bluetooth: Client connection event – techtutorialsx

  6. Pingback: ESP32 Arduino Serial over Bluetooth: Client connection event – techtutorialsx

  7. Pingback: ESP32 Arduino Serial over Bluetooth: Client disconnection event – techtutorialsx

  8. Pingback: ESP32 Arduino Serial over Bluetooth: Client disconnection event – techtutorialsx

  9. Hola Nuno, te felicito por la buena ayuda das en la página.

    Soy Mao y te contacto para pedir ayuda.

    He estado revisando los ejemplos que tienes acá en la página en busca de lo que requiero hacer, y es por eso que te solicito tu colaboración con lo siguiente:

    Tengo una tarjeta Widora AIR – ESP32 y quiero conectarla con módulos HC-05 esclavos con Bluetooth clásico, pero NO SE COMO HACERLO con la librería BluetoothSerial !!!

    La tarjeta Widora la puedo ya contactar con un celular Android, pero no con los otros módulos.

    Me puedes ayudar con esto, si me das una indicación o si me compartes algún código que me pueda servir para ello, sería genial !!!

    Gracias por la atención prestada.

    Quedo atento tuyo.

    Mao

  10. Hola Nuno, te felicito por la buena ayuda das en la página.
    Soy Mao y te contacto para pedir ayuda.
    He estado revisando los ejemplos que tienes acá en la página en busca de lo que requiero hacer, y es por eso que te solicito tu colaboración con lo siguiente:
    Tengo una tarjeta Widora AIR – ESP32 y quiero conectarla con módulos HC-05 esclavos con Bluetooth clásico, pero NO SE COMO HACERLO con la librería BluetoothSerial !!!
    La tarjeta Widora la puedo ya contactar con un celular Android, pero no con los otros módulos.
    Me puedes ayudar con esto, si me das una indicación o si me compartes algún código que me pueda servir para ello, sería genial !!!
    Gracias por la atención prestada.
    Quedo atento tuyo.
    Mao

  11. Hi Nuno, I’ve tested your tutorial with ESP32 and nRF H-05 works really well, thank you for sharing.

    at like to ask though,
    is it possible to send serial data from one ESP32 to another ESP32 over BT?

    the idea is to collect sensor information using one ESP32, format it and send it via BT on the display of another ESP32 (for home automation).

    best regards, Kostas

Leave a Reply

%d bloggers like this: