Awawausb Webusb Firefox

awawausb — WebUSB Extension for Firefox

Skill by ara.so — Daily 2026 Skills collection.

awawausb adds WebUSB (navigator.usb) to Firefox via a two-part system: a browser extension (.xpi) and a native stub binary (compiled Rust) that communicates over native messaging.

Architecture

Copy code
Web Page (navigator.usb)
    ↕  WebExtension API
Firefox Extension (extension/)
    ↕  Native Messaging (stdio, JSON-framed)
Native Stub Binary (native-stub/ — Rust)
    ↕  OS USB APIs (WinUSB / libusb / IOKit)
USB Device

Installation (End Users)

1. Install the Extension

• Signed release: Download .xpi from GitHub Releases, open in Firefox.
• Developer/testing: about:debugging → "This Firefox" → "Load Temporary Add-on…" → select extension/manifest.json.

2. Install the Native Stub

Download and unzip the release archive for your platform, then run:

bashCopy code
# Linux / macOS
./install.sh

# Windows
install.bat

Supported platforms: macOS x86_64/ARM64, Linux x86_64/aarch64, Windows AMD64/ARM64.

Building from Source

bashCopy code
# Clone
git clone https://github.com/ArcaneNibble/awawausb
cd awawausb/native-stub

# Default build (host platform)
cargo build --release

Platform Notes

Cross-compiling (Linux → Windows example)

bashCopy code
# Install mingw-w64, then:
rustup target add x86_64-pc-windows-gnullvm
cargo build --release --target x86_64-pc-windows-gnullvm

Manual Native Manifest Setup

After building, tell Firefox where the native stub binary is by placing a JSON manifest file in the correct location.

Manifest Content

jsonCopy code
{
  "name": "awawausb_native_stub",
  "description": "Allows WebUSB extension to access USB devices",
  "path": "/absolute/path/to/awawausb-native-stub",
  "type": "stdio",
  "allowed_extensions": ["awawausb@arcanenibble.com"]
}

On Windows, path can be just "awawausb-native-stub.exe" (no absolute path required).

Manifest Locations

macOS

Copy code
# Global
/Library/Application Support/Mozilla/NativeMessagingHosts/awawausb_native_stub.json

# User-local
~/Library/Application Support/Mozilla/NativeMessagingHosts/awawausb_native_stub.json

Linux

Copy code
# Global
/usr/lib/mozilla/native-messaging-hosts/awawausb_native_stub.json
/usr/lib64/mozilla/native-messaging-hosts/awawausb_native_stub.json

# User-local
~/.mozilla/native-messaging-hosts/awawausb_native_stub.json

Windows (registry keys)

Copy code
# Global
HKLM\SOFTWARE\Mozilla\NativeMessagingHosts\awawausb_native_stub

# User-local
HKCU\SOFTWARE\Mozilla\NativeMessagingHosts\awawausb_native_stub

The registry value should be the full path to the manifest .json file.

Quick Linux user-local setup script

bashCopy code
#!/usr/bin/env bash
STUB_PATH="$(pwd)/native-stub/target/release/awawausb-native-stub"
MANIFEST_DIR="$HOME/.mozilla/native-messaging-hosts"
mkdir -p "$MANIFEST_DIR"

cat > "$MANIFEST_DIR/awawausb_native_stub.json" <<EOF
{
  "name": "awawausb_native_stub",
  "description": "Allows WebUSB extension to access USB devices",
  "path": "$STUB_PATH",
  "type": "stdio",
  "allowed_extensions": ["awawausb@arcanenibble.com"]
}
EOF

echo "Native manifest written to $MANIFEST_DIR/awawausb_native_stub.json"

Quick macOS user-local setup

bashCopy code
#!/usr/bin/env bash
STUB_PATH="$(pwd)/native-stub/target/release/awawausb-native-stub"
MANIFEST_DIR="$HOME/Library/Application Support/Mozilla/NativeMessagingHosts"
mkdir -p "$MANIFEST_DIR"

cat > "$MANIFEST_DIR/awawausb_native_stub.json" <<EOF
{
  "name": "awawausb_native_stub",
  "description": "Allows WebUSB extension to access USB devices",
  "path": "$STUB_PATH",
  "type": "stdio",
  "allowed_extensions": ["awawausb@arcanenibble.com"]
}
EOF

Windows PowerShell setup

powershellCopy code
$stubPath = "C:\path\to\awawausb-native-stub.exe"
$manifestPath = "C:\ProgramData\Mozilla\awawausb_native_stub.json"

