ZeroTrace Companion
Custom Firmware
Configure Companion to recognise and connect to a device running custom or modified firmware.
Companion ships with handshake patterns for the standard ZeroTrace devices — HID, BLE Logger, AirLeak. If you have flashed your own firmware to the underlying hardware (or you're using a third-party board with a similar serial interface), you can add a custom device profile so Companion treats it like a known device.
When you need a custom profile
You need a custom profile if:
- The device runs firmware you wrote or modified.
- The device runs a third-party fork of ZeroTrace firmware.
- The hardware is similar to ZeroTrace but uses a different vendor / product ID.
- Auto-detection labels the port as "Unknown device" but you know it's something specific.
You do not need a custom profile if:
- The device is a stock ZeroTrace HID / BLE Logger / AirLeak — auto-detection handles it.
- You just want to use the generic terminal — that works against any port without a profile.
Defining a custom profile
In Settings → Connection → Custom Device Profile, you can set:
| Field | What it does |
|---|---|
| Name | The label that will appear in the device picker |
| Baud rate | What baud rate Companion opens the port at |
| Probe command | The string Companion sends during the handshake |
| Expected banner | A regex / substring Companion looks for in the response |
| Workspace | Which Companion view to open after connection — HID, AirLeak, or generic terminal |
Save the profile. The next time you open the device picker, Companion includes your custom probe in the auto-detection scan.
Example: a custom firmware fork
Suppose you have a ZeroTrace HID running a custom firmware variant that responds to version instead of the standard information system. Profile:
| Field | Value |
|---|---|
| Name | MyCustomHID |
| Baud rate | 115200 |
| Probe command | version\r\n |
| Expected banner | MyHID v\d+\.\d+ |
| Workspace | HID |
After saving, plugging in the device and opening the picker shows it as Custom firmware: MyCustomHID alongside any standard ZeroTrace devices.
Multiple custom profiles
You can define more than one. Companion tries each profile during the probe; the first one to match wins. If two of your profiles both match the same device, the order in your settings determines which one Companion picks.
For custom firmware where the response varies, use a regex-style expected-banner that matches the stable parts. A literal substring also works if the banner is consistent.
What custom profiles do not change
- The terminal. Once connected, the terminal sends and receives whatever the device speaks. The custom profile only affects the handshake and the workspace selection.
- Workspace features. Picking the AirLeak workspace for a custom-firmware device means Companion will try to render the AirLeak views — but those views expect the standard AirLeak data format. If your custom firmware doesn't produce that format, the views will be empty.
When a custom profile is not enough
If your custom firmware is genuinely different — different command set, different response format, different real-time data shape — you may need to:
- Use the generic terminal workspace (works for any text-based serial protocol).
- Run your firmware behind your own UI, separate from Companion.
- File a feature request — if the firmware is a popular fork, Companion may add native support.
The custom-profile mechanism is for "mostly compatible with existing workspaces, just with a different handshake." For genuinely novel firmware, the generic terminal is your friend.
Privacy and safety
Custom probes you define are sent to whatever device the user picks. Two principles to keep in mind:
- Don't put destructive commands in the probe. The probe runs against unknown devices during auto-detection.
- Banner-matching does not validate identity. A device that matches your expected banner could be running anything — the banner is a fingerprint, not an attestation. Treat custom-detected devices with appropriate caution if you're connecting in untrusted environments.