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