Accept List#

Introduction#

Connection Accept List (old terminology: whitelisting) filters devices based on a list of Bluetooth addresses on both central and peripheral side. If accept list is on the central side, scan results from non-listed devices are dropped and connecting to non-listed devices is not enabled. If accept list is on the peripheral side, only listed devices can connect and receive scan responses (scan requests and connection requests from non-listed devices are dropped).

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

The list size matches the maximum number of bonded devices configuration, which can be modified with the command sl_bt_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 accept list, they can also be added manually as described later in this document.

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

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

Using Accept List#

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

Adding the Feature#

By default, this feature is not included in the stack and the Whitelisting software component must be installed to get it work:

This will also add the initialization function to the stack init.

Enable/Disable Accept List#

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

sl_bt_gap_enable_whitelisting(uint8 enable)

Adding Devices Manually to the Accept List#

To add devices to the accept list, use the command below.

sl_bt_sm_add_to_whitelist(bd_addr address, uint8_t address_type)

Removing the Device from the Accept List#

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

sl_bt_sm_delete_bonding(uint8_t bonding)

Erasing the Complete Accept List#

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

sl_bt_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. 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. Add the Whitelisting software component to the project in the Software Components view, then build, and flash the project to the radio board.

Open the NCP Commander from the Tools Dialog. Connect to the NCP device. Click Start under Discover to start scanning. A list of advertising devices along with their addresses will populate, as shown in this figure. Make a note of the address of Device 1 or the device which you want to add to the accept list. Stop scanning.

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 add to the accept list.

sl_bt_gap_enable_whitelisting(1)
sl_bt_sm_add_to_whitelist(12:90:78:56:34:12, 0)

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