BLE Debugging and Error Handling#

The Bluetooth Low Energy (BLE) stack returns error codes to indicate the success or failure of operations. Understanding and handling these errors is essential for robust BLE applications.

Error Code Format#

Return Values:

• 0 (RSI_SUCCESS): Operation completed successfully

• Non-Zero Values: Error codes indicating specific failure reasons

• Error Callbacks: Some errors are delivered asynchronously through event callbacks

Error Code Sources:

• Synchronous Errors: Returned directly from API function calls

• Asynchronous Errors: Delivered through error event callbacks (for example, rsi_ble_event_error_resp_t, rsi_ble_on_gatt_error_resp_t)

• Status Codes: Referenced in API documentation, see WiSeConnect Status Codes

Common BLE Error Codes#

Firmware / Wi-Fi SDK Errors:

• 0x0103: Firmware timeout

  • Cause: Firmware did not respond to a command within the expected time window

  • Resolution: Check Network Processor (NWP)/host interface health, retry the command, and verify power/coex configuration

Connection Errors:

• 0x4D04: BLE not connected

  • Cause: Attempted operation on a device that is not connected

  • Resolution: Verify device state using rsi_ble_get_device_state() before performing operations (returns overall state only; track per-connection through connection events)

• 0x4D05: BLE socket not available

  • Cause: No available connection slot

  • Resolution: Check connection limits, close unused connections, or increase connection limit configuration

• 0x4D08: Profile record full

  • Cause: Maximum number of GATT profiles/services reached

  • Resolution: Remove unused services or increase profile/attribute count configuration within the supported limit (also bounded by available memory configuration)

• 0x4D0C: Feature not enabled or configuration bit not set

  • Cause: A required feature bit is not set in the BLE feature bitmap. For example, rsi_ble_mtu_exchange_resp() returns 0x4D0C when RSI_BLE_MTU_EXCHANGE_FROM_HOST is not set.

  • Resolution: Enable the required feature bit during stack initialization

GATT Operation Errors:

• 0x4A01: Invalid Handle

  • Cause: Attribute handle is out of valid range or doesn't exist

  • Resolution: Verify handle value, ensure service/characteristic discovery completed

• 0x4A02: Read not permitted

  • Cause: Characteristic does not have read property or insufficient permissions

  • Resolution: Check characteristic properties and security requirements

• 0x4A03: Write not permitted

  • Cause: Characteristic does not have write property or insufficient permissions

  • Resolution: Check characteristic properties and security requirements

• 0x4A05: Insufficient authentication

  • Cause: Operation requires authentication but device is not authenticated

  • Resolution: Complete pairing/authentication before performing operation

• 0x4A06: Request not supported

  • Cause: Requested operation is not supported by the characteristic

  • Resolution: Check characteristic properties and supported operations

• 0x4A08: Insufficient authorization

  • Cause: Operation requires authorization but device is not authorized

  • Resolution: Complete authorization process before performing operation

• 0x4A0A: Attribute not found

  • Cause: Requested attribute (service/characteristic) does not exist

  • Resolution: Verify UUID and ensure service discovery completed

• 0x4A0C: Insufficient encryption key size

  • Cause: Encryption key size is insufficient for the operation

  • Resolution: Use appropriate encryption key size (typically 16 bytes for BLE). The minimum accepted size can be configured through rsi_ble_vendor_set_SMP_min_enc_keysize().

• 0x4A0F: Insufficient encryption

  • Cause: Operation requires encryption but connection is not encrypted

  • Resolution: Enable encryption on the connection before performing operation

• 0x4E60: Invalid Handle Range

  • Cause: Attribute handle is out of valid range

  • Resolution: Verify handle value and ensure it's within valid range

• 0x4E62: Invalid Parameters (typically GATT/BLE-buffer scope per neighboring codes)

  • Cause: One or more function parameters passed to a BLE API are invalid

  • Resolution: Check parameter values (handles, lengths, addresses, etc.)

• 0x4E64: BLE Buffer already in use

  • Cause: Buffer is currently being used by another operation

  • Resolution: Wait for current operation to complete, or use different buffer

• 0x4E65: Invalid Attribute Length When Small Buffer Mode is Configured

  • Cause: Data length exceeds configured buffer size

  • Resolution: Reduce data length or reconfigure buffer mode

SMP (Security) Errors:

• 0x4B01: SMP Passkey entry failed

• 0x4B02: SMP OOB not available

• 0x4B03: SMP Authentication Requirements

• 0x4B04: SMP confirm value failed

• 0x4B05: SMP Pairing not supported

• 0x4B06: SMP Encryption key size insufficient

• 0x4B07: SMP command not supported

• 0x4B08: SMP pairing failed

• 0x4B09: SMP repeated attempts

• 0x4B0A: SMP Invalid parameters

• 0x4B0B: DHKEY Check Failed

• 0x4B0C: SMP Numeric Comparison Failed

• 0x4BFD: SMP Invalid Keys Generated

