Home > Features > HID Automation

HID Automation

HID Automation lets Biscuit act as a keyboard, media controller, or mouse for repeatable testing on computers and devices you own or are authorized to assess. The public feature name is HID Automation for both USB and Bluetooth operation.

Supported hardware

Hardware	USB HID	Bluetooth HID	Script storage
Biscuit Pro or Ultra	Through compatible S3 HID Nodes	Coming Soon in the app	Biscuit flash storage
T-Dongle-C5 DIY	No	Coming Soon in the app	`/scripts` on the SD card
S3 HID Node	Yes	No	Streamed temporarily from the Biscuit into node memory

The ESP32-C5’s USB port is a fixed serial/debug interface, so a T-Dongle-C5 uses Bluetooth HID. S3 HID Node firmware uses the ESP32-S3’s native USB interface when wired HID is required. Compatible boards route native USB D- and D+ on GPIO 19 and GPIO 20 to a host-facing connector. The node does not need an SD card when operating with a Pro or Ultra.

Import a script

On Android or iOS, open Misc → HID Automation. The menu stays visible but unlocks only for a Biscuit Pro or Ultra running firmware newer than v1.5.60. Other models show the model requirement, while eligible models on older firmware show the firmware requirement.

Open Manage Files, choose Import File, then select one of these files:

.txt — a classic 1.0-compatible HID command script
.kl — an optional 256-byte keyboard layout file

The app validates the filename, size, commands, and line lengths before upload. It intentionally does not include a script editor. US keyboard mapping is built in; imported layouts are available for local runs. Synchronized remote-node cohorts currently use the built-in US layout.

Scripts that expand beyond 1,048,576 HID actions through repetition or text expansion are rejected before upload.

If a file with the same name is already saved, choose Replace to update it. The existing file stays saved until the replacement finishes. Wait for Uploaded before disconnecting or switching phones.

If refreshing the file list reports an error, refresh again before choosing a replacement. An incomplete list does not mean a saved file has been deleted.

If an upload fails or is interrupted, its progress and recovery controls remain visible in the Script section. Finishing upload cleanup means the app is still checking the earlier upload. If Upload cleanup needs attention appears, reconnect to the same Biscuit and choose Retry Cleanup. New imports remain unavailable until cleanup is confirmed.

Finish or cancel an upload before switching phones. If cleanup stays blocked, return to the phone that started the upload and use its cancellation controls. If that does not resolve it, restart the Biscuit, reconnect, and try Retry Cleanup. Restarting interrupts any unfinished work; it does not require a firmware update or removing your saved nodes. Deleting a saved file from another phone does not clear the original phone’s upload recovery.

STRING commands accept printable ASCII and tabs; ALTSTRING accepts printable ASCII. Use key names or a keyboard layout file when a test needs a different physical key mapping.

For script portability, a valid ID 1234:abcd Manufacturer:Product line is accepted as compatibility metadata. Biscuit keeps its configured USB or Bluetooth identity; the ID line does not change device descriptors or generate an HID action.

Add an S3 HID Node

The phone remains connected to the Biscuit Pro or Ultra. It does not connect to the S3 HID Node as a separate Biscuit.

HID Automation loads the Biscuit’s Node Manager settings and refreshes its saved nodes when you open the screen. Connected nodes update automatically in Automation and Node Management. Wait for Loading Node Manager settings to finish, or use Refresh if an update fails. You do not need to visit the normal Node Management screen first.

Open Misc → HID Automation → Node Management.
If prompted, open the Biscuit’s Node Manager settings and choose Manager.
Return to the HID Node Management tab, choose Nearby, and tap Discover. Tap Stop Discovery when finished.
Choose a node and tap Add to Memory, or use Add All for the visible nearby nodes.
Return to Automation and wait until the node shows as available before selecting it for a run.

Choose Ignore to hide a nearby node until you restart discovery. Ignored nodes are excluded from Add All.

Discovery ends automatically after 30 seconds. Tap Discover again if you need more time. On older Biscuit firmware, use Refresh if the button still says Stop Discovery after the search ends.

View, rename, and remove saved nodes

The Saved list shows all remembered HID nodes, including offline nodes. The memory summary shows how many registrations are used and the capacity reported by your Biscuit. Nearby discoveries do not use saved memory until you add them.

