Scanner#

Scanner.

This is the scanning feature that is brought in when the application includes a software component for the scanning functionality. The functionality differences are listed below for various component inclusion scenario:

  • The bluetooth_feature_scanner component is included but neither bluetooth_feature_legacy_scanner nor bluetooth_feature_extended_scanner is included:

    • The scanner can scan advertising devices that use legacy or extended advertising PDUs.

    • The sl_bt_evt_scanner_scan_report event is used to report the received advertisements.

  • The bluetooth_feature_legacy_scanner component is included but the bluetooth_feature_extended_scanner is not:

  • The bluetooth_feature_extended_scanner component is included:

  • Either the bluetooth_feature_legacy_scanner or bluetooth_feature_extended_scanner component is included:

Modules#

Event Type Flags of Advertisement Reports

sl_bt_evt_scanner_legacy_advertisement_report

sl_bt_evt_scanner_extended_advertisement_report

sl_bt_evt_scanner_scan_report

Enumerations#

enum
sl_bt_scanner_discover_limited = 0x0
sl_bt_scanner_discover_generic = 0x1
sl_bt_scanner_discover_observation = 0x2
}

These values indicate which Bluetooth discovery mode to use when scanning for advertising devices.

enum
sl_bt_scanner_scan_mode_passive = 0x0
sl_bt_scanner_scan_mode_active = 0x1
}

The scanning modes.

enum
sl_bt_scanner_scan_phy_1m = 0x1
sl_bt_scanner_scan_phy_coded = 0x4
sl_bt_scanner_scan_phy_1m_and_coded = 0x5
}

The enum defines the scanning PHYs.

enum
sl_bt_scanner_data_status_complete = 0x0
sl_bt_scanner_data_status_incomplete_more = 0x1
sl_bt_scanner_data_status_incomplete_nomore = 0x2
}

Defines the data completeness status types of an advertisement reported by the scanner.

enum
sl_bt_scanner_filter_policy_basic_unfiltered = 0x0
sl_bt_scanner_filter_policy_basic_filtered = 0x1
sl_bt_scanner_filter_policy_extended_unfiltered = 0x2
sl_bt_scanner_filter_policy_extended_filtered = 0x3
}

The scanning filter policy setting determines which advertisements and scan responses are delivered to the application when scanning. See the Bluetooth Core specification Volume 6, Part B, Section 4.3.3 "Scanning filter policy" for a detailed description of this setting.

Functions#

sl_status_t
sl_bt_scanner_set_parameters(uint8_t mode, uint16_t interval, uint16_t window)
sl_status_t
sl_bt_scanner_set_parameters_and_filter(uint8_t mode, uint16_t interval, uint16_t window, uint32_t flags, uint8_t filter_policy)
sl_status_t
SL_BGAPI_DEPRECATED sl_status_t
sl_bt_scanner_set_timing(uint8_t phys, uint16_t scan_interval, uint16_t scan_window)
SL_BGAPI_DEPRECATED sl_status_t
sl_bt_scanner_set_mode(uint8_t phys, uint8_t scan_mode)
sl_status_t
sl_bt_scanner_start(uint8_t scanning_phy, uint8_t discover_mode)

Enumeration Documentation#

sl_bt_scanner_discover_mode_t#

sl_bt_scanner_discover_mode_t

These values indicate which Bluetooth discovery mode to use when scanning for advertising devices.

Enumerator
sl_bt_scanner_discover_limited

(0x0) Discover only limited discoverable devices.

sl_bt_scanner_discover_generic

(0x1) Discover limited and general discoverable devices.

sl_bt_scanner_discover_observation

(0x2) Discover non-discoverable, limited and general discoverable devices.


Definition at line 3654 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_scanner_scan_mode_t#

sl_bt_scanner_scan_mode_t

The scanning modes.

Enumerator
sl_bt_scanner_scan_mode_passive

(0x0) Passive scanning mode where the device only listens to advertising packets and does not transmit packets

sl_bt_scanner_scan_mode_active