• 0x4BFE: SMP Identical Public Key

General Error Codes:

• 0x0007: SAPI / Wi-Fi SDK timeout (SL_STATUS_TIMEOUT)

  • Cause: A WiSeConnect SDK API timed out waiting for a response from the firmware (SAPI-level timeout). Commonly seen when the firmware is busy, the host-firmware bus is stalled, or the command response never arrives.

  • Resolution: Check host-firmware connectivity (bus/interface health), verify firmware is not stuck in a previous operation, ensure prior commands completed, and retry after re-initialization if the condition persists

• 0x4E0C: Command disallowed

  • Cause: Command cannot be run in current state

  • Resolution: Check current state and ensure prerequisites are met

• 0x4046: Invalid Arguments (GAP scope)

  • Cause: One or more function arguments passed to a GAP-layer API are invalid

  • Resolution: Verify all argument values and types

• -4: Buffer not available to serve the command

  • Cause: No buffer available for the command

  • Resolution: Wait for buffers to become available or reduce command rate

Error Handling Best Practices#

1. Check Return Values: Always check return values from BLE API functions

   • Compare against RSI_SUCCESS (0) to determine success

   • Handle non-zero return values appropriately

2. Handle Errors Gracefully: Implement appropriate error handling for each error code

   • Provide meaningful error messages for debugging

   • Implement fallback behavior where appropriate

   • Log errors for troubleshooting

3. Use Error Callbacks: Register and handle error event callbacks

   • rsi_ble_on_gatt_error_resp_t: GATT error response received (asynchronous client APIs)

   • rsi_ble_event_error_resp_t: General BLE error event

   • rsi_bt_event_smp_failed_t: Pairing/security operation failed

4. Validate Parameters: Validate parameters before calling BLE APIs

   • Check handle values are within valid range

   • Verify data lengths are within limits

   • Ensure device addresses are properly formatted

5. Connection State: Verify connection state before performing connection-dependent operations

   • Use rsi_ble_get_device_state() for overall device state only. To know which connections are active, track rsi_ble_event_conn_status_t / rsi_ble_event_enhance_conn_status_t and disconnect events in the application (no API returns the connection list).

   • Handle disconnection events appropriately

6. Resource Management: Monitor and manage resources to prevent exhaustion

   • Track active connections and close unused connections

   • Monitor buffer usage

   • Manage GATT profiles/services efficiently

7. Retry Logic: Implement retry logic for transient errors where appropriate

   • Connection failures may be transient (device out of range)

   • Buffer unavailability may be temporary

   • Use exponential backoff for retries

8. Error Logging: Log errors for debugging and troubleshooting

   • Include error code, operation context, and relevant parameters

   • Use appropriate log levels (error, warning, and debug)

9. iOS Peer Interoperability: When the peer device is iOS, configure BLE connection parameters per Apple's Bluetooth Accessory Design Guidelines — mismatched intervals, latency, or supervision timeout commonly trigger iOS-side disconnects.

Error Recovery Strategies#

Connection Errors:

• Re-establish connection if device is still in range

• Verify device is advertising and discoverable

• Check connection limits and available resources

• Implement connection timeout handling

Handle Errors:

• Re-discover services/characteristics if handles become invalid

• Verify handles are valid before use

• After a successful discovery, cache the handles

Buffer Errors:

• Wait for buffer availability before retrying

• Reduce data size if possible

• Increase buffer configuration if frequently occurring

• Implement queueing mechanism for high-frequency operations

Resource Errors:

• Free unused resources (connections, services, buffers)

• Reduce connection count if at limit

• Reconfigure limits based on application needs

• Monitor resource usage proactively

Security Errors:

• Retry pairing with different method if supported

• Verify pairing capabilities match between devices

• Check encryption requirements and key sizes

• Ensure proper authentication/authorization flow

Error Event Callbacks#

GATT Error Callback:

• rsi_ble_on_gatt_error_resp_t: Invoked when a GATT error response is received

  • Provides device address, handle, and error code

  • Used for asynchronous client API operations

General Error Event:

• rsi_ble_event_error_resp_t: General BLE error event structure

  • Contains device address, handle, and error code

  • Used for various BLE error conditions

SMP Error Event:

• rsi_bt_event_smp_failed_t: Pairing/security operation failed

  • Provides failure reason code

  • Used for security-related errors

Debugging Methodology#

• Logging: Record error codes, operation context, and relevant parameters (see Error Handling Best Practices).

• Connection State: Track rsi_ble_event_conn_status_t / rsi_ble_event_enhance_conn_status_t and disconnect events; use rsi_ble_get_device_state() only for overall device state.

• Mode and tooling: For host–NWP integration paths and mode-specific behavior, see Processing modes. For trace and debug options, use the WiSeConnect SDK documentation for your release and target.

APIs Used in This Section#

Note: Error codes may vary by SDK version. See WiSeConnect Status Codes for the complete list and version-specific codes. See the BLE API Reference guide for API-specific return values.