Overview
Whitelist functionality in BLE allows a Peripheral to filter out the Central devices trying to scan or connect with the device. Based on the advertising filter policy selected, the BLE peripheral will give the privilege of scanning or connecting only to the Centrals in whitelist . Whereas for a Central, if filter policy is set ‘whitelist only’, it will process advertisement packets only from the advertisers in the White list. In this example, the device is configured as a Peripheral where you can select the advertising filter policies as well as you can add the devices to whitelist . Adding to whitelist means that only the Central devices that are added to the Peripheral’s whitelist will be able to receive the scan response packet and establish a connection with it.
APIs Used in the Example Project
- Setting advertising filter policy – Using the API wiced_btm_ble_update_advertisement_filter_policy( wiced_bt_ble_advert_filter_policy_t advertising_policy); the device advertising filter policy can be set.
a. This API can be called either before starting the advertisement or while in advertising state.
b. This API takes one parameter which defines the type of advertising policy.
This parameter defines how the scan and connection requests are filtered
- BTM_BLE_ADVERT_FILTER_ALL_CONNECTION_REQ_ALL_SCAN_REQ– Process scan and connect requests from all Central devices.
- BTM_BLE_ADVERT_FILTER_ALL_CONNECTION_REQ_WHITELIST_SCAN_REQ– Process scan requests only from devices in the White List and connect requests from all devices.
- BTM_BLE_ADVERT_FILTER_WHITELIST_CONNECTION_REQ_ALL_SCAN_REQ– Process scan requests from all devices and connect requests only from devices in the White List.
- BTM_BLE_ADVERT_FILTER_WHITELIST_CONNECTION_REQ_WHITELIST_SCAN_REQ– Process scan and connect requests only from devices in the White List.
Check the API details in wiced_bt_ble.h file (Path: /20719-B1_Bluetooth/include/20719/wiced_bt_ble.h)
c. This API is useful when you want to change the advertising filter policy in runtime.
2. Adding device to whitelist - Using the WICED API wiced_bt_ble_update_advertising_white_list(wiced_bool_t add,wiced_bt_device_address_t remote_bda); you can add or remove the devices from whitelist. In current implementation, you can add only two devices to the whitelist using this API. If you want to add more than 2 devices to the device whitelist, then you can use the Vendor specific command. For that use the WICED API wiced_bt_dev_vendor_specific_command with the below parameters. Check the API details in wiced_bt_dev.h (Path: /20719-B1_Bluetooth/include /20719 /wiced_bt_dev.h)
a. Example: If you want to add device address 0x00A050112233 to whitelist, call the API wiced_bt_dev_vendor_specific_command(opcode,param_length,param_buffer,callback); where
i) Opcode : 0xE9 for adding whitelist
ii) param_length : 9 bytes
iii) param_buffer :
- Length : 0x0E
- Address Type : 0x00
- Address : 0x33,0x22,0x11,0x50,0xA0,0x00 ( LSB First )
- Enabling whitelist : 0x04
iv) callback : call back for command complete
b. Make sure you are stopping the advertisement before adding the device to whitelist
3. Removing the device from whitelist: Using the API wiced_bt_ble_update_advertising_white_list(wiced_bool_t add, wiced_bt_device_address_t remote_bda); by passing the first parameter as False , the device can be removed from the whitelist. Note that you should call this API when the connection is down, not in any other BLE states.
4. To get maximum limit of whitelist: Using the API wiced_bt_ble_get_white_list_size(void); you will get the size of whitelist on the controller side. Check the API details in wiced_bt_ble.h file.
Steps for Testing
- Connect the Eval board to PC and load the whitelist project attached below. Refer to the corresponding Kit User Guide for details on programming the firmware.
- Open the teraterm and open peripheral uart port with baud rate 115200bps
- You can see the logs as in Figure 1.
- Press ‘F’ for selecting the filter policy. For verifying ‘connecting from whitelist’ policy, select either 2 or 3
- Press ‘A’ to add the device address to whitelist and enter the device address (12 nibbles of address – MSB first).
- Press ‘S’ for starting advertisement. Device will start advertising with device name as ‘Whitelist_Demo’.
- Open any of BLE client apps (For example open CySmart app in mobile or PC). Try to connect to the device. The central won’t be able to connect, unless its address is what we added in whitelist (‘0x00A050112233’)
- Press ‘D’ to stop advertising.
- Make sure you are stopping the advertisement before adding the next device to whitelist.
- Refer Figure 1 for Debug logs.
Figure 1: Debug logs for Whitelist Demo
