Installing an Arduino Library

What's a Library?

Arduino libraries take a complex task and boil it down to simple to use functions. Arduino users have written lots of exciting add-ons for Arduino. For example, capacitive sensing takes difficult timing and pulsing of digital pins. We can write the code from scratch, or we can stand on the shoulders of great people who are smarter than we are.

Capacitive touch sensing is a very popular interface. The CapacitiveSensor library takes care of everything so that we don’t have to write code like this:

*sOut &= ~sBit;        // set Send Pin Register low
*rReg &= ~rBit;        // set receivePin to input
*rOut &= ~rBit;        // set receivePin Register low to make sure pullups are off
*rReg |= rBit;         // set pin to OUTPUT - pin is now LOW AND OUTPUT
*rReg &= ~rBit;        // set pin to INPUT 
*sOut |= sBit;         // set send Pin High
interrupts();         // enable interrupts

while ( !(*rIn & rBit)  && (total < CS_Timeout_Millis) ) {
    total++;
}

if (total > CS_Timeout_Millis) 
    return -2;         //  total variable over timeout

// set receive pin HIGH briefly to charge up fully
noInterrupts();         // disable interrupts
*rOut  |= rBit;        // set receive pin HIGH - turns on pullup 
*rReg |= rBit;         // set pin to OUTPUT - pin is now HIGH AND OUTPUT
*rReg &= ~rBit;        // set pin to INPUT 
*rOut  &= ~rBit;       // turn off pullup
*sOut &= ~sBit;        // set send Pin LOW
interrupts();         // re-enable interrupts

while ( (*rIn & rBit) && (total < CS_Timeout_Millis) ) { 
    total++;
}

if (total >= CS_Timeout_Millis)
    return -2;     // total variable over timeout
else
    return 1;

All that code can be replaced with a much easier to use and understand statement such as:

senseReading = myCapPad.capacitiveSensor(30);

myCapPad.capacitiveSensor() takes care of all the heavy lifting and the senseReading variable contains the value sensed from our capacitive pad. Libraries make complex tasks easier so that we can focus on larger projects.

There are thousands of libraries out there! And luckily it’s pretty easy to install them. This tutorial will show you how to a library in Arduino v1.0.5 but should apply for many past, present, and future versions of Arduino.

Installing a Library - Windows

This section covers installing a library under the Windows environment and utilizes quite a few screen shots. If you’re more of a text learner then check out the Arduino tutorial on installing libraries.

We are going to use the Capacitive Sense library for this example. Navigate to the library’s page and download the zip file.

The contents of the Capacitive Sense zip file

Find the zip file on your local computer (wherever downloaded files end up). Under Windows, you should be able to double click on the file to open it up.

This particular library contains libraries for both the basic Arduino and the more advanced Arduino Due. You can use both if you’d like, but, for this example, we will be copying and installing only the CapacitiveSensor folder.

Libraries will usually contain a .cpp file and .h file. Most will also contain an examples folder.

Under Windows, Arduino stores all the add-on libraries within the My Documents folder. Here we see the location of the Arduino libraries folder.

Open an explorer window and navigate to the libraries folder under My Documents. Now copy the newCapacitiveSensor folder to the libraries folder.

Success!

Note: Arduino does not allow library folders to contain symbols such as hyphens ‘-’. Arduino will throw an error upon starting up. If the library you are installing has a funky folder name then this step is the ideal time to clean it up.

To verify the library has been installed correctly, open up the Examples folder under the Arduino IDE.

Wait. Where’s the CapacitiveSensor example? Did you have Arduino open when you copied and pasted the directory? Arduino checks the library directory at startup so if you already have Arduino open, you will need to restart Arduino any time you add to the libraries directory. If you don’t see the CapacitiveSensor example try closing and re-opening Arduino.

There it is! Let’s open the example provided with our new library.

Examples are the greatest thing about libraries! Good libraries will have well written examples showing how to use the library. These sketches are wonderful resources for example code and learning how to write good code under Arduino.

