Here at Nomi Design we have a fair amount of experience writing Arduino Libraries. So we thought we would share with the world our techniques for writing code into simple , clean, and easy to use Arduino Libraries.
First of the question that most people have is, “why bother?” Honestly you don’t ever need to write an arduino library. You could just dump all your code into a long sketch and be done with it. However writing an Arduino library allows for easier reuse and a chance to share your knowledge with the rest of the Arduino community. By wrapping up your code in a library others can access and build upon your hard work. Doesn’t that give you a warm fuzzy feeling?
Lets assume you have already written a sketch that interfaces with some sensor or device, its working perfectly so you are now ready to share that knowledge with the world, so you decide to rewrite your sketch into an Arduino library.
The first step that I do is to actually write the most basic example sketch for the library. I consider this a planing step, kind of like story boarding before a film shoot. I write an example sketch first in order to plan how I want people to use my library. I later work backwards from this example sketch to make the library itself. This sounds counter intuitive but it allows you to first envision the clearest way for people to interface with the library. By writing your ideal interface first, you can then work to design the library to match. Sometimes you are not able to write the library to totally match but you can at least try for as close a match as you can. If you were to start the library first, there is a good chance you would make an overly complex and hard to use library.
Lets say this is my envisioned example sketch. I want people to interface with my new exampleLib in this manner:
#include "ExampleLib.h"
//the constructor
ExampleLib exLib
void setup(){
exLib.begin(); //initialize
}
void loop(){
exLib.update(); //update every loop
}
So by looking at this example I see that my Arduino Library will need an constructor (they always do). A begin() function to setup the library, and an update() function to poll my sensor and do some calculations or something every loop cycle. Now this is my ideal interface. There is a good chance I am going to need to pass in some data, or perhaps set or get some flags inside the library at the very least. If there is something you know you need to do from the sketch, you should write it in now and try to make this as realistic and close to your final interface as possible.
The next step is to go ahead and start to write your library. The first thing to realize about an Arduino Library is that they are made of at least one, possibly many C++ classes. A common misconception about Arduino is that the Arduino language is based on Java, or it has its own language. The reality is, the Arduino is made from nothing but a loose collection of C/C++ functions and objects. I know this probably feels like the time your older brother told you Santa isn’t real, but those are the facts. To their credit though, the Arduino team do a pretty good job of hiding this from Arduino users, which is probably the reason why the Arduino became so popular. C/C++ especially for the AVR can be pretty intimidating to a new coder. So since an Arduino Library is made from C++ classes, the first thing to do is to actually write a C++ class. To do so you first create 2 files, the .h file and the .cpp file.
In the .h file you can write out the basic outline of a class, basically an easily readable class blueprint. Which is always setup about the same way:
//include guard
#ifndef EXAMPLE_LIB_H
#define EXAMPLE_LIB_H
//Start of the class
class ExampleLib {
public: //everything under here is public, accessible outside of the class
//the class constructor
ExampleLib();
void begin();
void update();
private: //everything under here is private, only accessible inside the class
int pollSensor();
int fancyAlgorithm(int inputData);
}; //end of class
#endif
//include guard end if
The next step is to start writing your .cpp file. The .cpp file is where all the “action” takes place. In your .cpp we will include the .h file and write the body of each function and the Constructor like so:
#include "ExampleLib.h"
//the constructor
ExampeLib::ExampleLib(){
}
//the body of begin function
void ExampleLib::begin(){
//setup your sensor here,for example
}
//the body of the update function
void ExampleLib::update(){
int data = pollSensor();
int result = fancyAlgorithm(data);
}
int ExampleLib::pollSensor(){
//analogRead or something
}
int ExampleLib::fancyAlgorithm(int inputData){
//some complex stuff
}
The first thing you might ask yourself about this, is what is this “ExampleLib::” nonsense? What this is a way to tell the compiler that this function is inside of the ExampleLib class. Without the ExampleLib:: before the function name the compiler would think this is a function that exists outside of the ExampleLib class. In other words just because its in the ExampleLib.cpp file doesn’t mean its actually inside the class. If you were a really messy programmer you could dump all kinds of random outside functions in this file, or have multiple classes in this file. Sometimes people do just that, so its always good to pay attention and check that each function is part of the class you think its should be part of. In the .cpp file you will notice there is no way to tell if a function is public or private, they are all just lumped together in the .cpp. If you want to know which function is which you should refer to your “design plan” the .h file. Speaking of which, what is public and private exactly anyway? Basically public functions and variables are things that you can access outside of the class. Like So:
exLib.update(); //the update function is public so we can use it in our sketch. exLib.xVarible; //a public variable, can also be accessed directly in the sketch.
If you tried to do the same thing with a private function, the compiler would complain. So if we write:
exLib.fancyAlgorithm(data); //this will fail, you will get a compiler error
You can however call this function from inside your ExampleLib class. So for example inside the update() function we can call fancyAlgorithm() and it works. Private functions are primarily used just to hide some of the complexity of a library and to prevent users from calling functions that would not make sense to call from outside the library.
So thats pretty much the basics of writing an Arduino library. Once its all written you just need to go ahead and place it in your libraries folder inside a folder with the name of your library. For example libraries/ExampleLib/ExampleLib.h If you are going to share this library with the rest of the world, you should probably also write up some examples so others can easily learn how use your library. Since you already wrote a sketch during your planning of the library you can just finish and test it and you have an example!
Advanced tip: If you write a library that consists of many .h and .cpp files you may be tempted to place some of them inside of subfolders. The problem is you can’t, since the Arduino IDE will not notice these cpp files and they will not be compiled or linked to your program. However there is a small trick you can do to get this to work. You can place all your extra .h and .cpp files inside a folder called utility. So for example. Libraries/ExampleLib/ExampleLib.h this is your main library .h file. So when you include your library you just need to type: #include “ExampleLib.h”. Then you can place the rest of your library class files inside the utility folder like so: Libraries/ExampleLib/utility/ExtraStuff.h and #include them into your ExampleLib.h this way: #include “utility/ExtraStuff.h”. This way if your library is made of 20 different cpp files you don’t need to have the user include them all into their sketch. They just need to include 1 file which is your library header file.
Well that should get you started writing your own Arduino Libraries. I am including the example library here, so you can use it as a template. Download
