Perform Bluetooth Low Energy GATT client functions

Prerequisites

Before you begin, set up the device, go to bluetoothctl menu, or menu gatt submenu as described in Set up the device for Bluetooth Low Energy GATT functions.

Connect to a remote device

To connect to a remote device, run the following command from the bluetoothctl menu:

connect <bt_address>

Parameters <bt_address> is the Bluetooth address of the remote device.

To get the Bluetooth address of the remote device, run a Bluetooth Low Energy GATT scan.

Example To connect to a server device with <bt_address> 6D:38:AF:C6:B5:62, run the following command:

connect 6D:38:AF:C6:B5:62

Sample output

[bluetooth]# connect 6D:38:AF:C6:B5:62
Attempting to connect to 6D:38:AF:C6:B5:62
[CHG] Device 6D:38:AF:C6:B5:62 Connected: yes
Connection successful
[NEW] Primary Service (Handle 0x0000)
      /org/bluez/hci0/dev_6D_38_AF_C6_B5_62/service0001
      00001801-0000-1000-8000-00805f9b34fb
      Generic Attribute Profile
[NEW] Characteristic (Handle 0x0000)
      /org/bluez/hci0/dev_6D_38_AF_C6_B5_62/service0001/char0002
      00002a05-0000-1000-8000-00805f9b34fb
      Service Changed
[NEW] Characteristic (Handle 0x0000)
      /org/bluez/hci0/dev_6D_38_AF_C6_B5_62/service0001/char0004
      00002b3a-0000-1000-8000-00805f9b34fb
      Server Supported Features
[NEW] Characteristic (Handle 0x0000)
      /org/bluez/hci0/dev_6D_38_AF_C6_B5_62/service0001/char0006
      00002b29-0000-1000-8000-00805f9b34fb
      Client Supported Features
[NEW] Characteristic (Handle 0x0000)
      /org/bluez/hci0/dev_6D_38_AF_C6_B5_62/service0001/char0008
      00002b2a-0000-1000-8000-00805f9b34fb
      Database Hash
[CHG] Device 6D:38:AF:C6:B5:62 UUIDs: 00001800-0000-1000-8000-00805f9b34fb
[CHG] Device 6D:38:AF:C6:B5:62 UUIDs: 00001801-0000-1000-8000-00805f9b34fb
[CHG] Device 6D:38:AF:C6:B5:62 ServicesResolved: yes

Start Bluetooth Low Energy GATT scan

To start a Bluetooth Low Energy GATT scan, run the following command from the bluetoothctl menu:

scan le

To get the scan results, the remote device must advertise using any Bluetooth Low Energy application.

Sample output

[MyDeviceB]# scan le
Discovery started
[CHG] Controller 22:22:9B:2C:79:1E Discovering: yes
[CHG] Device F8:7D:76:9D:9B:6B RSSI: -70
[NEW] Device A4:30:7A:EE:AF:EF [TV] MyDeviceA (43)
[NEW] Device 52:2F:07:6F:AA:93 52-2F-07-6F-AA-93
[CHG] Device A4:30:7A:EE:AF:EF ManufacturerData Key: 0x0075
[CHG] Device A4:30:7A:EE:AF:EF ManufacturerData Value:
42 04 01 01 e7 a4 30 7a ee af ef a6 30 7a ee af B..... 0z....0z....
ee 01 3b 00 00 00 00 00                          ......
[CHG] Device A4:30:7A:EE:AF:EF Modalias: bluetooth:v04E8p8080d0000
[CHG] Device A4:30:7A:EE:AF:EF UUIDs: 0000110a-0000-1000-8000-00805f9b34fb
[CHG] Device A4:30:7A:EE:AF:EF UUIDs: 0000110b-0000-1000-8000-00805f9b34fb
[CHG] Device A4:30:7A:EE:AF:EF UUIDs: 0000110c-0000-1000-8000-00805f9b34fb
[CHG] Device A4:30:7A:EE:AF:EF UUIDs: 0000110e-0000-1000-8000-00805f9b34fb
[CHG] Device A4:30:7A:EE:AF:EF UUIDs: 00001112-0000-1000-8000-00805f9b34fb
[CHG] Device A4:30:7A:EE:AF:EF UUIDs: 0000111f-0000-1000-8000-00805f9b34fb
[CHG] Device A4:30:7A:EE:AF:EF UUIDs: 00001200-0000-1000-8000-00805f9b34fb
[CHG] Device A4:30:7A:EE:AF:EF ManufacturerData Key: 0x0075
[CHG] Device A4:30:7A:EE:AF:EF ManufacturerData Value:
42 04 01 01 e7 a4 30 7a ee af ef a6 30 7a ee af B..... 0z....0z....
ee 01 3b 00 00 00 00 00                          ......
[CHG] Device A4:30:7A:EE:AF:EF ManufacturerData Key: 0xff19
[CHG] Device A4:30:7A:EE:AF:EF ManufacturerData Value:
00 75 00 09 01 00 00 00 06 01 00 00 00 00 00 00 .u..................
00 00 00 00 00 00 00 00                         ................
[CHG] Device F8:7D:76:9D:9B:6B RSSI: -60
[CHG] Device A4:30:7A:EE:AF:EF ManufacturerData Key: 0x0075
[CHG] Device A4:30:7A:EE:AF:EF ManufacturerData Value:
42 04 01 20 e7 20 0d 00 02 01 2b 01 01 00 01 00 B .. ..... .......
00 00 00 00 00 00 00 00                        ........
[CHG] Device A4:30:7A:EE:AF:EF ManufacturerData Key: 0xff19
[CHG] Device A4:30:7A:EE:AF:EF ManufacturerData Value:
00 75 00 09 01 00 00 00 06 01 00 00 00 00 00 00  .u.............
00 00 00 00 00 00 00 00                            .......
[NEW] Device 4A:04:87:DF:CB:35 4A-04-87-DF-CB-35
[DEL] Device 52:2F:07:6F:AA:93 52-2F-07-6F-AA-93

