Arduino libraries how to

Arduino libraries, what they are and how to install them

What is a Library?

Libraries are great places, and not yet illegal in the United States! If you ever need to learn how to do something, like say fix a motorcycle, you can go to your local library and take out a book. Sure you could buy the book but the library is nice because as a resource you can get the book whenever you need it, keeping your house uncluttered.

Software Libraries are very similar. We already studied what a procedure is, in lesson 3 : a procedure is a list of things to do. A library is a big collection of procedures, where all the procedures are related! If you, say, want to control a motor, you may want to find a Motor Control Library: a collection of procedures that have already been written for you that you can use without having to do the dirty work of learning the nuances of motors.

For example, this is the Serial Library, which allows the Arduino to send data back to the computer:

Using libraries ?

One of the best features of the Arduino project is the ability to add on pre-crafted libraries that add hardware support. There's tons of them, and you can pick and choose which to install. They're only loaded in when the sketch you're working on needs them, so for the most part you can download and stash them for future use.
Sketches will often depend on libraries, you can see what they are by looking at the top of the sketch.

If you see something like #include <FatReader.h> 
that means that you'll need a library called FatReader or a library that contains the file FatReader. If you dont have it installed you'll get an error:

Whats in a Library!

A library is a folder with some files in it, the files will end in .cpp (C++ code file) and .h (C++ header file).

There may also be some .o files. The .o files are C++ compiled Objects. If you end up working on the library and modifying it, be sure to delete the .o files as that will force the Arduino IDE to recompile the modified .cpp's into fresh .o's

