Thư viện BluetoothSerial: ESP32 Bluetooth Classic SPP

BluetoothSerial là thư viện ESP32 dùng Bluetooth Classic Serial Port Profile (SPP) — giống module HC-05 nhưng tích hợp ngay trong ESP32. App Android "Serial Bluetooth Terminal" kết nối, gửi/nhận text như UART. Bài này hướng dẫn từ pairing đến truyền data nhị phân.

1. Bluetooth Classic vs BLE — chọn đúng

ESP32 (cổ điển và S3) hỗ trợ cả 2. Bài này chỉ về Classic SPP. Đọc ESP32 BLE vs Bluetooth Classic để chọn.

Tóm tắt: SPP đơn giản, code ngắn, dùng được với app Android "Serial Bluetooth Terminal". Không hoạt động với iOS (Apple bỏ Classic).

Lưu ý: ESP32-C3, C6 KHÔNG hỗ trợ Bluetooth Classic — chỉ có ESP32 cổ điển và S3.

2. Cài đặt

BluetoothSerial đi kèm Arduino-ESP32 — không cần cài thêm.

#include 
BluetoothSerial BT;

3. Hello world — echo giữa Serial và Bluetooth

#include 
BluetoothSerial BT;

void setup() {
  Serial.begin(115200);
  BT.begin("ESP32-ArduinoVN");      // tên hiện khi pair
  Serial.println("Bluetooth ready, ten: ESP32-ArduinoVN");
}

void loop() {
  if (BT.available()) Serial.write(BT.read());
  if (Serial.available()) BT.write(Serial.read());
}

Trên điện thoại Android:

Cài app "Serial Bluetooth Terminal" (Kai Morich).
Setting → Bluetooth → Pair với ESP32-ArduinoVN. Khi hỏi PIN, để mặc định 1234 hoặc nhấn OK.
Mở app → Devices → chọn ESP32-ArduinoVN → kết nối.
Gõ text → ESP32 in lên Serial Monitor. Gõ Serial → app hiển thị.

4. API cơ bản

BT.begin(name) — khởi tạo (master/slave tự auto).
BT.begin(name, true) — master mode, scan và connect.
BT.available() — số byte trong buffer nhận.
BT.read() — đọc 1 byte.
BT.write(byte) / BT.print() / BT.println() — gửi.
BT.hasClient() — true nếu có client đang kết nối.
BT.end() — tắt Bluetooth.
BT.disconnect() — ngắt client hiện tại.

5. Set PIN bảo mật

BT.setPin("5678");
BT.begin("ESP32-Secret");

Khi pair, điện thoại sẽ hỏi PIN — nhập đúng mới connect được.

6. Phát hiện connect/disconnect — callback

void btCallback(esp_spp_cb_event_t event, esp_spp_cb_param_t* param) {
  if (event == ESP_SPP_SRV_OPEN_EVT) {
    Serial.println("Client connected");
  } else if (event == ESP_SPP_CLOSE_EVT) {
    Serial.println("Client disconnected");
  }
}

void setup() {
  BT.register_callback(btCallback);
  BT.begin("ESP32-CB");
}

Hữu ích để bật LED báo trạng thái hoặc stop motor khi mất kết nối.

7. Đọc/ghi dữ liệu nhị phân

SPP truyền byte tuần tự. Gửi struct:

typedef struct {
  float temp;
  uint16_t hum;
  uint8_t status;
} __attribute__((packed)) Data;   // packed - không padding

Data d = {25.4, 67, 1};
BT.write((uint8_t*)&d, sizeof(d));

Phía nhận parse ngược tương tự. Lưu ý __attribute__((packed)) — không có padding bytes ngẫu nhiên.

8. Master mode — ESP32 connect HC-05/HC-06

BluetoothSerial BT;
uint8_t macTarget[6] = {0x98, 0xD3, 0x31, 0x12, 0x34, 0x56};   // MAC HC-05

void setup() {
  Serial.begin(115200);
  BT.begin("ESP32-Master", true);    // master mode
  bool connected = BT.connect(macTarget);
  if (connected) Serial.println("Connected to HC-05");
}

void loop() {
  if (BT.connected()) {
    BT.println("Hello from ESP32");
    delay(2000);
  }
}

Tìm MAC HC-05: pair với điện thoại, vào setting Bluetooth xem MAC.

9. Lưu ý partition

BluetoothSerial nặng ~500KB flash. Partition mặc định "Default 4MB with spiffs" (1.2MB app) sẽ tràn nếu kèm WiFi + thư viện khác. Đổi sang Minimal SPIFFS (1.9MB app) hoặc Huge APP (3MB).

10. WiFi + Bluetooth đồng thời

ESP32 có anten 2.4GHz chung — chạy được nhưng giảm throughput. Tránh stream lớn cả 2 cùng lúc.

WiFi.begin(SSID, PASS);
while (WiFi.status() != WL_CONNECTED) delay(500);
BT.begin("ESP32-Both");

11. Ứng dụng

Robot xe điều khiển bằng app Android: nút bấm → BT command → ESP32 → motor.
Cân thông minh: ESP32 đọc HX711, gửi cân nặng về app.
Đo tốc độ xe đạp: ESP32 + cảm biến tốc độ, app hiển thị km/h.
Sửa lỗi/log từ device đã đóng vỏ: không tháo USB, dùng BT serial debug.
Audio streaming (A2DP): ESP32 thành loa Bluetooth — dùng thư viện ESP32-A2DP riêng.

12. Lỗi thường gặp

Pair được nhưng không gửi data: app phía điện thoại chưa connect đến SPP profile — phải mở app như "Serial Bluetooth Terminal".
iOS không thấy ESP32: Apple không hỗ trợ SPP. Chuyển sang BLE.
Code crash khi enable WiFi + BT + nhiều thư viện: hết RAM, hết flash. Tối ưu hoặc tách device.
Disconnect ngẫu nhiên: ăng-ten ESP32 yếu khi dùng cả WiFi + BT. Module có IPEX kết nối anten ngoài tốt hơn.

Liên quan

Đọc ESP32 BLE vs Bluetooth Classic. Áp dụng dự án Xe robot Bluetooth điều khiển bằng app Android.