ble_scan
========

Presentation
------------
**ble_scan** identifies Bluetooth Low Energy devices that emit advertisements, hence allowing to identify which devices assume the role of Broadcaster or Peripheral.
It extracts from those advertisments potentially useful information, like the device's name or its BD address.
There is a possiblity to limit the execution time with the *TIME* parameter (execution duration in seconds). If this parameter is set to an empty string (""), the execution doesn't automatically stop.
It is also possible to target a specific device by specifying its BD address in the *TARGET* parameter.
The information to display can be easily modified using the *DISPLAY* parameter: it allows to provide a list of information to display (among **address**, **name**, **company**, **flags** and **data**).

Compatible devices
------------------

 * `HCI Device <devices.html#hci-device>`_
 * `BTLEJack Device <devices.html#btlejack-device>`_
 * `HackRF Device <devices.html#hackrf-device>`_
 * `Sniffle Device <devices.html#sniffle-device>`_
 * `ButteRFly Device <devices.html#butterfly-device>`_
 * `Ubertooth Device <devices.html#ubertooth-device>`_
 * `NRFSniffer Device <devices.html#nrfsniffer-device>`_

Input parameters
-----------------

+----------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+
| Name                                   | Default value                         | Possible values                                                                         | Description                                                                               |
+========================================+=======================================+=========================================================================================+===========================================================================================+
| INTERFACE                              | hci0                                  | hciX, microbitX, ubertoothX, nrfsnifferX,butterflyX,hackrfX,sniffleX                    | Interface to use                                                                          |
+----------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+
| TARGET                                 |                                       | <BD address>                                                                            | Target address                                                                            |
+----------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+
| DISPLAY                                | address,name,company,flags,data       | address, name, company, flags, data                                                     | Information to display                                                                    |
+----------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+
| TIME                                   | 20                                    | <integer>                                                                               | Execution duration                                                                        |
+----------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+

Output parameters
------------------

If no devices have been identified, no output parameters are generated.
If there is only one device identified, the output parameters are listed in the following table :


+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+
| Name                                   | Possible values                                             | Description                                                          |
+========================================+=============================================================+======================================================================+
| ADVERTISING_ADDRESS                    | <BD address>                                                | BD address of the identified device                                  |
+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+
| TARGET                                 | <BD address>                                                | BD address of the identified device                                  |
+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+
| ADVERTISING_DATA                       | <hexadecimal>                                               | Received advertising data (ADV_IND)                                  |
+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+
| SCANNING_DATA                          | <hexadecimal>                                               | Received advertising data (SCAN_RSP)                                 |
+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+

If multiple devices have been identified, the same output parameters are generated, but are suffixed by the number of the device :

+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+
| Name                                   | Possible values                                             | Description                                                          |
+========================================+=============================================================+======================================================================+
| ADVERTISING_ADDRESS1                   | <BD address>                                                | BD address of the first device                                       |
+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+
| ADVERTISING_DATA1                      | <hexadecimal>                                               | Received advertising data from the first device (ADV_IND)            |
+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+
| SCANNING_DATA1                         | <hexadecimal>                                               | Received advertising data from the first device (SCAN_RSP)           |
+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+
| ADVERTISING_ADDRESS2                   | <BD address>                                                | BD address of the second device                                      |
+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+
| ADVERTISING_DATA2                      | <hexadecimal>                                               | Received advertising data from the second device (ADV_IND)           |
+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+
| SCANNING_DATA2                         | <hexadecimal>                                               | Received advertising data from the second device (SCAN_RSP)          |
+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+
| \.\.\.                                 | \.\.\.                                                      | \.\.\.                                                               |
+----------------------------------------+-------------------------------------------------------------+----------------------------------------------------------------------+

Usage
------

If you want to list the devices during 20 seconds :