You now have the Capacitive Sensor library installed! Feel free to start from the example sketch, or begin writing your own code using the functions provided by the library. A library usually has documentation either on its site or written into readme files and example code. In general, to quickly learn how to use a library check out the example code.

Installing a Library - Mac

This section covers installing a library under the Mac OS X environment. If you’re more of a text learner then check out the Arduino tutorial on installing libraries.

We are going to use the Capacitive Sense library for this example. Navigate to the library’s page and download the zip file.

Find the zip file on your local computer (wherever downloaded files end up). Unzip it, and look at the folder contents.

The contents of the Capacitive Sense zip file. Libraries will usually contain a .cpp file and .h file. Most will also contain an examples folder.

This particular library contains libraries for both the basic Arduino and the more advanced Arduino Due. You can use both if you’d like, but, for this example, we will be copying and installing only the CapacitiveSensor folder.

Now we need to add this folder to the Libraries folder for Arduino. This folder is somewhat hidden in OS X. To get there you can do one of two things. Option one, right-click on the Arduino icon located in your Dock. Go up to ‘Options’, then click ‘Show in Finder’.

Option two, find the Arduino app located in your applications folder within Finder.

Either option should get you to this point. Now, right-click on the Arduino app, and select ‘Show Package Contents’.

Navigate through the following folders, ‘Contents -> Resources -> Java’, until you reach the ‘libraries’ folder. Note: if you don’t have a libraries folder, simply create one here.

Inside the libraries folder is where you want to copy/move the library folder you just downloaded and unzipped. You’ll aslo notice this is where all the default libraries live as well as any other libraries you may have installed in the past.

Note: Arduino does not allow library folders to contain symbols such as hyphens ‘-’. Arduino will throw an error upon starting up. If the library you are installing has a funky folder name then this step is the ideal time to clean it up. Make sure the name of your folder matches the name of the files located within the library folder.

Next, make sure that restart the Arduino IDE if it was open when you installed the library. This is a very important, often overlooked step. If you don’t restart, the library you just installed will not yet be available to the IDE.

To verify the library has been installed correctly, open up the ‘Examples’ folder under the Arduino IDE.

There it is! Let’s open the example provided with our new library.

Examples are the greatest thing about libraries! Good libraries will have well written examples showing how to use the library. These sketches are wonderful resources for example code and learning how to write good code under Arduino.

You now have the Capacitive Sensor library installed! Feel free to start from the example sketch, or begin writing your own code using the functions provided by the library. A library usually has documentation either on its site or written into readme files and example code. In general, to quickly learn how to use a library check out the example code.

Resources and Going Further

If you’re looking for some great libraries to get started with, here are some of our favorites:

• TinyGPS is the gold standard for interfacing to GPS modules.
• SevSeg is a library we wrote to make controlling 7-segment displays easier.
• Sdfat is a very good library that allows you to read and write files to SD cards. Great for datalogging! Be sure to checkout all the examples included with the library.
• MP3Shield is a great example of a customer of SparkFun taking complex example code and creating a very good library to make the device easier to use.
• EEPROM is a built-in library that allows users to read and store settings within the non-volatile memory of the ATmega328. Very useful!
• Capacitive Sensor is the library we covered in this tutorial. It’s great for non-contact capacitive switches and field sensing.
• Infrared Remote is a great library for reading signals from IR remotes and controlling IR remote based things like TVs and sound systems.

Built in libraries

You may not realize it, but you’re probably already using libraries! If you’ve used:

Serial.print("Hello world!");

Then you’re using the Serial() library built in to Arduino. Arduino has quite a few built-in libraries. Here’s the list of the libraries that you can start using immediately!

Write your own Arduino library

Once you’ve used a handle of different libraries, consider writing your own! Here’s a good tutorial showing how to write your own library so that you can help the world by making complex tasks a little easier.

8:28 PM