925 Bluetooth Review: GATT Pitfalls and Summary

Series Navigation

This is Part 3 of the Bluetooth Comprehensive Review series:

Overview and Visualizations - Protocol stacks, state machines, initial scenarios
Advanced Scenarios - Medical security, battery drain, smart locks
GATT Pitfalls (this chapter) - Common implementation mistakes
Assessment - Visual gallery and understanding checks

925.1 Common GATT Implementation Pitfalls

Show code

{
  const container = document.getElementById('kc-bt-7');
  if (container && typeof InlineKnowledgeCheck !== 'undefined') {
    container.innerHTML = '';
    container.appendChild(InlineKnowledgeCheck.create({
      question: "A developer creates a BLE temperature sensor peripheral with a NOTIFY characteristic. During testing with nRF Connect app, notifications work perfectly. But when they build a custom Android app, the app connects successfully, discovers the characteristic, but never receives notifications even though the sensor is calling notify() every second. What is the most likely issue?",
      options: [
        {text: "The Android app needs to use a different BLE library that supports notifications", correct: false, feedback: "All standard Android BLE libraries (BluetoothGatt, RxAndroidBle, Nordic libraries) support notifications. The issue is not the library choice."},
        {text: "The custom app failed to write 0x0001 to the CCCD (Client Characteristic Configuration Descriptor) to enable notifications", correct: true, feedback: "Correct! BLE notifications require the client to explicitly opt-in by writing 0x0001 (notifications) or 0x0002 (indications) to the CCCD descriptor (UUID 0x2902). nRF Connect automatically does this when you tap 'Enable Notifications'. Custom apps must manually call setCharacteristicNotification() AND write to the CCCD. This is a security/power feature - peripherals don't send notifications until the client subscribes."},
        {text: "The sensor peripheral needs to call indicate() instead of notify() for Android compatibility", correct: false, feedback: "Both notify() and indicate() work on Android. The difference is that indicate() requires acknowledgement from the central. The issue is not the notification type."},
        {text: "Android requires the characteristic to have READ permission in addition to NOTIFY permission", correct: false, feedback: "NOTIFY and READ are independent permissions. A characteristic can be notify-only. The issue is that the client hasn't subscribed to notifications via CCCD."}
      ],
      difficulty: "hard",
      topic: "gatt-profiles"
    }));
  }
}

Pitfall: Not Enabling CCCD Before Expecting Notifications

The Mistake: Creating a BLE peripheral with NOTIFY characteristics, but notifications never arrive at the central device. The central connects, discovers services, but never receives pushed data even though the peripheral is calling notify().

Why It Happens: BLE notifications require the client to explicitly enable them by writing to the Client Characteristic Configuration Descriptor (CCCD). This is a security and power-saving feature - peripherals don’t spam data until the client opts in. Many developers forget this step, especially when transitioning from other protocols.

The Fix: After discovering characteristics, the central must write 0x0001 (notifications) or 0x0002 (indications) to the CCCD descriptor (UUID 0x2902):

// Central/Client side - MUST enable notifications
void on_characteristic_discovered(uint16_t char_handle, uint16_t cccd_handle) {
    // Write 0x0001 to CCCD to enable notifications
    uint8_t enable_notify[2] = {0x01, 0x00};  // Little-endian
    ble_gattc_write(conn_handle, cccd_handle, enable_notify, 2);
}

// Peripheral side - check if notifications are enabled
void send_sensor_reading(float value) {
    if (cccd_enabled) {  // Only notify if client subscribed
        ble_gatts_hvx(conn_handle, &hvx_params);
    }
    // Otherwise, client must poll via READ
}

Common symptoms: Works in nRF Connect (which auto-enables CCCD) but fails in custom apps. Debug by checking CCCD value after connection.

Pitfall: Using Custom UUIDs When Standard GATT Services Exist

The Mistake: Creating custom 128-bit UUIDs for common sensor data (temperature, heart rate, battery level) instead of using Bluetooth SIG standard services, breaking interoperability with existing apps and tools.

