Scanner#

Scanner.

Modules#

sl_bt_evt_scanner_scan_report Reports an advertising or scan response packet that is received by the device's radio while in scanning mode.

Enumerations#

enum | sl_bt_scanner_discover_mode_t { 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.

Functions#

sl_status_t | sl_bt_scanner_set_timing (uint8_t phys, uint16_t scan_interval, uint16_t scan_window)

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)

sl_status_t | sl_bt_scanner_stop ()

Detailed Description#

Scanner.

The commands and events in this class are related to scanning functionalities in GAP central and observer roles.

Enumeration Type Documentation#

◆ sl_bt_scanner_discover_mode_t#

enum 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.

Function Documentation#

◆ sl_bt_scanner_set_timing()#


sl_status_t sl_bt_scanner_set_timing	(	uint8_t
	uint16_t	`scan_interval,`
	uint16_t	`scan_window`
)

Set the scanning timing parameters on the specified PHYs. If the device is currently scanning for advertising devices on PHYs, new parameters will take effect when scanning is restarted.

Parameters

 [in]| `phys`| PHYs for which the parameters are set.

1: 1M PHY
4: Coded PHY
5: 1M PHY and Coded PHY

---|---|--- [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.

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_scanner_set_mode()#


sl_status_t sl_bt_scanner_set_mode	(	uint8_t	`phys,`
	uint8_t	`scan_mode`
)

Set the scan mode on the specified PHYs. If the device is currently scanning for advertising devices on PHYs, new parameters will take effect when scanning is restarted.

Parameters

 [in]| `phys`| PHYs for which the parameters are set.

1: 1M PHY
4: Coded PHY
5: 1M PHY and Coded PHY

---|---|--- [in]| scan_mode|

Scan mode. Values:

0: Passive scanning
1: Active scanning
In passive scanning mode, the device only listens to advertising packets and does not transmit packets.
In active scanning mode, the device sends out a scan request packet upon receiving an advertising packet from a remote device. Then, it listens to the scan response packet from the remote device.

Default value: 0

Returns

SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_scanner_start()#


sl_status_t sl_bt_scanner_start	(	uint8_t	`scanning_phy,`
	uint8_t	`discover_mode`
)

Start the GAP discovery procedure to scan for advertising devices on the specified scanning PHYs. 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.

Parameters

 [in]| `scanning_phy`|

The scanning PHYs.

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.

1: 1M PHY
4: Coded PHY
5: 1M PHY and Coded PHY. The stack performs simultaneous scanning on both PHYs.

---|---|--- [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.

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

sl_bt_evt_scanner_scan_report - This event is triggered each time an advertising packet is received. Packets are not filtered in any way, so multiple events will be received for every advertising device in range.

◆ 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.