bluetoothctl-advertise

Advertise Submenu

Version:

BlueZ

Copyright:

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

Date:

November 2022

Manual section:

1

Manual group:

Linux System Administration

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.

Advertise Options Commands

uuids

Set/Get advertise uuids.

Usage:

> uuids [uuid1 uuid2 …]

Uses:

org.bluez.LEAdvertisement(5) property ServiceUUIDs

[uuid1 uuid2 …]:

List of UUIDs to advertise (default: none)

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.

Usage:

> solicit [uuid1 uuid2 …]

Uses:

org.bluez.LEAdvertisement(5) property SolicitUUIDs

[uuid1 uuid2 …]:

List of UUIDs to advertise (default: none)

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.

Usage:

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

Uses:

org.bluez.LEAdvertisement(5) property ServiceData

[uuid]:

Service UUID

[data=xx xx …]:

Service data

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.

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.

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

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

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 …]

Uses:

org.bluez.LEAdvertisement(5) property Data

[type]:

Advertising data type

[data=xx xx …]:

Advertising data (default: none)

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.

Usage:

> sr-uuids [uuid1 uuid2 …]

[uuid1 uuid2 …]:

List of UUIDs to advertise in scan response

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.

Usage:

> sr-solicit [uuid1 uuid2 …]

[uuid1 uuid2 …]:

List of UUIDs to advertise in scan response

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.

Usage:

> sr-service [uuid] [data=xx xx …]

[uuid]:

Service UUID

[data=xx xx …]:

Service data

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.

Usage:

> sr-manufacturer [id] [data=xx xx …]

[id]:

Manufacturer ID (default: 0x004C for Apple Inc.)

[data=xx xx …]:

Manufacturer data

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.

Usage:

> sr-data [type] [data=xx xx …]

[type]:

Scan Response data type

[data=xx xx …]:

Scan Response data

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.

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 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]

Uses:

org.bluez.LEAdvertisement(5) property Discoverable

[on/off]:

Enable/Disable LE General Discoverable Mode

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.

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

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

Example Show current TX power advertisement setting:

> tx-power

Example Enable TX power advertisement with default power:

> tx-power on

Example Disable TX power advertisement:

> tx-power off

name

Configure local name to be advertised.

Local name to be used in the advertising report.

If the string is too big to fit into the packet it will be truncated.

It will either advertise as a complete local name or if it has to be truncated then a shortened local name.

Usage:

> name [on/off/name]

Uses:

org.bluez.LEAdvertisement(5) property LocalName

[name]:

Local name (optional, shows current if omitted)

Example Show current advertised name setting:

> name

Example Enable advertising the system hostname:

> name on

Example Disable name advertisement:

> name off

Example Advertise “My Device” as local name:

> name “My Device”

Example Advertise “Smart Sensor” as local name:

> name “Smart Sensor”

Example Advertise device with ID suffix:

> name “BLE-Peripheral-001”

Example Advertise long name (will be truncated to fit):

> name “0123456789abcdef0123456789abcdef”

Example Long descriptive name (automatically truncated):

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

Example Name with special characters:

> name “Device™”

Example Name with accented characters:

> name “Tëst-Dëvicë”

appearance

Configure custom appearance to be advertised.

Usage:

> appearance [on/off/value]

Uses:

org.bluez.LEAdvertisement(5) property Appearance

[value]:

Appearance value (optional, shows current if omitted)

Example Show current appearance setting:

> appearance

Example Enable appearance advertisement with default value:

> appearance on

Example Disable appearance advertisement:

> appearance off

Example Set appearance to keyboard (0x03C1):

> appearance 961

Example Set appearance to mouse (0x03C2):

> appearance 962

Example Set appearance to joystick (0x03C3):

> appearance 963

Example Set appearance to gamepad (0x03C4):

> appearance 964

Example Set appearance to generic audio sink (0x0340):

> appearance 832

Example Set appearance to speaker (0x0341):

> appearance 833

Example Set appearance to microphone (0x0342):

> appearance 834

Example Set appearance to headset (0x0343):

> appearance 835

Example Set appearance to headphones (0x0344):

> appearance 836

Example Set appearance to heart rate sensor (0x0540):

> appearance 1344

Example Set appearance to thermometer (0x05C0):

> appearance 1472

Example Set appearance to glucose meter (0x0640):

> appearance 1600

Example Set appearance to generic phone (0x0040):

> appearance 64

Example Set appearance to generic computer (0x0080):