(0x1) Active scanning mode where the device sends out a scan request packet upon receiving a scannable advertising packet from a remote device and listens to the scan response packet from the remote device


Definition at line 3668 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_scanner_scan_phy_t#

sl_bt_scanner_scan_phy_t

The enum defines the scanning PHYs.

Enumerator
sl_bt_scanner_scan_phy_1m

(0x1) Initiate the scanning on the 1M PHY

sl_bt_scanner_scan_phy_coded

(0x4) Initiate the scanning on the Coded PHY

sl_bt_scanner_scan_phy_1m_and_coded

(0x5) Simultaneous scanning by initiating the scanning on the 1M and Coded PHY alternatively


Definition at line 3686 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_scanner_data_status_t#

sl_bt_scanner_data_status_t

Defines the data completeness status types of an advertisement reported by the scanner.

Enumerator
sl_bt_scanner_data_status_complete

(0x0) All data of the advertisement has been reported.

sl_bt_scanner_data_status_incomplete_more

(0x1) Data of the advertisement is incomplete in this event, and more data will come in new events.

sl_bt_scanner_data_status_incomplete_nomore

(0x2) Data of the advertisement is incomplete in this event, but no more data will come, i.e., the data of the advertisement is truncated.


Definition at line 3701 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_scanner_filter_policy_t#

sl_bt_scanner_filter_policy_t

The scanning filter policy setting determines which advertisements and scan responses are delivered to the application when scanning. See the Bluetooth Core specification Volume 6, Part B, Section 4.3.3 "Scanning filter policy" for a detailed description of this setting.

Note that some filter policies require the application to include additional Bluetooth feature components. Filter policies that use the Filter Accept List require that the application has included the bluetooth_feature_accept_list component. Filter policies that require the Bluetooth controller to resolve a Resolvable Private Address require that the application has included the bluetooth_feature_resolving_list component.

Enumerator
sl_bt_scanner_filter_policy_basic_unfiltered

(0x0) Advertising and scan response PDUs are processed from all devices. For directed advertising, the target address must additionally match the identity address of the local device or be a Resolvable Private Address that is resolved to the local device by the Bluetooth controller.

sl_bt_scanner_filter_policy_basic_filtered

(0x1) Advertising and scan response PDUs are processed only from devices that the application has added to the Filter Accept List. For directed advertising, the target address must additionally match the identity address of the local device or be a Resolvable Private Address that is resolved to the local device by the Bluetooth controller.

sl_bt_scanner_filter_policy_extended_unfiltered

(0x2) Advertising and scan response PDUs are processed from all devices. For directed advertising, the target address must additionally match the identity address of the local device or be any Resolvable Private Address.

sl_bt_scanner_filter_policy_extended_filtered

(0x3) Advertising and scan response PDUs are processed only from devices that the application has added to the Filter Accept List. For directed advertising, the target address must additionally match the identity address of the local device or be any Resolvable Private Address.


Definition at line 3735 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

Function Documentation#

sl_bt_scanner_set_parameters#

sl_status_t sl_bt_scanner_set_parameters (uint8_t mode, uint16_t interval, uint16_t window)
Parameters
[in]mode

Enum sl_bt_scanner_scan_mode_t.

Passive or active scan. Values:

  • sl_bt_scanner_scan_mode_passive (0x0): Passive scanning mode where the device only listens to advertising packets and does not transmit packets

  • sl_bt_scanner_scan_mode_active (0x1): Active scanning mode where the device sends out a scan request packet upon receiving a scannable advertising packet from a remote device and listens to the scan response packet from the remote device

Default value: sl_bt_scanner_scan_mode_passive.

[in]interval

The time interval when the device starts its last scan until it begins the subsequent scan. In other words, how often to scan

  • Time = Value x 0.625 ms

  • Range: 0x0004 to 0xFFFF

  • Time Range: 2.5 ms to 40.96 s

Default value: 10 ms

