BLE Initialization and Configuration#

For Bluetooth Low Energy (BLE) stack architecture, physical layer (PHY) overview, and summarized connection and advertising limits, see BLE architecture.

PHY Options#

PHY Selection and Negotiation#

Default Behavior:

• All connections start with 1M PHY unless initiated from a Coded PHY advertisement

• PHY can be changed after connection establishment using rsi_ble_setphy()

• PHY negotiation occurs between both devices based on their capabilities

PHY Update Process:

1. Either device can request a PHY change using rsi_ble_setphy()

2. The remote device accepts or rejects based on its capabilities

3. PHY change takes a minimum of six connection intervals to complete

4. rsi_ble_event_phy_update_t event indicates successful PHY change

Reading Current PHY:

• Use rsi_ble_readphy() to query the current PHY on a connection

• Response includes both TX and RX PHY information (see rsi_ble_resp_read_phy_t structure)

Asymmetric PHY: The stack supports asymmetric PHY rates on a connection (for example, TX on 1M PHY and RX on 2M PHY). Use rsi_ble_setphy() and rsi_ble_readphy() to configure and read TX/RX PHY independently.

Maximum Simultaneous Connections#

The SiWx917 NWP supports multiple simultaneous BLE connections, enabling applications to communicate with multiple devices concurrently.

Connection Limits#

Total Connections:

• The SiWx917 NWP supports up to 10 simultaneous BLE connections total (legacy advertising).

• When using extended advertising (AE), the connection limit is 2.

• Connection limits are configured during system initialization.

• The exact maximum may depend on system configuration and available memory.

Role-Based Connection Distribution:

• Central Role: Can maintain up to 8 simultaneous connections to peripheral devices.

• Peripheral Role: Can accept up to 2 simultaneous connections from central devices.

• Dual Role: Can maintain connections in both central and peripheral roles simultaneously, subject to the total limit of 10 connections.

• Example: A device can maintain 8 central connections and 2 peripheral connections simultaneously.

Connection Management:

• Each connection is identified by a unique device address.

• Device state: Use rsi_ble_get_device_state() to get overall device state (for example, advertising, scanning, connected); it does not return which connections are active. For per-connection state, track connection and disconnect events and maintain the list in the application.

• Connections can be terminated using rsi_ble_disconnect().

Memory Considerations:

• Each connection consumes memory for connection state, buffers, and GATT data.

• Connection limits may be reduced if extended advertising or other memory-intensive features are used.

• System configuration determines the maximum number of supported connections.

Note: For specific connection limits for your configuration, see the WiSeConnect SDK documentation or contact Silicon Labs support.

Advertising Set Limits#

BLE 5.0 introduced the concept of advertising sets, allowing multiple independent advertising configurations. The SiWx917 supports extended advertising with multiple advertising sets.

Advertising Set Support#

Maximum Advertising Sets:

• The maximum number of extended advertising (AE) sets is configurable at build time but capped at 2 on SiWx917 (for example, through SL_SI91X_BLE_AE_MAX_ADV_SETS(num_adv_sets); see APIs Used in This Section at the end of this page). An AE set can be configured for legacy or extended advertising; rsi_ble_start_advertising() is a separate single-instance API for legacy advertising when you are not using the set-based path (see Legacy Advertising below).

• At runtime, use rsi_ble_get_max_no_of_supp_adv_sets() to get the effective number of supported advertising sets (as configured by the operating mode). Always use this API to confirm the value in your build.

• Maximum advertising data length per set can be queried with rsi_ble_get_max_adv_data_len() (see Extended advertising).

Note: The WiSeConnect documentation describes AE sets only in the context of extended advertising. For build-specific limits and concurrency behavior, see the WiSeConnect SDK documentation or Silicon Labs support.

Advertising Set Capabilities:

• Each advertising set can have independent:

  • Advertising data

  • Advertising parameters (interval, type, etc.)

  • Random address (for privacy)

  • PHY selection (1M, Coded PHY)

• Advertising sets can be started and stopped independently.

• Multiple advertising sets can be active simultaneously.

Legacy Advertising:

• Legacy advertising (pre-BLE 5.0) uses a single advertising instance.

• Legacy advertising is still supported for backward compatibility.

• Use rsi_ble_start_advertising() for legacy advertising.

Extended Advertising:

• Extended advertising uses advertising sets.

• Use rsi_ble_start_ae_advertising() to start extended advertising on an advertising set.

• See Extended advertising for details on extended advertising.

BLE Stack Initialization#

