13

USB Programming

This chapter looks at various aspects of using the Arduino with USB. This includes the keyboard and mouse emulation features provided by the Arduino Leonardo and also the reverse process of allowing a USB keyboard or mouse to be connected to a suitably equipped Arduino.

Keyboard and Mouse Emulation

Three Arduino boards—the Due, the Leonardo, and the Micro, which is based on the Leonardo—can use their USB port to emulate a keyboard or mouse. There are also Arduino-compatible boards like the LeoStick from Freetronics (Figure 13-1) that can perform this trick.

Figure 13-1   The LeoStick.

This feature is practically used largely for things like music controllers, giving the Arduino a way to interface with music synthesis and control programs like Ableton Live. You could, for example, build novel musical instruments with Arduino that use accelerometer readings, interrupted beams of light, or pedal boards to control music software.

Some of the sillier applications of these features include pranks where the computer mouse appears to take on a life of its own or the keyboard itself types random letters.

The Arduino Due has two USB ports. Keyboard and mouse emulation takes place on the native USB port, and you normally program the Arduino Due using the programming USB port (Figure 13-2).

Figure 13-2   The Arduino Due’s two USB ports.

Keyboard Emulation

The keyboard functions are quite easy to use. They are part of the core language, so there is no library to include. To begin keyboard emulation, simply put the following command in your startup function:

Keyboard.begin();

To have the Arduino “type” something, you can use print and println commands and the text will appear wherever the cursor is positioned:

Keyboard.println("It was the best of times.");

If you need to use modifier keys, such as typing ctrl-c, then you can use the press command:

The press command takes a single char as its parameter, and in addition to all the normal characters, a number of constants such as KEY_LEFT_CTRL are defined for you to use. Once you issue the press command, it is as if the key is held down until the releaseAll command is given. You can find a full list of the special keys here: http://arduino.cc/en/Reference/KeyboardModifiers.

NOTE   When using the keyboard and mouse emulation features, you may encounter difficulty programming the board as it might be trying to type text while you are trying to program it. The trick is to keep the Reset button depressed and only release it when the “uploading” message appears in the status line of the Arduino IDE.

Keyboard Emulation Example

The following example automatically types text of your choice (for instance, a password) every time the Arduino is reset:

This example would be better if an external button triggered the typing; if you are using a Mac, the operating system thinks a new keyboard has been attached when you reset the device, which opens a system dialog that you must dismiss before the text is typed.

Mouse Emulation

Emulating a mouse follows much the same pattern as emulating a keyboard. Indeed, there is no reason why you cannot use both in the same sketch.

The first step is to begin emulation:

Mouse.begin();

You can then move the mouse using Mouse.move. The three parameters are the amount to move the x, y, and scroll button in pixels. These numbers can be positive (right or down) or negative (left and up). They are relative to the current mouse position, and as there is no way to get the absolute position of the cursor, this emulation just emulates the mouse that moves the cursor, not the cursor itself.

You can also click the mouse using the click command. With no parameters, this command is a simple left button click. You can also optionally supply an argument of MOUSE_RIGHT or MOUSE_MIDDLE.

If you want to control the duration of a mouse click, then you can use the Mouse.press and Mouse.release commands. Mouse.press takes the same optional arguments as Mouse.click. This can be useful if you are, say, making your own mouse from an Arduino and want the button click to be controlled by a switch connected to a digital input on the Arduino. Doing this would allow you to double- or triple-click.

Mouse Emulation Example

The following example moves the mouse randomly around your screen. To stop the program so you can regain control of your computer, either press and hold down the Reset button or just unplug the board.

USB Host on the Arduino Due

The Arduino Due has the ability to act as a built-in USB Host. This feature is, at the time of writing, considered to be “experimental” by the Arduino team. Check the official Arduino documentation (http://arduino.cc/en/Reference/USBHost) for changes to the status of this work or any changes to the way it is used.

The Due does not have a full-size USB socket into which you can directly plug a USB keyboard or mouse. To use such devices, you must get a Micro USB OTG Host Cable like the one attached to the Due pictured in Figure 13-3. In the figure, the USB adapter for a wireless keyboard is attached to the Arduino Due, but a regular USB keyboard would work just fine.

Figure 13-3   Arduino Due with a Micro USB OTG Host Cable and keyboard.

The USB libraries on the Arduino Due are actually a great deal easier to use than the USB Host library and will return the ASCII value of a key that is pressed and not just the USB key scancode. The following example illustrates interfacing to a keyboard. It simply echoes each keypress in the Serial Monitor.

The KeyboardController library invokes the keyPressed function in the sketch every time a key is pressed. You can also intercept key release using the keyReleased function. To find out which key was pressed, you must call one of the following functions on the keyboard object:

• getModifiers Returns a bit mask for any modifier key that is depressed (shift, ctrl, and so on). See http://arduino.cc/en/Reference/GetModifiers for the codes.

• getKey Gets the current key as an ASCII value.

• getOemKey Returns the key scancode.

Using a mouse is equally easy and follows a similar pattern to the keyboard controller. The following example writes a letter—L, R, U, or D—depending on whether the mouse is moved left, right, up, or down:

As well as the mouseMoved function, you can also add the following functions to intercept other mouse events:

• mouseDragged This event is triggered when moving the mouse while holding down the left button.

• mousePressed This event is triggered when a mouse button is pressed and should be followed by a call to mouse.getButton, which takes a button name of LEFT_BUTTON, RIGHT_BUTTON, or MIDDLE_BUTTON as an argument and returns true if it has been pressed.

• mouseReleased This function is the counterpart to mousePressed and is used to detect when the mouse has been released.

Summary

In this chapter, you looked at a few ways to use an Arduino with USB devices.

In the next chapter, we will look at using wired and wireless network connections with an Arduino and learn how to do some network programming as well as make use of the Ethernet and WiFi Arduino shields.