15.11.
2025 19:40 Writing a Library for Arduino | Arduino Documentation
Writing a Library for Arduino
Creating libraries to extend the functionality of Arduino. Goes step-by-step through the process
of making a library from a sketch.
Last revision 24.04.2023
This document explains how to create a library for Arduino. It starts with a sketch for
flashing Morse code and explains how to convert its functions into a library. This
allows other people to easily use the code that you've written and to easily update it
as you improve the library.
For more information, see the API Style Guide for information on making a good
Arduino-style API for your library.
We start with a sketch that does simple Morse code:
1 int pin = 13;
2
3 void setup()
4 {
5 pinMode(pin, OUTPUT);
6 }
7
8 void loop()
9 {
10 dot(); dot(); dot();
11 dash(); dash(); dash();
12 dot(); dot(); dot();
13 delay(3000);
14 }
15
16 void dot()
17 {
18 digitalWrite(pin, HIGH);
19 delay(250);
20 digitalWrite(pin, LOW);
21 delay(250);
22 }
23
24 void dash()
25 {
26 digitalWrite(pin, HIGH);
27 delay(1000);
28 digitalWrite(pin, LOW);
29 delay(250);
30 }
[Link] 1/10
15.11.2025 19:40 Writing a Library for Arduino | Arduino Documentation
If you run this sketch, it will flash out the code for SOS (a distress call) on pin 13.
The sketch has a few different parts that we'll need to bring into our library. First, of
course, we have the
dot()
and
dash()
functions that do the actual blinking. Second, there's the
pin
variable which the functions use to determine which pin to use. Finally, there's the call to
pinMode()
that initializes the pin as an output.
Let's start turning the sketch into a library!
You need at least two files for a library: a header file (w/ the extension .h) and the
source file (w/ extension .cpp). The header file has definitions for the library:
basically a listing of everything that's inside; while the source file has the actual
code. We'll call our library "Morse", so our header file will be
Morse.h
. Let's take a look at what goes in it. It might seem a bit strange at first, but it will make more sense
once you see the source file that goes with it.
The core of the header file consists of a line for each function in the library, wrapped
up in a class along with any variables you need:
[Link] 2/10
15.11.2025 19:40 Writing a Library for Arduino | Arduino Documentation
1 class Morse
2 {
3 public:
4 Morse(int pin);
5 void begin();
6 void dot();
7 void dash();
8 private:
9 int _pin;
10 };
A class is simply a collection of functions and variables that are all kept together in
one place. These functions and variables can be public, meaning that they can be
accessed by people using your library, or private, meaning they can only be accessed
from within the class itself. Each class has a special function known as a constructor,
which is used to create an instance of the class. The constructor has the same name
as the class, and no return type.
You need a couple of other things in the header file. One is an #include statement
that gives you access to the standard types and constants of the Arduino language
(this is automatically added to normal sketches, but not to libraries). It looks like
this (and goes above the class definition given previously):
1 #include "Arduino.h"
Finally, it's common to wrap the whole header file up in a weird looking construct:
1 #ifndef Morse_h
2 #define Morse_h
3
4 // the #include statement and code go here...
5
6 #endif
Basically, this prevents problems if someone accidentally
#include
's your library twice.
[Link] 3/10
15.11.2025 19:40 Writing a Library for Arduino | Arduino Documentation
Finally, you usually put a comment at the top of the library with its name, a short
description of what it does, who wrote it, the date, and the license.
Let's take a look at the complete header file:
1 /*
2 Morse.h - Library for flashing Morse code.
3 Created by David A. Mellis, November 2, 2007.
4 Released into the public domain.
5 */
6 #ifndef Morse_h
7 #define Morse_h
8
9 #include "Arduino.h"
10
11 class Morse
12 {
13 public:
14 Morse(int pin);
15 void begin();
16 void dot();
17 void dash();
18 private:
19 int _pin;
20 };
21
22 #endif
Now let's go through the various parts of the source file, [Link].
First comes a couple of #include statements. These give the rest of the code access
to the standard Arduino functions, and to the definitions in your header file:
1 #include "Arduino.h"
2 #include "Morse.h"
Then comes the constructor. Again, this explains what should happen when someone
creates an instance of your class. In this case, the user specifies which pin they
would like to use. The constructor records that in a private variable for use in the
other functions:
[Link] 4/10
15.11.2025 19:40 Writing a Library for Arduino | Arduino Documentation
1 Morse::Morse(int pin)
2 {
3 _pin = pin;
4 }
There are a couple of strange things in this code. First is the Morse:: before the
name of the function. This says that the function is part of the Morse class. You'll see
this again in the other functions in the class. The second unusual thing is the
underscore in the name of our private variable,
_pin
. This variable can actually have any name you want, as long as it matches the definition in the
header file. Adding an underscore to the start of the name is a common convention to make it clear
which variables are private, and also to distinguish the name from that of the argument to the
function (
pin
in this case).
Next, you'll create a
begin()
function to handle hardware configuration. This will be called from the
setup()
function of the sketch. Hardware configuration is done in a dedicated function instead of the
constructor because the hardware has not yet been initialized at the time the constructor code is
executed. In our library, we need to set the pin as an output:
1 void Morse::begin()
2 {
3 pinMode(_pin, OUTPUT);
4 }
Then comes the actual code from the sketch that you're turning into a library
(finally!). It looks pretty much the same, except with Morse:: in front of the names of
the functions, and
_pin
[Link] 5/10
15.11.2025 19:40 Writing a Library for Arduino | Arduino Documentation
instead of
pin
:
1 void Morse::dot()
2 {
3 digitalWrite(_pin, HIGH);
4 delay(250);
5 digitalWrite(_pin, LOW);
6 delay(250);
7 }
8
9 void Morse::dash()
10 {
11 digitalWrite(_pin, HIGH);
12 delay(1000);
13 digitalWrite(_pin, LOW);
14 delay(250);
15 }
Finally, it's typical to include the comment header at the top of the source file as
well. Let's see the whole thing:
[Link] 6/10
15.11.2025 19:40 Writing a Library for Arduino | Arduino Documentation
1 /*
2 [Link] - Library for flashing Morse code.
3 Created by David A. Mellis, November 2, 2007.
4 Updated by Jason A. Cox, February 18, 2023.
5 Released into the public domain.
6 */
7
8 #include "Arduino.h"
9 #include "Morse.h"
10
11 Morse::Morse(int pin)
12 {
13 _pin = pin;
14 }
15
16 void Morse::begin()
17 {
18 pinMode(_pin, OUTPUT);
19 }
20
21 void Morse::dot()
22 {
23 digitalWrite(_pin, HIGH);
24 delay(250);
25 digitalWrite(_pin, LOW);
26 delay(250);
27 }
28
29 void Morse::dash()
30 {
31 digitalWrite(_pin, HIGH);
32 delay(1000);
33 digitalWrite(_pin, LOW);
34 delay(250);
35 }
And that's all you need (there's some other nice optional stuff, but we'll talk about
that later). Let's see how you use the library.
First, make a Morse directory inside of the libraries sub-directory of your sketchbook
directory. Copy or move the Morse.h and [Link] files into that directory. Now
launch the Arduino environment. If you open the Sketch > Import Library menu, you
should see Morse inside. The library will be compiled with sketches that use it. If the
library doesn't seem to build, make sure that the files really end in .cpp and .h (with
no extra .ino, .pde or .txt extension, for example).
Let's see how we can replicate our old SOS sketch using the new library:
[Link] 7/10
15.11.2025 19:40 Writing a Library for Arduino | Arduino Documentation
1 #include <Morse.h>
2
3 Morse morse(13);
4
5 void setup()
6 {
7 [Link]();
8 }
9
10 void loop()
11 {
12 [Link](); [Link](); [Link]();
13 [Link](); [Link](); [Link]();
14 [Link](); [Link](); [Link]();
15 delay(3000);
16 }
There are a few differences from the old sketch (besides the fact that some of the
code has moved to a library).
First, we've added an #include statement to the top of the sketch. This makes the
Morse library available to the sketch and includes it in the code sent to the board.
That means if you no longer need a library in a sketch, you should delete the
#include statement to save space.
Second, we now create an instance of the Morse class called morse:
1 Morse morse(13);
When this line gets executed (which actually happens even before the
setup()
function), the constructor for the
Morse
class will be called, and passed the argument you've given here (in this case, just 13).
Notice that our
setup()
now has a call to
[Link] 8/10
15.11.2025 19:40 Writing a Library for Arduino | Arduino Documentation
[Link]()
which configures the pin that was set in the constructor.
Finally, to call the
dot()
and
dash()
functions, we need to prefix them with
morse
. - the name of the instance we want to use. We could have multiple instances of the
Morse
class, each on their own pin stored in the _pin private variable of that instance. By calling a function
on a particular instance, we specify which instance's variables should be used during that call to a
function. That is, if we had both:
1 Morse morse(13);
2 Morse morse2(12);
then inside a call to
[Link]()
,
_pin
would be 12.
If you tried the new sketch, you probably noticed that nothing from our library was
recognized by the environment and highlighted in color. Unfortunately, the Arduino
software can't automatically figure out what you've define in your library (though it
would be a nice feature to have), so you have to give it a little help. To do this,
create a file called [Link] in the Morse directory. It should look like this:
[Link] 9/10
15.11.2025 19:40 Writing a Library for Arduino | Arduino Documentation
1 Morse KEYWORD1
2 begin KEYWORD2
3 dash KEYWORD2
4 dot KEYWORD2
Each line has the name of the keyword, followed by a tab (not spaces), followed by
the kind of keyword. Classes should be KEYWORD1 and are colored orange;
functions should be KEYWORD2 and will be brown. You'll have to restart the Arduino
environment to get it to recognize the new keywords.
It's also nice to provide people with an example sketch that uses your library. To do
this, create an examples directory inside the Morse directory. Then, move or copy the
directory containing the sketch (let's call it SOS) we wrote above into the examples
directory. (You can find the sketch using the Sketch > Show Sketch Folder command.)
If you restart the Arduino environment (this is the last time, I promise) - you'll see
a Library-Morse item inside the File > Sketchbook > Examples menu containing your
example. You might want to add some comments that better explain how to use your
library.
[Link] 10/10