Skip to content

ZeroTrace Companion

Tutorial — push your first script to a HID device

From a brand-new ZeroTrace HID to a runnable script in twenty minutes.

You bought a ZeroTrace HID. You want it to do something. By the end of this tutorial you'll have a script on the device, runnable on demand, with a confirmed test execution.

Setup

  1. Plug the HID into your computer.
  2. Open Companion. The device picker should show "ZeroTrace HID" on the port the device is plugged into.
  3. Click Connect. Companion switches to the HID dashboard.

If your device doesn't appear, run through serial ports troubleshooting. Don't proceed until you can see the device info on the dashboard.

Step 1 — Confirm the dashboard

The dashboard should show:

  • Device name (default zerotrace-hid or similar).
  • Firmware version.
  • Storage and free space.
  • Default keyboard layout.

Take a moment to confirm everything looks right. The firmware version in particular should be current — older firmware lacks features later steps assume.

If firmware is out of date, click Update in the dashboard's quick actions and follow the prompts. Reconnect after update.

Step 2 — Open the terminal

Click the Terminal icon in the sidebar (or Ctrl+K, type "terminal", Enter).

The terminal opens with the device's prompt visible. Type:

help

You should see the device's full command list. This confirms two-way communication is working.

Step 3 — List existing scripts

Type:

script list

For a fresh device, the list is likely empty. For a device you've used before, you may see scripts already there. Either way, the listing confirms scripts are accessible.

Step 4 — Write your first script

ZeroTrace HID scripts use a simple language documented at HID scripting. For your first script, keep it minimal.

Open a text editor on your computer. Save a file called hello.zts with these contents:

DELAY 500
STRING Hello from ZeroTrace
ENTER

What this does:

  • Wait half a second.
  • Type the literal text "Hello from ZeroTrace".
  • Press the Enter key.

Save the file somewhere you can find it.

Step 5 — Push the script to the device

Companion's file management lets you upload files to the device's storage. From the dashboard:

  1. Click Files (sidebar or Ctrl+K → Files).
  2. Click Upload.
  3. Pick the hello.zts file you just saved.
  4. Confirm the upload.

The file appears in the device's file list. Companion shows the size and a confirmation toast.

Step 6 — Run the script

Switch to the terminal. Type:

script run hello.zts

The script will type into whatever window has focus. Click into a text editor or a notepad on your computer before running, so the typed text goes somewhere harmless. Running the script with focus on Companion itself is fine — the typed text appears in the terminal as if you typed it.

You should see the device respond with "OK" (or similar success indicator) in the terminal, followed by — if you switched focus to a text editor — the words "Hello from ZeroTrace" typed automatically by the device.

You have just done the unit operation of HID scripting. Every more complex script is a longer version of the same shape.

Step 7 — Make it run on a trigger

Most real HID use is not "type script run from a terminal" — the value of a HID device is that the script runs from a trigger (button press, plug-in event, schedule).

The simplest trigger is a button on the device:

script bind button hello.zts

(Exact syntax depends on your device's firmware; consult HID scripting.)

After binding, pressing the device's button runs the script. Test it: press the button while focused on a text editor; the text should type.

Step 8 — Save the dashboard state

Open the dashboard. The current state — script list, storage, configuration — is what you want to preserve as a baseline.

Use the dashboard's Export action. Save the snapshot somewhere known. If you ever need to confirm the device "had hello.zts in this state on date X," the snapshot is your evidence.

What you have at the end

  • A device with at least one script on it.
  • A confirmed end-to-end execution path.
  • A trigger that runs the script without you sitting at the terminal.
  • A snapshot of the device's state.

This is the foundation. Every more complex HID workflow — keyboard injection, multi-step scripts, payload management, trigger configuration — builds on the same dashboard + terminal + file-management pattern.

For your second script, try something useful — automatic password entry for a specific window, a long-form-fill, a system-administration command. The HID scripting language supports keyboard layouts, conditionals, loops, and most of what a small program needs.

Where to go next

Command Palette

Search for a command to run...