Source: https://mokxi.com/libraries/bluetoothserial
Updated: 2026-11-02

Libraries / Communication
Arduino library · Communication

# ESP32 BluetoothSerial: a wireless serial port to a phone

BluetoothSerial makes the classic ESP32 look like an HC-05: a Bluetooth Classic serial port (the SPP profile) that an Android terminal app or a PC can pair with. In code it is a Stream, so SerialBT.print(), SerialBT.available() and SerialBT.read() work exactly like Serial’s, and the classic bridge sketch copies bytes both ways between the two.

Open the example in the editor See the calls

Built in on Mokxi: #include <BluetoothSerial.h> and it builds, with nothing to install. Free, and no account needed.

## What BluetoothSerial (ESP32 core) does

It only exists on the original ESP32 chip. The ESP32-S3, C3 and C6 have Bluetooth Low Energy only, so on those boards the header refuses to build and you need the BLE library instead. iPhones do not offer SPP to apps either, which is why iOS projects use BLE even on a classic ESP32.

Pairing defaults to "just works". To require a code, call disableSSP() and setPin() before begin() for a legacy PIN, or enableSSP() with a confirm callback for the six-digit numeric comparison. register_callback() reports connects, disconnects and incoming data as SPP events.

Library Manager name | BluetoothSerial (ESP32 core)

Author | Espressif

Include | #include <BluetoothSerial.h>

Boards | ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display

In the simulator | Simulated: it runs against the part the way it does on the bench.

## Install it

It builds on ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display.

In Mokxi it is built in: #include <BluetoothSerial.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board it comes with the board package (Espressif), so the Arduino IDE has it as soon as the board is installed: there is nothing to add from the Library Manager.

ESP32 DevKit · ESP32-DevKitC V4 · LOLIN32 Lite · Wemos D1 R32 · Cheap Yellow Display · TTGO T-Display

## The calls you will use

In the order a sketch meets them.

### BluetoothSerial SerialBT

The Bluetooth serial port object, declared once at the top of the sketch.

### SerialBT.begin("ESP32test")

Starts Bluetooth and makes the board discoverable under that name. Returns false if the stack could not start.

### SerialBT.available()

How many bytes the phone has sent that are waiting to be read.

### SerialBT.println("Temperature: 21.5")

Sends text to the connected device, like Serial.println(). Nothing is sent while no device is connected.

### SerialBT.hasClient()

True while a device is connected, for showing the link state or skipping sends.

### SerialBT.setPin("1234")

Sets a legacy PIN. Call SerialBT.disableSSP() and then setPin() before begin(), or the phone pairs without asking for it.

### SerialBT.register_callback(callback)

Registers a function for SPP events: ESP_SPP_SRV_OPEN_EVT when a device connects, ESP_SPP_CLOSE_EVT when it leaves, ESP_SPP_DATA_IND_EVT when data arrives.

### SerialBT.enableSSP()

Turns on secure simple pairing with numeric comparison; pair it with onConfirmRequest() and confirmReply() to accept the code.

## Example: ESP32 Bluetooth serial lamp

On the ESP32 DevKit V1. It runs in the browser exactly as printed.

sketch.ino · ESP32 DevKit V1

Open it in the editor, wired and ready to run · ESP32 Bluetooth serial lamp: the project page

## Common errors and how to fix them

### Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.

The board is an ESP32-S3, C3 or C6, which have no Bluetooth Classic. Use a classic ESP32 DevKit for BluetoothSerial, or rewrite the sketch with the BLE library, which those chips do support.

### The iPhone cannot see the board

iOS does not let apps use the Bluetooth serial profile, so a classic ESP32 running BluetoothSerial never appears there. Use an Android phone or a PC, or switch the project to BLE for iPhone users.

### Sketch too big after adding BluetoothSerial

Bluetooth Classic plus WiFi can overflow the default app partition. Choose a larger partition scheme such as Huge APP in the board settings, or drop the library you are not using.

## Keep going

### Learn

- Arduino HC-05 Bluetooth: Wiring, Code, AT Commands
- UART Serial Explained: Baud, Frames and the Wire

### More communication libraries

- OneWire
- TinyGPS
- TinyGPSPlus
- MFRC522
- SoftwareSerial
- AltSoftSerial
- i2cdetect
- Keyboard

Every built-in library · Open the editor

## Try BluetoothSerial (ESP32 core) without installing anything

Open the example, change the sketch, and keep your version in a free account.

Start building free

Open the editor