bluetoothctl-gatt

Generic Attribute 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] [gatt.commands]

This submenu interacts with GATT services, characteristics, and descriptors using the org.bluez.GattService(5), org.bluez.GattCharacteristic(5), org.bluez.GattDescriptor(5), and org.bluez.GattManager(5) interfaces.

Generic Attribute Commands

list-attributes

Lists the attributes of either the local device or a remote device, encompassing services, characteristics, and handles. This command provides a comprehensive overview of the available Bluetooth attributes, which can be further interacted with using other commands.

Usage:

> list-attributes [dev/local]

[dev/local]:

Device MAC address, object path, or “local” to list locally registered attributes (optional, lists all if omitted)

Example List attributes for specific service:

> list-attributes /org/bluez/hci0/dev_00_11_22_33_44_55/service001a

Example List attributes for specific characteristic:

> list-attributes /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c

Example List attributes for service on different device:

> list-attributes /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0020

Example List all Generic Access service attributes:

> list-attributes 0x1800

Example List all Battery Service attributes:

> list-attributes 0x180F

Example List all Device Name characteristic attributes:

> list-attributes 0x2A00

Example List attributes using full UUID:

> list-attributes 00001801-0000-1000-8000-00805f9b34fb

Example List attributes for custom service UUID:

> list-attributes 12345678-1234-5678-9abc-123456789abc

select-attribute

Selects a specific attribute on either the local or remote device for subsequent operations. Before you can read or write to an attribute, you must select it with this command. This establishes a context for many other commands (read, write, notify, etc.), specifying the attribute they should operate on.

Usage:

> select-attribute <attribute/UUID/local> [attribute/UUID]

<attribute/UUID/local>:

GATT attribute path, UUID, or “local” to select from local attributes

[attribute/UUID]:

Additional attribute path or UUID when using “local” (optional)

Example Select specific characteristic:

> select-attribute /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c

Example Select specific descriptor:

> select-attribute /org/bluez/hci0/dev_00_11_22_33_44_55/service0020/char0022/desc0024

Example Select service on different device:

> select-attribute /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service001a

Example Select Device Name characteristic:

> select-attribute 0x2A00

Example Select Battery Level characteristic:

> select-attribute 0x2A19

Example Select Client Characteristic Configuration descriptor:

> select-attribute 0x2902

Example Select Temperature characteristic using full UUID:

> select-attribute 00002a6e-0000-1000-8000-00805f9b34fb

Example Select custom characteristic:

> select-attribute 12345678-1234-5678-9abc-123456789abc

attribute-info

Displays detailed information about an attribute. If no attribute or UUID is specified, it shows information about the currently selected attribute. This command is useful for understanding the properties and capabilities of an attribute.

Usage:

> attribute-info [attribute/UUID]

[attribute/UUID]:

GATT attribute path or UUID to get info for (optional, uses current if omitted)

Example Show information for currently selected attribute:

> attribute-info

Example Show info for specific characteristic:

> attribute-info /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c

Example Show info for Battery Level characteristic:

> attribute-info 0x2A19

Example Show info for Device Name characteristic:

> attribute-info 0x2A00

Example Show info for Temperature characteristic:

> attribute-info 00002a6e-0000-1000-8000-00805f9b34fb

read

Reads the value of an attribute. Requires that an attribute be selected beforehand with select-attribute. The optional offset parameter can be used for attributes that allow partial reads.

Usage:

> read [offset]

Uses:

org.bluez.GattCharacteristic(5) method ReadValue

[offset]:

Byte offset to start reading from (optional, defaults to 0)

Example Read attribute value from offset 0:

> read

Example Read attribute value from offset 0 (explicit):

> read 0

Example Read attribute value starting from offset 4:

> read 4

Example Read attribute value starting from offset 10:

> read 10

Example Read attribute value starting from offset 16:

> read 16

write

Writes a value to an attribute. This command necessitates that an attribute be selected in advance using select-attribute. Data must be provided in hexadecimal format. Optional offset and type parameters can accommodate specific write requirements.

Usage:

> write <data=”xx xx …”> [offset] [type]

Uses:

org.bluez.GattCharacteristic(5) method WriteValue

<xx xx …>:

Hexadecimal data bytes to write to the attribute

[offset]:

Byte offset to start writing at (optional, defaults to 0)

[type]:

Write type - request, command, or reliable (optional, defaults to request)

Example Write “Hello” to attribute (ASCII bytes):

> write “48 65 6C 6C 6F”

Example Write binary data to attribute:

> write “01 02 03 04”

Example Write single byte value:

> write “FF”

Example Write 2 bytes starting at offset 4:

> write “01 02” 4

Example Write with write request (default):

> write “48 65 6C 6C 6F” 0 request

Example Write with write command (no response):

> write “01 02 03” 0 command

Example Write with reliable write:

> write “FF EE DD” 0 reliable

acquire-write

