bluetoothctl-advertise(1)

Name
bluetoothctl-advertise - Advertise Submenu

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>

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