Merge pull request #153 from riverloopsec/release/2.7.1

Updated for 2.7.1 packaging.

Author: Ryan Speers

.gitignore

@@ -1,6 +1,7 @@
 *.pyc
+.vscode/
 build/
 dist/
+pdf/
 .DS_Store
 *.egg-info/
-

FAQ.md

@@ -0,0 +1,104 @@
+# Frequently Asked Questions
+
+We often receive the same questions via email, and include this to answer some of the most common ones.
+
+## Installation
+
+#### Failed install due to Python.h missing
+
+- Appears as:
+    ```bash
+    ...
+    zigbee_crypt/zigbee_crypt.c:13:10: fatal error: Python.h: No such file or directory
+     #include <Python.h>
+              ^~~~~~~~~~
+    compilation terminated.
+    error: command 'x86_64-linux-gnu-gcc' failed with exit status 1
+    ```
+
+- Cause:
+The requirements were not installed per `README.md`, specifically the Python development package.
+
+- Fix:
+Install the requirement, such as `sudo apt-get install -y python-dev` (or `python3-dev`).
+
+#### Failed install due to gcrypt.h missing
+
+- Appears as:
+    ```bash
+    ...
+    zigbee_crypt/zigbee_crypt.c:15:10: fatal error: gcrypt.h: No such file or directory
+     #include <gcrypt.h>
+              ^~~~~~~~~~
+    compilation terminated.
+    error: command 'x86_64-linux-gnu-gcc' failed with exit status 1
+    ```
+
+- Cause:
+The requirements were not installed per `README.md`, specifically the gcrypt development package.
+
+- Fix:
+Install the requirement, such as `sudo apt-get install -y libgcrypt-dev`.
+
+## Device Usage
+
+### Atmel RZUSBSTICK
+
+#### Flashing
+
+See `firmware/README.md` for details.
+
+#### ValueError device has no langid
+
+- Appears as:
+    ```bash
+    zbid
+    ...
+    Traceback (most recent call last):
+      File "/usr/local/bin/zbid", line 23, in <module>
+        show_dev(gps=arg_gpsdev, include=args.include)
+      File "/usr/local/lib/python2.7/dist-packages/killerbee/__init__.py", line 46, in show_dev
+        for dev in kbutils.devlist(vendor=vendor, product=product, gps=gps, include=include):
+      File "/usr/local/lib/python2.7/dist-packages/killerbee/kbutils.py", line 285, in devlist
+        devlist = devlist_usb_v1x(vendor, product)
+      File "/usr/local/lib/python2.7/dist-packages/killerbee/kbutils.py", line 215, in devlist_usb_v1x
+        usb.util.get_string(dev, dev.iProduct),     \
+      File "/usr/lib/python2.7/dist-packages/usb/util.py", line 314, in get_string
+        raise ValueError("The device has no langid")
+    ValueError: The device has no langid
+    ```
+
+- Cause: USB permissions
+
+- Fix: Run as sudo, or change the permissions to the USB device so your user can query it
+
+### Apimote v4beta
+
+#### Does not enumerate reliably
+
+- Appears as:
+  - Device doesn't show up in `zbid` sometimes
+  - "Serial timeout" message printed to console during running commands
+
+- Cause:
+As detailed on the page for this device, it is in beta due to instability observed with it establishing
+a serial sync with some hosts.
+
+- Fix:
+  - Help improve it, likely by working on the settings for the FTDI chip on the PCB
+  - Specify the device using `-i` when you run commands, so enumeration doesn't need to be run each time
+  - Unplug and replug the device as needed
+
+#### Does not get frames received
+
+- Appears as: Missing frames that you expect and see with other devices
+- Cause: Often we find that users are not attaching the antenna as required.
+- Fix: As detailed in the product documentation, you must either:
+  - have an appropriate antenna attached to the RP-SMA port
+  - or, move the component C501 on the PCB to select the internal antenna
+
+#### Shows v2 when it enumerates
+
+- Appears as: `zbid` lists the device as 'v2'
+- Cause: expected behavior, as from the software side only v1 is different than v2-v4, and thus it doesn't see a difference
+- Fix: N/A

README.md

@@ -11,7 +11,7 @@ All Rights Reserved.
 
 The main toolkit was/is authored by:
 + 2009, Joshua Wright <jwright@willhackforsushi.com>
-+ 2010-2017, Ryan Speers <ryan@riverloopsecurity.com>
++ 2010-2019, Ryan Speers <ryan@riverloopsecurity.com>
 + 2010-2011, Ricky Melgares <ricky@riverloopsecurity.com>
 
 We appreciate the many contributers to the framework, including the following who have contributed capabilities:
@@ -28,6 +28,7 @@ We appreciate the many contributers to the framework, including the following wh
 + Jeff Spielberg
 + Scytmo (bug fixes and CC2530/1 EMK board support)
 + Adam Laurie/rfidiot (APS crypto implementation, firmware, DFU & BOOTLOADER, SubGHZ, SiLabs NodeTest)
++ Steve Martin
 
 REQUIREMENTS
 ================
@@ -36,14 +37,8 @@ KillerBee is developed and tested on Linux systems.
 MacOS usage is possible but not supported.
 
 We have striven to use a minimum number of software dependencies, however, it
-is necessary to install the following Python modules before installation:
-
-+ serial
-+ usb
-+ crypto  (for some functions)
-+ pygtk   (for use of tools that have GUIs)
-+ cairo   (for use of tools that have GUIs)
-+ scapy (for some tools which utilize 802.15.4 Scapy extensions)
+is necessary to install the following Python modules before installation.
+The install will detect and prompt you for what is needed.
 
 On Ubuntu systems, you can install the needed dependencies with the following
 commands:
