Whitelisting#

Introduction#

Whitelisting filters devices based on a list of Bluetooth addresses on both central and peripheral side. If whitelisting occurs on the central side, scan results and connecting to non-whitelisted devices are dropped. If whitelisting occurs on the peripheral side, only whitelisted devices can connect and receive scan responses.

This feature was introduced in Bluetooth SDK version 2.11 and, as of right now, it only supports the central side whitelisting. However, it allows connecting to non-whitelisted devices if their Bluetooth address is known by the application.

The whitelist size matches the maximum number of bonded devices configuration, which can be modified with the command sm_store_bonding_configuration. If the maximum number of bonded devices is modified when using the feature, reset the device before using the new setting.

Although bonded devices are automatically added to the whitelist, they can also be added manually as described later in this document.

Whitelisting currently supports public and static random Bluetooth addresses, which means that devices using resolvable random addresses will not be visible during scanning if whitelisting is enabled. Additionally, if a device using static random decides to change the address after a power cycle this will blacklist the device.

Note: Because most phones running Android platform or iOS use resolvable random addresses, this feature effectively puts phones on blacklist during device discovery.

Using Whitelisting#

To add the whitelisting feature to your application, follow the instructions below. For details about command parameters, see the Bluetooth Software API Reference Manual.

Feature Initialization#

After initialization, the application can enable whitelisting. By default, this feature is not initialized in the stack and must be explicitly enabled with the initialization function below.

gecko_init_whitelisting()

Enable/Disable Whitelisting#

Enabling or disabling whitelisting can be done at run-time but it will not take effect when an active scan request is on-going, only after the scan is stopped and restarted. Enable whitelisting using the command below.

gecko_cmd_le_gap_enable_whitelisting(uint8 enable)

Adding Devices Manually to the Whitelist#

To add devices to the whitelist, use the command below.

gecko_cmd_sm_add_to_whitelist(bd_addr address,uint8 address_type)

Delete the Bonding or Whitelist of a Device#

Because bonded devices are automatically added to the whitelist, deleting the bonds will also automatically remove them from the whitelist. This is done with the command below.

gecko_cmd_sm_delete_bonding(uint8 bonding)

Delete all Bondings and the Complete Whitelist#

The command below deletes all bondings and clears the entire whitelist, including devices which were added manually.

gecko_cmd_sm_delete_bondings()

Test Setup#

Two devices (WSTK radio boards) are used to demonstrate this feature.

Device 1: A radio board running the SoC - Empty example. This program advertises using the name Empty Example and the Bluetooth address used in the advertisement is public. In Simplicity Studio IDE, select the board and flash the SoC - Empty example from the demo section. Alternatively, use any device which is advertising using a public Bluetooth address.

Device 2: A radio board running a modified version of NCP Empty example. In Simplicity Studio IDE, create a project with the NCP Empty example from the Software Examples section on the Launcher tab. In main.c insert the whitelisting initialization function as shown here, then build, and flash the project to the radio board.

  // Initialize stack
  gecko_init(&config);

  // Initialize NCP USART
  ncp_usart_init();

  //Initialize whitelisting
  gecko_init_whitelisting(); // -> Add this command

  while (1) {
    struct gecko_cmd_packet *evt;

Open the BGTool UI from Compatible Tools on the launcher tab. Connect to the NCP device using the appropriate COM port. Click Start under Discover to start scanning. A list of advertising devices along with their addresses will populate as shown in this figure. Note the address of Device 1 or the device which you want to whitelist. Stop scanning.

imgimg

In the command prompt execute the following commands, one at a time. Replace the Bluetooth address with the address of the device you want to whitelist.

gecko_cmd_le_gap_enable_whitelisting(1)
gecko_cmd_sm_add_to_whitelist(d0:cf:5e:d8:89:95,0)

Start scanning again. You will only see the device which was whitelisted, as shown in the figure below. Also, notice a bonding handle assigned to the whitelisted device. Use the delete bonding command mentioned above to remove devices from the whitelist.

imgimg