ble_discover

Presentation

ble_discover allows to discover the ATT attributes and GATT services/characteristics of a given device, implementing the discovering algorithms proposed in the Bluetooth specification. It needs to be connected to the device beforehand, hence needing to be used inside a chain of modules containing a module initiating the connection (eg: ble_connect or ble_hijack). It identifies the data proposed by a GATT/ATT server and select precisely the information to get with the WHAT parameter. This parameter accepts the following values:

  • “attributes” : get the attributes (ATT layer)

  • “all” : get the secondary and primary services, along with the characteristics (GATT layer)

  • “primaryservices” : get the primary services (GATT layer)

  • “secondaryservices” : get the secondary services (GATT layer)

  • “characteristics” : get the characteristics (GATT layer)

It also has a simple filtering mechanism, configured with the FILTER and FILTER_BY parameters, allowing to filter according to the type or the value of particular ATT attributes. Finally, this tool can export the extracted data in a text format (.cfg/.ini) for later use, for example to clone a device. The export files are provided via the ATT_FILE and GATT_FILE parameters, propagated at the end of the module’s execution to be used in chained operations.

Compatible devices

Input parameters

Name

Default value

Possible values

Description

INTERFACE

hci0

hciX, microbitX

Interface to use

START_HANDLE

0x0001

<integer (2 bytes)>

First handle of the zone to discover

END_HANDLE

0xFFFF

<integer (2 bytes)>

Last handle of the zone to discover

WHAT

all

all,primaryservices,secondaryservices,characteristics,services,attributes

Data type to discover

FILTER_BY

type|value

Filtering type

FILTER

<hexadecimal>

Value to filter on

ATT_FILE

<file path>

ATT export file

GATT_FILE

<file path>

GATT export file

Output parameters

Name

Possible values

Description

ATT_FILE

<file path>

ATT export file

GATT_FILE

<file path>

GATT export file

Usage

If you want to list the attributes of a specific device, you need to set the input parameter named WHAT to “attributes” :

$ sudo mirage  "ble_connect|ble_discover" ble_connect1.TARGET=XX:XX:XX:59:EC:3B ble_discover2.WHAT=attributes
[INFO] Module ble_connect loaded !
[INFO] Module ble_discover loaded !
[SUCCESS] HCI Device (hci0) successfully instanciated !
[INFO] Trying to connect to : XX:XX:XX:59:EC:3B (type : public)
[INFO] Updating connection handle : 1
[SUCCESS] Connected on device : XX:XX:XX:59:EC:3B
┌Attributes────────┬─────────────────────────────────────────────────────┬──────────────────────────────────────────┐
│ Attribute Handle │ Attribute Type                                      │ Attribute Value                          │
├──────────────────┼─────────────────────────────────────────────────────┼──────────────────────────────────────────┤
│ 0x0001           │ Primary Service                                     │ 0018                                     │
│ 0x0002           │ Characteristic Declaration                          │ 020300002a                               │

[...]

│ 0x0042           │ a8b3ffe14834405189d03de95cddd318                    │ 05                                       │
│ 0x0043           │ Characteristic Declaration                          │ 0a440018d3dd5ce93dd08951403448e2ffb3a8   │
│ 0x0044           │ a8b3ffe24834405189d03de95cddd318                    │                                          │
└──────────────────┴─────────────────────────────────────────────────────┴──────────────────────────────────────────┘
[INFO] Mirage process terminated !

These data can be easily exported in a .cfg file using the ATT_FILE parameter :

$ sudo mirage "ble_connect|ble_discover" ble_connect1.TARGET=XX:XX:XX:59:EC:3B ble_discover2.WHAT=attributes ble_discover2.ATT_FILE=/tmp/att.ini
[INFO] Module ble_connect loaded !
[INFO] Module ble_discover loaded !
[SUCCESS] HCI Device (hci0) successfully instanciated !
[INFO] Trying to connect to : XX:XX:XX:59:EC:3B (type : public)
[INFO] Updating connection handle : 1
[SUCCESS] Connected on device : XX:XX:XX:59:EC:3B
┌Attributes────────┬─────────────────────────────────────────────────────┬──────────────────────────────────────────┐
│ Attribute Handle │ Attribute Type                                      │ Attribute Value                          │
├──────────────────┼─────────────────────────────────────────────────────┼──────────────────────────────────────────┤
│ 0x0001           │ Primary Service                                     │ 0018                                     │
│ 0x0002           │ Characteristic Declaration                          │ 020300002a                               │

[...]

│ 0x0042           │ a8b3ffe14834405189d03de95cddd318                    │ 05                                       │
│ 0x0043           │ Characteristic Declaration                          │ 0a440018d3dd5ce93dd08951403448e2ffb3a8   │
│ 0x0044           │ a8b3ffe24834405189d03de95cddd318                    │                                          │
└──────────────────┴─────────────────────────────────────────────────────┴──────────────────────────────────────────┘
[SUCCESS] Discovered attributes are saved as /tmp/att.ini (CFG file format)
[INFO] Mirage process terminated !