Two optional files you may see are keywords.txt (this is a hints file to tell the Arduino IDE how to colorize your sketch and examplesfolder, which may have some handy test-sketches. These will show up under the Files/ Examples/ Library dropdown

It is important to remember!

The structure of the library folder is very important! The .c and .h files must be in the 'lowest level' of folders. For example, you cant have Arduino/libraries/WaveHC/WaveHC/file.c or Arduino/libraries/MyLibraries/WaveHC/file.c - it must beArduino/libraries/WaveHC/file.c
How to install libraries

In Arduino v16 and earlier, libraries were stored in the ArduinoInstallDirectory/hardware/libraries folder, which also contained all the built-in libraries (like Wire and Serial).

In v17 and up, the user libraries are now stored in the ArduinoSketchDirectory/libraries folder. You may need to make the librariessub-folder the first time. However, the good thing about this is you wont have to move & reinstall your libraries every time you upgrade the software.

For example, here is how it looks when NewSoftSerial is installed in Windows (of course your username will be different)

After you're done, restart the Arduino IDE

Amtel Chip bootloader hack for Arduino

Burning bootloader chips using an Arduino
by Ladyada, Adafruit Industries

A lot of people start learning about microcontrollers with an Arduino but then want to build their own projects without having to sacrifice their dev board. Or maybe they want to make their own Arduino variant, that is compatible with the IDE. Either way, a common problem is how to burn the bootloader onto the fresh AVR chip. Since AVRs come blank, they need to be set up to be Arduino IDE compatible but to do that you need an AVR programmer (like the USBtinyISP).

This tutorial is an extention of that tutorial. First we'll show how you can make a permanent bootloader-burner by soldering a 28-pin ZIF socket to a proto shield and use the PWM output line of the Arduino to generate a clock. This will let you 'rescue' many chips that have been set to the wrong type of oscillator, or change ones that are set from external oscillator (most Arduino bootloaders) to internal (such as the lilypad)

According to the the ArduinoISP writeup from, thus does not work with the newest UNO Arduinos. BUT we got it to work just fine, so not sure if the issue was fixed or its a rare error, or what.


You will need...
  1. An Arduino
  2. A proto shield kit
  3. 28-pin ZIF (zero-insertion force) socket (you can use a plain socket but ZIF is ideal)
  4. Some wire
  5. Blank ATmega328P

First up, place the ZIF socket on the proto shield like so:

Solder the following wires to the ZIF socket
  1. Pin 1 to digital 10 - Blue
  2. Pin 7 to 5V - Red
  3. Pin 8 to Ground - Black
  4. Pin 9 to digital 9 - Gray
  5. Pin 17 to digital 11 - Brown
  6. Pin 18 to digital 12 - Orange
  7. Pin 19 to digital 13 - Yellow
  8. Pin 20 to +5V - Red
  9. Pin 22 to Ground - Black

Follow the protoshield tutorial to solder in the Red LED into LED1 position, Green LED into LED2 position. Also solder in the two 1.0K resistors next to the LEDs. We'll use the LEDs as indicators. Then solder a wire from the LED2 breakout (white) to analog 0 and a wire from LED1 breakout (white) to digital 8

Finally, you'll need to solder on the header to allow the shield to be placed on, break the 0.1" male header and place it into the Arduino sockets. Then place the shield above on top to solder it in place

Load the Code

Time to load the sketch! Grab the code from our Github repository and paste it into a new sketch. Then upload it to the Arduino
Plug the shield on top, lift the latch, pop in the chip and then lower the latch. Make sure the chip orientation is like so: so with the lever on the left side you can read the text.

With the USB cable still plugged in (and the same Serial port selected as before) Select Tools->Burn Bootloader->w/Arduino as ISP

The Green LED will be on during the programming, when its done you'll see this message and the LED will turn off

Thats it! Don't forget, you can burn a few different kinds of bootloaders, such as Uno, Duemilanove, Lilypad so depending on your situation you may want to use one over the other.

The parts in this project could be purchase from Adafruit Industries

Arduino Alternative Power Sources

Using alternative power source to power an Arduino project.

Advanced Arduino

Including Multiple Libraries In Your Project

Arduino IDEThe Arduino IDE is a great environment for getting started programming microprocessors. It radically lowers the cost of entry, and greatly simplifies the learning curve. The importance of these properties should not be underestimated. Most of us are capable of advanced microprocessor programming given time, desire and opportunity even without the Arduino environment. The biggest obstacle, however, is getting started. When that first hurdle is at last overcome, we can then soar to greater heights. That is where the Arduino is an incredible blessing. It is so simple that it removes most of the barriers to entry. From scratch, we can get started in microprocessors and build our confidence and knowledge at an easy pace. Once that is done, then we can advance to more complex projects and techniques.

That easy means of entry, however, can also become a limitation. Because the Arduino IDE makes the cost of getting started very low, that same simplicity can also prevent us from advancing to more complex projects. A good example is when you want to create new libraries that make use of existing libraries. When you try to do so in the usual fashion of including libraries, you are confronted with compiler errors. This article will examine the problem in combining various libraries within the IDE and how to work around them. It will also address some more advanced C++ practices that help when dealing with multiple libraries and larger projects.

Including Libraries within Another Library

The Arduino IDE has an easy way to include libraries in your sketch. Just use theImport Library command, and an include directive appears in your sketch. From there, not only is the header file (ending in .h) included in your sketch, but the code file (ending .cpp) is also compiled behind the scenes.

Now, say we are developing a more complex project that will use a library of our own. That library will itself build on other libraries. When we try to include one of those existing libraries in our new custom library, this automatic mechanism fails. In fact, it doesn’t even exist. To see what I mean, let’s look at an example:

class Bounce;

class MyLibrary {
Bounce* btn;

MyLibrary(int btnPin);

#include "Bounce.h"

MyLibrary::MyLibrary(int btnPin) {
btn = new Bounce(btnPin, 5);

In this example, in my header file, I’ll provide a forward declaration to the classBounce, and then in my code file, I’ll include the Bounce library. If I did this include in a sketch file, I would have no problem. When I try it in a library file, it fails.

Getting Your Library to Compile while including a Library

When you try to compile this code, the first error you get indicates that theBounce.h file can not be found. The reason is the Arduino IDE searches for library includes, so the user is not hassled with specifying their exact location. It is setup to search the library directory from sketches only, not from within the library directory itself. When including files from within the library, if the include file is not in the same directory as the file doing the including, it won’t be found.

The remedy is simple – provide a directory specification to the file to include. In this example, to include the “Bounce.h” file, we specify the relative file path this way:

#include "../Bounce/Bounce.h"

That is the relative path in Linux. In Windows, you may need to use backslashes (‘\’) instead. The ‘../’ indicates the parent directory of the current one which is “MyLibrary”. If we followed the path specifier, we go up one directory, which puts us in the library directory, and then down into the Bounce directory. Lastly, we then specify the filename to include.

Now when you try to compile, the compiler will find the Bounce header code and compile with no problem. That was simple wasn’t it? Not so fast. We now run into our next problem. As part of keeping things simple for the new user, the Arduino IDE makes no distinction between compiling and linking. These are two distinct operations and the linking operation comes after the compile operation. What is linking you may be asking? Read on.

Linking versus Compiling

What the compile operation does is check the source files for syntax errors, and then if all is well, it converts them to machine code. Next comes the linking part. In this step, the linker scours all the source files (generally ending in .cpp) given it and connects or “links” the functions being called with their actual code, with result being one large file (called a hex file), which is then uploaded to your Arduino. If a needed file is not given to the linker, the link step will fail. Most development environments separate the two processes, so it is easy to track down the cause of the error. In the Arduino IDE, this separation is not made. That being the case, one way to detect a link error from a compile error is to simply to watch the compile error window. Compile errors show up quickly. If you have to wait a while before you get errors, the errors are likely coming from the linker.

Getting Your Library to Link to another Library

When you try to compile and link our changed example, you will now get errors complaining that various functions being called in the Bounce library cannot be found:

MyLibrary/MyLibrary.cpp.o: In function `MyLibrary::MyLibrary(...)': /home/scott/Arduino Sketches/libraries/MyLibrary/MyLibrary.cpp:28: undefined reference to `Bounce::read()'

That is because the Bounce library is not being sent to the linker. The Arduino IDEmagic has again failed. The fix is unfortunately somewhat of a hack. Being a hack, it must be applied every time it is needed, and it isn’t real pretty. Having said all that, it is relatively easy.

The Arduino IDE sends any files included in the sketch to the linker, so the fix is to simply include the missing files in the sketch itself. In our example, in our sketch we put:

#include "Bounce.h"

You should understand that the linker really is looking for the source code file “Bounce.cpp”. Since we have no way in the IDE to specify which source files to include in the linking process, the only way to specify to the Arduino IDE to link to this file is to include the header file in the sketch itself. That signals the IDE to send the corresponding .cpp file to the linker. You will need to repeat this step for every library used in your project. In the end, your sketch file will have one include for every library used in the entire project.

With this simple include statement in our sketch, the example will not only compile, it will also link. Problem solved.

Good Include Practices

While we are on the arcane subject of file includes, I thought it would be useful provide some good programming practices and clear up some confusion that may exist on the subject.

Forward Class Declaration vs Includes

In my simple example’s header file, you may have noticed that I did not try to include the Bounce.h file, but instead simply wrote what is known as a forward declaration to it:
class Bounce;
I did so because it is good programming practice. You should only include header files when necessary, especially within header files, since they in turn are included in other files. It speeds compile time and prevents possible trouble down the road. When you need to make use of another class within your header file, instead of including that class’s header file, you only need to provide a forward declaration to it. Then in your source code file, you actually include the class header so you can use the class. If you are confused, just look at my example header and source code file again.

Using Brackets vs Quotation Marks for Includes

You may have noticed when looking at other people’s code, that sometimes files are included using brackets (<>), and sometimes using quotes (“”). What is the reason for these two ways and which one should be used? I haven’t found documentation for any particular rules in the Arduino IDE. From my experience, it appears both can be used interchangeably. Normally though, C++ does make a distinction. The brackets should be used for built-in language library files, and quotes for your own files as well as third party libraries. In the Arduino’s case, if including a file in the Arduino IDE directory, you should use brackets. For example:
For anything in your sketch directory, including libraries, use quotes:
#include "Bounce.h"
Like I said, the Arduino IDE doesn’t enforce this distinction, but other IDEs may. It is good practice to make your code conform to the rules of C++. Good practices in the beginning will avoid countless headaches down the road.


Because of the inherent limitations in the Arduino IDE, many people migrate to more powerful development tools such as Eclipse as they begin to tackle larger projects. Interestingly, the Arduino website has a tutorial on converting over to Eclipse. Unfortunately, Eclipse has a bit of learning curve itself. If you are not ready to make that plunge, the technique provided in this tutorial will serve you until you take that next step.

In summary, we have examined some of the limitations of the Arduino IDE in regards to including files and provided a workaround. We examined good coding practices that may save trouble later on. At some point you may outgrow the IDE and migrate to Eclipse or some other IDE. Until that day, this article will make you better equipped to work within its limitations.

In researching solutions to this library include problem, as well as correct include syntax, I couldn’t find any relevant documentation on the subject. Therefore, the recommendations given are drawn from my own experience. As such, these techniques and practices may be flawed or there may be better ones available. If you have any advice to the contrary, please post them in the comments section. Anything valid and pertinent will be added to this article.