This is a simple library that handles real buttons, button-like digital switches (photo gates, Hall Effect switches, etc), as well as virtual buttons such as auto buttons and null buttons. If you want to be able to sense a whole bunch of input devices, such as buttons, keypads, rotary encoders, joysticks, etc, use the phi_interfaces library.

An auto button gets automatically pressed at a constant rate. It saves you an I/O pin when selecting from a short list or entering number. You just set the up button as an auto button so a list will cycle through all its items and all you need is one real confirm button.

A null button never gets pressed. If all you need is say 2 buttons, define the rest as null makes your buttons structure compatible with the rest of your/my codes. You don’t have to go into your code and delete the other buttons that you don’t use.

Any button has repeat when you hold on to it for some time. The button will be automatically pressed repeatedly as long as you hold it down. After repeating for 10 times, it enters a dash mode where the repeat is more rapid. This helps covering larger range of changes.

Lots of button status are defined.

Code snippets:

To create phi_buttons objects, do the following:

phi_buttons myButton(btn_pin, Polarity);

Now myButton is a button that is attached to arduino digital pin btn_pin, its polarity is either LOW or HIGH. If you use LOW polarity, then the button is depressed only when the digital pin changes to LOW. If you use HIGH polarity, then the button is depressed only when the digital pin changes to HIGH.

The phi_buttons constructor automatically sets the internal pull-up resistor on the corresponding pin so all you have to do is to connect one side of the button to GND, and the other side the the Arduino pin, and use LOW polarity. If you prefer the opposite polarity, you need a resistor to pull down the Arduino pin. Read this tutorial for HIGH polarity buttons:

To sense a button do the following:

int button_status;


Then you can react to the sensed button status according to the returned button_status:

buttons_up    button is not pressed
buttons_pressed   button is pressed (not in use)
buttons_down    button is down
buttons_held    button is held
buttons_released   button is released (use this to trigger actions when button is released)

Example 01: To sense a button release:

Make sure that your button is connected between digital pin 5 and ground. You can change the pin in the define command to any other pin.

#define btn 5

phi_buttons btn_1(btn, LOW);

void setup(){



void loop(){

int temp=temp1=btn_1.sense();

if (temp==buttons_released) Serial.println(“Button pressed, time to do something”);


Example 02: To sense all 6 buttons on Phi-2 shield:

#include <phi_buttons.h>

#define btn_u 5
#define btn_d 10
#define btn_l 11
#define btn_r 4
#define btn_b 14
#define btn_a 15
phi_buttons btn_1(btn_u, LOW);
phi_buttons btn_2(btn_d, LOW);
phi_buttons btn_3(btn_l, LOW);
phi_buttons btn_4(btn_r, LOW);
phi_buttons btn_5(btn_b, LOW);
phi_buttons btn_6(btn_a, LOW);

void setup(){



void loop(){

int temp=sense_all();

if (temp!=0) Serial.println(temp);


int sense_all()


byte temp1, temp2, temp3, temp4, temp5, temp6;

if ((temp4==buttons_released)||(temp4==buttons_held))
}   while (1);

return (0);


The current version is 327, released on 3/27/2011. Please find the library hosted on Google code under downloads:


First download the package, then extract the files under your Arduino Sketchbook/Libraries folder, so that the three files will be under c:/Arduino22/Sketchbooks/Libraries/phi_buttons/ (Just example, your directory may be different). Make sure you don’t have c:/Arduino22/Sketchbooks/Libraries/phi_buttons/phi_buttons/

Then close all Arduino IDE windows.

Reopen Arduino IDE, open a sketchbook you want to use the phi_buttons. Then choose under the Arduino IDE meny Sketch->Import library->phi_buttons

The Arduino IDE automatically creates a line in the beginning of your sketchbook: #include <phi_buttons.h>

OK you’re done!

Future directions:

This library is still supported but its future is unclear. I have constructed a phi_interfaces library to sense a whole bunch of different input devices and replaced phi_buttons with phi_interfaces in all my libraries that use input devices. I may absorb phi_buttons in a future release of phi_interfaces.

7 Responses to Phi_buttons

  1. Pingback: Morse code translator new version « Liudr's Blog

  2. Nicola says:

    Hi, great works.
    Just a simple question, it’s possible to connect the buttons to analogic port (A0-A5) ?
    Thanks in advance.

    • liudr says:

      Thanks! If by analogic port you mean connecting one button to analog port 0, yes, just use digital port 14 for analog port 0, 15 for analog 1 etc. If you were referring to using a special analog button setup, where you connect a few buttons and resistors all to one analog port, then the library can’t do yet. But I’m working on it with the new library update. When the new release is out, it will do alalog keys and rotary encoders.

      • hyrum says:

        Did this update come out yet? Are you going to give info on how to set it up with the resistors? Also, you say here that you just connect the buttons to ground do we need to use resistors with those?

      • liudr says:

        Been busy all semester so I have not rolled out the updates yet. Expect sometime after x-mas to do it. You are right about connecting buttons between an arduino pin and gnd. There is no need for resistors. The library enables internal pull-up resistors inside the arduino ATMEGA328P processor. The resistors I talked about was referring to an analog button design that some LCD shields use to save arduino pins. It’s what I will make the library compatible once I have time. Right now the library only takes digital buttons hooked up to digital pins.

  3. Nicola says:

    Thanks to you!!!
    Yes for analogic port i mean connecting a digital button (microswitch) to analog port.(because i’ve busy all other !!!)

    I’ve try with A0 to A5, but not working!
    Now i try with 14 to up !
    Thanks again!

    • liudr says:

      Yes, when used as digital ports, analog 0 is digital 14 and so on. So to declare a button on analog 0, just do phi_buttons (14,LOW); This is assuming that if you press the button, you connect the analog 0 to GND.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: