[RR Bluetooth] installing dbus-python

In order to use bluez in python, dbus-python has to be installed

Although many said that it cannot be installed by pip, however, I am using virtualenv, it's worth to give it a try.

$ pip install dbus-python

The first error is:

checking for DBUS_GLIB... no
configure: error: Package requirements (dbus-glib-1 >= 0.70) were not met:
No package 'dbus-glib-1' found

Apparently dbus-gdb-1-dev is missing, so I installed "libdbus-glib-1-dev"

and surprisingly, 

Successfully installed dbus-python

dbus-python-1.2.4 is installed by pip !!!

[RR Bluetooth] gatttool - What HCI Commands are Sent by gatttool (6) char-read-hnd, char-read-uuid

According to BT Spec Core 4.2, "4.9 CHARACTERISTIC VALUE WRITE"

There are five sub-procedures that can be used to write a Characteristic Value: Write Without Response, Signed Write Without Response, Write Characteristic Value, Write Long Characteristic Values and Reliable Writes.

char-write-cmd  <handle> <new value>           Characteristic Value Write (No response)

Write Command

< ACL Data TX: Handle 71 flags 0x00 dlen 8                     [hci0] 20.201215      ATT: Write Command (0x52) len 3        Handle: 0x0029          Data: 01

< 02 47 00 08 00 04 00 04 00 52 29 00 01 

> HCI Event: Number of Completed Packets (0x13) plen 5         [hci0] 20.779127        Num handles: 1        Handle: 71        Count: 1

> 04 13 05 01 47 00 01 00 

char-write-req  <handle> <new value>           Characteristic Value Write (Write Request)

Write Request

< ACL Data TX: Handle 71 flags 0x00 dlen 8                     [hci0] 61.390350
      ATT: Write Request (0x12) len 3
        Handle: 0x0029
          Data: 00

< 02 47 00 08 00 04 00 04 00 12 29 00 00 

> HCI Event: Number of Completed Packets (0x13) plen 5         [hci0] 61.524557
        Num handles: 1
        Handle: 71
        Count: 1

> 04 13 05 01 47 00 01 00 

Write Response

> ACL Data RX: Handle 71 flags 0x02 dlen 5                     [hci0] 61.587358
      ATT: Write Response (0x13) len 0

> 02 47 20 05 00 01 00 04 00 13 

[RR Bluetooth] gatttool - What HCI Commands are Sent by gatttool (5) char-read-hnd, char-read-uuid

According to BT Spec Core 4.2, 4.8 CHARACTERISTIC VALUE READ

There are four sub-procedures that can be used to read a Characteristic Value: Read Characteristic Value, Read Using Characteristic UUID, Read Long Characteristic Values, and Read Multiple Characteristic Values.

it looks like gatttool only support the first two.

char-read-hnd   <handle>                       Characteristics Value/Descriptor Read by handle

This sub-procedure is used to read a Characteristic Value from a server when the client knows the Characteristic Value Handle

Read Request

< ACL Data TX: Handle 71 flags 0x00 dlen 7                      [hci0] 3.380041
      ATT: Read Request (0x0a) len 2
        Handle: 0x0001

< 02 47 00 07 00 03 00 04 00 0A 01 00 

> HCI Event: Number of Completed Packets (0x13) plen 5          [hci0] 4.003567
        Num handles: 1
        Handle: 71
        Count: 1

 > 04 13 05 01 47 00 01 00 

Read Response

> ACL Data RX: Handle 71 flags 0x02 dlen 7                      [hci0] 4.072557
      ATT: Read Response (0x0b) len 2
        Value: 0018

> 02 47 20 07 00 03 00 04 00 0B 00 18 

char-read-uuid  <UUID> [start hnd] [end hnd]   Characteristics Value/Descriptor Read by UUID

This sub-procedure is used to read a Characteristic Value from a server when the client only knows the characteristic UUID and does not know the handle of the characteristic. （4.8.2 Read Using Characteristic UUID @ Core 4.2) This is typically the handle range for the service in which the characteristic belongs.

Read By Type Request

