How to Build an Arduino Library

Have you ever wanted to simplify or automate a task using an Arduino? Yes? Well, have you
ever wanted to simplify the code required for that task into a neat collection of easy-to-use
functions? Also yes? Then this tutorial is for you! In this tutorial, we will be creating a library to
initialise and control a small, Arduino-powered circuit; but first, what is a library?

WHAT IS A LIBRARY AND HOW DO THEY WORK?

A library is a collection of resources designed to simplify a process or task. These resources can
include (but aren't limited to): subroutines, functions, classes, values or type specifications. A
library typically consists of:

A Header File (.h) - This contains the library's definitions

Source Code (.cpp) - This contains the library's code

A Keyword file (.txt) - This contains the keywords used in the library

A Readme file (.txt) - This contains other information about the library (Revision Number,
TODO's, etc.)

Examples (.ino) - These are to show a user how to operate the library

All of these files should be put in a single folder (called the name of your library) which is then to
be placed within the \Arduino\libraries directory of your computer. This will be shown later in
the tutorial. If you're looking for a shortcut, the library we're building in this tutorial can be
found on GitHub and you can read the last section on Examples, Zipping and Including to see
how to get started from there.

THIS LIBRARY'S PURPOSE AND DESCRIPTION

This library's purpose is to easily control 3 LED's connected to 3 digital pins on the Arduino. It
will have the ability to:

Declare which pins the LEDs are connected to (Pins 3,5 & 6 aren't necessarily required)

Turn all LEDs on

Turn all LEDs off

Flash all LEDs 4 times

Note: This is just an introduction to library creation; once you understand how the Source File
and Header File are written and combined, you can modify this code (or write your own) to
perform lots of different processes using a variety of electrical components!
CREATING THE HEADER FILE

To create the header file and source code, we will need to use a word editor of some sort. I'll be
using Notepad++ due to its ability to understand Arduino syntax. Once that is downloaded,
open up a new document and save it as myFirstLibrary.h making sure to save as type "C++
source file". After this is done, copy the code below and paste it into the document. Have a look
through the comments to get an understanding of how the header file works, this will become
clearer after exploring the source file.

/*

* myFirstLibrary.h - An introduction to library setup

* Created by Christian @ Core Electronics on 1/06/18

* Revision #5 - See readMe

*/

// The #ifndef statement checks to see if the myFirstLibrary.h

// file isn't already defined. This is to stop double declarations

// of any identifiers within the library. It is paired with a

// #endif at the bottom of the header and this setup is known as

// an 'Include Guard'.

#ifndef myFirstLibrary_h

// The #define statement defines this file as the myFirstLibrary

// Header File so that it can be included within the source file.

#define myFirstLibrary_h

// The #include of Arduino.h gives this library access to the standard

// Arduino types and constants (HIGH, digitalWrite, etc.). It's

// unneccesary for sketches but required for libraries as they're not

// .ino (Arduino) files.

#include "Arduino.h"
// The class is where all the functions for the library are stored,

// along with all the variables required to make it operate

class myFirstLibrary{

// 'public:' and 'private:' refer to the security of the functions

// and variables listed in that set. Contents that are public can be

// accessed from a sketch for use, however private contents can only be

// accessed from within the class itself.

public:

// The first item in the class is known as the constructor. It shares the

// same name as the class and is used to create an instance of the class.

// It has no return type and is only used once per instance.

myFirstLibrary(int pinOne, int pinTwo, int pinThree);

// Below are the functions of the class. They are the functions available

// in the library for a user to call.

void on();

void off();

void flash(int delayTime);

private:

// When dealing with private variables, it is common convention to place

// an underscore before the variable name to let a user know the variable

// is private.

int _pinOne, _pinTwo, _pinThree;

};

// The end wrapping of the #ifndef Include Guard

CREATING THE SOURCE FILE

Creating the source code for this library will be done in a similar manner to the above section.
We will open a new document in Notepad++ and save it as myFirstLibrary.cpp once again,
making sure that the save as type selection is "C++ source file". Once again, read through the
code below, following the comments along the way. Copy it into the document and save it in the
same folder as the myFirstLibrary.h file. The folder should be called myFirstLibrary, now
containing both the Header and Source files.

/*

* myFirstLibrary.cpp - An introduction to library setup

* Created by Christian @ Core Electronics on 1/06/18

* Revision #5 - See readMe

*/

// The #include of Arduino.h gives this library access to the standard

// Arduino types and constants (HIGH, digitalWrite, etc.). It's

// unneccesary for sketches but required for libraries as they're not

// .ino (Arduino) files.

#include "Arduino.h"

// This will include the Header File so that the Source File has access

// to the function definitions in the myFirstLibrary library.

#include "myFirstLibrary.h"

// This is where the constructor Source Code appears. The '::' indicates that

// it is part of the myFirstLibrary class and should be used for all constructors

// and functions that are part of a class.

myFirstLibrary::myFirstLibrary(int pinOne, int pinTwo, int pinThree){

// This is where the pinModes are defined for circuit operation.

pinMode(pinOne, OUTPUT);
 pinMode(pinTwo, OUTPUT);

pinMode(pinThree, OUTPUT);

// The arguments of the constructor are then saved into the private variables.

_pinOne = pinOne;

_pinTwo = pinTwo;

_pinThree = pinThree;

// For the 'on', 'off' and 'flash' functions, their function return type (void) is

// specified before the class-function link. They also use the private variables

// saved in the constructor code.

void myFirstLibrary::on(){

digitalWrite(_pinOne, HIGH);

digitalWrite(_pinTwo, HIGH);

digitalWrite(_pinThree, HIGH);

void myFirstLibrary::off(){

digitalWrite(_pinOne, LOW);

digitalWrite(_pinTwo, LOW);

digitalWrite(_pinThree, LOW);

void myFirstLibrary::flash(int delayTime){

for(int i = 0; i < 4; i++){

digitalWrite(_pinOne, HIGH);

digitalWrite(_pinTwo, HIGH);

digitalWrite(_pinThree, HIGH);
 delay(delayTime);

digitalWrite(_pinOne, LOW);

digitalWrite(_pinTwo, LOW);

digitalWrite(_pinThree, LOW);

delay(delayTime);

CREATING THE KEYWORDS AND README FILES

Inside the myFirstLibrary folder, save two blank text documents, keywords and readme. It's
within these two files that you will:

Tell the Arduino IDE which words are 'important' so that it can highlight them when they're
called in a program (not required, just good practice and makes debugging easier)

Identify the library's revision number and what it does

List the functions of the library

The keywords file is the file that tells the IDE which words are important and should be
highlighted. Two different types of keywords exist (KEYWORD1 -> Classes, KEYWORD2 ->
Functions) and they should have a space between them. The keywords file for this library is
shown below. The readme file should explain what the library does, it's revision number and the
date it was last revised such that a user with no knowledge of the library could understand what
it's used for and when it was last edited.

myFirstLibrary KEYWORD1

on KEYWORD2

off KEYWORD2

flash KEYWORD2

EXAMPLES, ZIPPING AND INCLUDING

Now that all of the above is completed, the last thing to do is to create some examples so users
have a working program that explains how to use the library's capabilities. Once you have a few
examples sketches made, create a folder called examples within the myFirstLibrary folder and
place them inside. Next, back out to the myFirstLibrary folder, right-click it and compress it into
a .zip file. Finally, open the Arduino IDE and navigate to Sketch>Include Library>Add .ZIP
Library. Find your zipped folder through its directory and you're done! Note:
File>Examples>myFirstLibrary (you may need to scroll down) will take you to the examples
found in the myFirstLibrary folder.
circuit-one-library-creation

This is Circuit 1

circuit-two-library-creation
This is Circuit 2