ZeroTrace Companion
First Launch
What to expect the first time you open Companion — permissions, optional driver checks, and the device picker.
The first time you launch Companion, three things happen in sequence: permission grants, optional driver checks, and the device picker. This page walks through each.
Step 1 — Operating-system permission grants
Companion needs permission to read from USB serial ports. The exact grant flow depends on your platform.
| Platform | What you'll see | What to grant |
|---|---|---|
| Windows | First-time Defender / SmartScreen prompt | Allow the binary; Companion does not auto-update silently |
| macOS | "App from unidentified developer" dialog if not yet notarized | Right-click → Open → Open. Subsequent launches open normally. |
| Linux | A udev permission prompt the first time you connect a serial device | Add your user to the dialout group: sudo usermod -aG dialout $USER then log out and back in |
If permission is denied, Companion still launches — but the device picker shows zero ports and you cannot connect.
Step 2 — Device-driver check
Some operating systems and some USB-serial chipsets need a driver before the device appears as a COM port:
- Windows — most modern ZeroTrace devices use a CDC-class chipset that Windows recognises out of the box. For older or third-party-firmware devices, you may need a CP210x or CH340 driver from the chipset vendor.
- macOS — Apple Silicon and recent Intel macOS ship with native CDC support. For legacy macOS, install the chipset's macOS driver.
- Linux — kernel CDC ACM support is built in. No driver install required.
If your device does not appear in the picker after plugging in, check the platform-specific driver guidance in troubleshooting.
Step 3 — The device picker
Companion's main window opens with the device picker in the top-left corner. It shows:
- Every COM port detected on your machine.
- Per-port identification — Companion probes each port to figure out what is on the other side. You see one of:
- ZeroTrace HID — a HID device responding to the standard handshake.
- ZeroTrace AirLeak — an AirLeak device responding at the high-speed baud rate.
- ZeroTrace BLE Logger — a BLE Logger responding to its handshake.
- Unknown device — a port that responded but did not match any known signature.
- Empty — no port detected, or detection failed.
- Connect button next to each detected device.
Pick the device you want and click Connect. Companion switches to the appropriate workspace for that device type.
What happens after you connect
The view changes based on what you connected:
- HID device → the HID dashboard fills the main window. The terminal becomes available in the sidebar.
- AirLeak device → the AirLeak workspace replaces the main view. Live data starts streaming immediately.
- Custom firmware → if you have a custom device profile configured, Companion uses your profile; otherwise it falls back to the generic terminal view.
What does not happen
A few things Companion deliberately does not do on first launch:
- No telemetry handshake. Companion never reports your install, your platform, or your usage to ZeroTrace.
- No automatic firmware update. Companion shows you when a firmware update exists but only flashes when you explicitly say so.
- No cloud session. Your devices, your sessions, your library — all stored locally.
- No account sign-in. Companion is free to install and use; nothing is gated behind authentication.
Next steps
Once your device is connected:
- HID → HID Dashboard.
- AirLeak → AirLeak workspace.
- Want to use the AI assistant? → AI Assistant (works with or without a connected device).