BLUETOOTHCTL-MONITOR(1)

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

💅 bluetoothctl-monitor, aka the Monitor Submenu of bluetoothctl

okay so bestie, welcome to bluetoothctl-monitor — the monitor submenu page out of the Linux System Administration crowd. Buckle up, this one's all about setting up advertisement monitors, and it's honestly lowkey iconic once you get the vibe. 🦋

✨ NAME ✨

bluetoothctl-monitor — Monitor Submenu. that's it, that's the name, periodt. 🎀

🌸 SYNOPSIS 🌸

bluetoothctl [--options] [monitor.commands]

so this submenu is where you configure advertisement monitors, and it does that through the org.bluez.AdvertisementMonitor(5) and org.bluez.AdvertisementMonitorManager(5) interfaces. two interfaces, one slay little submenu. 💅

👑 MONITOR COMMANDS 👑

set-rssi-threshold

sets the RSSI threshold parameter, i.e. the signal-strength window you care about. 📶

Usage:

> set-rssi-threshold <low_threshold> <high_threshold>
  • <low_threshold> — the lower RSSI threshold value, in dBm, for monitoring.
  • <high_threshold> — the higher RSSI threshold value, in dBm, for monitoring.

ok now the examples, because seeing it is believing:

Example — set low threshold to -80 dBm and high threshold to -40 dBm:

> set-rssi-threshold -80 -40

Example — set low threshold to -70 dBm and high threshold to -30 dBm:

> set-rssi-threshold -70 -30

Example — set a very sensitive low threshold and a moderate high threshold:

> set-rssi-threshold -90 -50

Example — set less sensitive thresholds for close range monitoring:

> set-rssi-threshold -60 -20

set-rssi-timeout

sets the RSSI timeout parameter. basically how long the monitor waits on each side of the threshold window. ⏳

Usage:

> set-rssi-timeout <low_timeout> <high_timeout>
  • <low_timeout> — timeout value, in seconds, for the low RSSI threshold.
  • <high_timeout> — timeout value, in seconds, for the high RSSI threshold.

Examples, say it with me:

Example — set low timeout to 5 seconds, high timeout to 10 seconds:

> set-rssi-timeout 5 10

Example — set a quick timeout response for both thresholds:

> set-rssi-timeout 1 5

Example — set longer timeout periods for stable monitoring:

> set-rssi-timeout 10 30

Example — set asymmetric timeout values:

> set-rssi-timeout 3 15

set-rssi-sampling-period

sets the RSSI sampling period parameter. it's giving "how often do we even bother reporting". 🧚

Usage:

> set-rssi-sampling-period <sampling_period>
  • <sampling_period> — sampling period in 100ms units (0-255, where 0 means report all, and 255 means report only first).
bestie pls note the range: it's 0 to 255, and those two endpoints are special little creatures, not just regular numbers. 🫶

Examples:

Example — set sampling period to 100ms (1 unit):

> set-rssi-sampling-period 1

Example — set sampling period to 500ms (5 units):

> set-rssi-sampling-period 5

Example — set sampling period to 1 second (10 units):

> set-rssi-sampling-period 10

Example — report all advertisements (no sampling):

> set-rssi-sampling-period 0

Example — report only first advertisement:

> set-rssi-sampling-period 255

add-or-pattern

registers an 'or pattern' type monitor with the RSSI parameters you specify. this is the main character of the submenu, honestly. 🔥

each pattern requires 3 arguments: <start_position> <ad_data_type> <content_of_pattern>. and yes, you can specify multiple patterns to create an OR condition — hence the name, iykyk.

Usage:

> add-or-pattern <start_pos> <ad_type> <content> [start_pos ad_type content ...]

Uses the org.bluez.AdvertisementMonitorManager(5) method RegisterMonitor.

  • <start_pos> — byte position in advertisement data where pattern matching starts (0-based, so don't come at it with 1).
  • <ad_type> — advertisement data type (e.g., 9 for Complete Local Name, 1 for Flags).
  • <content> — hexadecimal pattern content to match.

Examples, one per vibe:

Example — monitor for Samsung in Complete Local Name (type 9):

> add-or-pattern 0 9 53616d73756e67

Example — monitor for devices with Flags type (type 1) containing 0x06:

> add-or-pattern 0 1 06

Example — monitor for two different patterns (OR condition):

> add-or-pattern 0 9 53616d73756e67 0 9 4170706c65

Example — monitor for specific manufacturer data (type 255):

> add-or-pattern 0 255 4c000215

get-pattern

gets an advertisement monitor. the "wait, what did I actually set up?" command. 🙈

Usage:

> get-pattern <monitor-id/all>
  • <monitor-id/all> — the monitor ID number to retrieve details for, or all for all active monitors.

Examples:

Example — get details of monitor ID 0:

> get-pattern 0

Example — get details of monitor ID 1:

> get-pattern 1

Example — get details of monitor ID 5:

> get-pattern 5

Example — get details of all active monitors:

> get-pattern all

remove-pattern

removes an advertisement monitor. the breakup command, and it's clean. 💀

Usage:

> remove-pattern <monitor-id/all>

Uses the org.bluez.AdvertisementMonitorManager(5) method UnregisterMonitor.

  • <monitor-id/all> — the monitor ID number to remove, or all to remove all active monitors.

Examples:

Example — remove monitor with ID 0:

> remove-pattern 0

Example — remove monitor with ID 1:

> remove-pattern 1

Example — remove monitor with ID 3:

> remove-pattern 3

Example — remove all active advertisement monitors:

> remove-pattern all

get-supported-info

gets the advertisement manager's supported features and supported monitor types. a little vibe check on what your setup can actually do. ⭐

Usage:

> get-supported-info

Uses the org.bluez.AdvertisementMonitorManager(5) properties.

Example — display supported monitor features and types:

> get-supported-info

prints the command usage. yes, a command for getting usage, we love self-awareness. 🌈

Usage:

> print-usage <add-or-pattern>
  • <add-or-pattern> — command name to display detailed usage information for.

Example — show detailed usage for the add-or-pattern command:

> print-usage add-or-pattern

🎀 RESOURCES 🎀

go touch grass on the official site, bestie. 🌸

🫶 REPORTING BUGS 🫶

  • linux-bluetooth@vger.kernel.org

found something cursed? tell the mailing list, not me. 😭

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

and that's the whole page! this cutie is brought to you by BlueZ, dated July 2023 — go forth and monitor those advertisements, you absolute icon. 💜🦋

📦 where this page comes from