Scanner#

Scanner.

Detailed Description#

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 scanner can only scan advertising devices that use legacy advertising PDUs.

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

• The bluetooth_feature_extended_scanner component is included:

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

  • The sl_bt_evt_scanner_legacy_advertisement_report event is used to report the received advertisements that use legacy advertising PDUs, and the sl_bt_evt_scanner_extended_advertisement_report event is used to report the received advertisements that use extended advertising PDUs.

• Either the bluetooth_feature_legacy_scanner or bluetooth_feature_extended_scanner component is included:

  • The sl_bt_scanner_set_timing and sl_bt_scanner_set_mode commands are not available to use. They are superseded by the sl_bt_scanner_set_parameters command.

  • Calling a superseded command receives SL_STATUS_NOT_SUPPORTED error code.

Enumeration Type Documentation#

◆sl_bt_scanner_discover_mode_t#

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

◆sl_bt_scanner_scan_mode_t#

The scanning modes.

◆sl_bt_scanner_scan_phy_t#

The enum defines the scanning PHYs.

◆sl_bt_scanner_data_status_t#

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

Function Documentation#

◆sl_bt_scanner_set_parameters()#

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

Parameters

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

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_scanner_stop()#

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

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_scanner_set_timing()#

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.

Parameters

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

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_scanner_set_mode()#

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.

Parameters

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

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_scanner_start()#

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.

Parameters

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

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