> appearance 128

Example Set appearance to generic watch (0x00C0):

> appearance 192

duration

Set/Get advertise duration.

The Duration parameter configures the length of an Instance.

The value is in seconds.

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

The default is 2 seconds.

If only one advertising Instance has been added, then the Duration value will be ignored.

If multiple advertising Instances have been added, then the Duration value will be used to determine the length of time each Instance is advertised for.

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

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

The advertising interval is determined by the advertising parameters that are set for each Instance. The advertising interval is the maximum of the advertising intervals set for each Instance.

Usage:

> duration [seconds]

Uses:

org.bluez.LEAdvertisement(5) property Duration

[seconds]:

Duration in seconds (optional, shows current if omitted)

Example Show current advertising duration setting:

> duration

Example Use default duration (2 seconds):

> duration 0

Example Set duration to 1 second:

> duration 1

Example Set duration to 5 seconds:

> duration 5

Example Set duration to 10 seconds:

> duration 10

Example Set duration to 30 seconds:

> duration 30

Example Set duration to 1 minute:

> duration 60

Example Set duration to 5 minutes:

> duration 300

timeout

Set/Get advertise timeout.

Usage:

> timeout [seconds]

Uses:

org.bluez.LEAdvertisement(5) property Timeout

[seconds]:

Timeout in seconds (optional, shows current if omitted)

Example Show current advertising timeout setting:

> timeout

Example Unlimited advertising (no timeout):

> timeout 0

Example Stop advertising after 30 seconds:

> timeout 30

Example Stop advertising after 2 minutes:

> timeout 120

Example Stop advertising after 1 hour:

> timeout 3600

secondary

Set/Get advertise secondary channel.

Usage:

> secondary [1M/2M/Coded]

Uses:

org.bluez.LEAdvertisement(5) property SecondaryChannel

[1M/2M/Coded]:

Secondary channel (optional, shows current if omitted)

Example Show current secondary channel setting:

> secondary

Example Use LE 1M PHY for secondary advertising channel:

> secondary 1M

Example Use LE 2M PHY for secondary advertising channel:

> secondary 2M

Example Use LE Coded PHY for secondary advertising channel:

> secondary Coded

rsi

Show/Enable/Disable RSI to be advertised.

RSI (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 current if omitted)

Example Show current RSI setting:

> rsi

Example Enable RSI advertisement:

> rsi on

Example Disable RSI advertisement:

> rsi off

interval

Set/Get advertise interval.

The Interval parameter configures the advertising interval of an Instance.

The value is in milliseconds.

A value of 0 indicates 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 will be used to advertise each Instance.

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

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

The advertising interval is the maximum of the advertising intervals set for each Instance.

Usage:

> interval [min] [max]

[min]:

Minimum advertising interval in milliseconds (optional, shows current if omitted)

[max]:

Maximum advertising interval in milliseconds (optional, defaults to min value)

Example Show current advertising interval setting:

> interval

Example Set minimum advertising interval (20ms):

> interval 20

Example Set advertising interval range (50-100ms):

> interval 50 100

Example Set normal advertising interval (100ms):

> interval 100

Example Set moderate advertising interval (200ms):

> interval 200

Example Set slow advertising interval (500ms):

> interval 500

Example Set very slow advertising interval (1 second):

> interval 1000

Example Set maximum advertising interval (10.24 seconds):

> interval 10240

clear

Clear advertise config.

This will stop advertising if it is currently advertising.

If you want to change the advertise configuration while advertising you must first clear the advertise configuration and then set the new advertise configuration.

Usage:

> clear [uuids/service/manufacturer/config-name…]

[uuids/service/manufacturer/config-name…]:

List of configuration to clear

Example Clear all advertising configuration:

> clear

Example Clear only advertised UUIDs:

> clear uuids

Example Clear only service data:

> clear service

Example Clear only manufacturer data:

> clear manufacturer

Example Clear only advertised name:

> clear name

Example Clear only appearance data:

> clear appearance

Example Clear only TX power advertisement:

> clear tx-power

Example Clear UUIDs and service data:

> clear uuids service

Example Clear manufacturer data and name:

> clear manufacturer name

Example Clear UUIDs, service data, and manufacturer data:

> clear uuids service manufacturer

Example Clear discoverable mode and TX power:

> clear discoverable tx-power

RESOURCES

http://www.bluez.org

REPORTING BUGS

linux-bluetooth@vger.kernel.org