Online means the Biscuit has detected the node. It becomes available in Automation after its secure connection is ready. If an online node stays unavailable, refresh the list and record the displayed error and firmware versions for support.

Tap a saved node to open its options. Its name, device address, firmware, and connection status help you tell similar nodes apart. Choose Rename to give an online node a recognizable name such as Lab Desktop. Names may contain 1–24 letters, numbers, spaces, or hyphens. The name is saved on the S3 HID Node itself, so that same name returns when it is discovered again or used with another Biscuit.

Choose Remove Saved Node to forget one node, or Delete All to clear the saved HID nodes after confirmation. Offline nodes can also be removed. These actions preserve the nodes’ names, your scripts, and your saved Wardrive nodes. You can add a removed node again during discovery.

Use Refresh to reload the list manually. Saved nodes remain visible while refreshing, and node management can finish loading before the script library. If an operation times out, the app checks the saved list before offering another attempt. Older Biscuit firmware supports individual management; update it to enable Add All, Delete All, and the capacity display.

Manager mode lets HID nodes connect; it does not start a node wardrive. HID nodes are never assigned wardriving work or included in wardrive results. Turning Manager off leaves saved HID nodes remembered but offline, and you can still remove them from memory.

When an enrolled HID node is online and authenticated, the Dashboard shows it in a separate Node pill with a keyboard icon. Tap that pill to open HID Automation. Saved, pending, offline, or unauthenticated HID nodes are not included in its count.

During beta testing, a powered HID node may take a while to return to the Dashboard after you restart the Biscuit. This reconnect delay is still being investigated.

The node remembers that Biscuit. To move it to a different Biscuit, hold GPIO0 for five seconds while the node is powered and idle, then add it from the new Biscuit. Resetting that Biscuit association does not erase the node’s saved name.

Trouble adding a node

If a node is no longer nearby when you tap Add to Memory, tap Discover and wait for it to reappear. Keep the node powered and the Biscuit in Manager mode while adding it.

A failure to save the HID node registry is different from full node memory. Check Saved after the app refreshes before trying again. If the save keeps failing, record the complete error and the Biscuit firmware version for support. Older app versions may incorrectly describe this as unavailable script storage; adding a node does not require a script.

An insufficient working-memory error while preparing a session does not mean the saved node registry is full. Update the Biscuit firmware and companion app. If it continues, record the complete error and firmware version for support.

Start on one or more HID devices

The device list chooses which Biscuit or S3 HID Node will act as the keyboard. It does not choose the computer or phone receiving the keystrokes.

Leave BadUSB selected. BadBLE is temporarily disabled and marked Coming Soon.
Select the script, keyboard layout, and one or more available HID devices.
Tap Start Session. Biscuit validates and prepares the script but does not type it yet.
Connect each receiving computer or phone to its selected HID device.
Wait for Host connected, then tap Play.

After a script finishes, the session stays ready so you can tap Play again without restarting either device. To choose a different script, tap Stop Session, make the new selection, and start the session again.

For BadUSB, connect each selected S3 HID Node to its authorized host. The node waits for USB to be ready before the app enables Play.

During a multi-device run, Biscuit waits until every selected keyboard is ready. If one device fails or drops out, Biscuit cancels the group instead of running only part of it.

The run screen uses one progress bar. While a script is still active, the bar keeps a visible gap and fills completely only after the run finishes.

On a standalone T-Dongle-C5 DIY, a local Bluetooth run temporarily changes its one Bluetooth radio from app control to keyboard operation. The app reconnects afterward to recover the result. An S3 HID Node is controlled through its saved Biscuit and exposes only USB HID to the receiving host.

Autorun and stopping a run

Autorun is off by default. When enabled, choose the exact script, interface, and layout that should run after insertion or startup. A missing script, disconnected host, or invalid layout prevents the run.

Use Cancel in the app to stop a prepared or active group. During a T-Dongle-C5 Bluetooth handoff, hold BOOT for one second to stop locally. On an S3 HID Node with the default physical recovery input, press GPIO0 briefly to abort the run. Cancellation, disconnect, validation failure, and completion all release keyboard, media, and mouse reports so keys and buttons are not left pressed.

Only use HID Automation on systems where you have clear permission to test.