Stop Bluetooth Low Energy GATT scan

To stop a Bluetooth Low Energy GATT scan, run the following command from the bluetoothctl menu:

scan off

Sample output

[MyDeviceB]# scan off
Discovery stopped
[CHG] Device A4:30:7A:EE:AF:EF RSSI is nil
[CHG] Device F8:7D:76:9D:9B:6B RSSI is nil
[CHG] Controller 22:22:9B:2C:79:1E Discovering: no

Get the list of attributes

To get the list of attributes of the remote device, run the following command from the menu gatt menu:

list-attributes <bt_address>

Parameters <bt_address> is the address of the remote device. Example To list the attributes of the remote device with the address 6D:38:AF:C6:B5:62, run the following command:

list-attributes 6D:38:AF:C6:B5:62

Sample output

[MyDeviceB]# list-attributes 6D:38:AF:C6:B5:62
Primary Service (Handle 0x0000)
      /org/bluez/hci0/dev_6D_38_AF_C6_B5_62/service0001
      00001801-0000-1000-8000-00805f9b34fb
      Generic Attribute Profile
Characteristic (Handle 0x0000)
      /org/bluez/hci0/dev_6D_38_AF_C6_B5_62/service0001/char0002
      00002a05-0000-1000-8000-00805f9b34fb
      Service Changed
Characteristic (Handle 0x0000)
      /org/bluez/hci0/dev_6D_38_AF_C6_B5_62/service0001/char0004
      00002b3a-0000-1000-8000-00805f9b34fb
      Server Supported Features
Characteristic (Handle 0x0000)
      /org/bluez/hci0/dev_6D_38_AF_C6_B5_62/service0001/char0006
      00002b29-0000-1000-8000-00805f9b34fb
      Client Supported Features
Characteristic (Handle 0x0000)
      /org/bluez/hci0/dev_6D_38_AF_C6_B5_62/service0001/char0008
      00002b2a-0000-1000-8000-00805f9b34fb
      Database Hash

Get attribute information

To get the information of an attribute, run the following command from the menu gatt menu:

attribute-info <attribute/UUID>

Parameters <attribute/UUID> is the UUID or the attribute path. Example To get the information of an attribute with the UUID 00002b29-0000-1000-8000-00805f9b34fb, run the following command:

attribute-info 00002b29-0000-1000-8000-00805f9b34fb

Sample output

[MyDeviceB]# attribute-info 00002b29-0000-1000-8000-00805f9b34fb
Characteristic - Client Supported Features
      UUID: 00002b29-0000-1000-8000-00805f9b34fb
      Service: /org/bluez/hci0/dev_73_F4_3F_FA_0A_DF/service0001
      Flags: read
      Flags: write
      MTU: 0x0205

Select an attribute

To select the attribute using the UUID or path, run the following command from the menu gatt menu:

select-attribute <attribute/UUID>

Parameters <attribute/UUID> is the UUID or path of the attribute. Example