If you want to discover the GATT layer datas, you can set the WHAT parameter to “all” (and export the data using the GATT_FILE parameter):

$ sudo mirage "ble_connect|ble_discover" ble_connect1.TARGET=XX:XX:XX:59:EC:3B ble_discover2.WHAT=all ble_discover2.GATT_FILE=/tmp/gatt.ini
[INFO] Module ble_connect loaded !
[INFO] Module ble_discover loaded !
[SUCCESS] HCI Device (hci0) successfully instanciated !
[INFO] Trying to connect to : XX:XX:XX:59:EC:3B (type : public)
[INFO] Updating connection handle : 1
[SUCCESS] Connected on device : XX:XX:XX:59:EC:3B
[INFO] Services discovery ...
┌Services──────┬────────────┬────────┬──────────────────────────────────┬────────────────────┐
│ Start Handle │ End Handle │ UUID16 │ UUID128                          │ Name               │
├──────────────┼────────────┼────────┼──────────────────────────────────┼────────────────────┤
│ 0x0001       │ 0x000b     │ 0x1800 │ 0000180000001000800000805f9b34fb │ Generic Access     │
│ 0x000c       │ 0x000f     │ 0x1801 │ 0000180100001000800000805f9b34fb │ Generic Attribute  │
│ 0x0010       │ 0x0016     │        │ a8b3fa014834405189d03de95cddd318 │                    │
│ 0x0017       │ 0x0029     │ 0x180a │ 0000180a00001000800000805f9b34fb │ Device Information │
│ 0x002a       │ 0x0036     │        │ a8b3ffc04834405189d03de95cddd318 │                    │
│ 0x0037       │ 0x003f     │        │ a8b3fa044834405189d03de95cddd318 │                    │
│ 0x0040       │ 0xffff     │        │ a8b3ffe04834405189d03de95cddd318 │                    │
└──────────────┴────────────┴────────┴──────────────────────────────────┴────────────────────┘
[INFO] Characteristics by service discovery ...
┌Service 'Generic Access'(start Handle = 0x0001 / end Handle = 0x000b)──────────┬────────────────────────────────────────────┬─────────────┬──────────────────┬─────────────┐
│ Declaration Handle │ Value Handle │ UUID16 │ UUID128                          │ Name                                       │ Permissions │ Value            │ Descriptors │
├────────────────────┼──────────────┼────────┼──────────────────────────────────┼────────────────────────────────────────────┼─────────────┼──────────────────┼─────────────┤
│ 0x0002             │ 0x0003       │ 0x2a00 │ 00002a0000001000800000805f9b34fb │ Device Name                                │ Read        │ XXXXXXXXXXXXXXX  │             │
│ 0x0004             │ 0x0005       │ 0x2a01 │ 00002a0100001000800000805f9b34fb │ Appearance                                 │ Read        │                  │             │
│ 0x0006             │ 0x0007       │ 0x2a02 │ 00002a0200001000800000805f9b34fb │ Peripheral Privacy Flag                    │ Write,Read  │                  │             │
│ 0x0008             │ 0x0009       │ 0x2a03 │ 00002a0300001000800000805f9b34fb │ Reconnection Address                       │ Write       │                  │             │
│ 0x000a             │ 0x000b       │ 0x2a04 │ 00002a0400001000800000805f9b34fb │ Peripheral Preferred Connection Parameters │ Read        │ 5000a0000000e803 │             │
└────────────────────┴──────────────┴────────┴──────────────────────────────────┴────────────────────────────────────────────┴─────────────┴──────────────────┴─────────────┘

[...]

┌Service a8b3ffe04834405189d03de95cddd318(start Handle = 0x0040 / end Handle = 0xffff)─┬─────────────┬───────┬─────────────┐
│ Declaration Handle │ Value Handle │ UUID16 │ UUID128                          │ Name │ Permissions │ Value │ Descriptors │
├────────────────────┼──────────────┼────────┼──────────────────────────────────┼──────┼─────────────┼───────┼─────────────┤
│ 0x0041             │ 0x0042       │        │ a8b3ffe14834405189d03de95cddd318 │      │ Read        │ 05    │             │
│ 0x0043             │ 0x0044       │        │ a8b3ffe24834405189d03de95cddd318 │      │ Write,Read  │       │             │
└────────────────────┴──────────────┴────────┴──────────────────────────────────┴──────┴─────────────┴───────┴─────────────┘
[SUCCESS] Discovered services and characteristics are saved as /tmp/gatt.ini (CFG file format)
[INFO] Mirage process terminated !