A variable delay occurs when switching channels at the end of each scanning interval, which is included in the scanning interval time. During the switch time, advertising packets are not received by the device. The switch time variation is use case dependent. For example, if scanning while keeping active connections, the channel switch time might be longer than when scanning without any active connections. Increasing the scanning interval reduces the amount of time in which the device can't receive advertising packets because it switches channels less often.

After every scan interval, the scanner changes the frequency at which it operates. It cycles through all three advertising channels in a round robin fashion. According to the specification, all three channels must be used by a scanner.

[in]window

The scan window, i.e., the duration of the scan, which must be less than or equal to the interval

  • Time = Value x 0.625 ms

  • Range: 0x0004 to 0xFFFF

  • Time Range: 2.5 ms to 40.96 s

Default value: 10 ms

Note that the packet reception is aborted if it's started just before the scan window ends.

Set scan parameters for subsequent scanning operations. If the device is currently scanning, new parameters will take effect when scanning is restarted.

This command sets the scanning filter policy to the default value sl_bt_scanner_filter_policy_basic_unfiltered. Use the command sl_bt_scanner_set_parameters_and_filter to set a specific scanning filter policy.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4319 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_scanner_set_parameters_and_filter#

sl_status_t sl_bt_scanner_set_parameters_and_filter (uint8_t mode, uint16_t interval, uint16_t window, uint32_t flags, uint8_t filter_policy)
Parameters
[in]mode

Enum sl_bt_scanner_scan_mode_t.

Passive or active scan. Values:

  • sl_bt_scanner_scan_mode_passive (0x0): Passive scanning mode where the device only listens to advertising packets and does not transmit packets

  • sl_bt_scanner_scan_mode_active (0x1): Active scanning mode where the device sends out a scan request packet upon receiving a scannable advertising packet from a remote device and listens to the scan response packet from the remote device

Default value: sl_bt_scanner_scan_mode_passive.

[in]interval

The time interval when the device starts its last scan until it begins the subsequent scan. In other words, how often to scan

  • Time = Value x 0.625 ms

  • Range: 0x0004 to 0xFFFF

  • Time Range: 2.5 ms to 40.96 s

Default value: 10 ms

A variable delay occurs when switching channels at the end of each scanning interval, which is included in the scanning interval time. During the switch time, advertising packets are not received by the device. The switch time variation is use case dependent. For example, if scanning while keeping active connections, the channel switch time might be longer than when scanning without any active connections. Increasing the scanning interval reduces the amount of time in which the device can't receive advertising packets because it switches channels less often.

After every scan interval, the scanner changes the frequency at which it operates. It cycles through all three advertising channels in a round robin fashion. According to the specification, all three channels must be used by a scanner.

[in]window

The scan window, i.e., the duration of the scan, which must be less than or equal to the interval

  • Time = Value x 0.625 ms

  • Range: 0x0004 to 0xFFFF

  • Time Range: 2.5 ms to 40.96 s

Default value: 10 ms

Note that the packet reception is aborted if it's started just before the scan window ends.

[in]flags

No flags are currently defined. Set this parameter to 0.

[in]filter_policy

Enum sl_bt_scanner_filter_policy_t.

The scanning filter policy to use when scanning is started. The filter policy determines which advertisements and scan responses are delivered to the application. Values:

  • sl_bt_scanner_filter_policy_basic_unfiltered (0x0): Advertising and scan response PDUs are processed from all devices. For directed advertising, the target address must additionally match the identity address of the local device or be a Resolvable Private Address that is resolved to the local device by the Bluetooth controller.

  • sl_bt_scanner_filter_policy_basic_filtered (0x1): Advertising and scan response PDUs are processed only from devices that the application has added to the Filter Accept List. For directed advertising, the target address must additionally match the identity address of the local device or be a Resolvable Private Address that is resolved to the local device by the Bluetooth controller.

  • sl_bt_scanner_filter_policy_extended_unfiltered (0x2): Advertising and scan response PDUs are processed from all devices. For directed advertising, the target address must additionally match the identity address of the local device or be any Resolvable Private Address.

  • sl_bt_scanner_filter_policy_extended_filtered (0x3): Advertising and scan response PDUs are processed only from devices that the application has added to the Filter Accept List. For directed advertising, the target address must additionally match the identity address of the local device or be any Resolvable Private Address.