Acquires a Write file descriptor for a previously selected attribute. This is useful for applications that need a file descriptor to perform write operations.

Usage:

> acquire-write

Uses:

org.bluez.GattCharacteristic(5) method AcquireWrite

Example Acquire write file descriptor for current attribute:

> acquire-write

release-write

Releases the Write file descriptor acquired with acquire-write. This command is necessary to clean up resources after you’re done with the write operation.

Usage:

> release-write

Example Release write file descriptor for current attribute:

> release-write

acquire-notify

Acquires a Notify file descriptor for a previously selected attribute. This enables applications to listen for notifications on attribute value changes.

Usage:

> acquire-notify

Uses:

org.bluez.GattCharacteristic(5) method AcquireNotify

Example Acquire notify file descriptor for current attribute:

> acquire-notify

release-notify

Releases the Notify file descriptor obtained with acquire-notify. Ensures resources are freed once notification listening is no longer needed.

Usage:

> release-notify

Example Release notify file descriptor for current attribute:

> release-notify

notify

Enables or disables notifications for attribute value changes. Before this command can be used, the relevant attribute must be selected. This command allows applications to be notified of attribute changes without polling.

Usage:

> notify <on/off>

Uses:

org.bluez.GattCharacteristic(5) methods StartNotify, StopNotify

<on/off>:

Enable or disable notifications for the current attribute

Example Enable notifications for current attribute:

> notify on

Example Disable notifications for current attribute:

> notify off

clone

Creates a clone of a device or attribute. This can be useful for creating a backup or working with a copy for testing purposes.

Usage:

> clone [dev/attribute/UUID]

[dev/attribute/UUID]:

Device MAC address, attribute path, or UUID to clone (optional, clones current if omitted)

Example Clone entire device GATT database:

> clone 00:11:22:33:44:55

Example Clone another device:

> clone AA:BB:CC:DD:EE:FF

Example Clone specific service:

> clone /org/bluez/hci0/dev_00_11_22_33_44_55/service001a

Example Clone specific characteristic:

> clone /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c

Example Clone Generic Access service:

> clone 0x1800

Example Clone Battery Service:

> clone 0x180F

Example Clone Battery Level characteristic:

> clone 0x2A19

register-application

Registers a new application with the Bluetooth system, allowing for the management of services, characteristics, and descriptors under this application.

Usage:

> register-application [UUID …]

Uses:

org.bluez.GattManager(5) method RegisterApplication

[UUID …]:

Optional list of service UUIDs to register with the application

Example Register GATT application without specific UUIDs:

> register-application

Example Register application with Battery Service:

> register-application 0x180F

Example Register with Generic Access and Battery Service:

> register-application 0x1800 0x180F

Example Register application with custom service UUID:

> register-application 12345678-1234-5678-9abc-123456789abc

Example Register with multiple standard services:

> register-application 0x1800 0x180F 0x180A

unregister-application

Removes a previously registered application from the Bluetooth system.

Usage:

> unregister-application

Uses:

org.bluez.GattManager(5) method UnregisterApplication

Example Unregister current GATT application:

> unregister-application

register-service

Adds a new service under a registered application. This command is crucial for defining new services that devices can offer.

Usage:

> register-service <UUID> [handle]

<UUID>:

Service UUID to register (16-bit, 32-bit, or 128-bit format)

[handle]:

Specific attribute handle to assign (optional, auto-assigned if omitted)

Example Register Generic Access service (auto handle):

> register-service 0x1800

Example Register Battery Service (auto handle):

> register-service 0x180F

Example Register Device Information service (auto handle):

> register-service 0x180A

Example Register Generic Access service at handle 1:

> register-service 0x1800 0x0001

Example Register Battery Service at handle 16:

> register-service 0x180F 0x0010

Example Register Device Info service at handle 32:

> register-service 0x180A 0x0020

Example Register custom service (auto handle):

> register-service 12345678-1234-5678-9abc-123456789abc

Example Register custom service at specific handle:

> register-service 12345678-1234-5678-9abc-123456789abc 0x0050

unregister-service

Removes a service from a registered application, effectively ceasing its availability.

Usage:

> unregister-service <UUID/object>

<UUID/object>:

Service UUID or object path of the service to unregister

Example Unregister Generic Access service:

> unregister-service 0x1800

Example Unregister Battery Service:

> unregister-service 0x180F

Example Unregister custom service:

> unregister-service 12345678-1234-5678-9abc-123456789abc

Example Unregister service by object path:

> unregister-service /org/bluez/example/service0

Example Unregister another service:

> unregister-service /org/bluez/example/service1

register-includes

Marks a service as included within another service, allowing for service hierarchies and complex service structures.

Usage:

> register-includes <UUID> [handle]

<UUID>:

Service UUID to register as included service

[handle]:

Specific attribute handle to assign (optional, auto-assigned if omitted)

Example Register Generic Access as included service:

> register-includes 0x1800

Example Register Battery Service as included at handle 21:

