TraceNetwork, Usage Guide

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.

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.

1. Setup#

TraceNetwork initializes only when both conditions hold on a device:

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

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

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

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).

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.

Recipe: same payload on multiple hosts#

1. On each planted device, enable TraceNetwork with the same passphrase and reboot.
2. Connect to any one of them in the app — they're peers, it doesn't matter which.
3. Select the agents you want to fire (optionally excluding the local device if you don't want it typing).
4. 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.

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.

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.

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.

7. Settings reference#

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

8. Constraints and gotchas#

9. Troubleshooting#

Devices don't see each other#

• 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.

10. Related#

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