Using USB Keyboard

Your PC or Mac will detect a new keyboard. Then your program can send keystrokes which your computer will recognize as coming from a standard USB keyboard.

There are two ways you can make your Teensy send USB keystrokes.

The Easy Way: Keyboard.print()

Here is a very simple example, using Keyboard.print().

int count = 0;
void setup() { } // no setup needed
void loop() {
  Keyboard.print("Hello World "); 
  Keyboard.println(count);
  count = count + 1;
  delay(5000);
}

When this program is run, it will type "Hello World" and the increasing count. As you can see in this screenshot, the computer sees a USB keyboard and the keystrokes directly enter the Arduino editor. If delay(5000) had not been used, the result could be very unpleasant.

You may notice "Hello World 0" does not appear. The PC takes a brief time to detect the presence of a new USB device, but this program begins running immediately. If you use Keyboard.print() before the PC finishes the detection process (called "enumeration" in USB lingo), Keyboard.print() does nothing. A delay() can be added in setup(), if necessary.

The Micro Manager Way

The USB keyboard can have up to 6 normal keys and 4 modifier keys pressed at the same time. To micro manage the keyboard, you use functions to set which combination of keys you want pressed (and zero for the ones you want not pressed), and then use Keyboard.send_now() to send each combination.

You can use delay() or write code to check millis() between calling Keyboard.send_now(), to create the condition of a key held down similarly to a human typing. Auto-repeat is done by the driver on your PC or Mac, so if you have a long delay between pressing and releasing a normal key, the auto-repeat feature many delivery many key events to software.

When micro managing, you need to send a zero for each key you've pressed to cause that key to be released (as if a finger were lifting off the key and its spring were returning it to the resting position).

Modifier Keys

If you want no modifier keys pressed, use a zero.

Keyboard.set_modifier(0);

To press just one modifier is simple.

Keyboard.set_modifier(MODIFIERKEY_SHIFT);

To press more than one modifier, use the logic OR operator. For example:

Keyboard.set_modifier(MODIFIERKEY_CTRL | MODIFIERKEY_ALT);

Normal Keys

Keyboard.set_key1(KEY_A);
Keyboard.set_key2(KEY_B);
Keyboard.set_key3(KEY_C);
Keyboard.set_key4(KEY_D);
Keyboard.set_key5(KEY_E);
Keyboard.set_key6(KEY_F);

To release a key, you must set it to zero. For the above example, all six would need to be set back to zero if the next Keyboard.send_now() should not have any of these 6 keys pressed.

Keyboard.send_now()

The keys remain as you set them, so between each call to Keyboard.send_now(), you only need to make the changes you need. For example, this code would send a CTRL-ALT-DELETE sequence.

// press and hold CTRL
Keyboard.set_modifier(MODIFIERKEY_CTRL);
Keyboard.send_now();

// press ALT while still holding CTRL
Keyboard.set_modifier(MODIFIERKEY_CTRL | MODIFIERKEY_ALT);
Keyboard.send_now();

// press DELETE, while CLTR and ALT still held
Keyboard.set_key1(KEY_DELETE);
Keyboard.send_now();

// release all the keys at the same instant
Keyboard.set_modifier(0);
Keyboard.set_key1(0);
Keyboard.send_now();

It is important to set normal keys back to zero and send. If you do not, the key will remain pressed, and the PC or Mac USB driver will begin auto-repeat.

All Keys Codes

Bandwidth - Less Than You Might Expect

The HID protocol is used by USB keyboards, and HID uses the USB "interrupt" transfer type, which allocates 1 packet per a configurable number of USB frames. Each USB frame is 1ms, and the Teensyduino USB keyboard code requests the interval to be every frame. If the operating system honors this request, bandwidth is available for 1000 packets per second.

Each keystroke requires 2 calls to Keyboard.send_now(), the first to press the key and the second to release it. This translates to 500 keystrokes per second. Of course, you can send 10 different keys in each, but logic inside the USB device driver will analyze for changes, which imposes a practical limit, especially when sending to already-written software which expects "normal" typing.

Some operating systems might disregard the request and instead schedule 1 packet every 8 frames. At 16ms each, only 62.5 keystrokes per second are possible.

Some software, even when running on a multi-gHz, multi-core processor may perform so much work per keystroke (or be written so infficiently), that sending at such "fast" speeds could overwhelm the computer. You might need to add extra delays.

USB keyboard is slow. If you need substantial bandwidth, use USB serial.