BLUETOOTHCTL-ADVERTISE(1)

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

💖 NAME 💖

okay bestie, welcome to BLUETOOTHCTL-ADVERTISE(1) from the Linux System Administration corner of the manual — this is the page for bluetoothctl-advertise, aka the Advertise Submenu. no cap, it's giving “LE advertising setup but make it cute.” 🦋

✨ SYNOPSIS ✨

bluetoothctl [--options] [advertise.commands]

This submenu configures LE advertising data and parameters using the org.bluez.LEAdvertisement(5) and org.bluez.LEAdvertisingManager(5) interfaces. literally the whole advertising buffet, and you're the main character choosing what goes in the packet 💅

🦋 uuids 🦋

Set/Get advertise uuids. it's the “who are you advertising” list, bestie.

Usage:

> uuids [uuid1 uuid2 ...]

Examples:

  • Example: Show current advertised UUIDs — > uuids
  • Example: Advertise custom 16-bit service UUID — > uuids 0x1234
  • Example: Advertise custom 32-bit service UUID — > uuids 0x12345678
  • Example: Advertise custom 128-bit service UUID — > uuids 90f95193-35de-4306-a6e9-699328f15059
  • Example: Advertise Battery and Generic Attribute services — > uuids 0x180F 0x1801
  • Example: Advertise Device Information, Battery, and HID services — > uuids 0x180A 0x180F 0x1812
  • Example: Advertise Generic Access service — > uuids 0x1800
  • Example: Advertise Environmental Sensing service — > uuids 0x181A
  • Example: Advertise Pulse Oximeter service — > uuids 0x183B
  • Example: Mix short and full UUID formats — > uuids 0x180F 12345678-1234-5678-9abc-123456789abc

🧚 solicit 🧚

Set/Get advertise solicit uuids. this is the “please notice me, service” list 💌

Usage:

> solicit [uuid1 uuid2 ...]

Examples:

  • Example: Show current solicited service UUIDs — > solicit
  • Example: Solicit Generic Access service — > solicit 0x1800
  • Example: Solicit Device Information service — > solicit 0x180A
  • Example: Solicit User Data service — > solicit 0x181C
  • Example: Solicit Battery and Generic Attribute services — > solicit 0x180F 0x1801
  • Example: Solicit Device Info, Environmental Sensing, and Pulse Oximeter — > solicit 0x180A 0x181A 0x183B

🎀 service 🎀

Set/Get advertise service data. cute little UUID-plus-data moment ✨

Usage:

> service [uuid] [data=xx xx ...]

Examples:

  • Example: Show current service data — > service
  • Example: Set battery level to 100 (0x64) — > service 0x180F 64
  • Example: Set battery level to 50 (0x32) — > service 0x180F 32
  • Example: Set battery level to 0 (0x00) — > service 0x180F 00
  • Example: Set environmental data (temperature, humidity, pressure) — > service 0x181A 20 15 C8 07
  • Example: Set device information data — > service 0x180A 01 02 03 04
  • Example: Set custom service data with 128-bit UUID — > service 12345678-1234-5678-9abc-123456789abc FF EE DD CC

🔥 manufacturer 🔥

Set/Get advertise manufacturer data. this one is the icon, but also kind of the drama section, so listen up 👑

Updating is in real time while advertising. This is currently limited to 25 bytes and will return an error message of "Too much data" if that maximum has been exceeded. However, this does not check if the advertising payload length maximum has been exceeded, so you may receive an error from bluetoothd that it "Failed to register advertisement" — which means you need to reduce your manufacturer data length. fr fr, trim the data, bestie.

Usage:

> manufacturer [id] [data=xx xx ...]
  • Uses: org.bluez.LEAdvertisement(5) property ManufacturerData
  • [id] — Manufacturer ID (default: 0x004C for Apple Inc.)
  • [data=xx xx ...] — Manufacturer data

