Arduino: using libraries

We’re millions of computer programmers, around the world, 95% of the time working on solving more or less the same problems. Thankfully developers realized, long ago, that code can be written to be reused, in the form of libraries. And those libraries can be shared among developers.

Often libraries are shared free of charge, openly, and this is the case of Arduino.

Some libraries are “Arduino official libraries”, curated by the Arduino team.

The official libraries can be found on this page: https://docs.arduino.cc/libraries/ and their source code is available on GitHub at https://github.com/arduino-libraries.

Since they are on GitHub, it’s easy to start collaborating on them, too, to submit fixes and improvements.

Official libraries are very easy to include in our project.

The steps below work in Arduino IDE 2, the current version of the IDE. The screenshots come from the older Arduino IDE 1, so your screen will look a bit different. If you’re new to the board, start with my introduction to Arduino.

In the Arduino IDE Sketch menu, select Include Library, and you will see a list of Arduino libraries included by default.

Pick one, for example Servo:

This will add a #include <Servo.h> line on top of the file, and you’re ready to go.

Here’s a complete sketch that uses it. A servo motor connected to pin 9 moves to 0, 90 and 180 degrees, waiting one second at each position:

#include <Servo.h>

Servo myServo;

void setup() {
  myServo.attach(9);
}

void loop() {
  myServo.write(0);
  delay(1000);
  myServo.write(90);
  delay(1000);
  myServo.write(180);
  delay(1000);
}

The #include line makes the library code available. Then we create a Servo object, tell it which pin the servo is wired to with attach(), and set the angle with write(). We don’t have to generate the control pulses ourselves, because the library does that for us. If you want to wire one up, I wrote a whole post on controlling a servo motor.

You can install more libraries through the Library Manager. In Arduino IDE 2 it lives in the left sidebar: click the library icon (the one that looks like books). You can also open it from the Tools menu with Manage Libraries..., or press Ctrl+Shift+I (Cmd+Shift+I on a Mac).

Search for the library you need, then click INSTALL. Once it’s installed, you’ll find its example sketches in File > Examples, or in the three-dots menu next to the library in the Library Manager.

Some libraries are built and maintained by the community, and they do not have a centralized place where they can be found.

Google is a good place where to find those libraries.

Sometimes you need to include a library that’s not official and not included in the Library manager.

In this case in the Arduino IDE Sketch menu, select Include Library, and then choose Add .ZIP Library... to load a library from a zip file.

After you load it, you will see it listed in the Contributed libraries section in the menu.

What’s inside a library

A library is just a folder. Inside it there’s a header file (.h) that declares what the library offers, and one or more source files (.cpp) with the code that does the work. When you write #include <Servo.h>, you’re pulling in that header.

Most libraries follow the layout described in the Arduino library specification. A simple library looks like this:

MyLibrary/
  library.properties
  keywords.txt
  src/
    MyLibrary.h
    MyLibrary.cpp
  examples/
    Basic/Basic.ino

The code lives in src, and the examples folder is where the sketches you see in File > Examples come from. Bigger libraries split the code into subfolders of src. Servo, for example, has src/Servo.h plus one subfolder per board family (avr, samd, renesas and so on), each with its own .cpp file, and two examples called Sweep and Knob.

library.properties is a small text file with the library metadata: its name, version, author, a one-line description, which board architectures it supports, and optionally which other libraries it depends on. Here’s Servo’s, without the long paragraph line:

name=Servo
version=1.3.0
author=Michael Margolis, Arduino
maintainer=Arduino <[email protected]>
sentence=Allows Arduino boards to control a variety of servo motors.
category=Device Control
url=https://www.arduino.cc/reference/en/libraries/servo/
architectures=avr,megaavr,sam,samd,nrf52,stm32f4,mbed,mbed_nano,mbed_portenta,mbed_rp2040,renesas,renesas_portenta,renesas_uno,zephyr

The Library Manager reads this file to show you the description, the version and the compatible boards.

Where installed libraries end up

Libraries you install go into the libraries folder inside your sketchbook. You can see the sketchbook path in the IDE preferences, under Sketchbook location (File > Preferences, or the Arduino IDE menu on a Mac).

By default the sketchbook is Documents/Arduino on Windows and macOS, and ~/Arduino on Linux, so libraries live in Documents/Arduino/libraries or ~/Arduino/libraries.

This also means you can install a library by hand. Copy its folder (the one containing library.properties or the .h file) into that libraries folder, then restart the IDE so it picks it up. That’s handy when you download a library from GitHub and don’t want to zip it first.

Libraries in the sketchbook take priority over the copies bundled with the IDE or with a board package. If you install a newer version of Servo there, your sketches will use it.

Installing a library’s dependencies

Some libraries need other libraries to work. When you install one of them from the Library Manager, Arduino IDE 2 shows an Install library dependencies dialog telling you which libraries are missing, and asks if you’d like to install them too.

Click Install All to get everything. Install without dependencies installs only the library you picked, and you’ll probably see missing include errors when you compile.

Updating and removing libraries

The Library Manager also takes care of updates. Libraries with a newer version show an UPDATE button on their card. To see only those, set the Type filter at the top of the Library Manager to Updatable.

To remove a library, find it in the Library Manager and click REMOVE. The IDE asks you to confirm, then deletes its folder from the sketchbook.

Installing libraries from the command line

If you use arduino-cli, the command line version of the IDE, you can do all of this from the terminal.

First refresh the list of available libraries, then search:

arduino-cli lib update-index
arduino-cli lib search servo

Install a library by its name (wrap it in quotes when the name has spaces):

arduino-cli lib install "Servo"

It installs the dependencies too, unless you add --no-deps.

The other commands work as you’d expect:

arduino-cli lib list
arduino-cli lib upgrade
arduino-cli lib uninstall Servo

lib list shows what’s installed, lib upgrade updates every installed library, and lib uninstall removes one.

Common problems

The library isn’t installed. If you include a header the IDE can’t find, compilation stops with an error like this:

fatal error: Servo.h: No such file or directory

Install the library from the Library Manager and compile again. If you installed it by hand, check that the folder is directly inside libraries, and not inside an extra folder created when you unzipped it.

Two libraries have the same header name. Different libraries sometimes ship a header with the same name, like SD.h. The build still works, but the output tells you which one was picked:

Multiple libraries were found for "SD.h"

Below that message you’ll see a Used: line and one or more Not used: lines with the folder paths. If the wrong one is used, remove the copy you don’t need.

The library doesn’t support your board. A library declares the architectures it runs on in library.properties. If your board isn’t in that list, you’ll see a warning like:

WARNING: library X claims to run on avr architecture(s) and may be incompatible with your current board which runs on esp32 architecture(s).

It’s a warning, not an error, so the sketch might still compile. But the library could rely on hardware the board doesn’t have, so look for a version made for your board.

Want me to talk about your product? You can sponsor this site.