bt_scan_filter_add()

Description

Sets a filter for the Bluetooth scanner.

Syntax

bt_scan_filter_add(filter_type, filter_array[], filter_len);

Parameters

Variable	Input

Variable

Input

filter_type

BT_SCAN_FILTER_TYPE_NAME - for adding name filter.

BT_SCAN_FILTER_TYPE_SHORT_NAME - for adding short name filter.

BT_SCAN_FILTER_TYPE_ADDR_PUBLIC - for adding public MAC address filter.

BT_SCAN_FILTER_TYPE_ADDR_RANDOM - for adding random MAC address filter.

BT_SCAN_FILTER_TYPE_UUID - for adding UUID filter.

BT_SCAN_FILTER_TYPE_APPEARANCE - for adding appearance filter.

BT_SCAN_FILTER_TYPE_MANUFACTURER_DATA - for adding manufacturer data filter.

BT_SCAN_FILTER_TYPE_PATTERN - for adding a pattern filter.

filter_array[]

The array which contains the desired filter.

filter_len

Length of your filter.

Filter name	Filter description	Length	Filter example

Filter name	Filter description	Length	Filter example
Name filter	Complete local name data type (0x09) filter allows scanning for devices with a specific local name. The local name is a user-friendly, human-readable string that a Bluetooth device broadcasts in its advertising packets.	1-29	`name_filter[] = ''P T EN 80CB7B'';`
Short name filter	Shortened local name data type (0x08) filter is similar to name filter, but it targets a different data type. Bluetooth devices may broadcast a shorter version of their name to save space in advertising packets.	1-29	`short_name_filter[] = ''P T EN 80CB7B'';`
Public address filter	This filter targets devices with a public Bluetooth Device Address (BD_ADDR). Public addresses are globally unique and assigned by the IEEE Registration Authority. This filter does not correspond to any of the standard Bluetooth data types as addresses are not included in the Bluetooth data packet. Public address has two fields: Company assigned value (24 bits). Company ID (24 bits).	6	`address_filter[MAC_ADDR_SIZE] = [0x12, 0x34, 0x56, 0xAB, 0xCD, 0xEF];`
Random address filter	This filter targets devices with a random Bluetooth Device Address (BD_ADDR). Random addresses are either static (unchanging) or resolvable (periodically changing for privacy). This filter does not correspond to any of the standard Bluetooth data types as addresses are not included in the Bluetooth data packet.	6	`address_filter[MAC_ADDR_SIZE] = [0xFF, 0x48, 0x80, 0x33, 0xE3, 0xA8];`
UUID filter	This filter targets devices advertising a specific Universally Unique Identifier (UUID). UUIDs represent services or characteristics offered by a Bluetooth device. Supported Bluetooth data types: Incomplete List of 16-bit Service Class UUIDs (0x02) Complete List of 16-bit Service Class UUIDs (0x03) Incomplete List of 32-bit Service Class UUIDs (0x04) Complete List of 32-bit Service Class UUIDs (0x05) Incomplete List of 128-bit Service Class UUIDs (0x06) Complete List of 128-bit Service Class UUIDs (0x07) The "incomplete" lists indicate that the device has more UUIDs than it has listed. The "complete" lists indicate that all of the device's UUIDs of that size are included. Note: UUIDs are written in big-endian format.	2 (16 bit) 4 (32 bit) 16 (128 bit)	Google/Eddystone 16-bit UUID: 0xFEAA `eddystone_filter[2] = [0xFE, 0xAA];` Custom 32-bit UUID: 0x12345678 `custom_uuid_32[4] = [0x12, 0x34, 0x56, 0x78];` Custom 128-bit UUID: 12345678-9abc-def1-2345-6789abcdef12 `custom_uuid_128[16] = [0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF1, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF, 0x12];`
Appearance filter	Appearance data type (0x19) filter targets devices based on their appearance category. The appearance indicates the device's general type (e.g., watch, keyboard, heart rate sensor). Refer to the https://www.bluetooth.com/specifications/assigned-numbers/ to find all possible appearance values. Note: Appearance filter is written in big-endian format.	2	Generic tag appearance ID from the Bluetooth specification: 0x0200 `new appearance_filter[2] = [0x02, 0x00];`
Manufacturer data filter	Manufacturer specific data type (0xFF) filter targets devices based on their manufacturer-specific data. This allows for filtering based on proprietary information broadcast by the device. This data type and filter has two parts: Manufacturer ID - 16-bit UUID representing the company ID assigned by the Bluetooth SIG. Manufacturer data - data following the Manufacturer ID. The filter value must be written in sequence - there can be no bytes in the Bluetooth packet between the manufacturer ID and manufacturer data. Note: Manufacturer ID is written in little-endian format.	1-29	iBeacon example: Apple company ID according to the Bluetooth specification: 0x004C (big endian) `manufacturer_data_filter[3] = [0x4C, 0x00, 0x02];`
Pattern filter	This software filter does not correspond to any data type. It will match any data that is in a sequence in the Bluetooth advertising indication or scan response packet. Filter can be written as ASCII string or hex array. Best used for: Filter multiple beacons of the same type and same name format (i.e. “bt_beacon_xx”, where “xx” is the unique ID). When other filter types are not applicable for the specific data type (i.e. service data (0x16) data type). A sequence in the middle of the data type needs to be matched (i.e. beacon identification is in the middle of the manufacturer data but cannot be filtered with manufacturer data filter). To get a callback when a specific value is reached. Note: This filter is only available from *_01_134 device firmware and 2.2.1** Bluetooth firmware	1-31	Example Bluetooth payload with the `P T EN 80CB71` name : 02 01 06 05 16 6E 2A 74 09 0E 09 50 20 54 20 45 4E 20 38 30 43 42 37 31 Example name fragment (in green) pattern filters to capture multiple sensors with similar name: `pattern_filter[] = ''T EN 80CB'';` `pattern_filter[9] = [0x54, 0x20, 0x45, 0x4E, 0x20, 0x38, 0x30, 0x43, 0x42];` Example data fragment for temperature service data UUID (in blue) for pattern filter: `pattern_filter_temperature[4] = [0x05, 0x16, 0x6E, 0x2A];`

