Hacking.LibraryTutorial History

Hide minor edits - Show changes to markup

January 08, 2014, at 05:54 PM by Tom Igoe -
Added lines 5-6:

For more information, see the API Style Guide for information on making a good Arduino-style API for your library.

Changed lines 250-251 from:

That's all for now but I'll probably write an advanced library tutorial soon. See the API Style Guide for information on making a good Arduino-style API for your library.

  In the meantime, if you have any problems or suggestions, please post them to the Software Development forum.
to:

That's all for now but I'll probably write an advanced library tutorial soon. In the meantime, if you have any problems or suggestions, please post them to the Software Development forum.

For more information, see the API Style Guide for information on making a good Arduino-style API for your library.

January 08, 2014, at 05:52 PM by Tom Igoe -
Changed lines 248-249 from:

That's all for now but I'll probably write an advanced library tutorial soon. In the meantime, if you have any problems or suggestions, please post them to the Software Development forum.

to:

That's all for now but I'll probably write an advanced library tutorial soon. See the API Style Guide for information on making a good Arduino-style API for your library.

  In the meantime, if you have any problems or suggestions, please post them to the Software Development forum.
March 28, 2013, at 04:18 PM by Roberto Guido - repetition typo, thanks to Filip Kovačić Popov for alert
Changed lines 3-4 from:

This document explains how to create a library for Arduino. It starts with a sketch 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.

to:

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.

March 01, 2012, at 01:39 PM by Tom Igoe -
Changed line 7 from:

[@

to:
Changed lines 38-39 from:

@]

to:
Changed line 50 from:

[@

to:
Changed lines 60-61 from:

@]

to:
Changed lines 66-69 from:
#include "WProgram.h"
to:
Changed line 72 from:

[@

to:
Changed lines 79-80 from:

@]

to:
Changed line 87 from:

[@

to:
Changed lines 96-97 from:
  1. include "WProgram.h"
to:
  1. include "Arduino.h"
Changed lines 109-110 from:

@]

to:
Changed lines 115-116 from:

[@

  1. include "WProgram.h"
to:
Changed lines 118-119 from:

@]

to:
Changed line 122 from:

[@

to:
Changed lines 128-129 from:

@]

to:
Changed line 134 from:

[@

to:
Changed lines 150-151 from:

@]

to:
Changed line 154 from:

[@

to:
Changed line 161 from:
  1. include "WProgram.h"
to:
  1. include "Arduino.h"
Changed lines 185-186 from:

@]

to:
Changed line 193 from:

[@

to:
Changed lines 209-210 from:

@]

to:
Changed line 217 from:

[@

to:
Changed lines 219-220 from:

@]

to:
Changed line 227 from:

[@

to:
Changed lines 230-231 from:

@]

to:
Changed line 236 from:

[@

to:
Changed lines 240-241 from:

@]

to:
February 02, 2010, at 09:40 PM by David A. Mellis -
Changed lines 189-190 from:

First, make a Morse directory inside of the hardware/libraries sub-directory of the Arduino application directory. Copy or move the Morse.h and Morse.cpp files into that directory. Now launch the Arduino environment. When it starts, it will compile your library, generating an object file (Morse.o) and displaying any warnings or errors. If you open the Sketch > Import Library menu, you should see Morse inside. As you work on your library, you'll need to delete the Morse.o file and relaunch the Arduino environment (or pick a new board from the Tools > Boards menu) to recompile your library. If the library doesn't seem to build, make sure that the files really end in .cpp and .h (with no extra .pde or .txt extension, for example).

to:

First, make a Morse directory inside of the libraries sub-directory of your sketchbook directory. Copy or move the Morse.h and Morse.cpp 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 .pde or .txt extension, for example).

May 24, 2009, at 04:06 PM by David A. Mellis -
Changed line 67 from:
  1. include "WConstants.h"
to:
  1. include "WProgram.h"
Changed lines 96-97 from:
  1. include "WConstants.h"
to:
  1. include "WProgram.h"
January 15, 2008, at 04:48 PM by David A. Mellis -
Changed lines 189-190 from:

First, make a Morse directory inside of the hardware/libraries sub-directory of the Arduino application directory. Copy or move the Morse.h and Morse.cpp files into that directory. Now launch the Arduino environment. When it starts, it will compile your library, generating an object file (Morse.o) and displaying any warnings or errors. If you open the Sketch > Import Library menu, you should see Morse inside. As you work on your library, you'll need to delete the Morse.o file and relaunch the Arduino environment (or pick a new board from the Tools > Boards menu) to recompile your library.