Examples:

  • Example: Show current manufacturer data — > manufacturer
  • Example: Set Apple Inc. manufacturer data — > manufacturer 0x004C 01 02 03 04
  • Example: Set Apple manufacturer data with 8 bytes — > manufacturer 0x004C FF FE FD FC FB FA F9 F8
  • Example: Set Microsoft Corp. manufacturer data — > manufacturer 0x0006 10 11 12 13
  • Example: Set Samsung Electronics manufacturer data — > manufacturer 0x0075 AA BB CC DD EE
  • Example: Set Google LLC manufacturer data — > manufacturer 0x00E0 01 23 45 67 89 AB CD EF
  • Example: Set custom manufacturer ID with test data — > manufacturer 0xFFFF DE AD BE EF

🌈 data 🌈

Set/Get advertise data. this is the “raw advertising data, choose your own adventure” command.

This allows you to advertise data with a given type. You cannot use a registered data type value {1} with this command. For LE the advertising shows up in the primary advertisements.

⚠️ If you set only the type of the data without any data (data 0x0c) this will cause a parse error when turning advertise on. not me setting a type and forgetting the actual data 💀

You can modify the advertising data while it is advertising.

To get the currently set data use the command data without any arguments.

Usage:

> data [type] [data=xx xx ...]

Examples:

  • Example: Show current advertising data — > data
  • Example: Set slave connection interval range data — > data 0x0C 01 0x0F 13
  • Example: Set complete local name to Hello — > data 0x09 48 65 6C 6C 6F
  • Example: Set shortened local name to Test — > data 0x08 54 65 73 74
  • Example: Set flags (LE General Discoverable + BR/EDR not supported) — > data 0x01 06
  • Example: Set appearance (keyboard, 0x0341) — > data 0x19 41 03
  • Example: Set TX power level to +4 dBm — > data 0x0A 04
  • Example: Set TX power level to -4 dBm — > data 0x0A FC
  • Example: Set URI //google.com — > data 0x24 17 2F 2F 67 6F 6F 67 6C 65 2E 63 6F 6D
  • Example: Set service data for Battery Service (UUID 0x180F, level 100) — > data 0x16 0F 18 64

🦋 sr-uuids 🦋

Set/Get scan response uuids. scan response is like the bonus track on the album, and these are the UUIDs on it ✨

Usage:

> sr-uuids [uuid1 uuid2 ...]
  • [uuid1 uuid2 ...] — List of UUIDs to advertise in scan response

Examples:

  • Example: Show current scan response UUIDs — > sr-uuids
  • Example: Set Generic Access in scan response — > sr-uuids 0x1800
  • Example: Set Device Info and Battery services in scan response — > sr-uuids 0x180A 0x180F
  • Example: Set custom UUID in scan response — > sr-uuids 12345678-1234-5678-9abc-123456789abc

🧚 sr-solicit 🧚

Set/Get scan response solicit uuids. same bonus-track energy, but for solicit UUIDs.

Usage:

> sr-solicit [uuid1 uuid2 ...]
  • [uuid1 uuid2 ...] — List of UUIDs to advertise in scan response

Examples:

  • Example: Show current scan response solicited UUIDs — > sr-solicit
  • Example: Solicit Generic Attribute service in scan response — > sr-solicit 0x1801
  • Example: Solicit Device Info and Environmental Sensing in scan response — > sr-solicit 0x180A 0x181A

🎀 sr-service 🎀

Set/Get scan response service data. the scan response said “let me add a little service data real quick” 💅

Usage:

> sr-service [uuid] [data=xx xx ...]
  • [uuid] — Service UUID
  • [data=xx xx ...] — Service data

Examples:

  • Example: Show current scan response service data — > sr-service
  • Example: Set battery level to 128 in scan response — > sr-service 0x180F 80
  • Example: Set environmental data in scan response — > sr-service 0x181A 22 18 C0 05
  • Example: Set device info Hello in scan response — > sr-service 0x180A 48 65 6C 6C 6F

🔥 sr-manufacturer 🔥

Set/Get scan response manufacturer data. manufacturer data but make it scan response 💖

Usage:

> sr-manufacturer [id] [data=xx xx ...]
  • [id] — Manufacturer ID (default: 0x004C for Apple Inc.)
  • [data=xx xx ...] — Manufacturer data

