Arduino – Writing a Library

This page gives a summary of how to convert a sketch to a C++ file. Note that you will need to have some level of basic C++ knowledge to take on this task.

Original code

int pin = 13;
void setup()
{
	pinMode(pin, OUTPUT);
}

void loop()
{
	LEDFlash(); LEDFlash(); LEDFlash();
	LEDLight(); LEDLight(); LEDLight();
	LEDFlash(); LEDFlash(); LEDFlash();
	delay(2000);
}

/* Quick flash */
void LEDFlash()
{
	digitalWrite(pin, HIGH); delay(100);
	digitalWrite(pin, LOW); delay(100);
}

/* Long flash */
void LEDLight()
{
	digitalWrite(pin, HIGH); delay(1000);
	digitalWrite(pin, LOW); delay(100);
}

Below are the steps to convert a single sketch into a C++ library.

1. Create a new header file called “RunwayLight.h”

   /*
     RunwayLight.h - Library for flashing runway light.
   */
   #ifndef RunwayLight_h
   #define RunwayLight_h
   #include "Arduino.h"
   class RunwayLight
   {
     public:
       RunwayLight(int pin);
       void LEDFlash();
       void LEDLight();
     private:
       int _pin;
   };
   #endif
   

2. Create a C++ program file called “RunwayLight.cpp”

   /*
     RunwayLight.cpp - Library for flashing runway light.
   */
   #include "Arduino.h"
   #include "RunwayLight.h"
   
   RunwayLight::RunwayLight(int pin)
   {
     pinMode(pin, OUTPUT);
     _pin = pin;
   }
   
   /* Quick flash */
   void RunwayLight::LEDFlash()
   {
     digitalWrite(_pin, HIGH); delay(100);
     digitalWrite(_pin, LOW);  delay(100);
   }
   
   /* Long flash */
   void RunwayLight::LEDLight()
   {
     digitalWrite(_pin, HIGH); delay(1000);
     digitalWrite(_pin, LOW);  delay(100);
   }
   

3. Next, make a RunwayLight directory inside of the libraries sub-directory of your sketchbook directory, and copy or move the RunwayLight.h and RunwayLight.cpp files into that directory.
4. Re-launch the Arduino environment. If you open the Sketch > Import Library menu, you should see RunwayLight 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).
5. This is how you would use the library.

   #include 
   
   RunwayLight rl(13);   /* RunwayLight object */
   
   void setup() { }
   
   void loop()
   {
     rl.LEDFlash(); rl.LEDFlash(); rl.LEDFlash();
     rl.LEDLight(); rl.LEDLight(); rl.LEDLight();
     rl.LEDFlash(); rl.LEDFlash(); rl.LEDFlash();
     delay(2000);
   }
   

Key points to know

• Keyword File
  If you tried the new sketch, you probably noticed that nothing from our library was recognized and highlighted in color by the IDE. The Arduino IDE software cannot automatically determine what your functions and variables are in your library (or libraries), so you have to give it a little helping hand. To acomplish this, create a file called keywords.txt in the RunwayLight directory. Its content should look like this.

  RunwayLight	KEYWORD1
  LEDFlash	KEYWORD2
  LEDLight	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 IDE environment to get it to recognize the new keywords.

• Examples for your Library
  It is also nice to provide people with an example sketch that uses your library. To do this, create an examples directory inside the RunwayLight directory and then, move or copy the directory containing the sketch we wrote above and into the examples directory. If you restart the Arduino IDE environment, you will see a Library-RunawayLight 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.