Sunday, August 30, 2009

Up and running on the ButtonShield (and the ButtonPad)

The ButtonShield has been on the Shop for a while now, and Justin and Mike have sold a lot more of them than anyone ever thought, so Justin figured he would email around (with permission of course, not spam!) and ask what projects guys (and gals) were doing with them. The funny thing is that quite a few people actually worked at companies doing electronic design full time. Some guys said they were using the ButtonShield to create mockups of devices for presenting to management in order to get real project funding to build a project or a new device. Apparently the process of doing this also has official names, like "rapid prototyping" and "concept mockups". I always thought of rapid prototyping as 3D printing your own hardware, but apparently you can't 3D print working electronics (yet...almost), so for that, that's where Arduino comes in.

At least now I know what people are doing with their ButtonShields, which is gratifying because most of the time if you build something for someone else, you never get to hear what they did with it. Anyway, I figured it's high time to do another "up and running" post, so this is "Up and Running with the ButtonShield".

Step 1: Get the IDE

The Antipasto Arduino branch of the Arduino IDE has the ButtonShield hardware libraries baked in, and it's available for Mac, Windows, and Linux over at the "App Store".

Here's the Windows version

Here's the Mac version

Here's the Linux version (although technically if you're using Linux, this link is redundant because you probably already checked gitub. Actually you probably already know everything in this blog post because you committed source code to the tree... thanks electricFeel and mediaCoder)

Step 2: Install the IDE

Launch the installer (after Firefox checks to make sure there aren't any viruses or spamware, which there aren't but just in case). And just save to the default location (please) because the installer's technically not that smart, and likes to just be saved to the default specified place (neither Chris nor I are experts at writing installers).

Then wait 1-mississippi 2 mississippi 3 mississippi ... n^k m (iss)^2 ippi... done.

Step 3: Launch the Antipasto Arduino IDE

(For Windows users, the Antipasto Arduino IDE installs into the main Start menu.) When the IDE launches, it show a tab that's sticking out on the left. That's the "Gadget Module" selector tab, which allows me to pick which modules I'm writing code for.

Step 4: Create a New Gadget

Go to File->New Gadget to create a new "Gadget file". A Gadget file is a meta-file format that Omar developed that allows anyone to store multiple source code files compiled for different module architectures. That way, a single Gadget file can contain source code for a TouchShield, Arduino, ButtonShield, etc.

You can name the gadget file anything you want, I usually just call it "test" or "default" or "hello", but there are definitely more creative names out there.

Step 5: Add the Arduino you have by clicking the Plus Sign in the Gadget Window

Like this:

This sets all the source code you need in order to program the Arduino. It also pops up a standard template program including loop() and setup().

Step 6: Copy and paste the Hello World ButtonShield Code

Copy and paste this code into the Antipasto Arduino IDE window, replacing and overwriting anything that was already there:


/* Setup for Mode A */
ButtonShield buttons = ButtonShield(0);

void setup() {



void loop() {


This code includes the ButtonShield header which includes all the communication primitives you need. Then it defines a variable, ButtonShield buttons, so that you can use the variable buttons anywhere else in the code. Of course Serial.begin sets up a serial communication between the Arduino and the computer. And the piece-de-resistance (haw haw hawww in French) is: Serial.println(buttons.readButtons()). Really that's just trying to be clever on one line. First it's calling:


which is the magic function. It will read whatever is being pressed on the ButtonShield keyboard at the current time. Then, it encases it in:


which is the function that sends the number back up to the computer to be displayed.

Step 7: Compile the Code

Press the run button, to compile the code. If anything goes wrong, just make sure that the code is exactly right. If it is, but it still isn't working, email me :)

Step 8: Put the ButtonShield on the Arduino

This is the ButtonShield and Arduino separated:

Action shot - slow-mo cut sequence:

This is the ButtonShield and Arduino, happily reunited:

Step 9: Connect the USB cable from the Arduino to the computer

This is so obvious I'm not putting a picture here, on principle.

Step 10: Set the USB port in the Tools->Serial Port menu

If you're like me, you regularly have 4 or 5 Arduinos (and these days, 10-15 Illuminato X Machina's) dangling off of various USB ports around your computer. So then I always have to try to guess which USB Com port the Arduino decided to become this time - it usually works on the second or third try. Or maybe you just have one Arduino plugging in at any given time, and it's a lot easier.

Step 11: Upload the Program to the Arduino

By pressing the Upload to I/O Board button. Wait until it's done uploading (by checking to make sure the LED's have stopped blinking like mad underneath the ButtonShield).

Step 12: Open the Serial Monitor

And press buttons on the ButtonPad, and the key codes will be displayed in the Serial Terminal window...

Step 13: Use this code if you have a ButtonPad

13 is a lucky number because this is code for the ButtonPad, which hasn't been blogged about yet... and isn't even up on the store yet as of this post, but yeah... if you have a ButtonPad, which as of right now is no one but me and Chris, you could use this code:


//Create a new ButtonPad
ButtonPad MyPad = ButtonPad();

void setup()

void loop()
//Display the pressed buttons to the PC


//Random LED blinkage

1 comment:

Matt said...

for some reason, blogger strips out the header line... it's supposed to be:

#include ButtonPad.h

where the buttonpad.h is enclosed in greater-than and less-than signs.