bluetoothctl-scan(1)

BLUETOOTHCTL-SCAN(1)

Linux System Administration

BLUETOOTHCTL-SCAN(1)

NAME

bluetoothctl-scan - Scan Submenu

SYNOPSIS

bluetoothctl [--options] [scan.commands]

This submenu configures discovery filters using org.bluez.Adapter(5) method SetDiscoveryFilter.

SCAN COMMANDS

uuids

Set/Get UUIDs filter.

Usage

> uuids [all/uuid1 uuid2 ...]

Uses

org.bluez.Adapter(5) method SetDiscoveryFilter property UUIDs

[all/uuid1 uuid2 ...]

List of UUIDs to filter for during scanning (default: none, use "all" to scan for any UUID)

Example Show current UUID filter settings

> uuids

Example Filter for Generic Access service only

> uuids 0x1800

Example Filter for Battery service only

> uuids 0x180F

Example Filter for Generic Access and Battery services

> uuids 0x1800 0x180F

Example Filter for Device Info, Battery, and Environmental Sensing

> uuids 0x180A 0x180F 0x181A

Example Filter for Generic Access using full UUID

> uuids 00001800-0000-1000-8000-00805f9b34fb

Example Filter using mixed short and long forms

> uuids 00001800-0000-1000-8000-00805f9b34fb 0000180f-0000-1000-8000-00805f9b34fb

Example Remove UUID filtering (scan for all devices)

> uuids all

rssi

Set/Get RSSI filter, and clears pathloss.

This sets the minimum rssi value for reporting device advertisements.

The value is in dBm.

If one or more discovery filters have been set, the RSSI delta-threshold imposed by starting discovery by default will not be applied.

Usage

> rssi [rssi]

Uses

org.bluez.Adapter(5) method SetDiscoveryFilter property RSSI

[rssi]

Minimum RSSI threshold value in dBm (optional, shows current if omitted)

Example Show current RSSI filter setting

> rssi

Example Only report devices with RSSI ≥ -60 dBm (close range)

> rssi -60

Example Report devices with RSSI ≥ -80 dBm (medium range)

> rssi -80

Example Report devices with RSSI ≥ -90 dBm (extended range)

> rssi -90

Example Report only very close devices (RSSI ≥ -40 dBm)

> rssi -40

Example Report devices with very weak signals (maximum sensitivity)

> rssi -100

pathloss

Set/Get Pathloss filter, and clears RSSI.

This sets the maximum pathloss value for reporting device advertisements.

The value is in dB.

If one or more discovery filters have been set, the RSSI delta-threshold imposed by starting discovery by default will not be applied.

Usage

> pathloss [pathloss]

Uses

org.bluez.Adapter(5) method SetDiscoveryFilter property Pathloss

[pathloss]

Maximum pathloss threshold value in dB (optional, shows current if omitted)

Example Show current pathloss filter setting

> pathloss

Example Report devices with maximum 4 dB pathloss (very close)

> pathloss 4

Example Report devices with maximum 10 dB pathloss (close range)

> pathloss 10

Example Report devices with maximum 20 dB pathloss (medium range)

> pathloss 20

Example Report devices with maximum 30 dB pathloss (extended range)

> pathloss 30

Example Report devices with maximum 50 dB pathloss (maximum range)

> pathloss 50

transport

Set/Get transport filter.

Transport parameter determines the type of scan.

The default is auto.

Possible values:

"auto": interleaved scan
"bredr": BR/EDR inquiry
"le": LE scan only

If "le" or "bredr" Transport is requested and the controller doesn't support it, an org.bluez.Error.Failed error will be returned.

If "auto" transport is requested, the scan will use LE, BREDR, or both, depending on what's currently enabled on the controller.

Usage

> transport [auto/bredr/le]

[auto/bredr/le]

Transport type for scanning (optional, shows current if omitted)

Example Show current transport filter setting

> transport

Example Use automatic transport selection (LE + BR/EDR)

> transport auto

Example Scan only Low Energy devices

> transport le

Example Scan only BR/EDR (Classic Bluetooth) devices

> transport bredr

duplicate-data

Set/Get duplicate data filter.

Disables duplicate detection of advertisement data.

When enabled, PropertiesChanged signals will be generated for ManufacturerData and ServiceData every time they are discovered.

Usage

> duplicate-data [on/off]

[on/off]

Enable or disable duplicate advertisement data reporting (optional, shows current if omitted)

Example Show current duplicate data filter setting

> duplicate-data

Example Enable reporting of duplicate advertisement data

> duplicate-data on

Example Disable duplicate data reporting (filter duplicates)

> duplicate-data off

discoverable

Set/Get discoverable filter.

Makes the adapter discoverable while discovering.

If the adapter is already discoverable, setting this filter won't have any effect.

Usage

> discoverable [on/off]

[on/off]

Make adapter discoverable during scanning (optional, shows current if omitted)

Example Show current discoverable filter setting

> discoverable

Example Make adapter discoverable during scanning

> discoverable on

Example Keep adapter non-discoverable during scanning

> discoverable off

pattern

Set/Get pattern filter.

Discover devices where the pattern matches either the prefix of the address or the device name, which is a convenient way to limit the number of device objects created during a discovery.

When set, it disregards device discoverable flags.

Note

The pattern matching is ignored if there are other clients that don't set any pattern, as it works as a logical OR. Also, setting an empty string "" pattern will match any device found.

Usage

> pattern [value]

[value]

Pattern to match device address prefix or name (optional, shows current if omitted)

Example Show current pattern filter setting

> pattern

Example Discover devices with "Samsung" in the name

> pattern Samsung

Example Discover devices with "iPhone" in the name

> pattern iPhone

Example Discover devices with "Headphones" in the name

> pattern Headphones

Example Discover devices with addresses starting with 00:11:22

> pattern 00:11:22

Example Discover devices with addresses starting with AA:BB:CC

> pattern AA:BB:CC

Example Clear pattern filter (match any device)

> pattern ""

auto-connect

Set/Get auto-connect filter.

Connect to discovered devices automatically if pattern filter has been set and it matches the device address or name and the device is connectable.

Usage

> auto-connect [on/off]

[on/off]

Automatically connect to discovered devices matching pattern filter (optional, shows current if omitted)

Example Show current auto-connect filter setting

> auto-connect

Example Enable automatic connection to matching devices

> auto-connect on

Example Disable automatic connection (manual connection required)

> auto-connect off

clear

Clears discovery filter.

Usage

> clear [uuids/rssi/pathloss/transport/duplicate-data/discoverable/pattern/auto-connect]

[uuids/rssi/pathloss/transport/duplicate-data/discoverable/pattern/auto-connect]

Specific filter(s) to clear (optional, clears all if omitted)

Example Clear all discovery filters

> clear

Example Clear only UUID filter

> clear uuids

Example Clear only RSSI filter

> clear rssi

Example Clear only pathloss filter

> clear pathloss

Example Clear only transport filter

> clear transport

Example Clear only duplicate data filter

> clear duplicate-data

Example Clear only discoverable filter

> clear discoverable

Example Clear only pattern filter

> clear pattern

Example Clear only auto-connect filter

> clear auto-connect

Example Clear UUID and RSSI filters

> clear uuids rssi

Example Clear transport and pattern filters

> clear transport pattern

Example Clear pattern and auto-connect filters

> clear pattern auto-connect

Example Clear RSSI, pathloss, and discoverable filters

> clear rssi pathloss discoverable

RESOURCES

http://www.bluez.org

REPORTING BUGS

linux-bluetooth@vger.kernel.org

COPYRIGHT

Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL).

July 2023

BlueZ