Why It Happens: Developers either don’t know standard services exist, or want “full control” over data format. Custom UUIDs require custom apps on every platform, while standard services work with generic BLE tools and OS integrations.

The Fix: Check the Bluetooth SIG GATT specifications before creating custom services. Use standard UUIDs with defined data formats:

// WRONG: Custom UUID for temperature
#define TEMP_SERVICE_UUID "12345678-1234-5678-1234-123456789abc"
// Requires custom app, no ecosystem support

// CORRECT: Standard Environmental Sensing Service
#define ENV_SENSING_SERVICE  0x181A  // Bluetooth SIG standard
#define TEMPERATURE_CHAR     0x2A6E  // Standard characteristic

// Standard data format for temperature (per GATT spec):
// sint16: temperature in 0.01 degrees Celsius
int16_t temp_value = (int16_t)(celsius * 100);
ble_gatts_notify(conn_handle, temp_char_handle, &temp_value, 2);

// Benefits of standard services:
// - Works with nRF Connect, LightBlue, and generic BLE apps
// - iOS/Android can display values in system Bluetooth settings
// - Interoperable with fitness apps, health platforms
// - Defined data encoding eliminates ambiguity

When to use custom UUIDs: Only for truly proprietary functionality that has no standard equivalent (e.g., device-specific configuration, firmware update protocol, vendor-specific commands).

Pitfall: Setting Supervision Timeout Too Short for High-Latency Peripherals

The Mistake: Using a short supervision timeout (e.g., 1 second) for a BLE connection to a peripheral that uses peripheral latency to skip connection events, resulting in unexpected disconnections during normal operation when no data is being exchanged.

Why It Happens: Developers set aggressive timeouts thinking “faster disconnect detection is better,” without accounting for the interaction between connection interval, peripheral latency, and supervision timeout. If peripheral latency allows skipping 10 events at 400ms intervals, the peripheral may not respond for 4 seconds—triggering a 1-second timeout.

The Fix: The supervision timeout must accommodate the worst-case response time based on your connection parameters. Use this formula:

Minimum supervision timeout = (1 + peripheral_latency) × connection_interval × 2

Example calculations:

Scenario A (fast response, no latency):
- Connection interval: 50ms
- Peripheral latency: 0 (respond every event)
- Minimum timeout: (1 + 0) × 50ms × 2 = 100ms
- Recommended: 500ms-1s (margin for retries)

Scenario B (power-optimized sensor):
- Connection interval: 400ms (maximum for iOS)
- Peripheral latency: 4 (skip up to 4 events when idle)
- Minimum timeout: (1 + 4) × 400ms × 2 = 4000ms
- Recommended: 6-10 seconds

Scenario C (ultra-low-power with max latency):
- Connection interval: 4s (BLE maximum)
- Peripheral latency: 0 (required at max interval)
- Minimum timeout: (1 + 0) × 4s × 2 = 8s
- Recommended: 16-32 seconds (BLE max is 32s)

Common mistake:
- CI: 200ms, Latency: 10, Timeout: 2s
- Worst-case response: (1+10) × 200ms = 2.2s > 2s timeout
- Result: Random disconnections when peripheral is idle!

Always verify: timeout > (1 + latency) × interval × safety_factor where safety_factor >= 2.

Show code

