README.md

---

⚡ Quick start

One line — nothing to clone:

curl -fsSL https://raw.githubusercontent.com/at0m-b0mb/AirDriver/main/install.sh | sudo bash

That installs the dependencies, the GUI, and the airdriver command. Then:

sudo airdriver           # opens the GUI

Prefer to read the script first? (Always a fair instinct for a curl | bash.)

git clone https://github.com/at0m-b0mb/AirDriver
cd AirDriver
sudo ./install.sh        # installs deps + the `airdriver` command
sudo airdriver           # opens the GUI

Changed your mind? Undoing it is one line too:

sudo ./uninstall.sh              # remove AirDriver, keep the Wi-Fi drivers it installed
sudo ./uninstall.sh --drivers    # …and remove those drivers as well

Don't want to install anything system-wide? Just run it from the folder:

git clone https://github.com/at0m-b0mb/AirDriver
cd AirDriver
./run.sh                 # sets up a local env on first run, then launches the GUI
./run.sh scan            # …or any CLI command

No graphical desktop / over SSH? Everything works headless from the CLI — airdriver scan, airdriver doctor, airdriver install. No GUI libraries needed.

Stuck on the first run? Jump to Troubleshooting — the two most common gotchas (the GUI not opening under sudo, and Qt xcb errors) are solved there.

Why

Getting an Alfa/Panda/TP-Link adapter working on Kali or Parrot is a rite of passage: figure out the chipset, find the right DKMS repo (half of them are abandoned), install kernel headers, fight Secure Boot, blacklist the in-tree module… AirDriver automates all of it and explains what it's doing.

It also solves the catch-22: no WiFi driver means no internet, which means you can't download the driver. AirDriver can bundle driver sources offline and build them on an air-gapped machine.

Features

• 🔍 Auto-detection, straight from the kernel — USB and PCI devices are read out of sysfs, not scraped from lsusb/lspci, so detection is complete on a minimal install with no usbutils/pciutils (they're used when present, only to borrow their vendor-resolved product names). Live wireless interfaces are correlated to the adapter that owns them by sysfs device path, so with an internal card and a dongle plugged in each interface lands on the right one. Ethernet NICs, Bluetooth radios and root hubs are filtered out by device class — never offered a Wi-Fi driver.
• 🧠 Smart driver selection — prefers the in-kernel driver when your kernel is new enough (no pointless DKMS build), otherwise apt → DKMS-from-git → offline bundle. For out-of-tree drivers it runs the maintainer's own install-driver.sh (morrownr / aircrack-ng) non-interactively, so the build is done the correct, supported way.
• 🔁 Auto-fallback installs — when the apt driver package is missing or hasn't caught up with your kernel, AirDriver transparently compiles the maintainer's driver from source in the same run (installing build prerequisites on the fly) instead of just failing. One click, and it finds a way to get you a working driver.
• ✅ Verified installs — after building, AirDriver checks the driver is really built, loaded, and bound to your adapter (not just "the build exited 0") and gives an honest verdict with the exact fix when it isn't — Secure Boot, missing firmware, a conflicting in-kernel module, or a needed re-plug/reboot.
• 📡 Brings it online — after loading the module it unblocks rfkill, brings the interface up, and nudges NetworkManager, so a clean build is a working adapter and not just a loaded module.
• 🔧 Survives kernel upgrades — the #1 way Wi-Fi "randomly breaks" on Kali: you upgrade, reboot, and the out-of-tree module was never built for the new kernel. airdriver status spots it instantly and airdriver rebuild fixes it in one command.
• 🔐 Secure Boot signing — airdriver sign generates a MOK key, signs every built module (handling compressed .ko.xz/.zst correctly), and hands you the one step that needs your own password: enrolling the key.
• 💿 Flip-storage dongles — many cheap adapters boot as a fake CD-ROM full of Windows drivers and never appear as Wi-Fi. AirDriver spots them and airdriver modeswitch ejects it.
• 🧹 Remove & fix — airdriver remove cleanly wipes a half-broken driver for a fresh retry; airdriver fix reloads it (depmod + modprobe); both surface the relevant dmesg.
• 🩺 One-shot diagnose — airdriver diagnose prints (and copies) a complete snapshot — kernel/headers, Secure Boot, rfkill, USB/PCI list, interfaces, modules, DKMS, and the dmesg tail — the single thing to paste when you ask for help.
• 🌐 Hybrid online/offline — uses apt/git when connected, falls back to a pre-fetched offline copy when not.
• 🩺 System doctor — checks kernel headers, DKMS, build tools, Secure Boot, and root before it ever tries to build, so failures are caught early.
• 🚫 Conflict handling — blacklists in-tree modules (e.g. r8188eu) that hijack adapters meant for the out-of-tree driver.
• 📶 Monitor mode + injection — enable/disable monitor mode and run an aireplay-ng injection self-test right from the GUI (or airdriver monitor status/start/stop/test).
• 📚 Searchable chipset browser — the GUI's Chipsets panel filters all 52 families and 1258 IDs by name, vendor, band, or vid:pid so you can check a card before you buy.
• 🛒 Buying advice — airdriver recommend ranks the chipsets that genuinely do monitor mode and injection, preferring ones that need no driver build at all.
• 🤖 Scriptable — airdriver scan --json and airdriver db --json emit machine-readable output; airdriver db --check validates the database (and runs in CI on every commit).
• 🎯 Honest capabilities — every chipset is flagged for monitor mode and real injection quality, so you know before you buy whether a card is attack-grade or connect-only.
• 🖥️ Polished GUI (PySide6) and a complete CLI for headless/SSH boxes.
• 📄 Diagnostic reports — export JSON + Markdown, perfect for forum help threads.
• ❓ Unknown-adapter flow — if your VID:PID isn't known yet, pick the closest chipset to try, then hit Report this adapter (or airdriver contribute) and AirDriver writes the whole bug report for you — USB descriptors, kernel, dmesg and all (and never your adapter's serial number, since the report goes to a public issue).
• 🖌️ Renders on a bare box — every icon is drawn with QPainter, not emoji, so the UI looks right on a minimal Kali install with no emoji font installed.

