Skip to main content

​
Prerequisites

Before you begin, set up the device 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:
  1. Select the intended attribute.
  2. 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:
  1. Select the intended attribute.
  2. 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:
  1. Select the intended attribute.
  2. 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 "0x11"
Attempting to write /org/bluez/hci0/dev_55_B1_D2_67_7C_CD/service0028/char0029/desc002c
[MyDeviceB:/service0028/char0829/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]#

​
Write a descriptor value

To write a descriptor value, do the following from the menu gatt menu:
  1. Select the intended attribute.
  2. 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/char0829/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:
  1. Select the intended attribute.
  2. Read the selected attribute by running the following command: 
    read 0
  3. 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:
  1. Select the intended attribute.
  2. 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"
  3. 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:
  1. Select the intended attribute.
  2. 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:
  1. Select the intended attribute.
  2. 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