HID Buttons Library for Arduino

As I keep working on a number of custom controllers using Arduino boards, I noticed that I tended to build the same sort of data structures every time; things to make it easier to write my own code using the built-in Arduino libraries. One of these bits I kept rebuilding was a wrapper class for the keyboard and mouse libraries that kept track of the keys I was using and their associated output states so that I could set them with a single line of code. Now instead of building yet another version of the same thing for my next project, I decided to turn it into a library instead.

The Arduino’s USB HID libraries work great – they make it easy to send Keyboard, Mouse, or Joystick inputs from your sketch, but they don’t do a great job of keeping track of which inputs you’re using and their state. At best this means you have to write some extra code with dedicated variables for the output key and output state with a group of ‘if’ statements to handle changes. At worst it means you’re spamming button presses to the PC and causing all sorts of other unintended behavior.

For example, here is some code borrowed from a friend’s project that presses a keyboard button when an analog stick moves into a given range:

boolean aPressed = false;

void loop() {
	int stickY = analogRead(A0);

	if (stickY < -300) {
		if (aPressed == 0){
			aPressed = 1;
			Keyboard.press('a');
		}
	}
	else {
		if (aPressed == 1) {
			aPressed = 0;
			Keyboard.release('a');
		}
	}
}

The 12 lines that make up the if statements to see whether to ‘press’ or ‘release’ the key were repeated for every input in the project. That’s a lot of repeated code that is a pain to write and even messier to read.

HID Buttons

For my own projects with HID buttons I tried to build a more elegant solution: a small class that keeps track of the key and button state, and only calls the HID output function when the state changes. You can see variations of this in the DJ Hero Lucio project and in the code for the Stream Cheap keypad. Seized by inspiration the other week, I reworked a version of this into an Arduino library that can be used in any sketch.

Using classes greatly reduces the amount of code the user has to write to track the state of a given HID button. Here’s the same code above, written using an HID_Button object:

#include <HID_Buttons.h>

KeyboardButton moveLeft('a');

void loop() {
	int stickY = analogRead(A0);
	moveLeft.set(stickY < -300);
}

The object keeps track of the key being pressed (in this case ‘a’) and the state of the output, so you only need to call the ‘set’ function to accomplish everything in the longer code above. Implementing a joystick to ‘WASD’ program only requires 7 more lines of code, compared to 40 with the long form ‘if’ statements above.

Features

The library has all of the typical functions you need to manipulate button outputs:

• Press
• Release
• Set
• Toggle
• Write

Since each object also keeps track of its own button’s information, you can also read the button’s state or the key value. All button objects are also inserted into a linked list, so it’s possible to reset all of them by calling releaseAll. This function is tied to each HID type, so if you’re making a composite device you can release the buttons of one HID type without affecting another – such as releasing all keyboard keys without letting go of the mouse buttons.

At the moment the library supports Keyboard, Mouse, and Joystick buttons, although I’ve included a guide for adding additional HID types.

Download

The library is available on GitHub and can also be downloaded through the Arduino IDE’s Library Manager (search for “HID Buttons”). Enjoy!