ZeroTrace Companion
Auto-Detection
How Companion identifies which ZeroTrace device is on which port — and what to do when it gets confused.
Companion does not assume anything about which port your device is on. It probes every COM port it can see and labels each one with what it found. The probe is fast (under a second per port) and runs every time you open the picker or hit refresh.
What gets probed
For each detected serial port, Companion runs a quick handshake. The exact order depends on which device card you have selected on the picker, because the AirLeak probe runs at 921,600 baud and the HID/Kit/BLE Logger probe runs at 115,200 — sending the wrong-baud probe to the wrong device temporarily garbles its serial input. Companion avoids that by probing only the relevant family for whichever card is on screen:
| You're on the card for… | Probe order |
|---|---|
| AirLeak / AirLeak Firmware | AirLeak probe at 921,600 baud only |
| Kit / BLE Logger / HID Firmware | Standard probe at 115,200 baud only |
| Custom firmware | Skipped — Companion uses your custom profile instead |
The handshake itself is the same on either side — open the port, send a recognised probe command, read the response, identify the device from the banner — but skipping the wrong-family probe means HID devices no longer momentarily drop off the picker after a rescan, and AirLeak devices stay locked in too.
Companion runs the relevant probe in parallel across all ports — even with five or six COM ports on a machine, the full scan takes about a second.
Sticky detections
Once a port has been successfully classified, Companion caches the result for ~12 seconds. If a follow-up rescan momentarily fails (USB driver hiccup, port-handle race after suspend/resume, anything brief), the picker keeps showing the cached detection rather than dropping the device to "unknown". A bad scan no longer wipes a known device from the UI.
The cache is per-port and is dropped automatically when the port physically disappears — unplugging the device clears it immediately on the next scan.
What you see in the picker
For each port, the picker shows a status:
| Label | Meaning |
|---|---|
| ZeroTrace HID | Standard HID handshake recognised |
| ZeroTrace AirLeak | AirLeak handshake at high-speed baud rate recognised |
| ZeroTrace BLE Logger | BLE Logger handshake recognised |
| Custom firmware: <name> | Matched a configured custom device profile |
| Unknown device | Port responded but Companion could not identify it |
| Busy | Another application has the port open |
| No response | Port exists but did not reply to any probe |
For each detected ZeroTrace device, Companion also surfaces:
- Product name (when the firmware reports one).
- Banner string the device sent back.
- Suggested baud rate.
When auto-detection gets it wrong
A few scenarios where the probe might mis-identify or miss a device:
Custom firmware on a standard ESP32
If you flashed your own firmware to ZeroTrace hardware, the probe may not recognise it. Solution: define a custom device profile so Companion knows what response to expect.
Device in deep sleep
Some firmware sleeps the USB CDC interface to save power. The probe fails because the device does not respond within the timeout. Wake the device (often by pressing a button) and re-scan.
Port already busy
If another application has the port open, Companion cannot probe it. The picker shows "Busy" — close the other application (or pick that port and you'll see a clear error message).
Driver in a stuck state
Occasionally — particularly on Windows after suspend/resume — the USB driver gets stuck. Symptom: the port appears in Device Manager but every probe times out. Solution: unplug the device, wait 5 seconds, plug back in. If that does not fix it, reboot.
Companion's "re-scan" button (or Ctrl+R) re-runs the probe across every port without restarting the application. Use it whenever you suspect the picker is showing stale results.
What happens when you connect
Picking a detected device and clicking Connect does:
- Open the port at the device's baud rate.
- Send a follow-up handshake to confirm the device is still responsive.
- Switch the main window to the appropriate workspace (HID dashboard / AirLeak workspace / terminal).
- Begin streaming any continuous data the device produces (heartbeats, state updates).
If the connection fails after picking from the detected list — usually because something changed between the probe and the connect — Companion shows the failure in a toast and re-runs the probe so you can try again.
What happens with multiple devices on the same port
You cannot have two devices on the same port. Each USB serial device gets its own port. If you swap devices physically without telling Companion, the picker re-probes and the labels update on the next scan.
Probing's privacy and safety
The probe is read-only and uses a small command set explicitly designed to be safe for arbitrary devices. The worst-case for an unknown device:
- The probe sends a few bytes the device does not understand.
- The device may log a "received unknown command" line in its own debug output.
- No state changes occur.
Companion does not send any "destructive" commands during auto-detection. Once you click Connect and the workspace opens, all subsequent commands are visible in the terminal — nothing happens behind your back.