Examples:

  • Example: Show current scan response manufacturer data — > sr-manufacturer
  • Example: Set Apple manufacturer data in scan response — > sr-manufacturer 0x004C 05 06 07 08
  • Example: Set Microsoft manufacturer data in scan response — > sr-manufacturer 0x0006 20 21 22 23
  • Example: Set custom manufacturer data in scan response — > sr-manufacturer 0xFFFF CA FE BA BE

🌈 sr-data 🌈

Set/Get scan response data. raw scan response data, no thoughts, just bytes 🫶

Usage:

> sr-data [type] [data=xx xx ...]
  • [type] — Scan Response data type
  • [data=xx xx ...] — Scan Response data

Examples:

  • Example: Show current scan response data — > sr-data
  • Example: Set complete local name ScanResp in scan response — > sr-data 0x09 53 63 61 6E 52 65 73 70
  • Example: Set TX power level +8 dBm in scan response — > sr-data 0x0A 08
  • Example: Set Battery service data (level 50) in scan response — > sr-data 0x16 0F 18 32

👑 discoverable 👑

Set/Get advertise discoverable. this is the “notice me” switch, and yes it's iconic.

For LE, discoverable on will set the LE General Discoverable Mode flag to true in the primary advertisement if on.

This feature can be changed during advertising, but it will only trigger LE General Discoverable Mode — even if you had previously selected discoverable-timeout, this will be ignored.

Entering the command by itself will show the status of the setting.

Usage:

> discoverable [on/off]

Examples:

  • Example: Show current discoverable setting — > discoverable
  • Example: Enable LE General Discoverable Mode — > discoverable on
  • Example: Disable discoverable mode — > discoverable off

⭐ discoverable-timeout ⭐

Set/Get advertise discoverable timeout. limited discoverable mode has a timer, and yes it's giving “you have [seconds] to notice me” 😭

Using this feature in LE will cause the LE Limited Discoverable Mode flag to be set in the primary advertisement, and the LE General Discoverable Mode flag will not be set.

The LE Limited Discoverable Mode flag will automatically turn off after [seconds]. discoverable on must be set to use this feature.

Entering the command by itself will show the current value set.

Usage:

> discoverable-timeout [seconds]
  • Uses: org.bluez.LEAdvertisement(5) property DiscoverableTimeout
  • [seconds] — Timeout duration in seconds for LE Limited Discoverable Mode

Examples:

  • Example: Show current discoverable timeout — > discoverable-timeout
  • Example: Set LE Limited Discoverable for 30 seconds — > discoverable-timeout 30
  • Example: Set LE Limited Discoverable for 2 minutes — > discoverable-timeout 120
  • Example: Set LE Limited Discoverable for 5 minutes — > discoverable-timeout 300
  • Example: Disable discoverable timeout (unlimited) — > discoverable-timeout 0

🌟 tx-power 🌟

Show/Enable/Disable TX power to be advertised. this one puts your transmit power in the packet, and honestly? flex.

This sets the TX Power Level field in the advertising packet.

The value is in dBm and can be between -127 and 127.

When this feature is turned on the LE device will advertise its transmit power in the primary advertisement.

This feature can be modified while advertising.

Entering the command by itself will show the current value set.

Usage:

> tx-power [on/off]
  • Uses: org.bluez.LEAdvertisement(5) property Includes
  • [on/off] — Enable or disable TX power advertisement (optional, shows current if omitted)

Alright bestie, we're mid-flow, so let's keep the tx-power era going 💅 — here are the rest of the moves:

> tx-power

Shows you what the TX power advertisement setting is rn ✨

> tx-power on

Turns TX power advertisement on, using the default power 🔥

> tx-power off

Turns it off. Goodbye TX power, you were iconic 💀

🎀 name

Sets up the local name that gets advertised. This is, like, the name the device shows off in the advertising report 📛

If your string is too chonky to fit in the packet, it gets truncated — no drama, it just gets cut down to size 😭

It'll either advertise as a complete local name, or, if it had to be truncated, as a shortened local name. Either way it's serving 🫶

Usage:

> name [on/off/name]

Uses org.bluez.LEAdvertisement(5) property LocalName ⭐

  • [name] — the local name (optional, shows the current one if you leave it out)
