bluetoothctl-gatt(1) Linux System Administration bluetoothctl-gatt(1)

bluetoothctl-gatt - Generic Attribute Submenu

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.

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.

> list-attributes [dev/local]
[dev/local]
Device MAC address, object path, or "local" to list locally registered attributes (optional, lists all if omitted)
> list-attributes /org/bluez/hci0/dev_00_11_22_33_44_55/service001a
> list-attributes /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c
> list-attributes /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0020
> list-attributes 0x1800
> list-attributes 0x180F
> list-attributes 0x2A00
> list-attributes 00001801-0000-1000-8000-00805f9b34fb
> list-attributes 12345678-1234-5678-9abc-123456789abc

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.

> 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)
> select-attribute /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c
> select-attribute /org/bluez/hci0/dev_00_11_22_33_44_55/service0020/char0022/desc0024
> select-attribute /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service001a
> select-attribute 0x2A00
> select-attribute 0x2A19
> select-attribute 0x2902
> select-attribute 00002a6e-0000-1000-8000-00805f9b34fb
> select-attribute 12345678-1234-5678-9abc-123456789abc

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.

> attribute-info [attribute/UUID]
[attribute/UUID]
GATT attribute path or UUID to get info for (optional, uses current if omitted)
> attribute-info
> attribute-info /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c
> attribute-info 0x2A19
> attribute-info 0x2A00
> attribute-info 00002a6e-0000-1000-8000-00805f9b34fb

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.

> read [offset]
org.bluez.GattCharacteristic(5) method ReadValue
[offset]
Byte offset to start reading from (optional, defaults to 0)
> read
> read 0
> read 4
> read 10
> read 16

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.

> write <data="xx xx ..."> [offset] [type]
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)
> write "48 65 6C 6C 6F"
> write "01 02 03 04"
> write "FF"
> write "01 02" 4
> write "48 65 6C 6C 6F" 0 request
> write "01 02 03" 0 command
> write "FF EE DD" 0 reliable

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

> acquire-write
org.bluez.GattCharacteristic(5) method AcquireWrite
> acquire-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.

> release-write
> release-write

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

> acquire-notify
org.bluez.GattCharacteristic(5) method AcquireNotify
> acquire-notify

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

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

> notify <on/off>
org.bluez.GattCharacteristic(5) methods StartNotify, StopNotify
<on/off>
Enable or disable notifications for the current attribute
> notify on
> notify off

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

> clone [dev/attribute/UUID]
[dev/attribute/UUID]
Device MAC address, attribute path, or UUID to clone (optional, clones current if omitted)
> clone 00:11:22:33:44:55
> clone AA:BB:CC:DD:EE:FF
> clone /org/bluez/hci0/dev_00_11_22_33_44_55/service001a
> clone /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c
> clone 0x1800
> clone 0x180F
> clone 0x2A19

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

> register-application [UUID ...]
org.bluez.GattManager(5) method RegisterApplication
[UUID ...]
Optional list of service UUIDs to register with the application
> register-application
> register-application 0x180F
> register-application 0x1800 0x180F
> register-application 12345678-1234-5678-9abc-123456789abc
> register-application 0x1800 0x180F 0x180A

Removes a previously registered application from the Bluetooth system.

> unregister-application
org.bluez.GattManager(5) method UnregisterApplication
> unregister-application

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

> 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)
> register-service 0x1800
> register-service 0x180F
> register-service 0x180A
> register-service 0x1800 0x0001
> register-service 0x180F 0x0010
> register-service 0x180A 0x0020
> register-service 12345678-1234-5678-9abc-123456789abc
> register-service 12345678-1234-5678-9abc-123456789abc 0x0050

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

> unregister-service <UUID/object>
<UUID/object>
Service UUID or object path of the service to unregister
> unregister-service 0x1800
> unregister-service 0x180F
> unregister-service 12345678-1234-5678-9abc-123456789abc
> unregister-service /org/bluez/example/service0
> unregister-service /org/bluez/example/service1

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

> register-includes <UUID> [handle]
<UUID>
Service UUID to register as included service
[handle]
Specific attribute handle to assign (optional, auto-assigned if omitted)
> register-includes 0x1800
> register-includes 0x180F 0x0015
> register-includes 12345678-1234-5678-9abc-123456789abc

Removes an included service relationship, simplifying the service structure.

> 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
> unregister-includes 0x1800 0x180F
> unregister-includes 12345678-1234-5678-9abc-123456789abc 0x180A

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

> 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)
> register-characteristic 0x2A00 read
> register-characteristic 0x2A19 read,notify
> register-characteristic 0x2A37 notify
> register-characteristic 0x2A00 read,write
> register-characteristic 0x2A19 read,write,notify
> register-characteristic 0x2A6E read,indicate
> register-characteristic 0x2A00 read 0x0003
> register-characteristic 0x2A19 read,notify 0x0013
> register-characteristic 12345678-1234-5678-9abc-123456789abc read,write,notify
> register-characteristic ABCD1234-ABCD-1234-ABCD-123456789ABC write-without-response
> register-characteristic 0x2A00 read,write,write-without-response,notify,indicate

Eliminates a characteristic from a service, removing its functionality.

> unregister-characteristic <UUID/object>
<UUID/object>
Characteristic UUID or object path of the characteristic to unregister
> unregister-characteristic 0x2A00
> unregister-characteristic 0x2A19
> unregister-characteristic 12345678-1234-5678-9abc-123456789abc
> unregister-characteristic /org/bluez/example/service0/char0
> unregister-characteristic /org/bluez/example/service1/char1

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

> 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)
> register-descriptor 0x2902 read,write
> register-descriptor 0x2901 read
> register-descriptor 0x2904 read
> register-descriptor 0x2902 read,write 0x0005
> register-descriptor 0x2901 read 0x0015
> register-descriptor 12345678-1234-5678-9abc-123456789abc read,write
> register-descriptor ABCD1234-ABCD-1234-ABCD-123456789ABC read
> register-descriptor 0x2906 read
> register-descriptor 0x2907 read
> register-descriptor 0x2908 read

Removes a descriptor from a characteristic, simplifying its behavior.

> unregister-descriptor <UUID/object>
<UUID/object>
Descriptor UUID or object path of the descriptor to unregister
> unregister-descriptor 0x2902
> unregister-descriptor 0x2901
> unregister-descriptor 12345678-1234-5678-9abc-123456789abc
> unregister-descriptor /org/bluez/example/service0/char0/desc0
> unregister-descriptor /org/bluez/example/service1/char1/desc1

http://www.bluez.org

<linux-bluetooth@vger.kernel.org>

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

November 2022 BlueZ