Troubleshooting

A field guide to issues that come up during normal AirLeak use. If something here doesn't cover your problem, reach support at support@zerotrace.pw.

---

Connection issues

The AirLeak port doesn't appear in the desktop's port dropdown

Likely causes: cable not data-capable, driver issue, or unit not powered.

1. Confirm the unit's LED is on. If dark, try a different USB-C port or cable. Some USB-C cables are charge-only and won't pass data — use the supplied cable.
2. Windows: open Device Manager → Ports (COM & LPT). Look for USB-Enhanced-SERIAL CH343. If absent, the driver didn't install. Right-click → Update Driver → Search automatically. If that fails, download the CH343 driver from https://dashboard.zerotrace.pw/drivers.
3. macOS: open Terminal, run ls /dev/cu.usbmodem*. The AirLeak shows as /dev/cu.usbmodem-XXXXX. If absent, try a different cable.
4. Linux: dmesg | tail after plugging in. Look for cdc_acm claiming ttyACM0 (or similar). If you see usb 3-2: new full-speed USB device but no cdc_acm, the kernel didn't enumerate the device — try a different USB port.

"Could not open port: PermissionError" (Windows)

Another process is holding the port. Common culprits:

• PlatformIO Serial Monitor (close it)
• Arduino IDE Serial Monitor (close it)
• PuTTY or another terminal (close it)
• Another instance of the ZeroTrace desktop (close all but one)

Close the offending process and try again.

"Permission denied: '/dev/ttyACM0'" (Linux)

Group membership is the usual issue.

1. Check current groups: groups. You should see dialout (Debian/Ubuntu/Pop) or uucp (Arch).
2. If absent, add: sudo usermod -a -G dialout $USER (or uucp)
3. Log out and log back in — group changes don't apply to the current session
4. Verify: ls -l /dev/ttyACM0 — the file's group should be dialout or uucp

Connection drops every few minutes

---

Capture issues

Connected but no events flow

Most common cause: the unit is in Setup mode.

1. Status bar shows Scan: off? Yes → switch to Monitor.
2. Open Overview, click the Monitor card. Within ~1 s, Scan: off → Scan: active and Devices/Events start incrementing.

If the status bar shows Scan: active but Events stays at 0:

• Are you in an empty area with no nearby devices? Wait 30 s — even a quiet room usually has at least one BLE peer.
• Open the Devices page. Empty? The radio might not be receiving. Try airleak-restart from the Command tab.

Status bar Scan says off but I'm in Monitor mode

Active scan is disabled. Open AirLeak → Settings → Settings tab → toggle Active BLE scan ON.

Or via CLI: airleak-active-scan on.

Heap drops below 12 % regularly

Indicates capture pressure exceeds throttle settings.

1. Increase throttle: airleak-throttle 2000
2. Reduce channel coverage: airleak-channels 1,6,11
3. Reduce BLE scan window: airleak-scan-window 50

If heap still drops below 12 % after these changes, the environment is genuinely dense and the unit is approaching its capacity. Consider running shorter sessions.

Drop % climbing in the status bar

USB stream is congested. Same fixes as above (throttle higher, fewer channels).

If the drop rate persists at 0 % but events feel slow, the issue might be the desktop UI struggling to render, not the firmware dropping events. Close the Devices tab and watch only the Overview status bar.

Safe-mode keeps triggering

See Safe Mode → If safe mode triggers regularly.

The throttle is too low for the environment. Bump it:

airleak-throttle 2500
airleak-channels 1,6,11

If safe-mode persists with conservative settings, run airleak-factory-reset to rule out NVS corruption.

Devices page is empty or shows wrong devices

• Filter is excluding them: clear all filters; the badge counts at the top of each tab show what's actually in the table.
• Mode is Setup: switch to Monitor.
• Aggregator was cleared: airleak-snapshot to force a re-emit.

---

Classification issues

A device is classified as unknown

• Wait 30 seconds. The classifier accumulates votes across multiple events; one observation often isn't enough.
• The device may not be advertising rich-enough data. Some IoT devices broadcast minimal payloads.
• Active scan may be off, hiding the friendly name.

A device is classified incorrectly

The classifier uses scored multi-signal voting. False classifications usually come from:

• Ambiguous Apple Continuity payloads — Beats and AirPods share some prefixes; the classifier disambiguates by exact-matching model_id, but rare devices may not be in the database.
• Generic Bluetooth speaker advertising names that look like multiple class possibilities.
• Custom-named devices — a phone renamed to MyHouseSpeaker may classify as smart speaker because the name dominates other signals.

