BLUETOOTHCTL-SCAN(1)

📦
version 5.87+2.git8750129efca8 · 10 versions
, in centos-stream 9

💙 bluetoothctl-scan — the Scan Submenu, explained by your favorite Bluetooth bestie 💅

Okay so this is the bluetoothctl-scan page from the Linux System Administration manual set, and it's basically the discovery-filter control room for bluetoothctl. Let's go ✨

✨ NAME ✨

bluetoothctl-scan — the Scan Submenu 🫶

🌸 SYNOPSIS 🌸

bluetoothctl [--options] [scan.commands]

This submenu configures discovery filters using the org.bluez.Adapter(5) method SetDiscoveryFilter. Like, that's its whole personality 💖

🎀 SCAN COMMANDS 🎀

🦋 uuids

Set/Get the UUIDs filter.

Usage  > uuids [all/uuid1 uuid2 ...]

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

  • [all/uuid1 uuid2 ...] — the list of UUIDs to filter for during scanning (default: none, use "all" to scan for any UUID).

Examples:

  • Show current UUID filter settings → > uuids
  • Filter for Generic Access service only → > uuids 0x1800
  • Filter for Battery service only → > uuids 0x180F
  • Filter for Generic Access and Battery services → > uuids 0x1800 0x180F
  • Filter for Device Info, Battery, and Environmental Sensing → > uuids 0x180A 0x180F 0x181A
  • Filter for Generic Access using full UUID → > uuids 00001800-0000-1000-8000-00805f9b34fb
  • Filter using mixed short and long forms → > uuids 00001800-0000-1000-8000-00805f9b34fb 0000180f-0000-1000-8000-00805f9b34fb
  • Remove UUID filtering (scan for all devices) → > uuids all

🔥 rssi

Set/Get the RSSI filter — and it clears pathloss. Yes, they're mutually exclusive besties, we don't make the rules 😭

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. No cap.

Usage  > rssi [rssi]

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

  • [rssi] — minimum RSSI threshold value in dBm (optional, shows current if omitted).

Examples:

  • Show current RSSI filter setting → > rssi
  • Only report devices with RSSI ≥ -60 dBm (close range) → > rssi -60
  • Report devices with RSSI ≥ -80 dBm (medium range) → > rssi -80
  • Report devices with RSSI ≥ -90 dBm (extended range) → > rssi -90
  • Report only very close devices (RSSI ≥ -40 dBm) → > rssi -40
  • Report devices with very weak signals (maximum sensitivity) → > rssi -100

🧚 pathloss

Set/Get the Pathloss filter — and this one clears RSSI. Told you, mutual exclusion is the vibe 💀

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 the org.bluez.Adapter(5) method SetDiscoveryFilter property Pathloss.

  • [pathloss] — maximum pathloss threshold value in dB (optional, shows current if omitted).

Examples:

  • Show current pathloss filter setting → > pathloss
  • Report devices with maximum 4 dB pathloss (very close) → > pathloss 4
  • Report devices with maximum 10 dB pathloss (close range) → > pathloss 10
  • Report devices with maximum 20 dB pathloss (medium range) → > pathloss 20
  • Report devices with maximum 30 dB pathloss (extended range) → > pathloss 30
  • Report devices with maximum 50 dB pathloss (maximum range) → > pathloss 50

🌈 transport

Set/Get the transport filter.

The 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. Rude but fair 🙈

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

Usage  > transport [auto/bredr/le]
  • [auto/bredr/le] — transport type for scanning (optional, shows current if omitted).

Examples:

  • Show current transport filter setting → > transport
  • Use automatic transport selection (LE + BR/EDR) → > transport auto
  • Scan only Low Energy devices → > transport le
  • Scan only BR/EDR (Classic Bluetooth) devices → > transport bredr

💜 duplicate-data

Set/Get the duplicate data filter.

Disables duplicate detection of advertisement data.

When enabled, PropertiesChanged signals will be generated for ManufacturerData and ServiceData every single time they are discovered. Like she never forgets, ever 🫶

Usage  > duplicate-data [on/off]
  • [on/off] — enable or disable duplicate advertisement data reporting (optional, shows current if omitted).

Examples:

  • Show current duplicate data filter setting → > duplicate-data
  • Enable reporting of duplicate advertisement data → > duplicate-data on
  • Disable duplicate data reporting (filter duplicates) → > duplicate-data off

⭐ discoverable

Set/Get the discoverable filter.

Makes the adapter discoverable while discovering. Main character energy, honestly 👑

If the adapter is already discoverable, setting this filter won't have any effect. Nothing to do, she's already that girl 💅

Usage  > discoverable [on/off]
  • [on/off] — make adapter discoverable during scanning (optional, shows current if omitted).

Examples:

  • Show current discoverable filter setting → > discoverable
  • Make adapter discoverable during scanning → > discoverable on
  • Keep adapter non-discoverable during scanning → > discoverable off

🍓 pattern

Set/Get the pattern filter.

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

Examples:

  • Show current pattern filter setting → > pattern
  • Discover devices with Samsung in the name → > pattern Samsung
  • Discover devices with iPhone in the name → > pattern iPhone
  • Discover devices with Headphones in the name → > pattern Headphones
  • Discover devices with addresses starting with 00:11:22 → > pattern 00:11:22
  • Discover devices with addresses starting with AA:BB:CC → > pattern AA:BB:CC
  • Clear pattern filter (match any device) → > pattern ""

🧚‍♀️ auto-connect

Set/Get the auto-connect filter.

Connect to discovered devices automatically if the pattern filter has been set and it matches the device address or name, and the device is connectable. She'll just walk up and say hi for you, no cap 🔥

Usage  > auto-connect [on/off]
  • [on/off] — automatically connect to discovered devices matching pattern filter (optional, shows current if omitted).

Examples:

  • Show current auto-connect filter setting → > auto-connect
  • Enable automatic connection to matching devices → > auto-connect on
  • Disable automatic connection (manual connection required) → > auto-connect off

🩷 clear

Clears the discovery filter. The reset button, the "new year new me", the factory reset of vibes ✨

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

Examples:

  • Clear all discovery filters → > clear
  • Clear only UUID filter → > clear uuids
  • Clear only RSSI filter → > clear rssi
  • Clear only pathloss filter → > clear pathloss
  • Clear only transport filter → > clear transport
  • Clear only duplicate data filter → > clear duplicate-data
  • Clear only discoverable filter → > clear discoverable
  • Clear only pattern filter → > clear pattern
  • Clear only auto-connect filter → > clear auto-connect
  • Clear UUID and RSSI filters → > clear uuids rssi
  • Clear transport and pattern filters → > clear transport pattern
  • Clear pattern and auto-connect filters → > clear pattern auto-connect
  • Clear RSSI, pathloss, and discoverable filters → > clear rssi pathloss discoverable

🌐 RESOURCES 🌐

http://www.bluez.org — go touch grass on the official site, iykyk 🦋

🐛 REPORTING BUGS 🐛

linux-bluetooth@vger.kernel.org — email the hive mind, they're nice fr fr 💖

Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL). Slay, legally speaking 👑

💫 That's the whole page, bestie. This lovely little manual comes from BlueZ, dated July 2023 — signed, sealed, and delivered with love. Mwah 💋

📦 where this page comes from