This project builds a scriptable USB keyboard using a Teensy. The board emulates a conventional keyboard, but with an extra twist: it receives commands over serial, so it can be driven from a laptop or a Raspberry Pi. This lets you control a computer before the operating system boots. You can select the bootloader, change BIOS settings, or interact with any pre-boot menu, all without a physical keyboard.
The problem is a common one: you have a headless machine, like a Raspberry Pi, and you need a keyboard for the initial setup. Often there isn’t one available. With this project, the laptop keyboard becomes the keyboard of the target machine. The project board describes the full flow, from programming the Teensy to using it over the network. All with inexpensive components and open source software.
How the scriptable USB keyboard works
The heart is the Teensy, a microcontroller with native USB support. You flash it with the sketch in the etherkey folder. Connected via USB to the system you want to control, it appears as a normal keyboard. The serial connection goes through a USB-to-UART adapter, with TX on Pin 0, RX on Pin 1, and GND on GND. Alternatively, you can use a Raspberry Pi, which adds network capabilities. This way you can send commands remotely.
Communication runs at 57600 baud. You use the cu command to open the serial port, for example cu -l /dev/ttyUSB0 -s 57600. The Teensy offers three operating modes. Interactive mode sends the keys pressed on the console directly. Command mode interprets the line as a command, such as SendRaw or Send. Debug mode shows information about the received character, including the ASCII code and the USB keycode.
The commands support modifiers like ALT, SHIFT, CTRL, and WIN. Special keys are indicated in curly braces, for example {ENTER} or {F2}. For Unicode characters there are specific sequences: UCL for Linux and UCW for Windows. You use 4-digit hexadecimal codes. This lets you type characters not present on an Italian keyboard, such as symbols or accented letters.
Setup and practical use
To get started, you need a Teensy and a USB-to-UART adapter. You program the Teensy with Teensyduino, the integrated development environment. Then you connect the adapter to the correct pins. Finally, you open a serial connection from the laptop. The target system sees the Teensy as a standard USB keyboard. From there you can type anything, even during POST or in the BIOS.
The Raspberry Pi can replace the USB-to-UART adapter. In this case you use the Pi’s UART serial port, accessible at /dev/ttyAMA0 or /dev/serial0. The connection is identical, but you add the ability to control the keyboard over the network. Additionally, the Pi can run more complex scripts. For example, you can automate the setup of multiple machines without manual intervention.
Command mode is particularly useful for automating repetitive operations. You can send a key sequence to access a machine’s boot menu. Or you can change the boot order in the BIOS. All without physically touching the target machine. This saves time and reduces typing errors.
Components and alternatives for the project
Besides the Teensy, you can use a Raspberry Pi Pico with the RP2040 chip. This microcontroller has similar USB capabilities and a lower cost. The expansion board for Raspberry Pi Pico and Pico W expansion board for Pico simplifies the connections. The Primer Kit Primer Kit Plug&Play provides everything you need to get started. Additionally, the 1 GB and 2 GB versions of Raspberry Pi 5 and Raspberry Pi 5 2 GB are excellent as control hosts.
The choice of microcontroller depends on your needs. The Teensy is simple and supported by Teensyduino. The RP2040 is cheaper and has an active community. Both work with the same wiring scheme. The Raspberry Pi is only needed if you want network control. For local use, the USB-to-UART adapter is sufficient.
In summary, this project solves a real problem with simple tools. The scriptable USB keyboard is versatile and reusable. You can adapt it to many scenarios, from server setup to embedded systems maintenance. It’s also a great starting point for learning how USB and serial protocols work.
- Teensy with etherkey sketch to emulate the keyboard
- USB-to-UART adapter or Raspberry Pi for serial
- Teensyduino to program the microcontroller
- cu command at 57600 baud for the connection
Source: https://github.com/Flowm/etherkey