To investigate: open the device detail page → "Why $class?" collapsible. Every vote is listed. If the rationale shows a clearly wrong vote (e.g. matching [TV] when the device isn't a TV), report via support@zerotrace.pw so we can refine the rule.

multi_hour_follower fires on devices I know

False positives are common in stable environments — your own family's iPhones, your neighbor's smart TV, etc. Mark them as own or add a label in the device detail page. The library remembers, and future captures will exclude them from follower scoring.

---

WiFi-specific

Some networks I know are around aren't showing up

Likely causes:

• The AP only beacons on 5 GHz, which the AirLeak can't see. AirLeak is 2.4 GHz only — see Why ESP32-S3? for the reason.
• The channel-hop missed the AP — wait 2–3 sweep cycles (about 6 seconds) before concluding it's missing.
• The AP is configured with hidden SSID. AirLeak captures hidden APs by BSSID but the SSID column shows <hidden>.

A network shows the wrong encryption

• Older firmware on AirLeak may misclassify newer encryption schemes. Update to the latest firmware.
• Some APs broadcast incomplete RSN IEs. The displayed encryption is our best parse — some networks (especially ones in transition modes between WPA2 and WPA3) display WPA2/3-Personal-Mixed correctly.

WPS shows enabled but my router has it disabled

The AP may be advertising legacy WPS IE for backward compatibility even though WPS is functionally off. Check your router admin UI to confirm.

---

Update / firmware issues

Update fails midway through

The OTA system rolls back automatically if the new firmware fails verification. After a failed update, the unit boots back into the previous firmware — you should be able to retry the update normally.

If the unit doesn't come back online after a failed update:

1. Wait 30 seconds — the boot loader may be retrying
2. If still no LED, hold BOOT, press RST, release BOOT (enters ROM bootloader)
3. Use the Web Flasher to manually reflash

Web Flasher doesn't see the AirLeak

Web Serial requires:

• A Chromium-based browser (Chrome, Edge, Brave, Opera). Firefox and Safari don't support Web Serial.
• The desktop app must be closed (or disconnected from the AirLeak port) — only one process can hold the port at a time.
• On Linux, the user must be in the dialout or uucp group.

After a firmware update, settings are different

Settings should persist across firmware updates. If they reset:

• The boot loader may have done a full NVS rewrite (rare, only on major version transitions).
• The previous version may have written settings with a key the new version doesn't recognize.

In either case, just re-apply your preferred settings via the desktop UI or CLI. They'll persist normally going forward.

---

Performance / desktop issues

Desktop app is sluggish during heavy capture

Most common: the Devices page is rendering many rows.

• Switch to Compact density (toggle at the top of the Devices table)
• Filter to reduce visible rows
• Pause the table (top-right) — paused tables don't re-render every event

Long-running session uses lots of disk

Sessions are JSON-encoded; ~200 bytes per event. A 24-hour Monitor session at 50 events/sec produces a ~900 MB session file.

To manage:

• Delete old sessions via Sessions page
• Reduce event volume by tuning the throttle higher
• Use shorter sessions (Setup → Monitor cycles finalize sessions and start new ones)

The desktop crashes on launch

• Delete the app's local data directory (Settings → Advanced → "Open data folder") — this resets desktop preferences but does not delete the firmware-side state.
• Update the desktop to the latest version
• Check the log file in the data folder for stack traces; report to support

---

Hardware issues

LED doesn't light up

The unit isn't getting power.

1. Try a different USB-C cable
2. Try a different USB port
3. Try plugging into a different computer
4. Check the USB port is delivering power (5 V): lsusb -v on Linux, Device Manager on Windows

If LED stays dark across all combinations, the unit may have a hardware fault. Contact support@zerotrace.pw with your order number.

Unit gets very hot

Normal Monitor-mode silicon temperature is 50–55 °C in still air. Above 70 °C is unusual; above 110 °C triggers automatic CPU throttle.

If the unit feels uncomfortably hot to touch:

• Move it out of direct sunlight
• Provide airflow (don't place in a closed enclosure)
• Reduce capture intensity (lower duty cycle, shorter scan window)

Antenna feels loose

The U.FL connector on the WROOM-1U module is rated for ~30 mate cycles. Frequent antenna swaps wear it out.

For long-term flexibility, install an RP-SMA bulkhead and swap antennas at the bulkhead instead of at the U.FL.

---

When to factory reset

If the unit is misbehaving in a way that doesn't match anything above:

airleak-factory-reset

This is the safe nuclear option. NVS is wiped, all settings return to defaults, the unit reboots. The desktop's library and sessions are unaffected — only firmware-side state is reset.

After factory reset:

• Reconnect the desktop
• Switch to Monitor
• Your library and historical data are still there
• Settings are at defaults — re-tune as needed

---

When to contact support

• Unit doesn't power on at all
• Unit boots but USB never enumerates
• Repeated crashes / safe-mode that survive factory reset
• Hardware damage (cracked enclosure, broken U.FL, USB-C port damage)
• Sustained operation issues that aren't covered above

Reach out via support@zerotrace.pw with:

• Your order number
• Firmware version (airleak-info)
• A description of the symptom and what you've tried
• If possible, a copy of the device-log around the time of the issue

---