Phone nearby

BLE GATT Server

A phone finds and controls the device. Starting point for local setup.

Phone nearby Phone connects in ESP32

Official path: examples/bluetooth/bluedroid/ble/gatt_server

01 Overview

The device acts as a GATT server and advertises over BLE. A phone, as a GATT client, can connect and read/write characteristics for local control.

Solves device configuration in router-less environments, e.g., smart lights, locks, sensors. The phone app connects directly without internet.

Use for app-based local setup, device debugging, or private protocol control. Not for public internet control due to BLE's short range.

Espressif recommends the service-table example for production to simplify code and improve maintainability.

This example is a foundation for learning BLE GATT: services, characteristics, notifications.

Module: BLE-capable ESP32 module, e.g., ESP32-WROOM-32. Note: ESP32-S2 lacks BLE.
Button: Common to add a pairing button to trigger advertising or enter pairing mode.
Status LED: Indicates connection or advertising state for debugging.
Power: Advertising consumes energy; battery products should advertise only on button press.
Antenna: Keep antenna area clear of metal for optimal range.
Connectors: Reserve I2C/SPI for external sensors if needed.

1. Initialize NVS, controller, and Bluedroid stack.

2. Create GATT service, characteristics, and CCCD; register callbacks.

3. Start advertising with name and UUID.

4. Wait for phone connection; handle connect/disconnect events.

5. Notifications only after client writes CCCD.

6. Handle read/write requests and execute control logic.

7. Change device name and UUIDs before shipping to avoid conflicts.

Notify is not on by default: Client must write CCCD to enable.
Demo UUIDs cannot ship: Use custom UUIDs to avoid clashes.
Custom work: Protocol, bonding, advertising interval, Wi-Fi provisioning combo.
Power: Advertising interval affects consumption; trade-off needed.
Security: Enable pairing and bonding if encryption is required.

中文

手机近场

手机发现并控制设备。近场配置和控灯/控锁的起点。

手机近场被手机连接 ESP32

官方路径: examples/bluetooth/bluedroid/ble/gatt_server

设备作为 GATT 服务器，通过 BLE 广播自身，等待手机连接。手机作为 GATT 客户端，可以读写特征值，实现近场控制。

解决无路由器环境下的设备配置问题，例如智能灯、门锁、传感器等。手机 App 直接连接设备，无需互联网。

适用于 App 近场配置、设备调试、私有协议控制等场景。不适用于远程公网控制，因为 BLE 是短距离通信。

官方建议量产时改用 service table 示例，以简化代码并提高可维护性。

本示例是学习 BLE GATT 的基础，理解服务、特征、通知等概念。

1. 初始化 NVS、控制器和 Bluedroid 协议栈。

2. 创建 GATT 服务、特征和 CCCD，注册回调函数。

3. 开始广播，设置广播名称和 UUID。

4. 等待手机连接，处理连接/断开事件。

5. 手机写入 CCCD 后，才能发送通知。

6. 处理读写请求，执行相应控制逻辑。

7. 出货前修改设备名称和 UUID，避免冲突。