to:

First, make a Morse directory inside of the hardware/libraries sub-directory of the Arduino application directory. Copy or move the Morse.h and Morse.cpp files into that directory. Now launch the Arduino environment. When it starts, it will compile your library, generating an object file (Morse.o) and displaying any warnings or errors. If you open the Sketch > Import Library menu, you should see Morse inside. As you work on your library, you'll need to delete the Morse.o file and relaunch the Arduino environment (or pick a new board from the Tools > Boards menu) to recompile your library. If the library doesn't seem to build, make sure that the files really end in .cpp and .h (with no extra .pde or .txt extension, for example).

January 15, 2008, at 04:43 PM by David A. Mellis -
Added lines 246-247:

If you'd like to check out the complete library (with keywords and example), you can download it: Morse.zip.

November 02, 2007, at 10:01 PM by David A. Mellis -
Changed lines 244-246 from:

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.

to:

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.

That's all for now but I'll probably write an advanced library tutorial soon. In the meantime, if you have any problems or suggestions, please post them to the Software Development forum.

November 02, 2007, at 09:55 PM by David A. Mellis -
November 02, 2007, at 09:54 PM by David A. Mellis -
Changed lines 189-190 from:

First, make a Morse directory inside of the hardware/libraries sub-directory of the Arduino application directory. Copy or move the Morse.h and Morse.cpp files into that directory. Now launch the Arduino environment. When it starts, it will compile your library, generating an object file (Morse.o) and displaying any warnings or errors. If you open the Sketch > Import Library menu, you should see Morse inside.

to:

First, make a Morse directory inside of the hardware/libraries sub-directory of the Arduino application directory. Copy or move the Morse.h and Morse.cpp files into that directory. Now launch the Arduino environment. When it starts, it will compile your library, generating an object file (Morse.o) and displaying any warnings or errors. If you open the Sketch > Import Library menu, you should see Morse inside. As you work on your library, you'll need to delete the Morse.o file and relaunch the Arduino environment (or pick a new board from the Tools > Boards menu) to recompile your library.

Changed lines 234-235 from:

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 keywords.txt in the Morse directory. It should look like this:

to:

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 keywords.txt in the Morse directory. It should look like this:

Changed line 244 from:
to:

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.

November 02, 2007, at 09:48 PM by David A. Mellis -
Changed lines 234-244 from:
to:

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 keywords.txt in the Morse directory. It should look like this:

Morse	KEYWORD1
dash	KEYWORD2
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.

November 02, 2007, at 09:29 PM by David A. Mellis -
Changed lines 228-229 from:

Morse morseA(13); Morse morseB(12);

to:

Morse morse(13); Morse morse2(12);

Changed lines 232-234 from:

then inside a call to morseB.dot(), _pin would be 12.

to:

then inside a call to morse2.dot(), _pin would be 12.

November 02, 2007, at 09:29 PM by David A. Mellis -
Changed lines 193-234 from:
to:
#include <Morse.h>

Morse morse(13);

void setup()
{
}

void loop()
{
  morse.dot(); morse.dot(); morse.dot();
  morse.dash(); morse.dash(); morse.dash();
  morse.dot(); morse.dot(); morse.dot();
  delay(3000);
}

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:

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() is now empty; that's because the call to pinMode() happens inside the library (when the instance is constructed).

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:

Morse morseA(13);
Morse morseB(12);

then inside a call to morseB.dot(), _pin would be 12.

November 02, 2007, at 09:18 PM by David A. Mellis -
Changed lines 185-187 from:

@]

to:

@]

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 hardware/libraries sub-directory of the Arduino application directory. Copy or move the Morse.h and Morse.cpp files into that directory. Now launch the Arduino environment. When it starts, it will compile your library, generating an object file (Morse.o) and displaying any warnings or errors. If you open the Sketch > Import Library menu, you should see Morse inside.

Let's see how we can replicate our old SOS sketch using the new library:

November 02, 2007, at 09:10 PM by David A. Mellis -
Changed lines 152-187 from:
to:

Finally, it's typical to include the comment header at the top of the source file as well. Let's see the whole thing:

/*
  Morse.cpp - Library for flashing Morse code.
  Created by David A. Mellis, November 2, 2007.
  Released into the public domain.
*/

#include "WProgram.h"
#include "Morse.h"

