If you’ve programmed Arduino boards for any length of time, you’ve certainly used a “library.” To do so, you insert the “magical” line #include <XYZ.h> in your code, and all of a sudden your Arduino IDE has new abilities. This can mean new ways to control a stepper motor, programmable LEDs, and a wide variety of other functionality. Some libraries are built into the Arduino IDE, while others can be installed with a search function or manually—and you can even write your own.
In this article, we’ll examine what a library actually is, what’s going on behind the scenes, and introduce you to the world of making your own custom library for code simplification and reuse.
What Is an Arduino Library?
Beyond an include statement, a library is a collection of code that’s compiled with your main sketch, but isn’t explicitly written out there. An Arduino library normally includes functions and variables that can be called in the sketch, along with a special function known as a constructor that is used to create instances of a class defined within the library.
Libraries are most helpful with code that doesn’t change, as something of a “black box” into which values may be input to execute certain functions automatically. Ideally, you should never have to concern yourself with what’s going on inside. The same functionality can be programmed into your main .ino sketch, but offloading things to a library can make code much easier to read. Note that this doesn’t actually save memory when compiled and sent to the Arduino; it’s simply organized nicely for mere humans.
How to Install an Arduino Library
Easily install libraries through the Arduino Library Manager
For libraries that are included with the IDE, or previously installed, go to Sketch > Include Library > [library in question] and the IDE will include it at the top of your sketch. If you need to use code that’s not already on your system but is listed in the Arduino Library Manager, go to Tools > Manage Libraries... search for what you need and hit Install once found.
You can also download a compressed .zip package, and add it with the Sketch > Include Library > Add .ZIP Library… option. Finally, you can add libraries manually, which is especially useful for non-standard libraries that may not be officially listed with Arduino.
How to Add a Library in Arduino
To add a library manually, navigate to your Arduino library folder. For my Windows 10 installation, it’s at C:\Program Files (x86)\Arduino\libraries. Place a new folder with the library files inside, which will include a .h, or header file, along with a .cpp file, which contains the bulk of the library’s code. Optionally, a library can contain an examples sub-folder with example sketches, and the .h and .cpp files are often placed in a src subfolder. A keywords.txt file can also be included to get the Arduino IDE to properly highlight certain words in the sketch.
Alternatively, libraries can be placed inside of the sketch folder itself. This can be especially useful if you need to make a new custom library for use in a specific project. When you’re ready to make your own, or need to examine how a library works, poke around in your libraries directory as described above to see how things are structured. I’d suggest opening these files with Notepad++, as it takes a bit of wrangling to open them directly in the Arduino IDE.
Create Your Own Arduino Library
Once you’ve used other libraries, how do you make your own? For that matter, why would you want to? The short answer is to simplify your code, and to make certain segments easy to reuse. For example, let’s say that you want to implement a library for the main function of the Charlieplexing routine below, discussed in a previous article:
void charlie(int a, int b){
if(b == 2){
pinMode(a, INPUT);
}
else{
pinMode(a, OUTPUT);
digitalWrite(a, b);
}
}
To get started, click on the down arrow to the upper-right on the Arduino IDE, and select New Tab, or use the keyboard shortcut Ctrl+Shift+N. Input your library name, followed by .h to create the header. Open an additional tab, and give it the same name, followed instead by .cpp. These will become new files in the sketch directory once saved.
The header and .cpp files don’t necessarily have to have the same name, but it’s often a good idea for simplicity. Code that you want to reuse can be copy/pasted into the .cpp file with a few changes.
Arduino Library Tutorial
The results of “library-izing” the Charlieplexing code can be found here on GitHub. While the code does work, in this case it’s not much of an improvement, readability-wise. Where this type of programming really shines is when there is a massive and/or reusable block of code.
There are quite a few other tricks to getting a library to function correctly, and there are references that give more information on this on the GitHub page. These .h and .cpp tabs are stored as separate files in the same folder as the .ino sketch file, not with your other libraries. In your main sketch, this location is indicated by the quote marks via the #include "Charlie.h" line. Angle brackets, e.g. #include <LiquidCrystal.h>, are used when you want to include code from the broader libraries directory.
Taking things full circle, if you’re going to be using a certain library over and over, you can place the .h and .cpp files in a new folder in the libraries directory and access it there using angle brackets. Of you can simply transfer it to a new sketch folder each time it’s needed, which can be a good way to share a file. Once you have a library that’s very well defined, and could be useful to others, you can even get it listed in the official Arduino Library Manager by putting in a request here.
