External Adapter Support Environment
The External Adapter Support Environment (EASE) allows WiFi Explorer Pro and Airtool 2 to use external USB adapters for Wi-Fi scanning and packet capturing in macOS. Adapters must be Linux-compatible and support monitor mode.
EASE is a custom, lightweight Debian VM that leverages the WiFi Explorer Pro's remote sensor functionality to configure an external Wi-Fi adapter as a pseudo-local sensor automatically. These pseudo-local sensors are listed in WiFi Explorer Pro separately from remote sensors, but they work in the same manner. Airtool 2 can also use the external adapters for Wi-Fi packet capturing, including packet captures on different channels simultaneously using multiple external adapters.
Installing EASE is relatively 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. Also, if at least one adapter is connected to the EASE VM, Airtool 2 will automatically show EASE as an available local sensor that can be used for packet capturing.
Supported external adapters
EASE can work with Linux-compatible external USB adapters that support monitor mode, for example:
- ASUS USB-N53
- ALFA AWUS051NH 802.11a/b/g/n
- ALFA AWUS036NHA 802.11b/g/n - Atheros AR9271
- COMFAST CF-912AC - Realtek RTL8812AU
- Edimax EW-7822UAC AC1200 - Realtek RTL8812AU
- Edimax EW-7833UAC AC1750 - Realtek RTL8814AU
- MediaTek MT7612U 1200Mbps Dual Band - MediaTek MT7612U
- Odroid Wi-Fi Module 4 - MediaTek (Ralink) RT5572N
- Odroid Wi-Fi Module 5 - Realtek RTL8812AU
- TP-Link 802.11b/g/n TL-WN272N
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 us.
- 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.
- If git is not installed, type:
- Install the support environment:
git clone https://github.com/intuitibits/ease.git cd ease vagrant up
The installation of the environment will take a few minutes as the custom Debian-based EASE VM is downloaded and provisioned. Once done, EASE is ready to be used, and you can proceed to attach the external USB Wi-Fi adapter(s).
We use a custom Vagrant box for the EASE VM that has all the necessary wireless drivers already installed, so provisioning the VM is easier and faster. Every time you start EASE using the
vagrant up command, Vagrant checks if there's a new version of the custom box. If a new version is found, you can update the box and re-create the EASE VM to get the latest changes by typing:
vagrant destroy vagrant box update vagrant up
Important: Please note that you will lose any customizations you may have made to the EASE VM by re-creating it using the steps above. So, do not update unless you want to keep your changes.
Attaching external 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.
- Plug in the adapter to any of the USB ports in your Mac.
- Open VirtualBox and select the EASE VM.
- Choose Settings > Ports > USB.
- Add a new USB filter by clicking the icon with the + sign and choosing the adapter you just plugged in.
- Click OK, then unplug and plug back in the adapter.
The adapter will be automatically connected to the EASE VM and made available for Wi-Fi scanning in WiFi Explorer Pro. In Airtool 2, you can now use the adapter for capturing when choosing EASE from the list of sensors. Repeat the steps above for every adapter you want to use with EASE.
Using external 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.
Using external adapters with Airtool 2
Airtool 2 automatically displays EASE as a remote sensor after at least one adapter is attached to the VM.
When you choose the EASE option in Airtool 2, you must specify the adapter used for capturing. The first adapter connected to the EASE VM is named
wlan0, the second adapter is named
wlan1, and so on.
If you connect more than one adapter to EASE, you can also choose the Multi-Source Capture option in Airtool 2 to capture on multiple channels simultaneously.
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.
Atheros AR9271 drivers not compatible with VirtualBox USB 2.0/3.0 controllers
Adapters that require the ath9k_htc driver for the Atheros AR9271 chip (e.g. ALFA AWUS036NHA) don't work with the VirtualBox USB 2.0/3.0 controllers. If you need to use one of these adapters, you must disable USB 2.0/3.0 on the EASE VM as follows:
Edit the Vagrantfile and change the following line:
vb.customize ["modifyvm", :id, "--usbxhci", "on"]
vb.customize ["modifyvm", :id, "--usbehci", "off"] vb.customize ["modifyvm", :id, "--usbxhci", "off"]
Note the additional line to disable USB 2.0 (eHCI).
Then, restart the EASE VM:
vagrant halt vagrant up
You may need to re-add the USB filters for the adapter as specified in the instructions for attaching USB adapters to the EASE VM.
If the adapter doesn't appear in WiFi Explorer Pro or EASE is not listed as a sensor in Airtool 2:
- 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.
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 status
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 or EASE is not an option in Airtool 2, contact us.