Your PC orMac will detect a new keyboard. Then your program can send keystrokeswhich 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().

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 thekeystrokes directly enter the Arduino editor. If delay(5000) had not been used,the result could be very unpleasant.

Sometimes 'Hello World 0' may not appear. The PC takes a brief time todetect the presence of a new USB device, but this program begins runningimmediately. If you use Keyboard.print() before the PC finishes the detectionprocess (called 'enumeration' in USB lingo), Keyboard.print() does nothing.A delay() can be added in setup().

Keyboard Layouts

If you see the wrong characters from Keyboard.print(), Teensy may be emulatinga US keyboard layout, but your computer expects a non-US keyboard, or vise-versa.The layout setting only affects Keyboard.print() and Keyboard.write().

Using Pushbuttons

The Bounce library provides the easiest way to reliably detect pushbuttons changes.This code shows the basic approach. Just update()each object, and then use thefallingEdge() to check if it has changed.

For a complete example:File > Examples > Teensy > USB_Keyboard > Buttons.

Individual Key Press / Release

You can use Keyboard.press(key) and Keyboard.release(key) to send individualkey press and release events. The 'key' may be ordinary characters, or specialkey codes.

All Keys Codes

TODO: document the 8 media key codes and the special set_media() function. Currently theseonly work on Mac and Linux. Windows does NOT work. A future version will redesignthis feature to hopefully work on Windows too.For now, the only documentation is the example, in File > Examples > Teensy > USB_Keyboard > MediaButtons.

The Micro Manager Way

Only key codes may be used with the Micro Manager functions. The key codesrepresent the location of a key on the USA English keyboard layout. The keyboardlayout is not used. The media and system keys are not supported. With this way,you are very directly controlling the actual key codes without any extra softwaretranslation!

The USB keyboard can have up to 6 normal keys and 4 modifier keys pressed at thesame time. To micro manage the keyboard, you use functions to set which combinationof keys you want pressed (and zero for the ones you want not pressed), and thenuse 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 longdelay between pressing and releasing a normal key, the auto-repeat feature maydeliver many key events to software.

When micro managing, you need to send a zerofor each key you've pressed to cause that key to be released (as if a finger werelifting 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.

To press just one modifier is simple.

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

Normal Keys

To release a key, you must set it to zero. For the above example, all sixwould need to be set back to zero if the next Keyboard.send_now() shouldnot 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 wouldsend a CTRL-ALT-DELETE sequence.

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

If you are familiar with the older PS/2 keyboard 'scan codes', please be awarethat USB keyboard codes work differently (and use different numerical values).The old scan codes sent differentmessages for key down and key up events, where each message represented a singlekey's change. With USB, each message represents the complete state of the keyboard.Up to any 6 keys may be pressed at once, plus any combination of the 8 modifier keys.

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 USBframes. Each USB frame is 1ms, and the Teensyduino USB keyboard coderequests the interval to be every frame. If the operating system honorsthis request, bandwidth is available for 1000 packets per second.

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

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

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

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