{
  const container = document.getElementById('kc-bt-8');
  if (container && typeof InlineKnowledgeCheck !== 'undefined') {
    container.innerHTML = '';
    container.appendChild(InlineKnowledgeCheck.create({
      question: "A BLE peripheral is configured with: connection interval = 200ms, peripheral latency = 10 (can skip up to 10 connection events), supervision timeout = 2 seconds. Users report random disconnections when the device is idle but working fine during active data transfer. What is causing the disconnections?",
      options: [
        {text: "The supervision timeout is too long, causing the central to give up waiting for responses", correct: false, feedback: "A longer timeout would actually reduce disconnections by giving more time for responses. The problem is the opposite - the timeout is too SHORT."},
        {text: "The peripheral latency of 10 is not supported by most BLE centrals", correct: false, feedback: "BLE spec allows peripheral latency up to 499. A value of 10 is well within spec and widely supported. The issue is the relationship between parameters, not the latency value itself."},
        {text: "The supervision timeout (2s) is shorter than the worst-case response time ((1+10) x 200ms = 2.2s), causing timeout before response", correct: true, feedback: "Correct! When the peripheral uses its full latency allowance, it won't respond for (1 + latency) × interval = (1 + 10) × 200ms = 2.2 seconds. But the supervision timeout is only 2 seconds, so the central times out first and disconnects. The fix: timeout must be > (1 + latency) × interval × safety_factor. For these parameters: timeout should be at least 4.4 seconds (2.2s × 2)."},
        {text: "The connection interval of 200ms is too slow for reliable BLE communication", correct: false, feedback: "200ms connection interval is well within BLE spec (7.5ms to 4s range) and commonly used for power-optimized sensors. The interval itself is fine; the issue is timeout calculation."}
      ],
      difficulty: "hard",
      topic: "connection-parameters"
    }));
  }
}

Pitfall: Ignoring iOS Connection Parameter Restrictions

The Mistake: Designing a BLE peripheral with connection parameters optimized for Android or embedded gateways (e.g., 500ms-4s connection intervals), then discovering that iPhones reject or override these parameters, causing connection failures or poor battery life on iOS.

Why It Happens: Apple enforces stricter connection parameter ranges than the BLE specification allows. Peripherals requesting parameters outside Apple’s limits will have their requests rejected or modified, leading to unexpected behavior that only appears during iOS testing.

The Fix: Design for Apple’s constraints first, then relax for Android/embedded if needed:

Apple's BLE Connection Parameter Requirements (as of iOS 17):

Connection Interval:
- Minimum: 15ms (BLE spec allows 7.5ms)
- Maximum: 2s (was 4s before iOS 11, then 2s)
- Must be multiple of 15ms

Peripheral Latency:
- Maximum: 30 (spec allows 499)
- Constraint: latency × interval ≤ 2 seconds

Supervision Timeout:
- Minimum: 2 seconds
- Maximum: 6 seconds
- Constraint: timeout ≥ (1 + latency) × interval × 3

Recommended cross-platform parameters:

For responsive devices (wearables, input devices):
  min_interval: 15ms (12 × 1.25ms)
  max_interval: 30ms (24 × 1.25ms)
  latency: 0
  timeout: 2000ms

For power-optimized sensors:
  min_interval: 100ms (80 × 1.25ms)
  max_interval: 200ms (160 × 1.25ms)
  latency: 4
  timeout: 4000ms

For ultra-low-power (environmental sensors):
  min_interval: 400ms (320 × 1.25ms)
  max_interval: 500ms (400 × 1.25ms)
  latency: 3
  timeout: 6000ms

Common mistake: CI=4s (max BLE spec)
- Android: Works fine
- iOS: Silently reduced to 2s, doubling power consumption
- Embedded: Works fine

Always test on iOS devices early in development—parameter negotiation failures are silent!

Show code

