In this lesson, we are going to talk about using the Arduino keyboard library! This is a really helpful way to automate keyboard functions by using the Arduino USB libraries and programming them to your Arduino board! Check out the video and lesson below!

 

USB Keyboard & mouse libraries

Have you ever found a repetitive task you’re doing on your computer and thought to yourself, “I wish I could automate this.”? Well, one way to automate these types of tasks is to use the USB libraries that are built-in with the Arduino IDE. In this lesson, we’re going to cover using the keyboard library. In the next lesson, we’ll be covering using the mouse library.

Both of these are super easy-to-use libraries. They’re really handy for automating these simple, repetitive tasks that you might find yourself doing from time to time on your computer.  We’re going to go through each function in these libraries.

Hardware (We’ll be using the Arduino Leonardo)

Let’s jump in by getting clear on what type of hardware you need in order to use for these libraries. So you need to use an Arduino board that is based on the 32u4 or the SAMD based boards. So that’s going to be a Leonardo, an Esplora (Retired), a Zero, a Due or any of the MKR Family Arduino boards. For this example, I’ll be using the Leonardo.

These types of boards allow the Arduino to act as a native USB device. When you plug it in your computer is going to recognize the board like a mouse, keyboard, or something that acts as an input device.

Pre-installed Libraries

As I mentioned the mouse and keyboard libraries come pre-installed with the Arduino.

 

But unlike the serial library, for example, you actually have to use the #include statements in order for them to work. It should look something like this.

Once you’ve included these two libraries, you get all of the functions inside of these libraries to be able to use in your sketch for free. You can also go up to sketch, include library.

And then over in the Arduino libraries, if you come down, you can find the keyboard or you can find the mouse.

And if you click on that, it just writes it right in there for you.

The other benefit of having these two USB libraries included is that they’re going to come with some example code which is the place to look when you’re trying to learn a new library.

So if you come up to file and you go to examples and you go down to USB, you can see there are several examples for the keyboard.

They’ve got multiple programs to sample and check out very instructive on how to use these functions.

Then they have a couple on the mouse and then they also have one on the keyboard & mouse combined.

The other place to look for information about these two libraries is the Arduino reference webpage.

If you navigate to USB libraries, you’ll find the keyboard & mouse libraries. Every solid developer will tell you, the documentation is your friend. So this is a good stuff to check out and read up on if you want to learn some of those small details that you might not pick up on, if you just try to implement the functions from the examples.

The code

We’re gonna work through all the functions in the keyboard library.

So with our code written out, we can see all the keyboard functions that we’re going to talk about.

Notice that I put all of the functions inside of an if statement and I want you to see what I set up here. Basically, I created a button, I set it as pin five. Then I set that button, which I’m calling enableBTN. I set it as an input. And then this, if statement checks, it’s going, it says digitalRead, enable pin. So it’s going to read the state at pin five. And if it’s high, it returns a one, which is also true. Or if it’s low, it returns a zero, which is also false.

So if the button is pressed, then we execute this code.

If the button is not pressed, the loop is gonna skip over this because the condition will be false. So this code only runs when this condition is true. And this condition is only true when I press a button.

Now I’m using a Kit-on-a-Shield for Arduino.

 

It happens to have a button that’s wired up to pin five. It’s got a pull-down resistor on it. So it’s normally low and when I press the button, it goes high, so this is working out pretty well.

Now you might ask, “Well, Mike, why do you have this construct here?”

The reason I have this construct here is that there is a caution on the Arduino website, in these libraries, both for the keyboard and the mouse that talk about the fact that as soon as you start using the keyboard and the mouse libraries, they are immediately active. And so that is, as soon as you plug in your Arduino board, it is going to begin emulating a keyboard or a mouse.

In this case, a keyboard. And that means it’s gonna start doing all these different commands that you might be wanting to do.

And you can imagine, your Arduino runs really fast and it can emulate keyboard typing a lot faster than you can actually type. So if you plug in your Arduino board and then all of a sudden you’ve got your keyboard printing inside a tight loop, you’re gonna have hundreds of lines of stuff being written in.

 

So it’s really important to make sure that these are all protected inside some type of construct like this, whether it be hardware or code or something like that.

Keyboard.begin & Keyboard.end

Let’s talk about these first two functions Keyboard.begin, Keyboard.end. In short, these functions are not yet implemented, so they essentially don’t do anything.

So if you go to the GitHub page for this library, the keyboard.cpp and you come down to where they are, they are blank. There’s nothing there.

So, we’ve got a couple more functions here. Let’s just run through them here real quick.

Keyboard.println & Keyboard.print

Let’s look at .print.ln and .print. So what these do is wherever your cursor is at, it is going to type in this text. If you use the print line, it’s gonna type in that text. And then basically it’s gonna press enter and go to a new line. If you just use print, it’s just gonna type this text. So let me go ahead and upload this to my Arduino board. And then I’m gonna put my cursor just right here, okay. So again, it’s wherever your cursor happens to be, it doesn’t mean it has to be in the Arduino IDE.