> register-includes 0x180F 0x0015

Example Register custom service as included:

> register-includes 12345678-1234-5678-9abc-123456789abc

unregister-includes

Removes an included service relationship, simplifying the service structure.

Usage:

> unregister-includes <Service-UUID> <Inc-UUID>

<Service-UUID>:

Parent service UUID that contains the included service

<Inc-UUID>:

Included service UUID to remove from the parent service

Example Unregister Battery Service inclusion from Generic Access:

> unregister-includes 0x1800 0x180F

Example Unregister Device Info inclusion from custom service:

> unregister-includes 12345678-1234-5678-9abc-123456789abc 0x180A

register-characteristic

Introduces a new characteristic under a service, specifying its properties and access permissions with flags.

Usage:

> register-characteristic <UUID> <Flags=read,write,notify…> [handle]

<UUID>:

Characteristic UUID to register (16-bit, 32-bit, or 128-bit format)

<Flags=read,write,notify…>:

Comma-separated list of characteristic properties and permissions

[handle]:

Specific attribute handle to assign (optional, auto-assigned if omitted)

Example Register Device Name (read-only):

> register-characteristic 0x2A00 read

Example Register Battery Level (read + notifications):

> register-characteristic 0x2A19 read,notify

Example Register Heart Rate Measurement (notify-only):

> register-characteristic 0x2A37 notify

Example Register Device Name (read + write):

> register-characteristic 0x2A00 read,write

Example Register Battery Level (read + write + notify):

> register-characteristic 0x2A19 read,write,notify

Example Register Temperature (read + indications):

> register-characteristic 0x2A6E read,indicate

Example Register Device Name at handle 3:

> register-characteristic 0x2A00 read 0x0003

Example Register Battery Level at handle 19:

> register-characteristic 0x2A19 read,notify 0x0013

Example Register custom characteristic with full capabilities:

> register-characteristic 12345678-1234-5678-9abc-123456789abc read,write,notify

Example Register custom write-only characteristic:

> register-characteristic ABCD1234-ABCD-1234-ABCD-123456789ABC write-without-response

Example Register with all flags:

> register-characteristic 0x2A00 read,write,write-without-response,notify,indicate

unregister-characteristic

Eliminates a characteristic from a service, removing its functionality.

Usage:

> unregister-characteristic <UUID/object>

<UUID/object>:

Characteristic UUID or object path of the characteristic to unregister

Example Unregister Device Name characteristic:

> unregister-characteristic 0x2A00

Example Unregister Battery Level characteristic:

> unregister-characteristic 0x2A19

Example Unregister custom characteristic:

> unregister-characteristic 12345678-1234-5678-9abc-123456789abc

Example Unregister characteristic by object path:

> unregister-characteristic /org/bluez/example/service0/char0

Example Unregister another characteristic:

> unregister-characteristic /org/bluez/example/service1/char1

register-descriptor

Adds a descriptor to a characteristic, further defining its behavior and access controls.

Usage:

> register-descriptor <UUID> <Flags=read,write…> [handle]

<UUID>:

Descriptor UUID to register (16-bit, 32-bit, or 128-bit format)

<Flags=read,write…>:

Comma-separated list of descriptor properties and permissions

[handle]:

Specific attribute handle to assign (optional, auto-assigned if omitted)

Example Register Client Characteristic Configuration:

> register-descriptor 0x2902 read,write

Example Register Characteristic User Description:

> register-descriptor 0x2901 read

Example Register Characteristic Presentation Format:

> register-descriptor 0x2904 read

Example Register CCCD at handle 5:

> register-descriptor 0x2902 read,write 0x0005

Example Register User Description at handle 21:

> register-descriptor 0x2901 read 0x0015

Example Register custom descriptor:

> register-descriptor 12345678-1234-5678-9abc-123456789abc read,write

Example Register custom read-only descriptor:

> register-descriptor ABCD1234-ABCD-1234-ABCD-123456789ABC read

Example Register Valid Range descriptor:

> register-descriptor 0x2906 read

Example Register External Report Reference:

> register-descriptor 0x2907 read

Example Register Report Reference:

> register-descriptor 0x2908 read

unregister-descriptor

Removes a descriptor from a characteristic, simplifying its behavior.

Usage:

> unregister-descriptor <UUID/object>

<UUID/object>:

Descriptor UUID or object path of the descriptor to unregister

Example Unregister Client Characteristic Configuration:

> unregister-descriptor 0x2902

Example Unregister Characteristic User Description:

> unregister-descriptor 0x2901

Example Unregister custom descriptor:

> unregister-descriptor 12345678-1234-5678-9abc-123456789abc

Example Unregister descriptor by object path:

> unregister-descriptor /org/bluez/example/service0/char0/desc0

Example Unregister another descriptor:

> unregister-descriptor /org/bluez/example/service1/char1/desc1

RESOURCES

http://www.bluez.org

REPORTING BUGS

linux-bluetooth@vger.kernel.org