omdrop-owl

AirDrop between iPhones and Linux laptops whose Wi-Fi isn't Apple's Broadcom chip. It's a radio backend for omdrop: AWDL, the Wi-Fi link AirDrop runs over, comes from OWL in userspace, and omdrop's own receiver and sender run over it unchanged. See which cards work.

It is a sibling of omdrop-awdl, the Broadcom radio package, and plugs into omdrop the same way: helpers in /usr/lib/omdrop that the omdrop CLI and panel call. The contract is described in omdrop's docs/radio-backend.md.

In shared mode Wi-Fi stays connected; in exclusive mode it's off while the machine is visible (why).

✅ means both directions work. Shared mode doesn't work on any Intel card tried (#1, #4). One card name can cover chips that behave differently, so a report from a machine, PCI ID (lspci -nn) or kernel not listed here helps too: see Adding your card.

What omdrop-owl does on each Wi-Fi driver comes from userspace/owl-profiles, one line per driver, so the iwlwifi line covers every Intel card, the untested AX200 too. A driver with no line falls back to the * line, which only runs once you opt in with echo 1 | sudo tee /etc/omdrop/allow-untested.

Cards that can inject frames from a monitor interface while connected to Wi-Fi are the likely candidates. Most mac80211 drivers can, but how they behave around it varies, which is what the profile records.

1. Find your driver: basename $(readlink /sys/class/net/<wifi>/device/driver). Put your AP on channel 6, 44 or 149.
2. Opt in (/etc/omdrop/allow-untested), and copy the * line to /etc/omdrop/owl-profiles with your driver's name. That file is read before the packaged table, so you can change settings without rebuilding.
3. Run sudo tools/test-card.sh. It walks you through a photo each way, watches Wi-Fi for five minutes after teardown, and writes a report.
4. To see if your card needs reconnect yes, run it again after echo 0 | sudo tee /etc/omdrop/reconnect-after. If Wi-Fi stops after teardown, it does (reload the driver to recover). Delete the file after.
5. If something fails, try the other mon_mac setting.
6. Open a pull request adding your line to userspace/owl-profiles, and paste the report's summary.txt. The other files include your router's MAC.

Cards that can't inject while connected can try mode exclusive, which takes Wi-Fi away for the window.

On Arch:

makepkg -si

On Debian or Ubuntu:

sudo apt install build-essential cmake git pkg-config dpkg-dev \
  libev-dev libpcap-dev libnl-3-dev libnl-genl-3-dev
tools/build-deb.sh
sudo apt install ./omdrop-owl_*.deb

Either way, this builds OWL at the commit pinned in pins, with patches/, and installs it root-owned into /usr/lib/omdrop together with omdrop-discoverable and omdrop-awdl's portable tools, a polkit policy for the helper, and a NetworkManager rule keeping awdl0, mon0 and awdlibss0 unmanaged. It conflicts with brcmfmac-awdl-dkms: one radio backend at a time.

Then install omdrop itself, a version with radio-backend support (not merged yet: brentkearney/omdrop-plugin#25), and turn it on from the bar. /usr/lib/omdrop/omdrop-discoverable probe says what, if anything, is in the way.

For development: just build assembles the same files in build/lib, and just test runs the card test against them.

From omdrop-awdl we reuse, unmodified, the tools that only talk to awdl0 or BlueZ: send-to-peer, airdrop-send.py, ble-airdrop-adv.py, awdl-airdrop-adv.py, awdl-mdns-respond.py and the modules they import. They are fetched at a pinned commit by tools/stage.sh, never committed here.

The Wi-Fi station stays associated, and AWDL shares its channel:

1. AWDL runs on the access point's own channel, which has to be 6, 44 or 149 (AWDL's channels). An iPhone spends a large share of its AWDL time slots on those channels, so the radio never has to leave the AP.
2. A monitor interface carries the station's MAC, and OWL runs on it with -S intersect, advertising only the phone's slots on that channel.
3. The MT7925 sends injected frames from the station's MAC regardless, and the station interface ACKs the phone's unicast to that MAC, so no "active" monitor interface is needed.
4. OWL creates awdl0. omdrop's receiver binds to it, and omdrop-awdl's awdl-airdrop-adv.py --plain announces _airdrop._tcp on it every few seconds (--plain, because OWL adds the AWDL encapsulation itself).

An Intel AX201 passes up no AWDL frames while associated, and no Intel card tried works in shared mode, so the iwlwifi profile says mode exclusive: Wi-Fi is off while the machine is visible, and stop gives it back to NetworkManager.

• An ad-hoc (IBSS) interface joins AWDL's BSSID, so the firmware ACKs the phone's unicast and sees its ACKs, which a monitor interface alone never does. Some AX211s refuse a second interface beside the Wi-Fi one, so there the Wi-Fi interface itself becomes the ad-hoc one, and stop turns it back and reconnects.
• The cell is HT20, because the iPhone sends at HT rates and ignores us until it restarts if we can't ACK them.
• It runs on channel 6: the helper tries 44 and 149 first, but the Intel cards tried won't start an ad-hoc cell on 5 GHz.
• It beacons every 10 s, since its beacons carry AWDL's BSSID and a restarted iPhone didn't list us at the usual rate.
• OWL injects through a monitor interface beside it with -F (owl-03): multicast in any slot, and unicast whenever the phone is on our channel, sent once without waiting for an ACK (owl-05) so a missed frame doesn't stall the queue behind 15 retries.
• OWL advertises our channel in all 16 slots with -S pin (owl-06), and elects its sync master by metric with -E (owl-04), as Apple devices do.

• Deleting a monitor interface while the station is associated wedges the MT7925. A bare monitor interface, added and deleted with nothing else running, leaves the station "Connected" but receiving nothing, from seconds to a few minutes later, until mt7925e is reloaded. That makes it an mt76/firmware bug. omdrop's contract forbids the radio helper from reloading the driver, so stop forces a reconnect right after deleting the interface instead. That has kept the station healthy in every test so far.
• On the MT7925, sending is slower than receiving (about 490 kB/s against 1.3 MB/s). Injected frames leave at a fixed pace of about one every 2.5 ms, whatever PHY rate OWL requests (owl -R, from patches/owl-01-tx-rate.patch) and however many slots the phone offers.
• In shared mode the AP has to be on channel 6, 44 or 149. Otherwise start exits 3 and says so.
• Intel cards are slow, and leave you without Wi-Fi while visible. The AX201 runs AWDL on channel 6, which an iPhone gives one or two slots in sixteen when idle and more during a transfer: a 2.4 MB photo took 17 s from an iPhone and 10.5 s to it. An iPad beside the iPhone connected once and then stopped ACKing our frames; why isn't known.
• iPhones randomise their AWDL address, so nothing here remembers a peer.