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, butterflyX, sniffleX |
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 !