ZeroTrace HID

TraceNetwork, Usage Guide

Name: ZeroTrace
Address: DE

Set up a fleet, run synchronized payloads, scan WiFi together, and orchestrate light shows

This is the operator's guide to TraceNetwork, the multi-device coordination feature. For the high-level "what is this" overview, see the feature page.

Operated from the mobile app

TraceNetwork is driven from the ZeroTrace mobile app's TraceNet tab over Bluetooth. The device has no web UI. The device you're connected to acts as the controller; every other device on the same passphrase is an agent.

How it works

                ┌────────────┐
                │ Controller │   the device you're connected to over BLE
                │  (any ZT)  │
                └─────┬──────┘
              ESP-NOW │  AES-128-GCM, channel 1, single-hop
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
  ┌──────────┐  ┌──────────┐  ┌──────────┐
  │  Agent   │  │  Agent   │  │  Agent   │   each runs the same firmware
  │          │  │          │  │          │   and shares the passphrase
  └──────────┘  └──────────┘  └──────────┘

There's no central server. Every device runs the same firmware and the same TraceNetwork stack. Whichever one you're connected to acts as the controller; the others act as agents. Heartbeats go out every ~10 seconds (~1 second while a script runs) so the fleet view stays current.

Single-hop only

There is no mesh forwarding or relay. Every agent must be in direct ESP-NOW range of the controller. Plan device placement accordingly.

1. Setup

TraceNetwork initializes only when both conditions hold on a device:

tracenet_enabled is true.
The passphrase is at least 8 characters.

On every device, in the app's Settings → TraceNetwork card:

Toggle Enable TraceNetwork on.
Set a passphrase of 8 or more characters. Use the same passphrase on every device.
Pick an Identify color (default red).
Reboot the device so the master enable takes effect.

The passphrase is the encryption key. The whole fleet shares one key derived from it. Devices with a mismatched passphrase produce traffic that others silently drop — they are invisible to each other. Rotating the passphrase later means re-keying every device.

After every device has rebooted, connect to any one of them in the app. Within ~10 seconds, the other devices appear in the fleet view.

2. Fleet operations

Everything below is issued from the controller over BLE and dispatched to agents over encrypted ESP-NOW. The underlying BLE control routes are tracenet.status, tracenet.fleet, tracenet.forget, tracenet.identify, tracenet.local, and tracenet.lightshow (all require an unlocked/licensed device).

Blinks a device's LED in its configured Identify color so you can physically locate it. The default is 5 blinks; a requested count is clamped to a maximum of 20.

Use it to find planted hardware in a room of identical units. The color comes from that device's own tracenet_identify_color setting.

3. Synchronized execution

The headline use case: fire the same payload on several planted devices at nearly the same instant.

What happens

The controller sends a RUN command to each selected agent with a shared start offset (e.g. 500 ms in the future).
Each agent, on receiving the packet, schedules the script to execute at now + offset on its own task.
At the deadline, every agent fires. Because ESP-NOW unicast latency over short range is single-digit milliseconds, the deadlines land close together — devices start within roughly 10–20 ms of each other.

The offset exists so the controller has time to dispatch to every agent before any of them begins.

If a script touches the LED (ledColor, ledOff, ledBlink), the firmware records that and won't auto-reset the LED afterward — so ledOff actually stays off after the script ends.

Recipe: same payload on multiple hosts

On each planted device, enable TraceNetwork with the same passphrase and reboot.
Connect to any one of them in the app — they're peers, it doesn't matter which.
Select the agents you want to fire (optionally excluding the local device if you don't want it typing).
Load or paste the payload and run it. Every selected device types within the same brief window.

4. Fleet WiFi scan

Each device has its own radio, so devices in different physical locations hear different networks. A fleet scan aggregates them.

Select the agents you want to scan from and start the scan.
Each agent scans independently and returns up to 20 access points.
Results come back over ESP-NOW and are merged into one deduplicated view.

A scan is refused while a script is running on the target device — scanning would disrupt HID injection. If an agent is mid-payload, its scan will not run until the script finishes.

5. Light show

A synchronized lighting effect across the fleet, chosen from a fixed set of patterns. Each device applies a per-device index offset, so multi-device patterns choreograph down the chain.

Pattern	What it does
Off	Turns the LED off.
Solid	Every device holds the same color.
Breathe	Triangle-wave fade in and out.
Blink	On/off flash.
Rainbow	HSV hue cycle, offset per device so the hue waves down the chain.
Chase	One device lit at a time, rotating through the chain by index.
Bounce	Like chase, but the lit position ping-pongs back and forth.

You pick a pattern, a color, a speed (ms per step), and a duration (0 runs until stopped). As with runs, a start offset is applied so devices begin in step; each device anchors its animation to wall-clock time, so drift doesn't accumulate over a long-running pattern.

Which patterns need multiple devices

Solid, breathe, and blink look the same on a single device. Rainbow, chase, and bounce use the per-device index offset, so they're most effective across two or more devices.

6. The `traceBroadcast` script command

Inside a HID or BLE script:

traceBroadcast 'label'

traceBroadcast takes exactly one argument and emits a single broadcast frame (command 0x30) to the fleet.

Emit-only in the current firmware

No receiver currently acts on the broadcast frame — there is no handler for it on the receiving side. Treat traceBroadcast as an emit-only presence beacon: it puts an encrypted, labeled packet on the air, but agents do not react to it and it triggers no fleet-wide event. It's useful today as a marker when observing traffic, not as a way to signal other devices to do something.

7. Settings reference

Setting	Default	Notes
`tracenet_enabled`	`false`	Master enable. When false, ESP-NOW never initializes. Takes effect after reboot.
`tracenet_passphrase`	empty	Shared fleet key. Must be ≥ 8 characters or TraceNetwork stays off. Secret — never read back or set remotely.
`tracenet_identify_color`	`red`	Color the LED blinks on Identify. Options: `red`, `green`, `blue`, `yellow`, `purple`, `orange`, `white`, `cyan`.

All are managed from the app's Settings → TraceNetwork card. The master enable requires a reboot; the identify color applies without one.

Confirm the passphrases are byte-for-byte identical (≥ 8 characters, no leading/trailing whitespace).
Confirm tracenet_enabled = true on every device.
Confirm each device was rebooted after enabling or changing the passphrase.
Confirm they're within direct ESP-NOW range — try moving them closer.

An agent shows stale or offline

Out of range, powered down, or busy. Idle heartbeats are only every ~10 s, so a row can look briefly stale even when healthy.
Check that nothing has retuned the radio off channel 1.

Fleet WiFi scan returns nothing for an agent

The agent may be running a script — scans are blocked during HID injection and will not run until the script ends.
The agent may be out of range or offline.

Light show devices look out of phase

The initial start can land devices a few to a few tens of milliseconds apart due to ESP-NOW jitter. Because each device anchors its animation to wall-clock time, they don't drift further apart over the run — restarting the show re-aligns the start.

Feature overview — short pitch and constraints
HID scripting commands — script reference
Mobile app TraceNet tab — drive the fleet from your phone