> name

Shows the currently advertised name setting 👑

> name on

Advertises the system hostname, slay ✨

> name off

Disables name advertisement. Bye bestie 👋

> name "My Device"

Advertises My Device as the local name 💖

> name "Smart Sensor"

Advertises Smart Sensor as the local name 🌸

> name "BLE-Peripheral-001"

Advertises the device with an ID suffix 🦋

> name "0123456789abcdef0123456789abcdef"

Advertises a long name — heads up, it will be truncated to fit 🙈

> name "This is a very long device name that will be truncated"

A long descriptive name, automatically truncated. The packet said no 💀

> name "Device™"

Name with special characters, trademark and all ✨

> name "Tëst-Dëvicë"

Name with accented characters, très chic 💅

🦋 appearance

Configures a custom appearance to be advertised. This is the vibe your device gives off at a glance 👀

Usage:

> appearance [on/off/value]

Uses org.bluez.LEAdvertisement(5) property Appearance ⭐

  • [value] — the appearance value (optional, shows the current one if you leave it out)
> appearance

Shows the current appearance setting 💖

> appearance on

Enables appearance advertisement with the default value 🌸

> appearance off

Disables appearance advertisement ✨

> appearance 961

Sets appearance to keyboard (0x03C1) ⌨️

> appearance 962

Sets appearance to mouse (0x03C2) 🖱️

> appearance 963

Sets appearance to joystick (0x03C3) 🕹️

> appearance 964

Sets appearance to gamepad (0x03C4) 🎮

> appearance 832

Sets appearance to generic audio sink (0x0340) 🔊

> appearance 833

Sets appearance to speaker (0x0341) 📢

> appearance 834

Sets appearance to microphone (0x0342) 🎤

> appearance 835

Sets appearance to headset (0x0343) 🎧

> appearance 836

Sets appearance to headphones (0x0344) 🎶

> appearance 1344

Sets appearance to heart rate sensor (0x0540) 💓

> appearance 1472

Sets appearance to thermometer (0x05C0) 🌡️

> appearance 1600

Sets appearance to glucose meter (0x0640) 🍓

> appearance 64

Sets appearance to generic phone (0x0040) 📱

> appearance 128

Sets appearance to generic computer (0x0080) 💻

> appearance 192

Sets appearance to generic watch (0x00C0) ⌚

⏳ duration

Sets/gets the advertise duration ⏰

The Duration parameter configures the length of an Instance — like, how long each one gets its moment 💫

The value is in seconds.

A value of 0 means a default value is chosen for the Duration.

The default is 2 seconds.

Heads up: if only one advertising Instance has been added, the Duration value gets ignored entirely 🙈

If multiple advertising Instances have been added, then Duration is what decides how long each Instance gets advertised for 👯

The Duration value is used to calculate the number of advertising events that'll be used to advertise each Instance.

That number of advertising events? It's calculated by dividing the Duration value by the advertising interval 🧮

The advertising interval is determined by the advertising parameters set for each Instance — and it's the maximum of the advertising intervals set for each Instance. Big brain math fr fr 🧠

Usage:

> duration [seconds]

Uses org.bluez.LEAdvertisement(5) property Duration ⭐

  • [seconds] — duration in seconds (optional, shows the current one if you leave it out)
> duration

Shows the current advertising duration setting ⏱️

> duration 0

Uses the default duration (2 seconds) ✨

> duration 1

Sets duration to 1 second 💫

> duration 5

Sets duration to 5 seconds 🌸

> duration 10

Sets duration to 10 seconds 💖

> duration 30

Sets duration to 30 seconds 🎀

> duration 60

Sets duration to 1 minute ⏰

> duration 300

Sets duration to 5 minutes 👑

⌛ timeout

Sets/gets the advertise timeout. This one's the "okay we're done here" timer 😌

Usage:

> timeout [seconds]

Uses org.bluez.LEAdvertisement(5) property Timeout ⭐

  • [seconds] — timeout in seconds (optional, shows the current one if you leave it out)
> timeout

Shows the current advertising timeout setting ⏳

> timeout 0

Unlimited advertising, no timeout at all — main character energy forever 💅

