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:
- Open the port at a low baud rate (115,200) with a short read timeout.
- Send a probe command that ZeroTrace devices recognise.
- Read the response. A ZeroTrace device replies with a recognisable banner.
- Identify the device type from the banner (HID, AirLeak, BLE Logger, custom firmware).
- If no response at the standard rate, retry at the AirLeak high-speed rate (921,600).
- If still no response, label the port as "unknown" and move on.
Companion does this in parallel across all ports — even with five or six COM ports on a machine, the full scan takes about a second.
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.