zigbee_scan
===========

Presentation
-------------
**zigbee_scan** scans the different zigbee channels to discover devices and PanIDs. It allows to configure the execution time (*TIME* parameter) along with the channels to scan (*START_CHANNEL* and *END_CHANNEL* parameters), and to select active or passive scanning (*ACTIVE* parameter).

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

 * `RZUSBStick Device <devices.html#rzusbstick-device>`_

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

+--------------------+---------------+--------------------------+--------------------------------+
| Name               | Default value | Possible values          | Description                    |
+====================+===============+==========================+================================+
| INTERFACE          | rzusbstick0   | rzusbstickX              | Interface to use               |
+--------------------+---------------+--------------------------+--------------------------------+
| START_CHANNEL      | 11            | <integer>                | First targeted channel         |
+--------------------+---------------+--------------------------+--------------------------------+
| END_CHANNEL        | 26            | <integer>                | Last targeted channel          |
+--------------------+---------------+--------------------------+--------------------------------+
| TIME               | 10            | <integer>                | Execution time                 |
+--------------------+---------------+--------------------------+--------------------------------+
| ACTIVE             | yes           | <boolean>                | Use active scanning            |
+--------------------+---------------+--------------------------+--------------------------------+

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

	* If no networks and no devices have been identified, then this module generates no output parameters.

	* If only one device is detected, the following output is produced:

	+-------------------------+---------------------------------+------------------------------------------------+
	| Name                    | Possible values                 | Description                                    |
	+=========================+=================================+================================================+
	| TARGET                  | <ZigBee address>                | device's address (if only one device detected) |
	+-------------------------+---------------------------------+------------------------------------------------+
	| TARGET_PANID            | <hexadecimal, 2 bytes>          | device's panId (if only one device detected)   |
	+-------------------------+---------------------------------+------------------------------------------------+
	| CHANNEL                 | <channel number>                | device's channel (if only one device detected) |
	+-------------------------+---------------------------------+------------------------------------------------+

	* If multiple networks and multiple devices are detected, the same output parameters are generated, but are suffixed by the number of the device :

	+-------------------------+---------------------------------+------------------------------------------------+
	| Name                    | Possible values                 | Description                                    |
	+=========================+=================================+================================================+
	| NETWORK_PANID1          | <hexadecimal, 2 bytes>          | 1st detected network's panID                   |
	+-------------------------+---------------------------------+------------------------------------------------+
	| NETWORK_CHANNEL1        | <integer>                       | 1st detected network's channel                 |
	+-------------------------+---------------------------------+------------------------------------------------+
	| NETWORK_ASSOC_PERMIT1   | <boolean>                       | 1st detected network's association acceptance  |
	+-------------------------+---------------------------------+------------------------------------------------+
	| NETWORK_COORDINATOR1    | <ZigBee address>                | 1st detected network's coordinator             |
	+-------------------------+---------------------------------+------------------------------------------------+
	| DEVICE_ADDR1            | <ZigBee address>                | 1st detected device's address                  |
	+-------------------------+---------------------------------+------------------------------------------------+
	| DEVICE_ROLE1            | coordinator\|end device\|router | 1st detected device's role                     |
	+-------------------------+---------------------------------+------------------------------------------------+
	| DEVICE_CHANNEL1         | <integer>                       | 1st detected device's channel                  |
	+-------------------------+---------------------------------+------------------------------------------------+
	| DEVICE_PANID1           | <hexadecimal, 2 bytes>          | 1st detected device's panID                    |
	+-------------------------+---------------------------------+------------------------------------------------+
	| NETWORK_PANID2          | <hexadecimal, 2 bytes>          | 2nd detected network's panID                   |
	+-------------------------+---------------------------------+------------------------------------------------+
	| NETWORK_CHANNEL2        | <integer>                       | 2nd detected network's channel                 |
	+-------------------------+---------------------------------+------------------------------------------------+
	| NETWORK_ASSOC_PERMIT2   | <boolean>                       | 2nd detected network's association acceptance  |
	+-------------------------+---------------------------------+------------------------------------------------+
	| NETWORK_COORDINATOR2    | <ZigBee address>                | 2nd detected network's coordinator             |
	+-------------------------+---------------------------------+------------------------------------------------+
	| DEVICE_ADDR2            | <ZigBee address>                | 2nd detected device's address                  |
	+-------------------------+---------------------------------+------------------------------------------------+
	| DEVICE_ROLE2            | coordinator\|end device\|router | 2nd detected device's role                     |
	+-------------------------+---------------------------------+------------------------------------------------+
	| DEVICE_CHANNEL2         | <integer>                       | 2nd detected device's channel                  |
	+-------------------------+---------------------------------+------------------------------------------------+
	| DEVICE_PANID2           | <hexadecimal, 2 bytes>          | 2nd detected device's panID                    |
	+-------------------------+---------------------------------+------------------------------------------------+
	| \.\.\.                  | \.\.\.                          | \.\.\.                                         |
	+-------------------------+---------------------------------+------------------------------------------------+


Usage
------

If you want to perform a passive scan, type the following command:

::

   $ mirage zigbee_scan INTERFACE=rzusbstick0 TIME=20 ACTIVE=no
   [INFO] Module zigbee_scan loaded !
   [INFO] RZUSBStick: Killerbee firmware in use.
   ┌────────┬─────────┬───────────────────────┬─────────────────┐
   │ Pan ID │ Channel │ Association permitted │ Nodes           │
   ├────────┼─────────┼───────────────────────┼─────────────────┤
   │ 0x3332 │ 12      │ unknown               │ 0x0000(unknown) │
   └────────┴─────────┴───────────────────────┴─────────────────┘
   [INFO] Mirage process terminated !

If you want to perform an active scan, type the following command:

::

   $ sudo mirage zigbee_scan INTERFACE=rzusbstick0 TIME=20 ACTIVE=yes
   [INFO] Module zigbee_scan loaded !
   [INFO] RZUSBStick: Killerbee firmware in use.
   ┌────────┬─────────┬───────────────────────┬─────────────────────┐
   │ Pan ID │ Channel │ Association permitted │ Nodes               │
   ├────────┼─────────┼───────────────────────┼─────────────────────┤
   │ 0x3332 │ 12      │ no                    │ 0x0000(coordinator) │
   └────────┴─────────┴───────────────────────┴─────────────────────┘
   [INFO] Mirage process terminated !