Default value: sl_bt_scanner_filter_policy_basic_unfiltered

Set scan parameters and the scanning filter policy for subsequent scanning operations. If the device is currently scanning, new parameters will take effect when scanning is restarted.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4413 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_scanner_stop#

sl_status_t sl_bt_scanner_stop ()

Stop scanning for advertising devices. For more information about the discovery, see the sl_bt_scanner_start command.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4428 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_scanner_set_timing#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_scanner_set_timing (uint8_t phys, uint16_t scan_interval, uint16_t scan_window)
Parameters
[in]phys

Enum sl_bt_scanner_scan_phy_t. The scanning PHY(s) the setting is set for. Values:

  • sl_bt_scanner_scan_phy_1m (0x1): 1M PHY

  • sl_bt_scanner_scan_phy_coded (0x4): Coded PHY

  • sl_bt_scanner_scan_phy_1m_and_coded (0x5): 1M and Coded PHYs

[in]scan_interval

Scan interval is defined as the time interval when the device starts its last scan until it begins the subsequent scan. In other words, how often to scan

  • Time = Value x 0.625 ms

  • Range: 0x0004 to 0xFFFF

  • Time Range: 2.5 ms to 40.96 s

Default value: 10 ms

A variable delay occurs when switching channels at the end of each scanning interval, which is included in the scanning interval time. During the switch time, advertising packets are not received by the device. The switch time variation is use case-dependent. For example, if scanning while keeping active connections, the channel switch time might be longer than when scanning without any active connections. Increasing the scanning interval reduces the amount of time in which the device can't receive advertising packets because it switches channels less often.

After every scan interval, the scanner changes the frequency at which it operates. It cycles through all three advertising channels in a round robin fashion. According to the specification, all three channels must be used by a scanner.

[in]scan_window

Scan window defines the duration of the scan which must be less than or equal to the scan_interval

  • Time = Value x 0.625 ms

  • Range: 0x0004 to 0xFFFF

  • Time Range: 2.5 ms to 40.96 s

Default value: 10 ms Note that the packet reception is aborted if it's started just before the scan window ends.

Deprecated and replaced by the sl_bt_scanner_set_parameters command.

Set the scanning timing parameters on the specified PHY(s). If the device is currently scanning, new parameters will take effect when scanning is restarted.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4482 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_scanner_set_mode#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_scanner_set_mode (uint8_t phys, uint8_t scan_mode)
Parameters
[in]phys

Enum sl_bt_scanner_scan_phy_t. The scanning PHY(s) the setting is set for. Values:

  • sl_bt_scanner_scan_phy_1m (0x1): 1M PHY

  • sl_bt_scanner_scan_phy_coded (0x4): Coded PHY

  • sl_bt_scanner_scan_phy_1m_and_coded (0x5): 1M and Coded PHYs

[in]scan_mode

Enum sl_bt_scanner_scan_mode_t.

The scan mode. Values:

  • sl_bt_scanner_scan_mode_passive (0x0): Passive scanning mode where the device only listens to advertising packets and does not transmit packets

  • sl_bt_scanner_scan_mode_active (0x1): Active scanning mode where the device sends out a scan request packet upon receiving a scannable advertising packet from a remote device and listens to the scan response packet from the remote device

Default value: sl_bt_scanner_scan_mode_passive.

Deprecated and replaced by the sl_bt_scanner_set_parameters command.

Set the scan mode on the specified PHY(s). If the device is currently scanning, new parameters will take effect when scanning is restarted.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4517 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_scanner_start#

sl_status_t sl_bt_scanner_start (uint8_t scanning_phy, uint8_t discover_mode)
Parameters
[in]scanning_phy

Enum sl_bt_scanner_scan_phy_t.

The scanning PHY(s).