< ACL Data TX: Handle 71 flags 0x00 dlen 11                     [hci0] 7.468811
      ATT: Read By Type Request (0x08) len 6
        Handle range: 0x0001-0x000b
        Attribute type: Characteristic (0x2803)

< 02 47 00 0B 00 07 00 04 00 08 01 00 0B 00 03 28 

> HCI Event: Number of Completed Packets (0x13) plen 5          [hci0] 7.513950
        Num handles: 1
        Handle: 71
        Count: 1

> 04 13 05 01 47 00 01 00 

Read By Type Response

> ACL Data RX: Handle 71 flags 0x02 dlen 27                     [hci0] 7.583487
      ATT: Read By Type Response (0x09) len 22
        Attribute data length: 7
        Attribute data list: 3 entries
        Handle: 0x0002
        Value: 020300002a
        Handle: 0x0004
        Value: 020500012a
        Handle: 0x0006
        Value: 020700022a

> 02 47 20 1B 00 17 00 04 00 09 07 02 00 02 03 00 00 2A 04 00
  02 05 00 01 2A 06 00 02 07 00 02 2A 

Note: the Read Blob Request would be used to read the remaining octets of a

long attribute value.

[RR Bluetooth] gatttool - What HCI Commands are Sent by gatttool (4) char-desc

char-desc       [start hnd] [end hnd]          Characteristics Descriptor Discovery

It is defined in "4.7 CHARACTERISTIC DESCRIPTOR DISCOVERY" in Bluetooth Specification Core 4.2.

This sub-procedure is used by a client to find all the characteristic descriptor’s
Attribute Handles and Attribute Types within a characteristic definition when
only the characteristic handle range is known

Find Information Request:

< ACL Data TX: Handle 71 flags 0x00 dlen 9                      [hci0] 5.648413
      ATT: Find Information Request (0x04) len 4
        Handle range: 0x0001-0x0002

< 02 47 00 09 00 05 00 04 00 04 01 00 02 00 

> HCI Event: Number of Completed Packets (0x13) plen 5          [hci0] 5.803482
        Num handles: 1
        Handle: 71
        Count: 1

> 04 13 05 01 47 00 01 00 

Find Information Response

> ACL Data RX: Handle 71 flags 0x02 dlen 14                     [hci0] 5.873329
      ATT: Find Information Response (0x05) len 9
        Format: UUID-16 (0x01)
        Handle: 0x0001
        UUID: Primary Service (0x2800)
        Handle: 0x0002
        UUID: Characteristic (0x2803)

> 02 47 20 0E 00 0A 00 04 00 05 01 01 00 00 28 02 00 03 28 

Note: The sub-procedure is complete when the Error Response is received and the Error Code is set to Attribute Not Found or the Find Information Response has an Attribute Handle that is equal to the Ending Handle of the request. (4.7.1 Discover All Characteristic Descriptors@ BT Spec Core 4.2)

[RR Bluetooth] gatttool - What HCI Commands are Sent by gatttool (3) characteristics

characteristics [start hnd [end hnd [UUID]]]   Characteristics Discovery

It follows 4.6 CHARACTERISTIC DISCOVERY at Bluetooth Specification Core 4.2

"There are two sub-procedures that can be used for characteristic discovery: Discover All Characteristics of a Service and Discover Characteristics by UUID."

Discover All Characteristics of a Service: 用來查已知service handle範圍内, 

Attribute Handle for the characteristic declaration

Attribute Value for the Characteristic Properties

Characteristic Value Handle

Characteristic UUID

[34:B1:F7:D5:59:64][LE]> characteristics 2 3 handle: 0x0002, char properties: 0x02, char value handle: 0x0003, uuid: 00002a00-0000-1000-8000-00805f9b34fb

Read By Type Request

it actually sends "Read by Type Request" with UUID 0x2803 (<<Characteristic>>)

< ACL Data TX: Handle 70 flags 0x00 dlen 11                   [hci0] 713.100301
      ATT: Read By Type Request (0x08) len 6
        Handle range: 0x0002-0x0003
        Attribute type: Characteristic (0x2803)