Screenshots

The screenshots above run on macOS, where AirDriver shows demo adapters so the GUI is fully previewable without hardware. On Kali/Parrot it detects your real adapters.

Install & run

Option A — full install (recommended)

sudo ./install.sh

The installer:

• installs system prerequisites — dkms, build-essential, kernel headers, iw, aircrack-ng, … plus usbutils/pciutils, which are optional: detection reads sysfs directly and works without them.
• installs the Qt runtime libraries the GUI needs (the usual cause of "installed but the window won't open"),
• creates an isolated virtualenv and installs the GUI (PySide6),
• drops a smart airdriver launcher on your PATH.

Then:

sudo airdriver           # GUI (installs run as root — smoothest)
airdriver scan           # CLI: list detected adapters
airdriver doctor         # CLI: is the system ready to build drivers?

Core + CLI are pure stdlib — they run on a stock box with zero pip installs. Only the GUI needs PySide6.

Option B — run without installing

./run.sh                 # GUI    (no root needed; install steps ask for sudo)
./run.sh scan            # or any CLI command

Option C — Make targets

make install             # = sudo ./install.sh
make gui                 # set up a local venv and launch the GUI
make scan                # CLI scan
make doctor              # CLI readiness check
make offline             # pre-fetch driver sources for air-gapped use
make test                # run the test suite
make uninstall           # remove AirDriver (keeps your Wi-Fi drivers)
make purge               # remove AirDriver *and* every driver it installed
make help                # list everything

Uninstalling

Two separate things can be removed, and AirDriver keeps them separate on purpose — uninstalling the tool should not take your Wi-Fi down with it.

sudo ./uninstall.sh              # remove AirDriver; drivers keep working
sudo ./uninstall.sh --drivers    # also remove every driver AirDriver installed
sudo ./uninstall.sh --all        # …and delete the Secure Boot signing key

To clear the drivers but keep AirDriver around:

sudo airdriver remove --all              # every driver AirDriver installed
sudo airdriver remove --all --dry-run    # show exactly what would go, change nothing
sudo airdriver remove rtl8812au          # just one chipset

Removal also deletes AirDriver's modprobe blacklist and loads the in-kernel driver back, so your adapter falls back to the kernel's own driver rather than being left with none. DKMS entries are matched against the chipset database first, so unrelated modules (VirtualBox, NVIDIA) are never touched.

