• USB
  • Beginner
  • 5 min
  • Serial CLI

Recipe · Beginner · USB

How to use USB HID keyboard and mouse mode

USB mode can emulate a keyboard or mouse through native USB. This is useful for controlled HID tests on your own host machine.

USB HID keyboard and mouse controls.
Test HID behavior directly from the firmware without writing a TinyUSB example.

Wiring View

Host BP USB datanative USBGNDUSB GND
Generated from the wiring summary: Host to BP.
Step 1

Commands

Run the typed commands first. If the command opens an interactive shell, select the named action from the shell menu instead of treating it as another CLI command.

Result

What success looks like

Keep tests small and visible. Use a text editor for keyboard output and a safe desktop area for mouse movement.

Troubleshooting

  • Testing on a host you do not control.
  • Expecting HID on boards without native USB support.
  • Sending mouse movement while the cursor is over dangerous UI.
  • Forgetting that bridge keyboard mode sends terminal keystrokes live.

Next steps

  • Use keyboard bridge mode only when you are ready.
  • Use gamepad for simple button tests.
  • Use adapters for dedicated USB tools.

USB HID keyboard and mouse FAQ

When should I prefer one-shot keyboard text over bridge mode?

Use one-shot text for predictable, scripted input such as a short test string. Use bridge mode only when you intentionally want live terminal keystrokes forwarded as HID reports.

Why are mouse movement values limited?

USB HID relative mouse reports use small signed deltas. The firmware caps movement values to the supported range so one command cannot encode an invalid movement report.

How do I avoid unsafe HID tests?

Use your own host, keep focus on a harmless text editor or input tester, and avoid privileged terminals or destructive UI before sending keyboard or mouse events.

Go deeper