Enables support for external USB adapters in WiFi Explorer Pro
Switch branches/tags
Nothing to show
Clone or download
Latest commit ef3def6 Aug 31, 2018
Permalink
Failed to load latest commit information.
images WiFi Explorer Pro toolbar showing scan modes. Dec 27, 2017
.gitignore Updated it. Dec 27, 2017
LICENSE Create LICENSE Jan 3, 2018
README.md Update README.md Aug 31, 2018
Vagrantfile First commit. Dec 27, 2017
bootstrap.sh Added support for Atheros firmware. Mar 11, 2018
ease First commit. Dec 27, 2017
ease.py Update ease.py Jan 3, 2018

README.md

External Adapter Support Environment

The External Adapter Support Environment (EASE) allows WiFi Explorer Pro to use certain external USB adapters for Wi-Fi scanning in macOS. Adapters must be Linux-compatible and support monitor mode.

EASE is basically a lightweight Debian VM that's been customized to leverage the remote sensor functionality to automatically configure an external Wi-Fi adapter as a pseudo-local sensor. These pseudo-local sensors are listed in WiFi Explorer Pro separately from remote sensors, but they work in the same manner.

EASE supports multiple adapters and the installation is fairly straightforward using Vagrant. Once installed, you only need to attach the adapter to the EASE VM and it will automatically show up in WiFi Explorer Pro where you can choose it for scanning.

Supported External Adapters

EASE can work with Linux-compatible external USB adapters that support monitor mode, however, only a few adapters have been tested:

Other adapters using the same driver/chipset should work fine. If your device works in Linux, supports monitor mode but cannot be used with EASE, contact me.

Installation

  1. Install Vagrant, VirtualBox and the VirtualBox Extension Pack (required to enable USB support in VirtualBox). If you have any of these components already installed, please make sure you're running the latest version.
  2. If git is not installed, type:
xcode-select --install
  1. Install the support environment:
git clone https://github.com/adriangranados/ease.git
cd ease
vagrant up

The installation of the environment will take a few minutes as we need to download a clean Debian image and provision it. Once done, EASE is ready to use and you can proceed to attach your external USB Wi-Fi adapter.

Attaching External USB Adapters to EASE

External USB adapters need to be attached to the EASE VM. Using VirtualBox's USB Device Filters we can configure the environment so that every time you plug in the adapter to the USB port in your computer, the adapter is automatically connected to the EASE VM.

  1. Plug in the adapter to any of the USB ports in your Mac.
  2. Open VirtualBox and select the EASE VM.
  3. Choose Settings > Ports > USB.
  4. Add a new USB filter by clicking the icon with the + sign and choosing the adapter you just plugged in.
  5. Click OK, then unplug and plug back in the adapter.

USB Device Filters

The adapter will be automatically connected to the EASE VM and made available for Wi-Fi scanning in WiFi Explorer Pro. Repeat the steps above for every adapter you want to use with EASE.

Using External USB Adapters with WiFi Explorer Pro

Once you have installed EASE and configured the USB device filters to automatically connect the external adapters to the EASE VM, you can choose the adapter from the Scan Mode menu in the WiFi Explorer Pro's toolbar.

WiFi Explorer Pro's Toolbar

Known Issues

  • It appears none of the adapters tested with EASE report noise values due to limitations of the driver. In order to produce other metrics, such as SNR, WiFi Explorer Pro will use a default noise floor of -96 dBm.

Troubleshooting

If the adapter doesn't appear in WiFi Explorer Pro:

  • Make sure you have unplugged and plugged back in the adapter after adding the USB device filter in VirtualBox.
  • Make sure the EASE VM is running. If the computer went to sleep, VirtualBox will pause the VM and save the VM state. You can check the status of the VM in VirtualBox or by using the Vagrant CLI.
    cd <directory containing the EASE Vagrantfile>
    vagrant status
    If the EASE VM is not running, simple type vagrant up from the same directory where the EASE's Vagrantfile is located.
    cd <directory containing the EASE Vagrantfile>
    vagrant up
  • If nothing helps, you can reboot the EASE VM by typing vagrant reload.
    cd <directory containing the EASE Vagrantfile>
    vagrant reload

If the adapter still doesn't appear in WiFi Explorer Pro, contact me.