Returns

Return value	Return explanation
SCRIPT_OPERATION_SUCCESS	Successfully added filter.
SCRIPT_OPERATION_FAILED	Failed to add filter. Check if the function arguments are correct or the maximum filter limit is reached.
SCRIPT_PARAM_INVALID	Given filter length is bigger than the maximum (31) or is equal to 0.

Notes and Warnings

Prior to adding a filter, it is necessary to initialize the scan module.
Filtering is limited to 10 unique filters.

Function call example

The code initializes Bluetooth module, initializes scan module and sets new MAC filter for scanning:

#include <io>
#include <read>
#include <float>
#include <string>
#include <core>
#include <write>
#include <define>
#include <socket>
#include <bluetooth>

new scan_parameters[.type, .options, .interval, .window, .timeout, .interval_coded, .window_coded];
new mac_addr_filter[] = [0xFF, 0x48, 0x80, 0x33, 0xE3, 0xA8];

main()
{
    scan_parameters[.type] = BT_SCAN_TYPE_ACTIVE;
    scan_parameters[.options] = BT_ADV_OPT_NONE;
    scan_parameters[.interval] = BT_SCAN_INTERVAL_FAST;
    scan_parameters[.window] = BT_SCAN_WINDOW_FAST;
    scan_parameters[.timeout] = 0;
    scan_parameters[.interval_coded] = 0;
    scan_parameters[.window_coded] = 0;
    
    bt_init();
    bt_scan_init(scan_parameters);
    bt_scan_filter_add(BT_SCAN_FILTER_TYPE_ADDR_PUBLIC, mac_addr_filter, sizeof(mac_addr_filter));
    for(;;)
    {
        Delay(100);
    }
}

The code initializes Bluetooth module, initializes scan module and sets new name filter for scanning:

#include <io>
#include <read>
#include <float>
#include <string>
#include <core>
#include <write>
#include <define>
#include <socket>
#include <bluetooth>

new scan_parameters[.type, .options, .interval, .window, .timeout, .interval_coded, .window_coded];
new name_filter[] = ''P T EN 80CB7B'';

main()
{
    scan_parameters[.type] = BT_SCAN_TYPE_ACTIVE;
    scan_parameters[.options] = BT_ADV_OPT_NONE;
    scan_parameters[.interval] = BT_SCAN_INTERVAL_FAST;
    scan_parameters[.window] = BT_SCAN_WINDOW_FAST;
    scan_parameters[.timeout] = 0;
    scan_parameters[.interval_coded] = 0;
    scan_parameters[.window_coded] = 0;
    
    bt_init();
    bt_scan_init(scan_parameters);
    bt_scan_filter_add(BT_SCAN_FILTER_TYPE_NAME, name_filter, strlen(name_filter));
    for(;;)
    {
        Delay(100);
    }
}