You’ll notice it may print twice. The reason is, the Arduino runs really fast and there isn’t any delay in current code. So, if I just hold the button down, it could it just starts filling it up, really fast.

So it’s not a bad idea to throw a little delay on the end of these things.

 

It’s not doing it super fast and you can press the button and release the button and it will work.

Keyboard.press, Keyboard.release & Keyboard.releaseAll

All right, so the next couple ones are Keyboard.press, Keyboard.release and Keyboard.releaseAll.

 

On your keyboard, you’ve got more than just numbers and letters, right? So if you wanna print out numbers and letters, that’s where you can use the println and the print. But what if you wanna do something, like Control + Alt + Delete or Control + Z or something like that, right?

Well, that’s where you can actually use keywords to press specific keys or a combination of keys. These are also going to be located on the Arduino Reference Page.

So, I tell you what, let’s go ahead and try the UP_ARROW. So I’m gonna put UP_ARROW into here. Let me comment this other stuff out. And then I’ll go ahead and upload this. I’m actually coming all this stuff out. All right, so every time I press the button, I’m gonna be pressing the UP_ARROW. So let me go ahead and upload this. So now when I press this button, the cursor should go up. All right, now, notice it went all the way up. I pressed it once, but it went all the way up. And look at that. I’m down here and it’s still going all the way up. What is with that? See, it’s like as if it’s always being pressed. Remember, anytime you use the keyboard or the mouse libraries, the library is always running. Now you might be like, “But, Mike, look, didn’t we call digitalRead shouldn’t that have stopped this?”

I’m not, ’cause you notice, I’m not pressing the button anymore. Shouldn’t this behavior have stopped when we’re not pressing this? Well, you might be tempted to think so, but what happens is these keyboard presses, they latch. So when you say press, we’re literally still pressing the button. So we’ve said, “Hey, we want this function to happen.” It happened. And when we exit it, it’s still being held down. So in order to not have this down, we have to use this next function, this Keyboard.release. Now here’s what’s entertaining. Look here, I’m gonna try to delete this comment here. Do you see how it’s fighting me.

This is why it can get a little tricky to program in here and you gotta be incremental in how you do it and careful on how you do it. As I was playing around with this library, I may have created a for loop that never exited and was writing letters all over the Arduino IDE and moving the mouse.

And I was struggling to be able to get the mouse up here to upload a different sketch because it literally, it takes over your mouse.

Now you can always unplug the Arduino board, but if you wanna try to reprogram near the Arduino, it can be a little bit difficult. Okay, so what I’m gonna do is I’m gonna go ahead and upload the sketch again. And what that’s gonna do is now we haven’t pressed this enabled button yet. So this line of code has not been executed yet. So now, what I’m gonna do is I’m gonna go Keyboard.release. So Keyboard.press is gonna press the UP_ARROW key, but now what I’ll do is I’m gonna use Keyboard.release and I’m going to release the KEY_UP_ARROW.

And for good measure, I’ll throw a delay in here. Let me upload this. Now when I have my mouse here and I press the button, see, I go up one, go up another, go up another. And again, it doesn’t matter where you are, wherever your cursor is active.

And then finally, we’ve got two more here. These are pretty straightforward. This last one here is Keyboard.releaseAll. So let’s say I wanted to do some keyboard combination where I wanted to have press the Command + Shift at the same time while I would have two buttons, right, that I am pressing. So two buttons pressed and instead of doing a Keyboard.release for each one of those, I could just do Keyboard.releaseAll, and then it would just release any button that was previously pressed, so that’s what releaseAll does.

Keyboard.write

So finally, we get to Keyboard.write.

Keyboard.write is a lot like Keyboard.print and keyboard.println, except that instead of printing a string out, like text, it is going to print in ASCII. So the number of 65 happens to be a capital A.

So if I comment these out and upload this and I stick my cursor right here, when I press the button, notice a bazillion As come out. And remember, a ton of them come out ’cause we don’t have any delay in this if statement. For the length of time, I’m pressing that button, we’re getting all those As, let’s just put a bunch of them in there just for fun. Yeah, see, that’s cool. All right. Okay, so get rid of those As. Let’s go ahead and just take a quick look at the Documentation for Keyboard.write. So I’m just in the Reference again, I’m in Functions coming down to keyboard. Now I’m looking for Keyboard.write. And you can see just right here, this is what we’re looking at. So it sends the ASCII value 65, it’s gonna print A, if you put your single character in quotes, it’ll print that, right? The ASCII there. You can write it in hexadecimal if you want, or hey, you could even do it in binary.

So that’s it with the keyboard library, hopefully your gears are turning in your head on how you can use it. It’s really pretty fun, especially if you find yourself having some repetitive task. So in the next video, we’ll talk about using the mouse library. It’s pretty similar, it’s also pretty straightforward. There’s a couple of things in there you got to think about, hopefully you found this really helpful.