In simultaneous scanning, the stack alternates the scanning on two PHYs by switching the PHY at every scan interval. When a timing parameter is set differently on 1M and Coded PHY, the stack chooses the most relaxed value for both PHYs during simultaneous scanning, i.e., the largest scan interval or the smallest scan window. If one PHY is set to passive scanning and the other to active scanning, passive scanning is chosen for simultaneous scanning. Values:

  • sl_bt_scanner_scan_phy_1m (0x1): Initiate the scanning on the 1M PHY

  • sl_bt_scanner_scan_phy_coded (0x4): Initiate the scanning on the Coded PHY

  • sl_bt_scanner_scan_phy_1m_and_coded (0x5): Simultaneous scanning by initiating the scanning on the 1M and Coded PHY alternatively

[in]discover_mode

Enum sl_bt_scanner_discover_mode_t. Bluetooth discovery Mode. Values:

  • sl_bt_scanner_discover_limited (0x0): Discover only limited discoverable devices.

  • sl_bt_scanner_discover_generic (0x1): Discover limited and general discoverable devices.

  • sl_bt_scanner_discover_observation (0x2): Discover non-discoverable, limited and general discoverable devices.

Start the GAP discovery procedure to scan for advertising devices that use legacy or extended advertising PDUs. To cancel an ongoing discovery procedure, use the sl_bt_scanner_stop command.

The invalid parameter error will be returned if the value of scanning PHYs is invalid or the device does not support a PHY.

Received advertising packets are not filtered in any way, so multiple events will be received for every advertising device in range.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events

  • sl_bt_evt_scanner_scan_report - This event is triggered for reporting a received advertisement if the application includes the bluetooth_feature_scanner component but does not include any other scanner component.

  • sl_bt_evt_scanner_legacy_advertisement_report - This event is triggered for reporting a received advertisement that uses legacy advertising PDUs if the application includes the bluetooth_feature_legacy_scanner or bluetooth_feature_extended_scanner component.

  • sl_bt_evt_scanner_extended_advertisement_report - This event is triggered for reporting a received advertisement that uses extended advertising PDUs if the application includes the bluetooth_feature_extended_scanner component.


Definition at line 4577 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

Macro Definition Documentation#

sl_bt_cmd_scanner_set_parameters_id#

#define sl_bt_cmd_scanner_set_parameters_id
Value:
0x06050020

Definition at line 3637 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_scanner_set_parameters_and_filter_id#

#define sl_bt_cmd_scanner_set_parameters_and_filter_id
Value:
0x07050020

Definition at line 3638 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_scanner_stop_id#

#define sl_bt_cmd_scanner_stop_id
Value:
0x05050020

Definition at line 3639 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_scanner_set_timing_id#

#define sl_bt_cmd_scanner_set_timing_id
Value:
0x01050020

Definition at line 3640 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_scanner_set_mode_id#

#define sl_bt_cmd_scanner_set_mode_id
Value:
0x02050020

Definition at line 3641 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_scanner_start_id#

#define sl_bt_cmd_scanner_start_id
Value:
0x03050020

Definition at line 3642 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_scanner_set_parameters_id#

#define sl_bt_rsp_scanner_set_parameters_id
Value:
0x06050020

Definition at line 3643 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_scanner_set_parameters_and_filter_id#

#define sl_bt_rsp_scanner_set_parameters_and_filter_id
Value:
0x07050020

Definition at line 3644 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_scanner_stop_id#

#define sl_bt_rsp_scanner_stop_id
Value:
0x05050020

Definition at line 3645 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_scanner_set_timing_id#

#define sl_bt_rsp_scanner_set_timing_id
Value:
0x01050020

Definition at line 3646 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_scanner_set_mode_id#

#define sl_bt_rsp_scanner_set_mode_id
Value:
0x02050020

Definition at line 3647 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_scanner_start_id#

#define sl_bt_rsp_scanner_start_id
Value:
0x03050020

Definition at line 3648 of file /mnt/raid/workspaces/ws.pY3F1RWXq/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h