Description
The Bluetooth Low Energy (BLE) GAP Scan API provides a way to initiate and control Bluetooth GAP scans on a BLE device. GAP scans are used to discover nearby BLE devices and gather information about them.
When a GAP scan request is sent a Bluetooth GAP Scan Status - 0xB5 will be received as feedback for the user regarding the state of the Scanner. If the scanner has successfully started, the user will receive Bluetooth GAP Scan Legacy Advertisement Response - 0xB4 frames with beacon information.
The GAP Scan API frame is used to start or stop a Bluetooth GAP scan. It allows for the configuration of six essential fields:
-
Start or Stop the Scan: This value determines whether the scan should start or stop.
-
Duration: The duration value specifies the amount of time, in seconds, for which the GAP scan should run. This value determines how long the BLE device will actively scan for nearby devices.
-
Window and Interval: Use the window and interval to optionally configure the scan duty cycle. The radio will actively scan advertisements during the window duration of every scan interval period.
-
Filter Type: The filter type controls which devices are considered valid scan results. Bluetooth devices transmit the payload using length, type, and value (LTV) format. Therefore, when the filter is enabled, it will filter all advertisements containing Complete Local Name (0x09) and Short Local Name (0x08) types.
-
Filter: The filter value is used in conjunction with the filter type to specify the device(s) to include or exclude from the scan results. The filter only accepts ASCII characters. After the filter is set, the scan will only display advertisements containing the text passed as a filter.
Format
The following table provides the contents of the frame. For details on frame structure, see API frames.
| Offset | Size | Field Name | Description |
|---|---|---|---|
0 |
8-bit |
Start Delimiter |
Indicates the start of an API frame. |
1 |
16-bit |
Length |
Number of bytes between the length and checksum. |
3 |
8-bit |
Frame Type |
Bluetooth Scan Request - 0x34. |
4 |
8-bit |
Start Command |
To start a scan, this value must be set to 0x01. To stop a running scan, this value must be set to 0x00. |
5 |
16-bit |
Scan Duration |
Scan duration should be set to 0x00 - 0xFFFF (x 1 s) (18.20 hrs.). If scan is set to 0x00, the scan will run indefinitely. |
7 |
32-bit |
Scan Window |
The range is from 0x9C4 - 0x270FD8F (x 1 us) (41 s). The window cannot be bigger than the scan interval. |
11 |
32-bit |
Scan Intervals |
The range is from 0x9C4 - 0x270FD8F (x 1 us) (41 s). The interval cannot be smaller than the scan window. |
15 |
8-bit |
Filter Type |
Supported Filter Types:
|
16-n |
variable |
Filter ID (optional) |
The range for the Filter ID is from 0-22 bytes; it can only accept up to 22 characters. |
EOF |
8-bit |
Checksum |
0xFF minus the 8-bit sum of bytes from offset 3 to this byte (between length and checksum). |
Examples
Each example is written without escapes (AP = 1) and all bytes are represented in hex format. For brevity, the start delimiter, length, and checksum fields have been excluded.
Start Bluetooth scanner without filtering responses
The request will start the scanner with the following parameters:
-
Duration: 10 seconds
-
Window: 11.25 milliseconds
-
Interval: 1.28 seconds
7E 00 0D 34 01 00 0A 00 00 2B F2 00 13 88 00 00 08
| Frame Type | Starts Command | Scan Duration | Scan Window | Scan Interval | Filter Type |
|---|---|---|---|---|---|
0x34 |
0x01 |
0x000A |
0x0002BF2 |
0x00138800 |
0x00 |
Request |
Start Scan |
10s |
11250 us |
128000 us |
No filtering |
Start Bluetooth scanner with filtering responses
The request will start the scanner with the following parameters:
-
Duration: 10 seconds
-
Window: 11.25 milliseconds
-
Interval: 1.28 seconds
-
Filter ID: Tester
7E 00 13 34 01 00 0A 00 00 2B F2 00 13 88 00 01 54 65 73 74 65 72 90
| Frame Type | Starts Command | Scan Duration | Scan Window | Scan Interval | Filter Type | Filter |
|---|---|---|---|---|---|---|
0x34 |
0x01 |
0x000A |
0x0002BF2 |
0x00138800 |
0x546573746572 |
0x546573746572 |
Request |
Start Scan |
10s |
11250 us |
128000 ux |
Filtering |
"Tester" |
Stop Bluetooth scanner
The request will stop the scanner. This option is useful if the user manually stops the scanner.
7E 00 0D 34 00 00 00 00 00 00 00 00 00 00 00 00 CB
| Frame Type | Starts Command | Scan Duration | Scan Window | Scan Interval | Filter Type |
|---|---|---|---|---|---|
0x34 |
0x00 |
0x0000 |
0x00000000 |
0x00000000 |
0x00 |
Request |
Stop Scan |
None |
None |
None |
None |