< 02 46 00 0B 00 07 00 04 00 08 02 00 03 00 03 28 

> HCI Event: Number of Completed Packets (0x13) plen 5        [hci0] 713.265526
        Num handles: 1
        Handle: 70
        Count: 1

> 04 13 05 01 46 00 01 00 

Read By Type Response

> ACL Data RX: Handle 70 flags 0x02 dlen 13                   [hci0] 713.328138
      ATT: Read By Type Response (0x09) len 8
        Attribute data length: 7
        Attribute data list: 1 entry
        Handle: 0x0002
        Value: 020300002a

The Attribute Data List (handle and value pair(s))

> 02 46 20 0D 00 09 00 04 00 09 07 02 00 02 03 00 00 2A 

[RR Bluetooth] gatttool - What HCI Commands are Sent by gatttool (2) primary

First of all, the packets below are all HCI ACL Data Packet (with indicator 0x02)

for example, ATT Command - Read By Group Type Request
0000: 02 47 00 0b 00 07 00 04  00 10 01 00 ff ff 00 28

0x02 is HCI ACL Data Packet (Table 2.1 HCI Packet Indicator)
0x47 is Handle
0x00 means PB Flag and BC Flag is 0
0x000b is Data Total Length

then follows the L2CAP packet

0x0007 is length
0x0004 is CID (Attribute Protocol PDU)

and then Attribute Protocol PDU

primary         [UUID]                         Primary Service Discover

the UUID means "Discover Primary Services By Service UUID"

If left UUID blank:

Read by Group Type Request

< ACL Data TX: Handle 71 flags 0x00 dlen 11            
      ATT: Read By Group Type Request (0x10) len 6
        Handle range: 0x0001-0xffff
        Attribute group type: Primary Service (0x2800)

0000: 02 47 00 0b 00 07 00 04  00 10 01 00 ff ff 00 28

Number of Completed Packets Event

> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 22:57:39.703757
        Num handles: 1
        Handle: 71
        Count: 1

> 0000: 04 13 05 01 47 00 01 00     

Read by Group Type Response

> ACL Data RX: Handle 71 flags 0x02 dlen 24            
      ATT: Read By Group Type Response (0x11) len 19
        Attribute data length: 6
        Attribute group list: 3 entries
        Handle range: 0x0001-0x000b
        UUID: Generic Access Profile (0x1800)
        Handle range: 0x000c-0x000f
        UUID: Generic Attribute Profile (0x1801)
        Handle range: 0x0010-0x0022
        UUID: Device Information (0x180a)

> 0000: 02 47 20 18 00 14 00 04  00 11 06 01 00 0b 00 00  0010: 18 0c 00 0f 00 01 18 10  00 22 00 0a 18           

It looks like that one response delivers a group a time, so successive request/response continues until handle reaches 0xffff

< ACL Data TX: Handle 71 flags 0x00 dlen 11              [hci0] 22:57:39.844179
      ATT: Read By Group Type Request (0x10) len 6
        Handle range: 0x0023-0xffff
        Attribute group type: Primary Service (0x2800)
> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 22:57:39.913884
        Num handles: 1
        Handle: 71
        Count: 1
> ACL Data RX: Handle 71 flags 0x02 dlen 26              [hci0] 22:57:39.983445
      ATT: Read By Group Type Response (0x11) len 21
        Attribute data length: 20
        Attribute group list: 1 entry
        Handle range: 0x0023-0x002d
        UUID: Unknown (f000aa00-0451-4000-b000-000000000000)
< ACL Data TX: Handle 71 flags 0x00 dlen 11              [hci0] 22:57:39.983995
      ATT: Read By Group Type Request (0x10) len 6
        Handle range: 0x002e-0xffff
        Attribute group type: Primary Service (0x2800)
> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 22:57:40.060765
        Num handles: 1
        Handle: 71
        Count: 1
> ACL Data RX: Handle 71 flags 0x02 dlen 26              [hci0] 22:57:40.123327
      ATT: Read By Group Type Response (0x11) len 21
        Attribute data length: 20
        Attribute group list: 1 entry
        Handle range: 0x002e-0x0038
        UUID: Unknown (f000aa10-0451-4000-b000-000000000000)