The BLE stack must be initialized before performing any BLE operations. Initialization configures the stack with required parameters and prepares it for use.

Initialization Sequence#

Prerequisite: Wi-Fi Stack Initialization

All BLE APIs require the Wi-Fi stack to be initialized first. The Wi-Fi initialization function (sl_wifi_init()) must be called before any BLE operations:

1. Wi-Fi Stack Initialization: Initialize the Wi-Fi stack using sl_wifi_init().

   • This initializes the underlying wireless interface and network processor.

   • Required for NCP and SoC/ACP modes (for RCP mode, initialization is driver-based; see Mode-Specific Initialization Details below).

   • Must complete successfully before proceeding to BLE initialization.

2. BLE Stack Initialization: The BLE stack is automatically initialized as part of the Wi-Fi stack initialization.

   • No separate BLE initialization function is required.

   • BLE capabilities are available after successful Wi-Fi initialization.

3. Mode-Specific Setup: Configure mode-specific parameters based on your operating mode.

   • NCP Mode: Configure host interface (UART/SPI) parameters.

   • RCP Mode: Configure HCI interface parameters.

   • SoC/ACP Mode: Configure IPC and shared memory parameters.

4. Feature Configuration: Configure BLE-specific features and limits.

   • Connection limits (see Maximum simultaneous connections).

   • Advertising set limits (see Advertising set limits).

   • Memory allocation for GATT data, connection state, and packet buffers.

   • Feature flags for extended advertising, DLE, and other BLE 5.x features.

5. Callback Registration: Register event callbacks for BLE operations.

   • Basic Callbacks: Register standard callbacks for core BLE functionality. Register the callbacks that match the BLE roles you use (Central, Peripheral, Broadcaster, Observer):

     • Register GAP callbacks using rsi_ble_gap_register_callbacks() for connection, advertising, advertising report, and basic GAP events—these cover all four roles (Central: connection, scan reports; Peripheral: connection, advertising; Broadcaster: advertising; Observer: advertising report).

     • Register GATT callbacks using rsi_ble_gatt_register_callbacks() for GATT client/server operations.

     • Register SMP callbacks using rsi_ble_smp_register_callbacks() for security and pairing events.

   • Extended Callbacks: Register extended callbacks if using the corresponding extended features

     • Register GAP Extended callbacks using rsi_ble_gap_extended_register_callbacks() for remote features and LE more data request events.

     • Register Enhanced GAP Extended callbacks using rsi_ble_enhanced_gap_extended_register_callbacks() for enhanced GAP extended features.

     • Register Extended Advertising callbacks using rsi_ble_adv_ext_events_register_callbacks() for extended advertising events.

     • Register GATT Extended callbacks using rsi_ble_gatt_extended_register_callbacks() for MTU exchange information events.

     • Register L2CAP CBFC callbacks using rsi_ble_l2cap_cbsc_register_callbacks() for connection-oriented channels (if using L2CAP CBFC).

   • Callbacks should be registered before starting BLE operations to ensure no events are missed.

6. Stack Ready: After successful initialization, the stack is ready for following BLE operations.

   • Advertising, scanning, and connection operations can begin

   • GATT server/client operations can be configured.

   • Event callbacks will be delivered for BLE events.

Initialization Pre-Conditions#

All BLE APIs require the following pre-condition:

• sl_wifi_init() must be called successfully before calling any BLE API function.

• This is documented in the API reference for each BLE function.

• Failure to initialize the Wi-Fi stack will result in BLE API calls returning error codes.

Mode-Specific Initialization Details#

SoC/ACP Mode:

• Full BLE stack runs on the Network Processor.

• Application communicates through IPC (Inter-Processor Communication) and shared memory.

• Initialization handled automatically when sl_wifi_init() is called.

• No additional BLE-specific initialization required.

NCP Mode:

• Full BLE stack runs on the Network Processor.

• Application runs on external host MCU (for example, EFR32, STM32).

• Host interface (UART or SPI) must be configured before calling sl_wifi_init().

• Host SDK handles protocol conversion between application and NWP.

• See NCP mode for detailed NCP mode information.

RCP Mode:

• BLE Controller runs on Network Processor, Host stack on external Linux host

• The host uses the Linux driver (for example, SiWT917 RCP driver). Controller initialization is through HCI after the driver is loaded; opermode and interface configuration are done when inserting the driver (for example, through insmod).

• Host stack initialization handled by external host operating system

• See RCP mode for detailed RCP mode information

Callback Registration Guidelines#

Basic Callbacks (Required for most applications):