{
  const container = document.getElementById('kc-bt-9');
  if (container && typeof InlineKnowledgeCheck !== 'undefined') {
    container.innerHTML = '';
    container.appendChild(InlineKnowledgeCheck.create({
      question: "A smart home company is designing a BLE environmental sensor optimized for iOS and Android. They initially set connection interval to 4 seconds (BLE specification maximum) to maximize battery life. During iOS testing, they discover the device battery drains twice as fast as expected. What is happening?",
      options: [
        {text: "iOS doesn't support BLE connection intervals longer than 1 second due to hardware limitations", correct: false, feedback: "iOS hardware fully supports BLE spec ranges. The issue is Apple's software policy, not hardware capability."},
        {text: "iOS silently rejects the 4-second interval and negotiates to 2 seconds (its maximum), doubling the connection frequency", correct: true, feedback: "Correct! Apple restricts BLE connection intervals to 15ms-2s maximum (was 4s before iOS 11). When a peripheral requests 4s, iOS silently reduces it to 2s. This doubles the number of connection events, waking the radio twice as often. The solution: design for Apple's constraints first (max 2s interval), then optimize for other platforms."},
        {text: "iOS requires Classic Bluetooth for connection intervals longer than 2 seconds", correct: false, feedback: "Classic Bluetooth doesn't use the same connection interval concept as BLE. iOS fully supports BLE but with different parameter limits than the BLE spec allows."},
        {text: "The sensor firmware has a bug that ignores iOS connection parameter update requests", correct: false, feedback: "The peripheral typically proposes parameters, and the central (iOS) accepts or modifies them. iOS modifying the interval is expected behavior, not a bug. The issue is designing outside iOS's accepted range."}
      ],
      difficulty: "medium",
      topic: "connection-parameters"
    }));
  }
}

925.2 Chapter Summary

Bluetooth has evolved from cable replacement to sophisticated IoT protocol. BLE revolutionized wireless sensors by enabling years of battery life.

Key Points: - Classic BT: Continuous connections (audio) - BLE: Intermittent, ultra-low power - Piconets: 7 active slaves max - Mesh: Scalable building automation - Profiles: Application-specific behavior - Security: Modern encryption & authentication

Show code

{
  const container = document.getElementById('kc-bt-10');
  if (container && typeof InlineKnowledgeCheck !== 'undefined') {
    container.innerHTML = '';
    container.appendChild(InlineKnowledgeCheck.create({
      question: "A factory wants to deploy 200 BLE-enabled asset tracking tags throughout their warehouse. Each tag broadcasts its location every 5 seconds. A central gateway collects all tag data. Using Classic Bluetooth with a single hub, what fundamental limitation will they encounter?",
      options: [
        {text: "Classic Bluetooth range is limited to 10 meters, insufficient for warehouse coverage", correct: false, feedback: "While standard Class 2 Bluetooth has ~10m range, Class 1 can reach 100m. Range can be addressed with multiple gateways. The fundamental limitation is different."},
        {text: "Classic Bluetooth piconets only support 7 active slaves simultaneously, making 200 devices impossible with one hub", correct: true, feedback: "Correct! Classic Bluetooth uses piconet topology with a hard limit of 7 active slaves per master (due to 3-bit address field in packet header). 200 devices would require ~29 separate hubs or a technology change. BLE doesn't have this piconet limitation, and BLE Mesh can support building-scale deployments with hundreds of nodes using managed flooding."},
        {text: "Classic Bluetooth doesn't support asset tracking profiles, requiring proprietary implementation", correct: false, feedback: "While there's no standard 'asset tracking profile', custom data can be transmitted over SPP or other profiles. The limitation is more fundamental than profile availability."},
        {text: "The 5-second broadcast interval is too slow for Classic Bluetooth's timing requirements", correct: false, feedback: "Classic Bluetooth can handle various data rates and timing. A 5-second interval is easily accommodated. The issue is device count, not timing."}
      ],
      difficulty: "easy",
      topic: "bluetooth-classic-vs-ble"
    }));
  }
}

Show code