< ACL Data TX: Handle 71 flags 0x00 dlen 11              [hci0] 22:57:40.123544
      ATT: Read By Group Type Request (0x10) len 6
        Handle range: 0x0039-0xffff
        Attribute group type: Primary Service (0x2800)
> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 22:57:40.193685
        Num handles: 1
        Handle: 71
        Count: 1
> ACL Data RX: Handle 71 flags 0x02 dlen 26              [hci0] 22:57:40.263413
      ATT: Read By Group Type Response (0x11) len 21
        Attribute data length: 20
        Attribute group list: 1 entry
        Handle range: 0x0039-0x0043
        UUID: Unknown (f000aa20-0451-4000-b000-000000000000)
< ACL Data TX: Handle 71 flags 0x00 dlen 11              [hci0] 22:57:40.263720
      ATT: Read By Group Type Request (0x10) len 6
        Handle range: 0x0044-0xffff
        Attribute group type: Primary Service (0x2800)
> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 22:57:40.403808
        Num handles: 1
        Handle: 71
        Count: 1
> ACL Data RX: Handle 71 flags 0x02 dlen 26              [hci0] 22:57:40.404839
      ATT: Read By Group Type Response (0x11) len 21
        Attribute data length: 20
        Attribute group list: 1 entry
        Handle range: 0x0044-0x004e
        UUID: Unknown (f000aa30-0451-4000-b000-000000000000)
< ACL Data TX: Handle 71 flags 0x00 dlen 11              [hci0] 22:57:40.405062
      ATT: Read By Group Type Request (0x10) len 6
        Handle range: 0x004f-0xffff
        Attribute group type: Primary Service (0x2800)
> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 22:57:40.473655
        Num handles: 1
        Handle: 71
        Count: 1
> ACL Data RX: Handle 71 flags 0x02 dlen 26              [hci0] 22:57:40.549909
      ATT: Read By Group Type Response (0x11) len 21
        Attribute data length: 20
        Attribute group list: 1 entry
        Handle range: 0x004f-0x005d
        UUID: Unknown (f000aa40-0451-4000-b000-000000000000)
< ACL Data TX: Handle 71 flags 0x00 dlen 11              [hci0] 22:57:40.550199
      ATT: Read By Group Type Request (0x10) len 6
        Handle range: 0x005e-0xffff
        Attribute group type: Primary Service (0x2800)
> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 22:57:40.613695
        Num handles: 1
        Handle: 71
        Count: 1
> ACL Data RX: Handle 71 flags 0x02 dlen 26              [hci0] 22:57:40.683447
      ATT: Read By Group Type Response (0x11) len 21
        Attribute data length: 20
        Attribute group list: 1 entry
        Handle range: 0x005e-0x0068
        UUID: Unknown (f000aa50-0451-4000-b000-000000000000)
< ACL Data TX: Handle 71 flags 0x00 dlen 11              [hci0] 22:57:40.683942
      ATT: Read By Group Type Request (0x10) len 6
        Handle range: 0x0069-0xffff
        Attribute group type: Primary Service (0x2800)
> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 22:57:40.753660
        Num handles: 1
        Handle: 71
        Count: 1
> ACL Data RX: Handle 71 flags 0x02 dlen 12              [hci0] 22:57:40.823257
      ATT: Read By Group Type Response (0x11) len 7
        Attribute data length: 6
        Attribute group list: 1 entry
        Handle range: 0x0069-0x006d
        UUID: Unknown (0xffe0)
< ACL Data TX: Handle 71 flags 0x00 dlen 11              [hci0] 22:57:40.823554
      ATT: Read By Group Type Request (0x10) len 6
        Handle range: 0x006e-0xffff
        Attribute group type: Primary Service (0x2800)
> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 22:57:40.893657
        Num handles: 1
        Handle: 71
        Count: 1