• rsi_ble_gap_register_callbacks(): Register for core GAP events. Register this for any role you use; the same API covers events for all four BLE roles:

  • Central: Connection/disconnection, advertising and scan response reports, PHY/data length/connection parameter updates

  • Peripheral: Connection/disconnection, advertising-related events, PHY/data length/connection parameter updates

  • Broadcaster: Advertising-related events

  • Observer: Advertising and scan response reports

  • Common: PHY update events, data length update events, connection parameter update events (where applicable)

  Appropriate usage: The API takes 10 callback parameters. For any parameter you do not need, pass NULL. Only the callbacks you pass as non-NULL will be invoked when those events occur.

  Parameters and purpose:

  Parameter	Purpose
  ble_on_adv_report_event	Advertising and scan response reports from scanning. Use when scanning (Central, Observer).
  ble_on_conn_status_event	Legacy connection established. Use when forming or accepting connections (Central, Peripheral).
  ble_on_disconnect_event	Disconnection. Use when you have connections (Central, Peripheral).
  timeout_expired_event	LE ping payload timeout. Use if you use LE Ping / connection monitor (Central, Peripheral).
  ble_on_phy_update_complete_event	PHY update complete. Use when using PHY update (Central, Peripheral).
  ble_on_data_length_update_complete_event	Data length update complete. Use when using DLE (Central, Peripheral).
  ble_on_enhance_conn_status_event	Enhanced connection established (Bluetooth 4.2 or later). Use when using extended/2M/Coded connections (Central, Peripheral).
  ble_on_directed_adv_report_event	Directed advertising report. Use when scanning for directed ads (Central, Observer).
  ble_on_conn_update_complete_event	Connection parameter update complete. Use when updating conn params (Central, Peripheral).
  ble_on_remote_conn_params_request_event	Remote device requested connection parameter change. Use to respond with rsi_ble_conn_param_resp() (typically Central).

  For GAP callback typedef and parameter details, see Callbacks Declarations (bt-low-energy8).

• rsi_ble_gatt_register_callbacks(): Register GATT callbacks. The API takes 23 callback parameters; pass NULL for any you do not need. Only non-NULL callbacks will be invoked.

  Parameters and purpose:

  Parameter	Purpose
  ble_on_profiles_list_resp	Profiles list response.
  ble_on_profile_resp	Profile response.
  ble_on_char_services_resp	Characteristic services response.
  ble_on_inc_services_resp	Included services response.
  ble_on_att_desc_resp	Attribute descriptors response.
  ble_on_read_resp	Response to read requests.
  ble_on_write_resp	Response to write commands.
  ble_on_gatt_event	GATT write events.
  ble_on_gatt_prepare_write_event	GATT prepare write events.
  ble_on_execute_write_event	GATT execute write events.
  ble_on_read_req_event	Read request events.
  ble_on_mtu_event	MTU exchange events.
  ble_on_gatt_error_resp_event	GATT error events.
  ble_on_gatt_desc_val_resp_event	GATT descriptor value events.
  ble_on_profiles_list_event	Profiles list events.
  ble_on_profile_by_uuid_event	Profile by UUID events.
  ble_on_read_by_char_services_event	Read by characteristic services events.
  ble_on_read_by_inc_services_event	Read by included services events.
  ble_on_read_att_value_event	Read attribute value events.
  ble_on_read_resp_event	Read response events.
  ble_on_write_resp_event	Write response events.
  ble_on_indicate_confirmation_event	Indication confirmation events.
  ble_on_prepare_write_resp_event	Prepare write response events.

  Which callbacks you need depends on your GATT role (Client, Server, or both). Use the parameter table above: as GATT client you typically use discovery and read/write response callbacks (ble_on_*_resp*, ble_on_*_event for discovery); as GATT server you typically use read/write request and MTU callbacks (ble_on_read_req_event, ble_on_gatt_event, ble_on_mtu_event, etc.).

  Notification and indication: The server sends notifications and indications through API (for example, rsi_ble_notify_value(), rsi_ble_indicate_value()). The client receives them in the ble_on_gatt_event callback (rsi_ble_on_gatt_write_event_t) with event_id RSI_BLE_EVENT_GATT_NOTIFICATION or RSI_BLE_EVENT_GATT_INDICATION. There is no separate callback parameter for notifications or indications.

  For typedef and parameter details (including event IDs), see Callbacks Declarations (bt-low-energy8).