> timeout 30

Stops advertising after 30 seconds 🛑

> timeout 120

Stops advertising after 2 minutes ⏲️

> timeout 3600

Stops advertising after 1 hour 🕐

🌈 secondary

Sets/gets the advertise secondary channel 📡

Usage:

> secondary [1M/2M/Coded]

Uses org.bluez.LEAdvertisement(5) property SecondaryChannel ⭐

  • [1M/2M/Coded] — the secondary channel (optional, shows the current one if you leave it out)
> secondary

Shows the current secondary channel setting 💖

> secondary 1M

Uses LE 1M PHY for the secondary advertising channel ✨

> secondary 2M

Uses LE 2M PHY for the secondary advertising channel 🔥

> secondary Coded

Uses LE Coded PHY for the secondary advertising channel 🦋

🧚 rsi

Shows/enables/disables RSI to be advertised ✨

RSI — that's Resolvable Set Identifier — is used to advertise a resolvable identifier for Coordinated Set Identification 🎯

Usage:

> rsi [on/off]
  • [on/off] — enable or disable RSI advertisement (optional, shows the current setting if you leave it out)
> rsi

Shows the current RSI setting 👀

> rsi on

Enables RSI advertisement 💖

> rsi off

Disables RSI advertisement 💀

🍓 interval

Sets/gets the advertise interval 📶

The Interval parameter configures the advertising interval of an Instance.

The value is in milliseconds.

A value of 0 means a default value is chosen for the Interval.

The default is 100 milliseconds.

The Interval value is used to calculate the number of advertising events that'll be used to advertise each Instance 🧮

That number of advertising events is calculated by dividing the Duration value by the advertising interval.

The advertising interval is determined by the advertising parameters set for each Instance.

And the advertising interval is the maximum of the advertising intervals set for each Instance — yes, again, it's the max, keep up bestie 😤

Usage:

> interval [min] [max]
  • [min] — minimum advertising interval in milliseconds (optional, shows the current one if you leave it out)
  • [max] — maximum advertising interval in milliseconds (optional, defaults to the min value)
> interval

Shows the current advertising interval setting 👑

> interval 20

Sets the minimum advertising interval (20ms) ⚡

> interval 50 100

Sets the advertising interval range (50–100ms) 🌈

> interval 100

Sets the normal advertising interval (100ms) ✨

> interval 200

Sets a moderate advertising interval (200ms) 🌸

> interval 500

Sets a slow advertising interval (500ms) 🐢

> interval 1000

Sets a very slow advertising interval (1 second) 😴

> interval 10240

Sets the maximum advertising interval (10.24 seconds) 🐌

💅 clear

Clears the advertise config 🧹

This will stop advertising if it's currently advertising — so yeah, heads up 😭

And listen: if you wanna change the advertise configuration while advertising, you must first clear the advertise configuration and then set the new one. That's the rule, no cap 🙏

Usage:

> clear [uuids/service/manufacturer/config-name...]
  • [uuids/service/manufacturer/config-name...] — list of configuration to clear
> clear

Clears all advertising configuration 💀

> clear uuids

Clears only advertised UUIDs 💖

> clear service

Clears only service data 🌸

> clear manufacturer

Clears only manufacturer data 🎀

> clear name

Clears only the advertised name ✨

> clear appearance

Clears only appearance data 🦋

> clear tx-power

Clears only TX power advertisement ⚡

> clear uuids service

Clears UUIDs and service data 🌈

> clear manufacturer name

Clears manufacturer data and name 💅

> clear uuids service manufacturer

Clears UUIDs, service data, and manufacturer data 👑

> clear discoverable tx-power

Clears discoverable mode and TX power 🔥

🌸 RESOURCES

http://www.bluez.org — the mothership, go say hi 🫶

💜 REPORTING BUGS

linux-bluetooth@vger.kernel.org — that's the address, ping them nicely please 🙈

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

okay that's the whole thing, you're officially a bluetoothctl-advertise scholar now 🎓✨ this was the BlueZ era of the page, dated November 2022 — go forth and advertise responsibly, bestie 💖🦋🎀

📦 where this page comes from