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 ------------------ * `HCI Device `_ * `BTLEJack Device `_ * `ButteRFly Device `_ * `Sniffle Device `_ Input parameters ----------------- +----------------------------------------+---------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------+ | Name | Default value | Possible values | Description | +========================================+=======================================+===========================================================================+=======================================================+ | INTERFACE | hci0 | hciX, microbitX, butterflyX, sniffleX | Interface to use | +----------------------------------------+---------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------+ | START_HANDLE | 0x0001 | | First handle of the zone to discover | +----------------------------------------+---------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------+ | END_HANDLE | 0xFFFF | | 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 | | | Value to filter on | +----------------------------------------+---------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------+ | ATT_FILE | | | ATT export file | +----------------------------------------+---------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------+ | GATT_FILE | | | GATT export file | +----------------------------------------+---------------------------------------+---------------------------------------------------------------------------+-------------------------------------------------------+ Output parameters ------------------ +----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+ | Name | Possible values | Description | +========================================+=============================================================+======================================================================+ | ATT_FILE | | ATT export file | +----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+ | GATT_FILE | | 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 !