20 BLE Field Debugging and Internals

20.2.1 War story: notifications never arrive

// Only reads once, no updates
value = characteristic.read();

// Enable notifications via CCCD
characteristic.getDescriptor(BLEUUID((uint16_t)0x2902))
              ->writeValue((uint8_t*)"\x01\x00", 2, true);
// Now notifications will arrive in callback

20.2.2 War story: the connection is too fast, too slow, or too expensive

20.3.1 War story: the payload grows past the default MTU

// Request MTU exchange
BLEDevice::setMTU(247);  // Request 247 bytes
// Actual MTU may be less based on negotiation

Scenario: Environmental sensor sends combined reading:
- Temperature: 2 bytes (int16)
- Humidity: 2 bytes (uint16)
- Pressure: 4 bytes (uint32)
- Timestamp: 4 bytes (uint32_t)
- Battery: 1 byte (uint8)
- Device ID: 6 bytes (MAC address)
Total: 19 bytes ✓ (fits in default 20-byte MTU)

Then you add:
- CO2 level: 2 bytes
- Light intensity: 2 bytes
Total: 23 bytes ✗ (exceeds 20-byte payload!)

Result without MTU negotiation:
- First 20 bytes transmitted
- Last 3 bytes silently dropped
- Light intensity always reads 0
- Hours of debugging "sensor malfunction"

// ESP32 Example: Request larger MTU
void on_connected(uint16_t conn_handle) {
    // Request 247 bytes (maximum for BLE 4.2+)
    esp_ble_gattc_send_mtu_req(conn_handle, 247);

    // Wait for MTU exchange callback before sending data!
    mtu_negotiated = false;
}

void on_mtu_exchanged(uint16_t conn_handle, uint16_t mtu) {
    Serial.printf("MTU negotiated: %d bytes\n", mtu);
    effective_mtu = mtu;
    max_payload = mtu - 3;  // Subtract ATT header
    mtu_negotiated = true;

    Serial.printf("Max payload: %d bytes\n", max_payload);
    // NOW safe to send large packets
}

// Only send when MTU is ready
void send_sensor_data() {
    if (!mtu_negotiated) {
        Serial.println("ERROR: Attempted to send before MTU negotiation!");
        return;
    }

    if (payload_size > max_payload) {
        Serial.printf("ERROR: Payload %d exceeds MTU %d\n",
                      payload_size, max_payload);
        return;
    }

    pCharacteristic->setValue(data, payload_size);
    pCharacteristic->notify();
}

// Fallback for devices that won't negotiate larger MTU
void send_large_data_chunked(uint8_t* data, size_t total_len) {
    const size_t CHUNK_SIZE = max_payload - 2;  // Reserve 2 bytes for sequence

    for (size_t offset = 0; offset < total_len; offset += CHUNK_SIZE) {
        size_t chunk_len = min(CHUNK_SIZE, total_len - offset);

        // Packet format: [sequence_number] [chunk_data]
        uint8_t packet[max_payload];
        packet[0] = offset / CHUNK_SIZE;  // Chunk sequence
        packet[1] = (offset + chunk_len >= total_len) ? 1 : 0;  // Last chunk flag
        memcpy(&packet[2], data + offset, chunk_len);

        pCharacteristic->setValue(packet, chunk_len + 2);
        pCharacteristic->notify();
        delay(20);  // Allow time for transmission
    }
}

20.3.2 Troubleshooting Quick Reference

Not every field failure is a notification, interval, or MTU bug. Before reaching for a sniffer, walk the connection lifecycle from the outside: can the device be found, does pairing complete, does the link hold, and does application data move once it is connected.

Connection lifecycle checklist:

Work through Troubleshooting Quick Reference as a connected sequence. Start with Can the device be discovered? Check advertising state, pairing-mode timeout, power, and any scan filters. Next, Does pairing fail? Confirm the pairing method matches both devices’ I/O capabilities and remove stale bonds before retrying — if the failure looks like a method-selection problem rather than a one-off retry, see BLE Pairing Methods. Then, Does it connect but drop? Check range, battery level, the granted connection interval, and Wi-Fi interference (see the coexistence check below). Finally, Does data fail after connection? Verify service and characteristic UUIDs and characteristic properties first — if the specific symptom is a missing notification stream or a truncated payload, that is Mistake 1 or Mistake 3 above, not a new problem.