Bundle drivers for offline use (do it while online)

./scripts/fetch_offline_drivers.sh

This pre-clones the DKMS driver repos into airdriver/data/drivers/ so AirDriver can build them later on a machine with no internet.

Usage

GUI

sudo airdriver           # launch the graphical app

Pick your adapter from the cards on the left, review the chipset details and the proposed install plan, then hit Install driver. Watch progress stream in the log. Use Dry run to preview without changing anything. The ? Help button has a built-in quick start and troubleshooter.

CLI

airdriver scan                  # list detected adapters
airdriver scan --json           # …machine-readable, for scripts
airdriver doctor                # system readiness (headers, dkms, secure boot…)
airdriver info 0bda:8812        # database details for a usb id / chipset id
airdriver install               # install driver for the first known adapter
airdriver install rtl8812au --dry-run   # preview the plan for a chipset
airdriver install 0bda:c811 --offline   # force the bundled offline driver
airdriver verify                # did the driver really install, load & bind?
airdriver fix                   # reload the driver (depmod + modprobe) and re-check
airdriver remove rtl8814au      # cleanly remove a driver to retry from scratch
airdriver remove --all          # remove every driver AirDriver installed
airdriver remove --all --dry-run  # …show what that would do, change nothing
airdriver diagnose              # full snapshot to share when stuck (rfkill, dmesg, dkms…)
airdriver monitor status        # show each interface's current mode
airdriver monitor start wlan0   # enable monitor mode
airdriver monitor test wlan0    # aireplay-ng injection self-test
airdriver report                # write a JSON + Markdown diagnostic report
airdriver db                    # dump the chipset database
airdriver db --check            # validate the database (exit non-zero on conflicts)

Driver management

airdriver status                # what's installed — and is it built for THIS kernel?
airdriver rebuild               # rebuild DKMS drivers after a kernel upgrade
airdriver sign                  # sign modules so Secure Boot will load them
airdriver modeswitch            # kick a "driver CD-ROM" dongle into WiFi mode
airdriver recommend --band 5    # which adapter should I actually buy/use?
airdriver contribute            # report an unknown adapter to the project

Wi-Fi died after apt full-upgrade? That's a stale DKMS module, and it's a two-command fix:

airdriver status                # shows "NOT built — stale" against the new kernel
sudo airdriver rebuild          # rebuilds, reloads, and re-checks

Every install ends with a verification report — it confirms the module is built, loaded, and bound to your adapter, or tells you precisely what to fix.

🛟 Troubleshooting

The GUI won't open when I run sudo airdriver / I get a Qt xcb error. This is the #1 issue and AirDriver now handles it for you:

• Running a GUI under sudo normally breaks the X11 connection. AirDriver's launcher re-attaches your desktop session automatically, so sudo airdriver should just work.
• If you still see could not load the Qt platform plugin "xcb", the Qt runtime libs are missing. Install them:

  sudo apt install -y libxcb-cursor0 libxkbcommon-x11-0 libegl1 \
                      libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \
                      libxcb-randr0 libxcb-render-util0 libxcb-shape0
  

  (sudo ./install.sh installs all of these for you.)

The driver "installed" but my adapter still doesn't work. First, get the full picture in one command (it's also copied to your clipboard):

sudo airdriver diagnose       # share this output when asking for help

Then re-check or recover:

airdriver verify              # is it built, loaded, and bound to the adapter?
airdriver fix                 # reload it (depmod + modprobe) and re-check
airdriver remove <chipset> && airdriver install <chipset>   # clean retry from scratch