To select an attribute using the UUID 00006677-0000-1000-8000-00805f9b34fb, run the following command:

select-attribute 00006677-0000-1000-8000-00805f9b34fb

Sample output

Characteristic User Description
[MyDeviceB]# select-attribute 00006677-0000-1000-8000-00805f9b34fb
<lect-attribute 00006677-0000-1000-8000-00805f9b34fb[MyDeviceB:/service0028/char0029/desc002c]#
[MyDeviceB:/service0028/char0029/desc002c]#

To select an attribute using the attribute path /org/bluez/hci0/dev_6C_5F_B9_ED_5B_48/service0001/char0002, run the following command:

select-attribute /org/bluez/hci0/dev_6C_5F_B9_ED_5B_48/service0001/char0002

Sample output

[MyDeviceB:/service0001/char0004]# ED_5B_48/service0001/char0002
[MyDeviceB:/service0001/char0002]#

Read a characteristic value

To read a characteristic value, do the following from the menu gatt menu:

Select the intended attribute.
Read the selected attribute by running the following command:
read 0

Sample output

[MyDeviceB:/service0028/char0029]# read 0
Attempting to read /org/bluez/hci0/dev_64_8C_C7_03_C4_B0/service0028/char0029
[CHG] Attribute /org/bluez/hci0/dev_64_8C_C7_03_C4_B0/service0028/char0029 Value:
   11
   11
[MyDeviceB:/service0028/char0029]#

Write a characteristic value

To write a characteristic value, do the following from the menu gatt menu:

Select the intended attribute.
Write a value to the selected attribute by running the following command:
write "<value>"
Parameters <value> is the value you intend to write. Example To write the attribute value as 0x11, run the following command:
write "0x11"

Sample output

[MyDeviceB:/service0028/char0029]# read 0b
Attempting to read /org/bluez/hci0/dev_64_8C_C7_03_C4_B0/service0028/char0029
[CHG] Attribute /org/bluez/hci0/dev_64_8C_C7_03_C4_B0/service0028/char0029 Value:
   22
   22
[MyDeviceB:/service0028/char0029]# write "0x11"
Attempting to write /org/bluez/hci0/dev_64_8C_C7_03_C4_B0/service0028/char0029
[MyDeviceB:/service0028/char0029]# read 0
Attempting to read /org/bluez/hci0/dev_64_8C_C7_03_C4_B0/service0028/char0029
[CHG] Attribute /org/bluez/hci0/dev_64_8C_C7_03_C4_B0/service0028/char0029 Value:
   11    
   11
[MyDeviceB:/service0028/char0029]#

Read a descriptor value

To read a descriptor value, do the following from the menu gatt menu:

Select the intended attribute.
Read the selected attribute by running the following command:
read 0

Sample output

[MyDeviceB]# select-attribute 00006677-0000-1000-8000-00805f9b34fb
<lect-attribute 00006677-0000-1000-8000-00805f9b34fb[MyDeviceB:/service0028/char0029/desc002c]#
[MyDeviceB:/service0028/char0029/desc002c]#
[MyDeviceB:/service0028/char0029/desc002c]# read 0
Attempting to read /org/bluez/hci0/dev_55_B1_D2_67_7C_CD/service0028/char0029/desc002c
[CHG] Attribute /org/bluez/hci0/dev_55_B1_D2_67_7C_CD/service0028/char0029/desc002c Value:
   00
   00
[MyDeviceB:/service0028/char0029/desc002c]#

Write a descriptor value

To write a descriptor value, do the following from the menu gatt menu:

Select the intended attribute.
Write a value to the selected attribute by running the following command:
write "<value>"
Parameters <value> is the value you intend to write. Example To write the attribute value as 0x11, run the following command:
write "0x11"

Sample output

[MyDeviceB]# select-attribute 00006677-0000-1000-8000-00805f9b34fb
<lect-attribute 00006677-0000-1000-8000-00805f9b34fb[MyDeviceB:/service0028/char0029/desc002c]#
[MyDeviceB:/service0028/char0029/desc002c]#
[MyDeviceB:/service0028/char0029/desc002c]# read 0
Attempting to read /org/bluez/hci0/dev_55_B1_D2_67_7C_CD/service0028/char0029/desc002c
[CHG] Attribute /org/bluez/hci0/dev_55_B1_D2_67_7C_CD/service0028/char0029/desc002c Value:
   00
   00