::

        $ mirage ble_scan
	[INFO] Module ble_scan loaded !
	[SUCCESS] HCI Device (hci0) successfully instanciated !
	┌Devices found──────┬──────┬─────────┬───────────────────────────────────────────────────┬────────────────────────────────────────────────────────────────────┐
	│ BD Address        │ Name │ Company │ Flags                                             │ Advertising data                                                   │
	├───────────────────┼──────┼─────────┼───────────────────────────────────────────────────┼────────────────────────────────────────────────────────────────────┤
	│ C7:FD:F2:07:36:2E │ Tile │         │ LE General Discoverable Mode,BR/EDR not supported │ 0201060303edfe050954696c65 (ADV_IND)                               │
	│ 56:A3:59:1D:18:61 │      │ Google  │                                                   │ 03039ffe17169ffe0000000000000000000000000000000000000000 (ADV_IND) │
	│                   │      │         │                                                   │ 09ffe0000130ca72fc5b (SCAN_RSP)                                    │
	└───────────────────┴──────┴─────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────┘
	┌Devices found──────┬─────────┬─────────┬───────────────────────────────────────────────────┬────────────────────────────────────────────────────────────────────────┐
	│ BD Address        │ Name    │ Company │ Flags                                             │ Advertising data                                                       │
	├───────────────────┼─────────┼─────────┼───────────────────────────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
	│ C7:FD:F2:07:36:2E │ Tile    │         │ LE General Discoverable Mode,BR/EDR not supported │ 0201060303edfe050954696c65 (ADV_IND)                                   │
	│ 56:A3:59:1D:18:61 │         │ Google  │                                                   │ 03039ffe17169ffe0000000000000000000000000000000000000000 (ADV_IND)     │
	│                   │         │         │                                                   │ 09ffe0000130ca72fc5b (SCAN_RSP)                                        │
	│ 1F:46:05:0E:35:44 │ Wistiki │         │ LE General Discoverable Mode,BR/EDR not supported │ 02010611072f2a93a6bdd84152ac0b109900c6feed080957697374696b69 (ADV_IND) │
	│                   │         │         │                                                   │ 19ffffff44350e05461f67d3f603228c6cdb8d566c277a41d521 (SCAN_RSP)        │
	└───────────────────┴─────────┴─────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────────┘
	┌Devices found──────┬─────────┬─────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────┬────────────────────────────────────────────────────────────────────────┐
	│ BD Address        │ Name    │ Company     │ Flags                                                                                                │ Advertising data                                                       │
	├───────────────────┼─────────┼─────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
	│ C7:FD:F2:07:36:2E │ Tile    │             │ LE General Discoverable Mode,BR/EDR not supported                                                    │ 0201060303edfe050954696c65 (ADV_IND)                                   │
	│ 56:A3:59:1D:18:61 │         │ Google      │                                                                                                      │ 03039ffe17169ffe0000000000000000000000000000000000000000 (ADV_IND)     │
	│                   │         │             │                                                                                                      │ 09ffe0000130ca72fc5b (SCAN_RSP)                                        │
	│ 1F:46:05:0E:35:44 │ Wistiki │             │ LE General Discoverable Mode,BR/EDR not supported                                                    │ 02010611072f2a93a6bdd84152ac0b109900c6feed080957697374696b69 (ADV_IND) │
	│                   │         │             │                                                                                                      │ 19ffffff44350e05461f67d3f603228c6cdb8d566c277a41d521 (SCAN_RSP)        │
	│ 67:C8:3C:D8:2D:60 │         │ Apple, Inc. │ LE General Discoverable Mode,Simultaneous LE and BR/EDR, Controller,Simultaneous LE and BR/EDR, Host │ 02011a0aff4c001005131cfd5003 (ADV_IND)                                 │
	└───────────────────┴─────────┴─────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────────┘
	[INFO] Mirage process terminated !

If you want to list the devices using the interface *hci1* without stopping the module after 20 seconds, use the following input parameters:

::

	$ mirage ble_scan INTERFACE=hci1 TIME=""
	[INFO] Module ble_scan loaded !
	[SUCCESS] HCI Device (hci1) successfully instanciated !
	┌Devices found──────┬──────┬─────────┬───────────────────────────────────────────────────┬──────────────────────────────────────┐
	│ BD Address        │ Name │ Company │ Flags                                             │ Advertising data                     │
	├───────────────────┼──────┼─────────┼───────────────────────────────────────────────────┼──────────────────────────────────────┤
	│ C7:FD:F2:07:36:2E │ Tile │         │ LE General Discoverable Mode,BR/EDR not supported │ 0201060303edfe050954696c65 (ADV_IND) │
	└───────────────────┴──────┴─────────┴───────────────────────────────────────────────────┴──────────────────────────────────────┘
	┌Devices found──────┬──────┬─────────┬───────────────────────────────────────────────────┬────────────────────────────────────────────────────────────────────┐
	│ BD Address        │ Name │ Company │ Flags                                             │ Advertising data                                                   │
	├───────────────────┼──────┼─────────┼───────────────────────────────────────────────────┼────────────────────────────────────────────────────────────────────┤
	│ C7:FD:F2:07:36:2E │ Tile │         │ LE General Discoverable Mode,BR/EDR not supported │ 0201060303edfe050954696c65 (ADV_IND)                               │
	│ 5A:E1:FC:EE:8C:8D │      │         │                                                   │ 03039ffe17169ffe0000000000000000000000000000000000000000 (ADV_IND) │
	└───────────────────┴──────┴─────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────┘
	[...]

Finally, you can focus on a specific device using the input parameter named *TARGET* (this feature is interesting if you want to use this module in a sequential execution) :
::

	$ mirage ble_scan INTERFACE=hci1 TARGET=1F:46:05:0E:35:44 
	[INFO] Module ble_scan loaded !
	[SUCCESS] HCI Device (hci1) successfully instanciated !
	┌Devices found──────┬─────────┬─────────┬───────────────────────────────────────────────────┬────────────────────────────────────────────────────────────────────────┐
	│ BD Address        │ Name    │ Company │ Flags                                             │ Advertising data                                                       │
	├───────────────────┼─────────┼─────────┼───────────────────────────────────────────────────┼────────────────────────────────────────────────────────────────────────┤
	│ 1F:46:05:0E:35:44 │ Wistiki │         │ LE General Discoverable Mode,BR/EDR not supported │ 02010611072f2a93a6bdd84152ac0b109900c6feed080957697374696b69 (ADV_IND) │
	│                   │         │         │                                                   │ 19ffffff44350e05461f67d3f603228c6cdb8d566c277a41d521 (SCAN_RSP)        │
	└───────────────────┴─────────┴─────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────────┘
	[INFO] Mirage process terminated !


This module allows to change the display using the *DISPLAY* parameter. It allows to provide a list of information to show :
::

	$ mirage ble_scan DISPLAY=address,name INTERFACE=microbit0
	[INFO] Module ble_scan loaded !
	[SUCCESS] BTLEJack device #0 successfully instantiated (firmware version : 3.14)
	[INFO] Custom Mirage Firmware used ! Advertisements sniffing and jamming will be supported.
	┌Devices found──────┬──────┐
	│ BD Address        │ Name │
	├───────────────────┼──────┤
	│ 5C:31:3E:37:20:84 │      │
	└───────────────────┴──────┘
	┌Devices found──────┬──────┐
	│ BD Address        │ Name │
	├───────────────────┼──────┤
	│ 5C:31:3E:37:20:84 │      │
	│ C7:FD:F2:07:36:2E │ Tile │
	└───────────────────┴──────┘
	┌Devices found──────┬──────┐
	│ BD Address        │ Name │
	├───────────────────┼──────┤
	│ 5C:31:3E:37:20:84 │      │
	│ C7:FD:F2:07:36:2E │ Tile │
	│ 58:AE:56:00:0E:15 │      │
	└───────────────────┴──────┘
	[INFO] Mirage process terminated !