Arduino Libraries Tutorial

Submitted by nanodano on Fri, 09/13/2019 - 17:47

Introduction

If you have ever written an Arduino sketch or function that you want to re-use or share, creating a library for it is a great idea. In this guide, we will look at creating, importing, and using libraries. We will also look at creating and using examples that come with a library. You wil learn all the basics about managing libraries and even create your own custom library.

This guide will help you understand how to:

Create and distribute a Arduino library ZIP
- With examples that can be opened via File -> Examples menu
- That can be imported via the Sketch -> Include Library -> Add ZIP Library
Create and open sketches that are found with the File -> Sketchbook menu
Include libraries in to your sketches

This guide focuses on the Arduino IDE, though it overlaps much with the Arduino CLI. Check out my Arduino CLI Tutorial to learn more about managing libraries using the CLI tool.

File locations

These example file locations are for Windows using the Arduino IDE/CLI.

Sketchbook directory

Your default sketch location is in an Arduino directory inside your user's Documents directory. Inside here you should place directories that contain .ino sketches. Sketches in this location are easily available via the File -> Sketchbook menu. You can change the default sketchbook path under File -> Preferences. You do not have to use the sketchbook directory to store your sketches.

%HOMEPATH%\Documents\Arduino\

For example:

C:\Users\NanoDano\Arduino\

This is also the location new sketches are stored when using the Arduino CLI to create a new sketch with the command:

arduino-cli sketch new mysketch

Library directories

Your libraries and 3rd party libraries by default should go in a libraries directory inside the Arduino folder in your Documents directory.

%HOMEPATH%\Documents\Arduino\libraries\

For example:

C:\Users\NanoDano\Arduino\libraries\

The Arduino core libraries (like Mouse.h) are in a different location:

%PROGRAMFILES(X86)%\Arduino\libraries\

For example:

C:\Program Files (x86)\Arduino\libraries\

Libraries in any of these directories are available from the Sketch -> Include Library menu.

Each library can have an examples/ directory with subdirectories that each contain a sketch that become available via the File -> Examples menu.

The Arduino.h that you may need to reference in your .cpp code can be found in: C:\Program Files (x86)\Arduino\hardware\arduino\avr\cores\arduino. Arduino.h is where important things like setup(), loop(), pinMode(), digitalRead(), digitalWrite(), and similar core functions are defined.

Create a library

Creating a library is a pretty easy process once you understand it.

Create a directory
Create a library.properties file
Optional Create your .cpp and .h files with the code you want to share.
(Optional) Create an examples/ directory and add sketch folders with example .ino sketches.
(Optional) Create a keywords.txt file.
(Optional) Provide a README file with further instructions
Zip the directory.

Read more about the library.properties and keywords.txt file, read Arduino library specifications.

Read more about Arduino libraries and check our the Arduino example library template.

Directory structure

To create a library, use the following basic structure. The source file and headers should go in a src/ directory, examples should go in examples/ directory. The keywords.txt file is optional, but the library.properties is required. More details about both are further down.

Write the .cpp code just like you would any other sketch, it's just regular C++. Create the .h header file so that your code can be included in sketches.

myproject/
myproject/library.properties
myproject/keywords.txt
myproject/src/somelib.h
myproject/src/somelib.cpp
myproject/examples/myexample1/myexample1.ino
myproject/examples/myexample2/myexample2.ino

The library.properties file

The library.properties file defines things like name, version, and author. Read more details in the Arduino library specifications.

Here is an example library.properties file.

name=My Cool Library
version=1.0.0
author=John Doe <jdoe@example.com, Jane Doe <jdoe2@example.com>
maintainer=John Doe <jdoe@example.com>
sentence=The coolest library around.
paragraph=Contains all kinds of cool features like X, Y, Z.
category=Other
url=https://github.com/Username/ProjectName
architectures=*

Category can be one of:

Display
Communication
Signal Input/Output
Sensors
Device Control
Timing
Data Storage
Data Processing
Other

Architecture defaults to * but can also be avr for example.

The keywords.txt file

The keywords.txt file is optional. You can read more about it in the Arduino library specifications.

Example sketches

When creating examples, make sure each .ino you file exists in a directory with the same name.

For example:

MyLibrary/examples/MyExample/
MyLibrary/examples/MyExample/MyExample.ino

Package a library

To package a library, just zip up the directory and you're done.

In PowerShell, you can zip a directory named MyLibrary to a zip named MyLibrary.zip like this:

Compress-Archive MyLibrary MyLibrary.zip

You can store this or share it with others. Anyone should be able to import it by extracting the contents to their library directory or using the Sketch -> Include Library -> Add ZIP Library.

Example library

To put all this knowledge in to action, let's create a simple library that provides some functions to manipulate the built-in LED of a board. There are no special dependencies needed, but it will be a good template for making more complex libraries.

You can also find this example at https://github.com/DevDungeon/BlinkyLEDArduinoLibrary.

Directory structure:

BlinkyLED/
BlinkyLED/library.properties
BlinkyLED/src/blinky_led.cpp
BlinkyLED/src/blinky_led.h
BlinkyLED/examples/blinky_example/blinky_example.ino

Here are the source files:

/* src/blinky_led.cpp */
#include <Arduino.h>

void setupBlinky() {
    pinMode(LED_BUILTIN, OUTPUT);
}

void steadyBlink(int duration) {
      digitalWrite(LED_BUILTIN, HIGH);
      delay(duration);
      digitalWrite(LED_BUILTIN, LOW);
      delay(duration);
}

/* src/blinky_led.h */

void setupBlinky();
void steadyBlink(int duration);

/* examples/blinky_example/blinky_example.ino */
#include <blinky_led.h>

void setup() {
    setupBlink();
}

void loop() {
    steadyBlink(250);
}

# library.properties
name=BlinkyLED
version=1.0.0
author=NanoDano <nanodano@devdungeon.com>
maintainer=NanoDano <nanodano@devdungeon.com>
sentence=Simple LED blink procedures
paragraph=Use the built-in LED to blink
category=Other
url=https://github.com/DevDungeon/BlinkyLED
architectures=*

After you have all the files in the directory, zip up the directory and it's ready to distribute. See the next section on how to import the library and use it.

Import a library

The easiest way to import a zipped library is in the Arduino IDE from the menu at Sketch -> Include Library -> Add .ZIP Library.

To import a library manually place the unzipped directory in to your Arduino libraries folder. In Windows, the library path is:

%HOMEPATH%\Documents\Arduino\libraries\

And the libray location would look like:

%HOMEPATH%\Documents\Arduino\libraries\myproject\

Open examples

If the library included any examples in its examples/ directory, then you can open them from the menu at File -> Examples.

Include a library

To include a library, go to Sketch -> Include Library and choose the library. It will automatically add the .h include staements needed.

To manually include a library, add the include statement you need to include the header file from the library. For example:

#include <Mouse.h>

Searching for libraries

The Arduino IDE has a library manager tool that helps you search for libraries online.

Go to the menu Tools -> Manage Libraries

Search for any library you want.

Conclusion

After reading this you should have a basic understanding of how to:

Create and distribute a Arduino library ZIP
- With examples that can be opened via File -> Examples menu
- That can be imported via the Sketch -> Include Library -> Add ZIP Library
Create and open sketches that are found with the File -> Sketchbook menu
Include libraries in to your sketches

Arduino Libraries Tutorial

Introduction

File locations

Sketchbook directory

Library directories

Create a library

Directory structure

The library.properties file

The keywords.txt file

Example sketches

Package a library

Example library

Import a library

Open examples

Include a library

Searching for libraries

Conclusion

References