{
  const container = document.getElementById('kc-bt-11');
  if (container && typeof InlineKnowledgeCheck !== 'undefined') {
    container.innerHTML = '';
    container.appendChild(InlineKnowledgeCheck.create({
      question: "A medical device company is building a BLE insulin pump that must maintain a secure connection with a smartphone app for dosage control. Regulatory requirements mandate that the device re-authenticate after 5 minutes of inactivity to prevent unauthorized access. Which security implementation approach is correct?",
      options: [
        {text: "Implement app-only timeout that shows a login screen after 5 minutes, relying on BLE encryption for ongoing security", correct: false, feedback: "App-only security is insufficient because other BLE clients (attackers with BLE scanners) can bypass the app and connect directly to the device. Security must be enforced at the device level."},
        {text: "Use BLE advertising with rotating MAC address every 5 minutes to prevent tracking and require re-pairing", correct: false, feedback: "MAC address rotation is a privacy feature to prevent tracking, not an authentication mechanism. It doesn't provide access control or re-authentication."},
        {text: "Configure GATT characteristic security to require encryption, implement device-side inactivity timeout that locks sensitive characteristics until app re-authenticates", correct: true, feedback: "Correct! Security must be enforced at the device level because other BLE clients can bypass app controls. The approach: (1) Require encrypted link for sensitive characteristics via GATT permissions, (2) Implement device-side timer that locks read/write after 5 minutes inactivity, (3) Require app-layer authentication (e.g., PIN or biometric confirmation forwarded to device) before unlocking. This ensures security regardless of which app connects."},
        {text: "Use Classic Bluetooth with SPP profile instead of BLE, since Classic has stronger built-in security for medical devices", correct: false, feedback: "Both Classic and BLE can achieve equivalent security levels. BLE with LE Secure Connections provides strong encryption. The key is proper implementation of authentication and access control, not the Bluetooth variant."}
      ],
      difficulty: "hard",
      topic: "bluetooth-security"
    }));
  }
}

Show code

{
  const container = document.getElementById('kc-bt-12');
  if (container && typeof InlineKnowledgeCheck !== 'undefined') {
    container.innerHTML = '';
    container.appendChild(InlineKnowledgeCheck.create({
      question: "A developer is implementing a BLE heart rate sensor. After pairing and bonding with an ESP32 gateway, the connection works perfectly. However, when the ESP32 reboots, it must re-pair with the sensor every time even though bonding was completed. The sensor stores the bonding keys correctly. What is the most likely cause?",
      options: [
        {text: "BLE bonding is not supported on ESP32 hardware and requires external security chips", correct: false, feedback: "ESP32 fully supports BLE bonding. The ESP-IDF and Arduino BLE libraries include bonding functionality with NVS (Non-Volatile Storage) support."},
        {text: "The ESP32 is not persisting bonding keys to flash/NVS storage, losing them on reboot", correct: true, feedback: "Correct! Bonding = Pairing + Key Storage. The ESP32 generates keys during pairing but must explicitly store them in Non-Volatile Storage (NVS) to persist across reboots. Without nvs_set_blob() calls to save LTK, IRK, and CSRK, the keys are lost when RAM is cleared on reboot. The sensor's stored keys then don't match the 'new' ESP32, requiring re-pairing. Solution: use NVS flash storage to persist bonding keys."},
        {text: "Heart rate sensors use Legacy Pairing which doesn't support bonding, only LE Secure Connections does", correct: false, feedback: "Both Legacy Pairing and LE Secure Connections support bonding (key storage). Bonding is orthogonal to the pairing method used. The issue is key persistence, not pairing mode."},
        {text: "The ESP32 needs to initiate the connection within 30 seconds of sensor power-on for bonding to persist", correct: false, feedback: "There's no time limit for bonding persistence. Once bonded, keys should remain valid until explicitly deleted. The issue is that keys aren't being saved to non-volatile storage."}
      ],
      difficulty: "medium",
      topic: "bluetooth-security"
    }));
  }
}

925.3 Original Source Figures (Alternative Views)

The following figures from the CP IoT System Design Guide provide alternative perspectives on Bluetooth concepts for review and comparison.

Original Bluetooth Protocol Stack (Alternative View)

Complete Bluetooth protocol stack showing layered architecture from Radio layer through Baseband, Link Manager Protocol, L2CAP, RFCOMM, and Application Profiles including Serial Port Profile, Human Interface Device, Hands-Free Profile, and Advanced Audio Distribution Profile