$manifest = @{
    name = "awawausb_native_stub"
    description = "Allows WebUSB extension to access USB devices"
    path = $stubPath
    type = "stdio"
    allowed_extensions = @("awawausb@arcanenibble.com")
} | ConvertTo-Json

Set-Content -Path $manifestPath -Value $manifest

# Register for current user
New-Item -Path "HKCU:\SOFTWARE\Mozilla\NativeMessagingHosts\awawausb_native_stub" -Force
Set-ItemProperty -Path "HKCU:\SOFTWARE\Mozilla\NativeMessagingHosts\awawausb_native_stub" `
    -Name "(Default)" -Value $manifestPath

Using WebUSB in Web Pages

Once installed, navigator.usb is available. Usage is identical to Chrome's WebUSB API:

javascriptCopy code
// Request a device (requires user gesture)
async function connectDevice() {
  try {
    const device = await navigator.usb.requestDevice({
      filters: [
        { vendorId: 0x1234 },                          // by vendor
        { vendorId: 0x5678, productId: 0x9abc },       // by vendor+product
        { classCode: 0xff }                             // by class
      ]
    });

    await device.open();
    await device.selectConfiguration(1);
    await device.claimInterface(0);

    // Send data
    const data = new Uint8Array([0x01, 0x02, 0x03]);
    await device.transferOut(1, data);

    // Receive data
    const result = await device.transferIn(1, 64);
    console.log('Received:', new Uint8Array(result.data.buffer));

    await device.close();
  } catch (err) {
    console.error('USB error:', err);
  }
}

// List previously-authorized devices
async function listDevices() {
  const devices = await navigator.usb.getDevices();
  devices.forEach(d => {
    console.log(`${d.manufacturerName} ${d.productName} (${d.vendorId}:${d.productId})`);
  });
}

// Watch for connect/disconnect
navigator.usb.addEventListener('connect', e => {
  console.log('Device connected:', e.device);
});
navigator.usb.addEventListener('disconnect', e => {
  console.log('Device disconnected:', e.device);
});

Note: The WebUSB API is only available on the main page — not in Web Workers.

System Requirements

Linux udev Rules (if device access is denied)

Copy code
# /etc/udev/rules.d/99-webusb.rules
SUBSYSTEM=="usb", ATTR{idVendor}=="1234", ATTR{idProduct}=="5678", MODE="0666", GROUP="plugdev"

bashCopy code
sudo udevadm control --reload-rules
sudo udevadm trigger

Windows: Switching to WinUSB Driver

If a device isn't listed, it may not use WinUSB. Use Zadig:

1. Open Zadig, select the device
2. Choose "WinUSB" as the driver
3. Click "Replace Driver"

⚠️ Switching to WinUSB removes the device from other Windows subsystems (e.g., a printer will no longer appear as a printer).

Troubleshooting

Check Extension Debugging Page

Click the awawausb toolbar button (under the Extensions icon) → use "List devices" to see all USB devices the extension can see.

• Device listed but page can't use it → likely a permissions/origin issue in the web page.
• Device NOT listed → OS-level configuration problem (driver, udev rules, permissions).

Native Stub Not Found

Symptoms: extension toolbar shows an error; no devices listed.

1. Verify the manifest file exists at the correct path for your OS.
2. Verify "path" in the manifest points to the actual binary.
3. Verify the binary is executable: chmod +x /path/to/awawausb-native-stub
4. Check Firefox's browser console (about:debugging → inspect extension) for native messaging errors.

Linux: Device Not Detected

bashCopy code
# Verify udev is running and broadcasting on NETLINK_KOBJECT_UEVENT group 2
udevadm monitor --udev --subsystem-match=usb

# Check kernel version
uname -r  # must be >= 4.8

Build Fails on Linux (musl)

bashCopy code
# Install musl target
rustup target add x86_64-unknown-linux-musl
# Install musl toolchain (Debian/Ubuntu)
sudo apt install musl-tools
cargo build --release --target x86_64-unknown-linux-musl

Shared Home Directory / Roaming Profiles

The native manifest uses absolute paths, which breaks when the same home directory is used across machines with different CPU architectures. Workarounds:

• Use a wrapper script at a fixed path that execs the correct binary based on uname -m.
• Use separate per-machine manifest directories if your OS supports it.

Known Limitations

• No Web Worker support (API only on main page).
• No Android support (no native messaging on Android Firefox).
• Windows requires WinUSB driver on target device.
• Linux requires udev-compatible daemon for hotplug detection.