• rsi_ble_smp_register_callbacks(): Register SMP (security/pairing) callbacks. The API takes 11 callback parameters; pass NULL for any you do not need. Only non-NULL callbacks will be invoked.

  Parameters and purpose:

  Parameter	Purpose
  ble_on_smp_request_event	SMP request callback.
  ble_on_smp_response_event	SMP response callback.
  ble_on_smp_passkey_event	SMP passkey callback.
  ble_on_smp_fail_event	SMP failed callback.
  rsi_ble_on_encrypt_started_event	Encryption enabled callback.
  ble_on_smp_passkey_display_event	SMP passkey display callback.
  ble_sc_passkey_event	Secure Connections passkey callback.
  ble_on_le_ltk_req_event	SMP LTK request callback.
  ble_on_le_security_keys_event	SMP security keys callback.
  ble_on_cli_smp_response_event	Client SMP response callback.
  ble_on_sc_method_event	Secure Connections method callback.

  For SMP callback typedef and parameter details, see Callbacks Declarations (bt-low-energy8).

Extended Callbacks:

• rsi_ble_gap_extended_register_callbacks(): Register for GAP Extended events:

  • Remote features exchange (rsi_ble_on_remote_features_t)

  • LE More Data Request (rsi_ble_on_le_more_data_req_t)

  • Required when using extended connection features

• rsi_ble_enhanced_gap_extended_register_callbacks(): Register for Enhanced GAP Extended features:

  • Uses callback ID-based registration for flexible event handling

  • Required for advanced extended GAP features

• rsi_ble_adv_ext_events_register_callbacks(): Register for Extended Advertising events:

  • Required when using extended advertising (see Extended advertising)

  • Handles extended advertising report events

  • Uses callback ID-based registration

• rsi_ble_gatt_extended_register_callbacks(): Register for GATT Extended events:

  • MTU Exchange Information events (rsi_ble_on_mtu_exchange_info_t)

  • Provides detailed MTU exchange information including initiator information

• rsi_ble_l2cap_cbsc_register_callbacks(): Register for L2CAP Credit-Based Flow Control (CBFC) events.

  • What: L2CAP CBFC provides connection-oriented channels for application data outside GATT, with credit-based flow control on the channel.

  • When: Register only if the application uses L2CAP CBFC. Pass NULL for any callback you do not need.

  • Callbacks (register before opening or accepting a CBFC channel):

    • rsi_ble_on_cbfc_conn_req_event_t — remote CBFC connection request

    • rsi_ble_on_cbfc_conn_complete_event_t — CBFC connection complete

    • rsi_ble_on_cbfc_rx_data_event_t — CBFC data received

    • rsi_ble_on_cbfc_disconn_event_t — CBFC channel disconnected

  • Related APIs: rsi_ble_cbfc_connreq(), rsi_ble_cbfc_connresp(), rsi_ble_cbfc_data_tx(), rsi_ble_cbfc_disconnect()

When to Register Extended Callbacks:

• Register extended callbacks if your application uses:

  • Extended advertising (BLE 5.0+)

  • Enhanced connection features

  • L2CAP connection-oriented channels

  • Advanced MTU exchange features

• Basic callbacks are sufficient for standard BLE 4.x functionality.

• Extended callbacks can be registered alongside basic callbacks.

Initialization Best Practices#

• Early Initialization: Initialize the Wi-Fi stack early in application startup, before any BLE operations.

• Error Checking: Always check return values from sl_wifi_init() and handle initialization errors gracefully.

• Callback Registration: Register all required callbacks before starting BLE operations to ensure no events are missed.

  • Register basic callbacks for core functionality.

  • Register extended callbacks if using the corresponding extended features.

  • Register callbacks in initialization phase, before any BLE operations begin.

• Configuration First: Configure connection limits, advertising sets, and feature flags before starting operations.

• Mode Selection: Choose the appropriate operating mode (NCP/RCP/SoC) based on your application requirements (see Processing modes - mode selection).

• Resource Planning: Allocate sufficient memory and configure limits based on expected number of connections and advertising sets.

Post-Initialization#

After successful initialization:

• Stack is ready for advertising, scanning, and connection operations

• GATT server/client operations can be configured

• Event callbacks will be delivered for BLE events

• Connection and advertising limits are enforced based on configuration

• All BLE 5.4 features are available (subject to configuration)

Note: Initialization parameters and procedures may vary by SDK version and operating mode. See Processing modes for mode-specific initialization details. See your SDK's getting started guide and Developing with WiSeConnect SDK for complete initialization examples.

APIs Used in This Section#

Integration: BLE architecture (overview and limits summary); BLE API reference (aggregated API grouping); Developing with WiSeConnect SDK.