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
#endif
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.
This is Circuit 1
This is Circuit 2
If you have any problems along the way, please visit our Forum and we'll do what we can to get your library up and running!