The usual culprits (AirDriver now handles the first two automatically, but check them if it's still dead):

• Radio is rfkill-blocked — the module loads but the radio is soft-blocked, so nothing transmits. Fix: sudo rfkill unblock all.
• Interface is down — sudo ip link set wlan0 up (AirDriver does this after install).
• Secure Boot is ON — a freshly built DKMS module is unsigned, so the kernel refuses to load it. Disable Secure Boot in firmware, or sudo mokutil --disable-validation then reboot and follow the blue MOK screen.
• No re-plug / reboot yet — unplug and re-plug the adapter, then airdriver scan. High-power cards like the AWUS1900 (RTL8814AU) want a USB 2.0 port or a powered hub — they can brown-out on an unpowered USB 3 port.
• Kernel headers don't match the running kernel — if you upgraded but didn't reboot, DKMS builds for the wrong kernel. sudo apt update && sudo apt full-upgrade, reboot, then airdriver remove <chipset> && airdriver install <chipset>.

Wi-Fi worked yesterday, then I updated the system and it's gone. Your kernel changed and the out-of-tree module wasn't rebuilt for the new one:

airdriver status              # "NOT built — stale" against the running kernel
sudo airdriver rebuild        # rebuild, reload, re-check

If the rebuild can't find matching headers, you're running an older kernel than the one installed — reboot into the newest kernel first, then rebuild.

My new dongle shows up as a CD drive / "Windows driver" disk, not Wi-Fi. It's in flip-storage mode and must be ejected before the radio appears:

sudo airdriver modeswitch     # detects it, or pass the id: ... modeswitch 0bda:1a2b
airdriver scan                # it comes back with a DIFFERENT usb id

Secure Boot keeps refusing my freshly built driver.

sudo airdriver sign                                  # makes a key + signs the modules
sudo mokutil --import /var/lib/airdriver/MOK.der     # you pick a one-time password
sudo reboot                                          # blue screen → Enroll MOK → Continue

airdriver: command not found after installing. The launcher went to ~/.local/bin (non-root install). Add it to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

…or just re-run sudo ./install.sh to put it in /usr/local/bin, or use ./run.sh.

error: externally-managed-environment when I tried pip install. That's modern Debian/Kali (PEP 668) blocking system-wide pip. Don't fight it — use ./install.sh or ./run.sh; both create an isolated virtualenv that side-steps it.

No display at all (headless box / SSH). Skip the GUI entirely — the CLI does everything: airdriver scan, doctor, install, monitor, report.

My adapter shows up as "unknown". Select it, choose the closest chipset under Identify as (GUI) or run airdriver install <vid:pid> (CLI). Please open an issue with the VID:PID so it can be added to the database.

Supported chipsets

AirDriver knows 52 chipset families spanning 1258 USB/PCI IDs. Capabilities are honest — some chips connect fine but can't inject, and AirDriver tells you up front. (Run airdriver db for the full list, or the 📚 Chipsets browser in the GUI.)

Where the IDs come from. Every vid:pid is taken from the Linux kernel's own driver device tables (rtl8xxxu, rt2800usb, ath9k_htc, carl9170, mt76*, rtw88/rtw89, rtl8187) and, for out-of-tree drivers, the maintainers' supported-device-IDs lists. None are guessed — a wrong id installs the wrong driver.

🏆 Attack-grade — reliable monitor mode + injection

Chipset	Typical adapters	Bands	Injection	Driver path
MT7612U	Alfa AWUS036ACM, Panda PAU09	2.4+5 AC1200	excellent	in-kernel (4.19+)
RTL8187	Alfa AWUS036H	2.4 G	excellent	in-kernel
AR9271	Alfa AWUS036NHA, TL-WN722N v1	2.4 N	excellent	in-kernel + firmware
RTL8812AU	Alfa AWUS036ACH	2.4+5 AC1200	good	apt → DKMS → offline (in-kernel 6.14+)
RTL8814AU	Alfa AWUS1900	2.4+5 AC1900	good	apt → DKMS → offline (in-kernel 6.16+)
AR7010	Alfa AWUS051NH v2	2.4+5 N	good	in-kernel + firmware
RT3070 / RT5370	Alfa AWUS036NH, Panda PAU06	2.4 N	good	in-kernel (rt2800usb)
RT3572 / RT5572	Alfa AWUS051NH/052NH, Panda PAU09	2.4+5 N	good	in-kernel (rt2800usb)
RT2800-series (other)	300+ rebadged RT2870/307x/35xx/53xx/55xx sticks	2.4 (some 5)	good	in-kernel (rt2800usb)
MT7610U	Alfa AWUS036ACHM	2.4+5 AC600	good	in-kernel (4.19+)
MT7921AU	Alfa AWUS036AXML, Brostrend AX9L	WiFi 6E	good	in-kernel (5.18+)
MT7925U	Netgear A9000	WiFi 7	good	in-kernel (6.7+)
AR5xxx (ath5k)	Atheros AR5212 miniPCI, Ubiquiti SR2/SR5	2.4+5 a/b/g	good	in-kernel
RT73 / RT2501USB	mid-2000s Ralink USB rebadges	2.4 G	good	in-kernel + firmware

👍 Works — fair injection

Chipset	Typical adapters	Bands	Driver path
RTL8811AU/8821AU	Alfa AWUS036ACS	2.4+5 AC600	apt → DKMS → offline (in-kernel 6.14+)
RTL8811CU/8821CU	TP-Link T2U Nano/Plus	2.4+5 AC600	apt → DKMS → offline
RTL8822BU/8812BU	TP-Link Archer T3U/T4U v3	2.4+5 AC1200	apt → DKMS (morrownr 88x2bu)
RTL8188EUS	TL-WN722N v2/v3	2.4 N	DKMS (blacklists r8188eu)
RTL8192EU	TL-WN822N v4/v5	2.4 N	apt → DKMS
RTL8852BU/8832BU	Alfa AWUS036AXM	WiFi 6	DKMS (morrownr) / in-kernel 6.17+
RTL8852CU/8832CU	generic AXE	WiFi 6E	DKMS (morrownr) / in-kernel 6.19+
ZD1211 / ZD1211B	ZyXEL G-220, 3Com 3CRUSB10075	2.4 G	in-kernel + firmware
RT2500USB (RT2570)	early Ralink USB rebadges	2.4 G	in-kernel
Prism54 USB (p54usb)	3COM 3CRWE254G72, D-Link DWL-G122	2.4 G	in-kernel + firmware

🔌 Connect-only — gets you online, not for attacks

Chipset	Notes
RTL8192CU / RTL8188CUS	Edimax EW-7811Un, TL-WN725N v2 — flaky monitor, unreliable injection
RTL8723BU	WiFi+BT combo dongles — connectivity only
RTL8188FU	cheap mini dongles — limited monitor
RTL8710BU / RTL8188GU	newer budget nano (Tenda W311MI) — often ships in CD-ROM mode; monitor sniffing only
RTL8723AU	older WiFi+BT combo — connectivity only
RTL8192FU	newer budget 2.4 GHz — needs kernel 6.2+ for the in-kernel driver
MT7601U	ultra-cheap nano — monitor sniffing only, no injection
AR9170 (carl9170)	legacy draft-N — weak injection
AR5523 (USB)	legacy a/b/g USB — monitor works, injection unproven (flagged unknown, not promised)

💻 Internal laptop cards (PCIe) — fixes "no WiFi after install"

Most "my Wi-Fi doesn't work on Kali" reports are about the card already inside the laptop, so these are covered in depth. Note how few of them can inject — if a table row says no, no amount of reinstalling will change it, and you want a USB adapter from the attack-grade list instead.

Chipset	Covers	Driver	Monitor	Injection
Atheros AR5416–AR9565	Dell DW1520, ThinkPad AR9285, Compex WLE200NX	ath9k (in-kernel)	✅	🏆 excellent
MediaTek MT7921E / MT7922 / MT7925E	AMD laptops, RZ616 / RZ717	mt7921e (6.6+)	✅	🙂 fair
Qualcomm QCA6174 / QCA9377 / QCA988x	Killer 1435, DW1810	ath10k	✅	❌ firmware limitation
Intel 7260 / 7265 / 3165 / 8260 / 8265 / 9260 / 9560	2014–2020 laptops	iwlwifi	✅	❌
Intel AX200 / AX201 / AX210 / AX211	2020+ laptops	iwlwifi	✅	❌
Intel BE200 / BE201 (WiFi 7)	2024+ laptops — needs kernel 6.7+	iwlwifi	✅	❌
RTL8852AE / 8852BE / 8852CE / 8922AE	2022+ budget & gaming laptops	rtw89 (5.16+)	✅	❌
RTL8821CE / RTL8822CE / RTL8723DE	very common Lenovo/HP/Acer cards	rtw88	✅	❌
RTL8188CE / 8192CE / 8723AE / 8723BE / 8821AE	older Realtek PCIe	rtlwifi	✅	❌
Qualcomm QCA6390 / WCN6855	2021+ Dell/Lenovo/HP, Killer AX1675	ath11k	❌ cannot	❌
Qualcomm QCN9074	AP/enterprise M.2	ath11k (5.13+)	✅	❓ unproven
Qualcomm WCN7850 (WiFi 7)	2024+ laptops, FastConnect 7800	ath12k (6.3+)	✅	❓ unproven
Intel 1000–6000 / Centrino-N	2009–2013 laptops	iwlwifi	✅	❌
Atheros AR5xxx	pre-2008 miniPCI, Ubiquiti SR-series	ath5k (in-kernel)	✅	🏆 good
Broadcom BCM43xx	MacBooks, DW1550, BCM43142	broadcom-sta-dkms (wl)	❌	❌
Broadcom FullMAC	Raspberry Pi 3/4/5, MacBook BCM4364	brcmfmac (in-kernel)	❌ cannot	❌

Atheros ath9k is the one to have. It's in-kernel, needs no firmware blob, and has the most reliable monitor mode and injection of any chipset in the database — better than most USB adapters people buy. If your laptop has one, you're already set.

Broadcom is the one to avoid. The proprietary wl driver supports neither monitor mode nor injection. AirDriver installs it so you at least get internet, and blacklists the conflicting b43/brcmsmac modules — but for any real work, use a USB adapter. Some pre-2012 cards do monitor fine on the open b43 driver, which is worth a try.

The full database lives in airdriver/data/chipsets.json and is trivial to extend — add a VID:PID or a whole chipset and AirDriver picks it up. See Adding a chipset.

How driver selection works

flowchart TD
    A([Plug in the adapter]) --> B["Enumerate USB + PCI<br/>straight from sysfs"]
    B --> C{"VID:PID in the<br/>chipset database?"}
    C -->|no| Z["airdriver contribute —<br/>a pre-filled report,<br/>so the database learns it"]
    C -->|yes| D{"In-kernel driver,<br/>and a new enough kernel?"}

    D -->|yes| K["Load it — no build at all"]
    D -->|no| P{"Best feasible method,<br/>in priority order"}

    P -->|"apt · online + Debian"| APT["Install the distro<br/>DKMS package"]
    P -->|"dkms_git · online"| GIT["Compile the<br/>maintainer's driver"]
    P -->|"offline · bundle present"| OFF["Compile the<br/>bundled source"]
    P -->|none feasible| NONE["Say so plainly —<br/>and why each option failed"]
    APT -.->|"missing, or lagging<br/>behind your kernel"| GIT

    K --> X
    APT --> X
    GIT --> X
    OFF --> X
    X["Blacklist conflicts · depmod · modprobe<br/>rfkill unblock · ip link up · nmcli radio on"]

    X --> V{"Verify — built?<br/>loaded? interface bound?"}
    V -->|yes| OK([Working adapter])
    V -->|no| BAD["The honest verdict, and the exact fix:<br/>rfkill-blocked · Secure Boot ·<br/>built-but-not-loaded · no interface"]

    classDef good fill:#1f9e72,stroke:#0f5f45,color:#ffffff
    classDef work fill:#38bdf8,stroke:#0b6a94,color:#04212e
    classDef warn fill:#f5a623,stroke:#8a5a05,color:#2b1a00
    class A,K,OK good
    class B,X,APT,GIT,OFF work
    class Z,BAD,NONE warn

Before any build, AirDriver verifies kernel headers, DKMS, and build tools are present, warns about Secure Boot, and blacklists conflicting in-tree modules.

If the chosen apt package can't be installed (missing on your distro, or lagging behind your kernel), the same step falls back to compiling the maintainer's driver from git automatically — installing the build prerequisites on the fly — so a single "Install" still ends in a working driver.

Adapter not recognised? Report it in 30 seconds

The database only covers what people send back. If your adapter is unknown — or matched to the wrong chipset — AirDriver writes the whole report for you:

airdriver contribute            # prints the report + a pre-filled issue link
airdriver contribute --open     # …and opens it in your browser

It collects the vid:pid, the USB descriptors (from lsusb -v, or from sysfs when usbutils isn't installed — never the serial number), your kernel and distro, and the matching dmesg lines. In the GUI, select the adapter and press Report this adapter.

Nothing is sent automatically. The report describes your machine, so AirDriver shows it to you and pre-fills the form — you decide whether to submit.

See CONTRIBUTING.md for adding a chipset yourself. It's one JSON file and no code changes.

Adding a chipset

The whole database is one JSON file — no code changes needed. Add an entry (or just a VID:PID to an existing one) to airdriver/data/chipsets.json:

{
  "id": "rtl8812au",
  "name": "Realtek RTL8812AU",
  "monitor_mode": true,
  "injection": true,
  "injection_quality": "good",
  "usb_ids": ["0bda:8812", "2357:0103"],
  "kernel_native": {"module": "rtw88_8812au", "min_kernel": "6.14"},
  "drivers": [
    {"method": "apt", "package": "realtek-rtl88xxau-dkms", "priority": 1},
    {"method": "dkms_git", "repo": "https://github.com/morrownr/8812au-20210820", "priority": 2}
  ]
}

Find your adapter's ID with airdriver scan (it lists unrecognised devices too), then open a PR — or an issue with the ID and we'll add it. Every vid:pid must be unique across the whole file (a duplicate silently mis-identifies hardware); airdriver db --check and the test-suite enforce that, so run it before opening a PR.

Development & tests

The core + CLI are pure standard library, so the tests need no dependencies:

python -m airdriver db --check           # validate the chipset database
python -m unittest discover -s tests -v  # run the suite (DB, detector, installer, CLI)

Both run in CI on every push across Python 3.9–3.13, plus a headless PySide6 GUI import smoke-test. To regenerate the GUI screenshots after a UI change:

QT_QPA_PLATFORM=offscreen python scripts/gen_screenshots.py

⚠️ Responsible use

AirDriver installs drivers and toggles monitor mode for authorized wireless security testing, research, and education. Monitor mode / packet injection on networks you don't own or have written permission to test may be illegal. You are responsible for staying within the law and your rules of engagement.

Project layout

AirDriver/
├── airdriver/
│   ├── core/            # detection, database, system probes, install engine
│   │   ├── chipset_db.py    detector.py   system.py    verify.py
│   │   ├── installer.py     monitor.py    modules.py   report.py
│   │   └── manage.py        # status · rebuild · sign · modeswitch · recommend
│   ├── data/chipsets.json   # the chipset → driver database (52 families)
│   ├── data/drivers/        # offline driver bundle (populated by script)
│   ├── gui/             # PySide6 app (theme, main window)
│   └── cli.py           # full-featured command line
├── tests/               # stdlib unittest suite (DB, detector, installer, CLI)
├── scripts/             # fetch_offline_drivers.sh · gen_screenshots.py
├── .github/workflows/   # CI (tests + GUI smoke, py3.9–3.13)
├── install.sh           # full system installer
├── run.sh               # zero-install quick launcher
└── Makefile             # convenience targets

Roadmap ideas

• Per-adapter TX-power / regulatory region tweaks
• Bootable USB persistence profile
• AppImage / .deb packaging

Recently shipped in v0.8.0 "Wider Net": 12 new chipset families (+400 IDs) taking the database to 52 families / 1258 IDs — Qualcomm ath11k/ath12k, Broadcom brcmfmac, Intel Centrino-N, and the classic ath5k/rt73usb/zd1211rw/p54usb injection chipsets. Capability flags are now read out of the kernel source rather than asserted, which is how QCA6390/WCN6855 are marked as unable to sniff at all (supports_monitor = false in ath11k's own table) while WCN7850 is marked as able. Before that, v0.7.0 "Ground Truth": detection rewritten to read sysfs directly — a missing lsusb used to make AirDriver fall back to demo mode and present three fabricated adapters on real hardware; wireless interfaces are now matched to adapters by sysfs device path instead of being handed to the first PCI card, which is what made the wrong adapter show as "Working"; and Ethernet NICs, Bluetooth radios and root hubs are filtered out by device class. Before that, v0.6.0 "Clean Sweep": 8 new internal-card families (ath9k, ath10k, Intel 7260–BE200, rtw89, rtlwifi, MediaTek PCIe, Broadcom) taking the database to 40 families / 858 IDs; a fix for airdriver remove silently removing nothing; remove --all and a real uninstall.sh; and resolution-independent icons. See the CHANGELOG.

License

MIT © at0m-b0mb