> ACL Data RX: Handle 71 flags 0x02 dlen 26              [hci0] 22:57:40.970015
      ATT: Read By Group Type Response (0x11) len 21
        Attribute data length: 20
        Attribute group list: 1 entry
        Handle range: 0x006e-0x0074
        UUID: Unknown (f000aa60-0451-4000-b000-000000000000)
< ACL Data TX: Handle 71 flags 0x00 dlen 11              [hci0] 22:57:40.970332
      ATT: Read By Group Type Request (0x10) len 6
        Handle range: 0x0075-0xffff
        Attribute group type: Primary Service (0x2800)
> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 22:57:41.033661
        Num handles: 1
        Handle: 71
        Count: 1
> ACL Data RX: Handle 71 flags 0x02 dlen 26              [hci0] 22:57:41.103462
      ATT: Read By Group Type Response (0x11) len 21
        Attribute data length: 20
        Attribute group list: 1 entry
        Handle range: 0x0075-0x007f
        UUID: Unknown (f000ccc0-0451-4000-b000-000000000000)
< ACL Data TX: Handle 71 flags 0x00 dlen 11              [hci0] 22:57:41.103968
      ATT: Read By Group Type Request (0x10) len 6
        Handle range: 0x0080-0xffff
        Attribute group type: Primary Service (0x2800)
> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 22:57:41.173666
        Num handles: 1
        Handle: 71
        Count: 1
> ACL Data RX: Handle 71 flags 0x02 dlen 26              [hci0] 22:57:41.243343
      ATT: Read By Group Type Response (0x11) len 21
        Attribute data length: 20
        Attribute group list: 1 entry
        Handle range: 0x0080-0xffff
        UUID: Unknown (f000ffc0-0451-4000-b000-000000000000)

If UUID is used (0x1801 for example):

Find By Type Value Request

< ACL Data TX: Handle 71 flags 0x00 dlen 13              [hci0] 01:01:43.451403
      ATT: Find By Type Value Request (0x06) len 8
        Handle range: 0x0001-0xffff
        Attribute type: Primary Service (0x2800)
          UUID: Generic Attribute Profile (0x1801)

< 0000: 02 47 00 0d 00 09 00 04  00 06 01 00 ff ff 00 28
  0010: 01 18  

> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 01:01:44.241679
        Num handles: 1
        Handle: 71
        Count: 1

Find By Type Value Response

Note: The Group End Handle may be greater than the Ending Handle in the Find By Type Value Request.

> ACL Data RX: Handle 71 flags 0x02 dlen 9               [hci0] 01:01:44.311128
      ATT: Find By Type Value Response (0x07) len 4
        Handle range: 0x000c-0x000f

> 0000: 02 47 20 09 00 05 00 04  00 07 0c 00 0f 00 

Then another Find By Type Value Request is sent with the rest of handle replied by the response above

< ACL Data TX: Handle 71 flags 0x00 dlen 13              [hci0] 01:01:44.311737
      ATT: Find By Type Value Request (0x06) len 8
        Handle range: 0x0010-0xffff
        Attribute type: Primary Service (0x2800)
          UUID: Generic Attribute Profile (0x1801)
> HCI Event: Number of Completed Packets (0x13) plen 5   [hci0] 01:01:44.381585
        Num handles: 1
        Handle: 71
        Count: 1

 Error Response

> ACL Data RX: Handle 71 flags 0x02 dlen 9               [hci0] 01:01:44.450990
      ATT: Error Response (0x01) len 4
        Find By Type Value Request (0x06)
        Handle: 0x0010
        Error: Attribute Not Found (0x0a)

> 0000: 02 47 20 09 00 05 00 04  00 01 06 10 00 0a 

[RR Bluetooth] gatttool - What HCI Commands are Sent by gatttool (1) Connect, Disconnect

It's interested in knowing what kind of HCI command are sent by gatttool.

here are the captures by btmon

remember,

HCI packet type codes
• Command = 0x01
• Data = 0x02
• Event = 0x04

OGF is 6 bits
For the Link Control commands, the OGF is defined as 0x01.
For the LE Controller Commands, the OGF code is defined as 0x08.

connect         [address [address type]]       Connect to a remote device

LE Create Connection:

< HCI Command: LE Create Connec.. (0x08|0x000d) plen 25  [hci0] 23:39:43.092169
        Scan interval: 60.000 msec (0x0060)
        Scan window: 30.000 msec (0x0030)
        Filter policy: White list is not used (0x00)
        Peer address type: Public (0x00)
        Peer address: 34:B1:F7:D5:XX:XX (Texas Instruments)
        Own address type: Public (0x00)
        Min connection interval: 50.00 msec (0x0028)
        Max connection interval: 70.00 msec (0x0038)
        Connection latency: 0x0000
        Supervision timeout: 420 msec (0x002a)
        Min connection length: 0.000 msec (0x0000)
        Max connection length: 0.000 msec (0x0000)

 < 0000: 01 0d 20 19 60 00 30 00  00 00 64 59 d5 f7 b1 34
  0010: 00 28 00 38 00 00 00 2a  00 00 00 00 00  

> HCI Event: Command Status (0x0f) plen 4                [hci0] 23:39:43.110011
      LE Create Connection (0x08|0x000d) ncmd 1
        Status: Success (0x00)

LE Connection Complete Event: 

> HCI Event: LE Meta Event (0x3e) plen 19                [hci0] 23:39:43.618997
      LE Connection Complete (0x01)
        Status: Success (0x00)
        Handle: 71
        Role: Master (0x00)
        Peer address type: Public (0x00)
        Peer address: 34:B1:F7:D5:XX:XX (Texas Instruments)
        Connection interval: 70.00 msec (0x0038)
        Connection latency: 0.00 msec (0x0000)
        Supervision timeout: 420 msec (0x002a)
        Master clock accuracy: 0x00

> 0000: 04 3e 13 01 00 47 00 00  00 64 59 d5 f7 b1 34 38  .>...G...dY...48
  0010: 00 00 00 2a 00 00    

 LE Read Remote Used Features Command:

< HCI Command: LE Read Remote Us.. (0x08|0x0016) plen 2  [hci0] 23:39:43.619334
        Handle: 71

 < 0000: 01 16 20 02 47 00    

> HCI Event: Command Status (0x0f) plen 4                [hci0] 23:39:43.623836
      LE Read Remote Used Features (0x08|0x0016) ncmd 0
        Status: Success (0x00)

The Num_HCI_Command_Packets event parameter allows the Controller to indicate the number of HCI command packets the Host can send to the Controller. If the Controller requires the Host
to stop sending commands, the Num_HCI_Command_Packets event parameter will be set to zero. To indicate to the Host that the Controller is ready to receive HCI command packets, the Controller generates a Command Status event with Status 0x00 and Command_Opcode 0x0000, and the Num_HCI_Command_Packets event parameter is set to 1 or more. Command_Opcode, 0x0000 is a NOP (No OPeration) and can be used to change the number of outstanding HCI command packets that the Host can send before waiting.

 @ Device Connected: 34:B1:F7:D5:XX:XX (1) flags 0x0000

> HCI Event: Command Status (0x0f) plen 4                [hci0] 23:39:44.067965
      NOP (0x00|0x0000) ncmd 1
        Status: Success (0x00)

> HCI Event: LE Meta Event (0x3e) plen 12                [hci0] 23:39:44.210047
      LE Read Remote Used Features (0x04)
        Status: Success (0x00)
        Handle: 71
        Features: 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00
          LE Encryption

> 0000: 04 3e 0c 04 00 47 00 01  00 00 00 00 00 00 00  

disconnect                                     Disconnect from a remote device

Disconnect Command

< HCI Command: Disconnect (0x01|0x0006) plen 3           [hci0] 01:30:43.714810
        Handle: 71
        Reason: Remote User Terminated Connection (0x13)

< 0000: 01 06 04 03 47 00 13 

Disconnection Complete Event:

> HCI Event: Disconnect Complete (0x05) plen 4           [hci0] 01:30:45.748097
        Status: Success (0x00)
        Handle: 71
        Reason: Connection Terminated By Local Host (0x16)

> 0000: 04 05 04 00 47 00 16