# 🧯 Handle Disconnects and Common BLE Pitfalls
## Learning Objectives
By the end of this lesson you will be able to:
- Explain what happens inside the ESP32 when a phone disconnects, and why the gadget can vanish from the scan list.
- Restart BLE advertising safely after every disconnect.
- Keep the gadget responsive by moving slow work out of BLE callbacks.
- Recognize and fix the classic beginner BLE bugs: flooding notifications, oversized payloads, and stale phone caches.
## Quick Review
In the last lesson you completed the full two-way loop from your phone: you scanned, connected, subscribed to notifications, watched values arrive, and wrote a command back to the ESP32, matching every phone-side event to a line in the Serial Monitor.
That working loop is your baseline. Today we cover what happens when that loop *breaks*, and how to make it recover on its own.
## Theory
### A BLE connection is a temporary rental
Your ESP32 is a **peripheral**: it advertises, a phone (**central**) connects, and the two exchange data until one side ends the link. When the link ends, the ESP32 does **not** automatically go back to advertising. The radio stack simply stops being discoverable, so your phone scans and finds nothing.
This confuses almost every beginner: the gadget worked, you walked away, and now it is "dead." It is not dead. It is invisible.
### The disconnect lifecycle
```mermaid
flowchart TD
Boot["🔌
Boot"] --> Adv["📡
Advertising"]
Adv -->|phone connects| Conn["🔗
Connected"]
Conn -->|phone leaves, out of range, app closed| Disc["✂️
Disconnected"]
Disc -->|startAdvertising from loop| Adv
Disc -->|forgot to restart| Silent["🚫
Invisible to phone"]
```
The fix is one call, `BLEDevice::startAdvertising()`, but *where* you call it matters.
### Keep callbacks short
`onConnect()` and `onDisconnect()` run inside the BLE stack task, not your `loop()`. Blocking there (a `delay()`, a slow `Serial` flood, a sensor read that takes 300 ms) stalls the stack, which can cause supervision timeouts or a watchdog reboot.
> [!IMPORTANT]
> The safe pattern is: the callback sets a **flag**, and `loop()` reads that flag and does the real work. Callbacks should finish in microseconds.
### Pitfalls that actually bite beginners
| Symptom | Usual cause | Fix |
| --- | --- | --- |
| Gadget disappears after first disconnect | Advertising never restarted | Set a flag in `onDisconnect`, call `BLEDevice::startAdvertising()` in `loop()` |
| Random reboots while connected | `delay()` or heavy work in callbacks or the main loop | Use `millis()` timing, no long blocking |
| `notify()` returns false | Not connected, phone not subscribed, or send queue full | Gate on connection and `getSubscribedCount()`, throttle the rate |
| Values cut off or garbled | Payload bigger than the default ATT size | Keep data at 20 bytes or less, or raise the MTU |
| Phone "cannot find service" after a firmware change | Phone caches the old GATT table | Forget the device in Bluetooth settings, reconnect |
| Device name missing from the scan list | Name too long for the 31-byte advertising packet | Shorten the name |
Two details worth memorizing:
- The default ATT payload is **23 bytes**, with **20 usable** for your data. Anything larger needs MTU negotiation (`BLEDevice::setMTU(185)` on the server side, plus a phone that asks for it).
- Disconnect reason `0x08` means **supervision timeout** (the phone stopped answering, often out of range), and `0x13` means the phone closed the connection on purpose.
## Worked Examples
### Example 1: Restart advertising the safe way
```cpp
#include
#include
volatile bool clientConnected = false;
volatile bool needsRestart = false;
class ServerCallbacks : public BLEServerCallbacks {
void onConnect(BLEServer* server) override {
clientConnected = true;
Serial.println("Phone connected");
}
void onDisconnect(BLEServer* server) override {
clientConnected = false;
needsRestart = true; // flag only, no blocking calls
Serial.println("Phone disconnected");
}
};
void loop() {
if (needsRestart) {
needsRestart = false;
delay(200); // let the stack release the link
BLEDevice::startAdvertising(); // visible again
Serial.println("Advertising restarted");
}
// sensor work here, no long delay()
}
```
The 200 ms settle delay is outside the callback, so it cannot stall the stack.
### Example 2: Gate and pace your notifications
```cpp
const unsigned long NOTIFY_PERIOD_MS = 200; // 5 notifications per second
unsigned long lastNotify = 0;
void loop() {
if (clientConnected && sensorChar->getSubscribedCount() > 0 &&
millis() - lastNotify >= NOTIFY_PERIOD_MS) {
lastNotify = millis();
char payload[20];
snprintf(payload, sizeof(payload), "%.1f", readTemperature());
sensorChar->setValue((uint8_t*)payload, strlen(payload));
if (!sensorChar->notify()) {
Serial.println("notify failed, will retry");
}
}
}
```
Three guards in one place: connected, subscribed, and paced.
### Example 3: Diagnose "my phone can't see it"
Click to reveal the checklist
1. Is the Serial Monitor printing "Advertising restarted"? If not, the restart never ran.
2. Did you change any UUID since the last successful test? Then forget the device on the phone and reconnect.
3. Is another phone still holding the connection? Check `BLEDevice::getServer()->getConnectedCount()`.
4. Is the device name longer than about 29 characters? Shorten it and retest.
5. Does the board reboot when you connect? Look for a watchdog message, which points to blocking code.