@@ -98,8 +93,7 @@ You must enable these to be searched for in `killerbee/config.py` and then reins
 
 ApiMote v4beta (and v3):
 ----------------
-The devices typically come preloaded and do not need to be reflashed for basic
-use.
+The devices typically come preloaded and do not need to be reflashed for basic use.
 
 The hardware is open-source at https://github.com/riverloopsec/apimote.
 It is available assembled by contacting team at riverloopsecurity dot com.
@@ -174,8 +168,6 @@ networks, built using the KillerBee framework.  Each tool has its own usage
 instructions documented by running the tool with the "-h" argument, and
 summarized below.
 
-
-+ kbbootloader -  Switches device into DFU/BOOTLOADER mode (if device is capable)
 + zbid         -  Identifies available interfaces that can be used by KillerBee
                 and associated tools.
 + zbwireshark  -  Similar to zbdump but exposes a named pipe for real-time 
@@ -218,17 +210,15 @@ summarized below.
 + zbdsniff     -  Captures ZigBee traffic, looking for NWK frames and over-the-air
                 key provisioning.  When a key is found, zbdsniff prints the
                 key to stdout.  The sample packet capture
-                sample/zigbee-network-key-ota.dcf can be used to demonstrate
+                `sample/zigbee-network-key-ota.dcf` can be used to demonstrate
                 this functionality.
 + zbfind       -  A GTK GUI application for tracking the location of an IEEE
-                802.15.4 transmitter by measuring RSSI.  Zbfind can be passive
+                802.15.4 transmitter by measuring RSSI. zbfind can be passive
                 in discovery (only listen for packets) or it can be active by
                 sending Beacon Request frames and recording the responses from
                 ZigBee routers and coordinators.
                 If you get a bunch of errors after starting this tool, make
-                sure your DISPLAY variable is set properly.  If you know how
-                to catch these errors to display a reasonable error message,
-                please drop me a note.
+                sure your `DISPLAY` variable is set properly.
 + zbgoodfind   -  Implements a key search function using an encrypted packet
                 capture and memory dump from a legitimate ZigBee or IEEE
                 802.15.4 device.  This tool accompanies Travis Goodspeed's
@@ -245,6 +235,7 @@ summarized below.
                 installed to run this.
 + zbscapy      -  Provides an interactive Scapy shell for interacting via a
                 KillerBee interface. Scapy must be installed to run this.
++ kbbootloader -  Switches device into DFU/BOOTLOADER mode (if device is capable)
 
 Additional tools, that are for special cases or are not stable, are stored in
     the Api-Do project repository: http://code.google.com/p/zigbee-security/
@@ -285,8 +276,8 @@ QUESTIONS/COMMENTS/CONCERNS
 ==============
 Please use the ticketing system at https://github.com/riverloopsec/killerbee/issues.
 
-The original version was written by: jwright@willhackforsushi.com
-The current version, fixes, etc are handled by: ryan@riverloopsecurity.com
-Additional Tools/Fixes by: bryanhalf@gmail.com
+The original version was written by: jwright@willhackforsushi.com.
+The current version, fixes, etc are handled by: ryan@riverloopsecurity.com.
+(See the list above for all contributors/credits.)
 
-For contributors/developers, see DEVELOPMENT.md for details and guidance.
+For contributors/developers, see `DEVELOPMENT.md` for details and guidance.

killerbee/__init__.py

@@ -24,7 +24,7 @@ def getKillerBee(channel, page= 0):
         raise Exception("Failed to create a KillerBee instance.")
     try:
         kb.set_channel(channel, page)
-    except Exception, e:
+    except Exception as e:
         raise Exception('Error: Failed to set channel to %d/%d' % (channel, page), e)
     return kb
 
@@ -53,14 +53,15 @@ def __init__(self, device=None, datasource=None, gps=None):
         Instantiates the KillerBee class.
 
         @type device:   String
-        @param device:  Device identifier, either USB vendor:product, serial device node, or IP address
+        @param device:  Device identifier, which is either USB `<BusNumber>:<DeviceNumber>`,
+            serial device path (e.g., `/dev/ttyUSB0`), or IP address.
+            The format needed depends on the device's firmware and connectivity to the host system.
         @type datasource: String
-        @param datasource: A known datasource type that is used
-        by dblog to record how the data was captured.
+        @param datasource: A known data-source type that is used by dblog to record how the data was captured.
         @type gps: String
-        @param gps: Optional serial device identifier for an attached GPS
-            unit. If provided, or if global variable has previously been set, 
-            KillerBee skips that device in initalization process.
+        @param gps: Optional serial device identifier for an attached GPS unit.
+            If provided, or if global variable has previously been set,
+            KillerBee skips that device in initialization process.
         @return: None
         @rtype: None
         '''
@@ -80,7 +81,7 @@ def __init__(self, device=None, datasource=None, gps=None):
             from dev_sewio import isSewio
             if isSewio(device):
                 from dev_sewio import SEWIO
-                self.driver = SEWIO(dev=device) #give it the ip address
+                self.driver = SEWIO(dev=device)  # give it the ip address
             else: del isSewio
 
         # Figure out a device is one is not set, trying USB devices next
@@ -222,7 +223,7 @@ def check_capability(self, capab):
         '''
         return self.driver.capabilities.check(capab)
 
-    def is_valid_channel(self, channel, page):
+    def is_valid_channel(self, channel, page=0):
         '''
         Use the driver's capabilities class to determine if a requested channel number
         is within the capabilities of that device.
@@ -314,7 +315,7 @@ def page(self):
         # Driver must have this variable name set in its set_channel function
         return self.driver._page
 
-    def set_channel(self, channel, page= 0):
+    def set_channel(self, channel, page=0):
         '''
         Sets the radio interface to the specifid channel & page (subghz)
         @type channel: Integer