Morse::Morse(int pin)
{
  pinMode(pin, OUTPUT);
  _pin = pin;
}

void Morse::dot()
{
  digitalWrite(_pin, HIGH);
  delay(250);
  digitalWrite(_pin, LOW);
  delay(250);  
}

void Morse::dash()
{
  digitalWrite(_pin, HIGH);
  delay(1000);
  digitalWrite(_pin, LOW);
  delay(250);
}



November 02, 2007, at 09:08 PM by David A. Mellis -
Added lines 132-152:

Next 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 instead of pin:

void Morse::dot()
{
  digitalWrite(_pin, HIGH);
  delay(250);
  digitalWrite(_pin, LOW);
  delay(250);  
}

void Morse::dash()
{
  digitalWrite(_pin, HIGH);
  delay(1000);
  digitalWrite(_pin, LOW);
  delay(250);
}

November 02, 2007, at 09:05 PM by David A. Mellis -
Changed lines 64-65 from:

You need a couple of other things in the header file. One is an #include statement that gives you access to the standard features 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):

to:

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):

Changed lines 111-131 from:
to:

Now let's go through the various parts of the source file, Morse.cpp.

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:

#include "WProgram.h"
#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. We configure the pin as an output save it into a private variable for use in the other functions:

Morse::Morse(int pin)
{
  pinMode(pin, OUTPUT);
  _pin = pin;
}

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).

November 02, 2007, at 08:52 PM by David A. Mellis -
November 02, 2007, at 08:52 PM by David A. Mellis -
Changed lines 46-47 from:

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.

to:

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.

Changed lines 62-111 from:

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.

to:

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 features 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):

#include "WConstants.h"

Finally, it's common to wrap the whole header file up in a weird looking construct:

#ifndef Morse_h
#define Morse_h

// the #include statment and code go here...

#endif

Basically, this prevents problems if someone accidently #include's your library twice.

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:

/*
  Morse.h - Library for flashing Morse code.
  Created by David A. Mellis, November 2, 2007.
  Released into the public domain.
*/
#ifndef Morse_h
#define Morse_h

#include "WConstants.h"

class Morse
{
  public:
    Morse(int pin);
    void dot();
    void dash();
  private:
    int _pin;
};

#endif

November 02, 2007, at 08:43 PM by David A. Mellis -
Changed lines 46-47 from:

You need at least two files for a library: a header file (w/ the extension .h) and the source file (w/ extension .cpp). We'll call our library "Morse", so our header file will be Morse.h. Let's take a look at what goes in it.

to:

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.

Changed line 58 from:
    int pin;
to:
    int _pin;
Changed line 62 from:
to:

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.

November 02, 2007, at 08:38 PM by David A. Mellis -
Changed lines 8-9 from:

int ledPin = 13;

to:

int pin = 13;

Changed line 12 from:
  pinMode(ledPin, OUTPUT);
to:
  pinMode(pin, OUTPUT);
Changed line 25 from:
  digitalWrite(ledPin, HIGH);
to:
  digitalWrite(pin, HIGH);
Changed line 27 from:
  digitalWrite(ledPin, LOW);
to:
  digitalWrite(pin, LOW);
Changed line 33 from:
  digitalWrite(ledPin, HIGH);
to:
  digitalWrite(pin, HIGH);
Changed line 35 from:
  digitalWrite(ledPin, LOW);
to:
  digitalWrite(pin, LOW);
Changed lines 44-62 from:
to:

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). We'll call our library "Morse", so our header file will be Morse.h. Let's take a look at what goes in 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:

class Morse
{
  public:
    Morse(int pin);
    void dot();
    void dash();
  private:
    int pin;
};

November 02, 2007, at 08:30 PM by David A. Mellis -
Added lines 1-44:

Writing a Library for Arduino

This document explains how to create a library for Arduino. It starts with a sketch 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.

We start with a sketch that does simple Morse code:

int ledPin = 13;

void setup()
{
  pinMode(ledPin, OUTPUT);
}

void loop()
{
  dot(); dot(); dot();
  dash(); dash(); dash();
  dot(); dot(); dot();
  delay(3000);
}

void dot()
{
  digitalWrite(ledPin, HIGH);
  delay(250);
  digitalWrite(ledPin, LOW);
  delay(250);
}

void dash()
{
  digitalWrite(ledPin, HIGH);
  delay(1000);
  digitalWrite(ledPin, LOW);
  delay(250);
}

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 ledPin 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.

Share