Common problems and solutions:

Debug checklist:

Pairing and discovery:

Work through Troubleshooting Quick Reference as a connected sequence. Start with [ ] Verify Bluetooth is enabled on both devices. Next, [ ] Check the device is in pairing mode (usually a 2-3 minute timeout). Then, [ ] Remove old pairings from the device list. Finally, [ ] Confirm Bluetooth version compatibility.

Connection:

Work through Troubleshooting Quick Reference as a connected sequence. Start with [ ] Verify devices are within range (10m for BLE). Next, [ ] Check for physical obstacles. Then, [ ] Identify interference sources (Wi-Fi, microwaves). Finally, [ ] Monitor RSSI (should be above -80 dBm).

Advertising and services:

Work through Troubleshooting Quick Reference as a connected sequence. Start with [ ] Check advertising interval (100 ms-10s typical). Then connect that result to [ ] Review GATT service/characteristic UUIDs.

Debugging tools:

When these failures are under control, the build starts looking like a product rather than a lab. The closing sections keep the same ideas but ask the production questions: power, security, evidence, and what to study next.

20.4.1 Connection Parameter Evidence and Timeout Bounds

The connection-interval mistake above is not only a battery problem; it is a parameter-coupling problem. Inspect Figure 20.1 to place the granted parameters on the same timeline as discovery, connection, and GATT exchange. A demo that connects once does not prove latency, battery, or recovery claims.

Read Figure 20.1 from advertising through scan request and response to the connection indication, then continue into GATT data exchange. At that point, record the granted interval, latency, timeout, MTU, notification rate, and disconnect reason together. The ordered evidence connects radio setup to the timeout bounds calculated next.

Peripheral latency is useful because it lets a device keep a short interval available for central-initiated work while sleeping through idle events. For example, a 50 ms interval with latency 4 gives a worst idle listening gap of about (1 + 4) x 50 ms = 250 ms, before application processing and phone scheduling are added. A 1 s interval with latency 9 gives about (1 + 9) x 1 s = 10 s, which can fit a slow environmental sensor but would feel broken for a lock, controller, or vibration alarm.

The supervision timeout must cover the longest legal silence, not the average report period:

supervision_timeout > (1 + peripheral_latency) x connection_interval x 2

With interval 30 ms and latency 4, the bound is (1 + 4) x 30 ms x 2 = 300 ms, so a 2 s supervision timeout is valid and a 200 ms timeout is not. With interval 1 s and latency 9, the bound is 20 s; a 10 s timeout detects loss sooner, but it is invalid for that latency. This is the hidden reason slow sensors often need long supervision timeouts when they also use high latency.

20.4.2 Folded Lab Notes: Sensor Beacon and Deployment Tuning

Use the existing GATT server lab as the foundation for a sensor beacon extension:

When the lab moves toward production, tune the radio behavior in three areas.

Payload discipline. Do not send large payloads immediately after requesting a larger MTU; wait for the negotiated MTU event, then subtract the 3-byte ATT header before sizing each write or notification.

Timing choices. Avoid continuous scanning on battery-powered gateways: match scan window and interval to the beacon advertising interval and the discovery latency you can accept. Pick the connection interval from the application latency requirement, then apply peripheral latency for routine sleep — a slow environmental sensor tolerates longer intervals than a lock, controller, or vibration monitor.

Field calibration. Calibrate RSSI in the deployment environment before using it for indoor positioning; a short walk test at known distances usually beats datasheet assumptions. For zone detection, model beacon placement around zone boundaries, not only zone centers — boundary ambiguity often dominates classification error.

20.4.3 Folded Code and Lab Portfolio Notes

Use the scanner, beacon, dashboard, and mesh exercises as a portfolio rather than as isolated demos:

For throughput and power worked examples, state the negotiated MTU, connection interval, peripheral latency, notification rate, and current budget together. Those parameters interact: a larger MTU can shorten an OTA transfer, but a short connection interval or continuous scanning can erase the battery benefit.