[MyDeviceB:/service0028/char0029/desc002c]# write "0x11"
Attempting to write /org/bluez/hci0/dev_55_B1_D2_67_7C_CD/service0028/char0029/desc002c
[MyDeviceB:/service0028/char0029/desc002c]# read 0
Attempting to read /org/bluez/hci0/dev_55_B1_D2_67_7C_CD/service0028/char0029/desc002c
[CHG] Attribute /org/bluez/hci0/dev_55_B1_D2_67_7C_CD/service0028/char0029/desc002c Value:
   11
   11
[MyDeviceB:/service0028/char0029/desc002c]#

Read an encrypted characteristic value

To read an encrypted characteristic value, do the following from the menu gatt menu:

Select the intended attribute.
Read the selected attribute by running the following command:
read 0
Enter yes when prompted to confirm the reading.

Sample output

[MyDeviceB:/service0028/char0029]# read 0
Attempting to read /org/bluez/hci0/dev_4F_A4_EC_0D_D2_F2/service0028/char0029
[DEL] Device 60:A3:37:5A:35:5F 60-A3-37-5A-35-5F
[NEW] Device 60:A3:37:5A:35:5F 60-A3-37-5A-35-5F
Request confirmation
[agent] Confirm passkey 161326 (yes/no): yes
[CHG] Attribute /org/bluez/hci0/dev_4F_A4_EC_0D_D2_F2/service0028/char0029 Value:
   00
[CHG] Device D4:8A:39:78:27:41 Address: D4:8A:39:78:27:41
[CHG] Device D4:8A:39:78:27:41 AddressType: public
   00
[CHG] Device D4:8A:39:78:27:41 Bonded: yes
[CHG] Device D4:8A:39:78:27:41 Paired: yes
[CHG] Device D4:8A:39:78:27:41 Class: 0x005a020c
[CHG] Device D4:8A:39:78:27:41 Icon: phone

Write an encrypted characteristic value

To write an encrypted characteristic value, do the following from the menu gatt menu:

Select the intended attribute.
Write a value to the selected attribute by running the following command:
write "<value>"
Parameters <value> is the value you intend to write. Example To write the attribute value as 0x11, run the following command:
write "0x11"
Enter yes when prompted to confirm writing.

Turn on notifications for an attribute

To turn on notifications for an attribute, do the following from the menu gatt menu:

Select the intended attribute.
Enable notifications for the attribute by running the following command:
notify on
You get notifications of any changes to the attribute.

Sample output

[MyDeviceB:/service0028/char0029]# notify on
[CHG] Attribute /org/bluez/hci0/dev_44_38_FB_67_B2_E2/service0028/char0029 Notifying: yes
Notify started
[CHG] Attribute /org/bluez/hci0/dev_44_38_FB_67_B2_E2/service0028/char0029 Value:
   55                                            U
[CHG] Attribute /org/bluez/hci0/dev_44_38_FB_67_B2_E2/service0028/char0029 Value:
   88                                            .
[CHG] Attribute /org/bluez/hci0/dev_44_38_FB_67_B2_E2/service0028/char0029 Value:
   55 55                                         UU
[CHG] Device D4:8A:39:78:27:41 RSSI: -74
[CHG] Attribute /org/bluez/hci0/dev_44_38_FB_67_B2_E2/service0028/char0029 Value:
   55                                            U
[CHG] Attribute /org/bluez/hci0/dev_44_38_FB_67_B2_E2/service0028/char0029 Value:
   11                                            U
[CHG] Attribute /org/bluez/hci0/dev_44_38_FB_67_B2_E2/service0028/char0029 Value:
   66                                            f

Turn off notifications for an attribute

To turn off notifications for an attribute, do the following from the menu gatt menu:

Select the intended attribute.
Disable notifications for the attribute by running the following command:
notify off

Sample output

[MyDeviceB:/service0028/char0029]# notify off
[CHG] Attribute /org/bluez/hci0/dev_44_38_FB_67_B2_E2/service0028/char0029 Notifying: no
Notify stopped

Introduction

Architecture

Key Documents

Technologies

System

Release Notes

Prerequisites

Connect to a remote device

Start Bluetooth Low Energy GATT scan

Stop Bluetooth Low Energy GATT scan

Get the list of attributes

Get attribute information

Select an attribute

Read a characteristic value

Write a characteristic value

Read a descriptor value

Write a descriptor value

Read an encrypted characteristic value

Write an encrypted characteristic value

Turn on notifications for an attribute

Turn off notifications for an attribute