Create Your Own Arduino Library (.h and .cpp files)

This document explains how to create a library for Arduino. 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 will make example main code (w/ extension .ino).

Step 1: Package your Arduino library

First, write this small Arduino sketch, which only has one function. The function will take twointegers as parameters and return the sum.

Example main_code.ino

int addTwoInts(int a, int b)
{
  return a + b;
}

void setup() 
{
  Serial.begin(9600);
  int result = addTwoInts(4,3);
  Serial.println(result);
}

void loop() {}

Now we will write the following code into those 3 files.

my_library.h

#ifndef MY_LIBRARY_H
#define MY_LIBRARY_H

#include <Arduino.h>

int addTwoInts(int a, int b);

#endif

This is a typical header file. You start with the header guards and add your code between the #define MY_LIBRARY_H and #endif. For the header guard’s name, usually it’s a good practice to use the name of your file in uppercase and add “_H”. Then, don’t forget to include the Arduino library.

my_library.cpp

#include "my_library.h"
int addTwoInts(int a, int b)
{
  return a + b;
}

Here you just import your header file, and you implement the code for the function.

main_code.ino

#include "my_library.h"

void setup() 
{
  Serial.begin(9600);
  int result = addTwoInts(4,3);
  Serial.println(result);
}

void loop() {}

You just have to include the header file and you can use the addTwoInts() function without changing your initial code.

Step 2: Package your Arduino library

First, you have to know where to put your library (.h and .cpp files). As for your Arduino sketches, there is a specific folder for libraries. Also, A great way to provide a quick introduction to your library is to create a code example using your library.

Go again in your Arduino folder (“My Documents/Arduino” or similar), and find a folder named libraries/. In this libraries/ folder, create a new folder named my_library/. Move the my_library.h and my_library.cpp files into my_library/.

Documents/
<span class="">└──</span> Arduino/
    <span class="">└──</span> libraries/
        <span class="">└──</span> my_library/
            <span class="">├──</span> my_library.h
            <span class="">└──</span> my_library.cpp

NOTE: Difference between #include “my_library.h” and #include <my_library.h>. When including a header file located in your project directory, use “ ”. If the header file is globally installed, or in this case, from the Arduino libraries folder, use <>.

Next, In the my_library/ folder, create an examples/ folder. Inside this examples/ folder, you’ll simply add a new Arduino project for each example.

For our custom library, let’s create an example to show how to use the addTwoInts() functions. In my_library/, create a folder add_two_ints/, and inside it a file named add_two_ints.ino.

Documents/
<span class="">└──</span> Arduino/
    <span class="">└──</span> libraries/
        <span class="">└──</span> my_library/
            <span class="">├──</span> examples/
                <span class="">├──</span> add_two_ints/
                    <span class="">├──</span> add_two_ints.ino
            <span class="">├──</span> my_library.h
            <span class="">└──</span> my_library.cpp

add_two_ints.ino

#include <my_library.h>

void setup() 
{
  Serial.begin(9600);

  // Get the sum of two integers into another integer
  int result = addTwoInts(4,3);

  Serial.println(result);
}

void loop() {}

Conclusion: To create any Arduino library library, we need .h and .cpp file. We have two option, either use library locally or globally. For global use in IDE, you have to put the file at specified location and restart IDE. Optionally, we can place example files for the Library.

Another Example: a library for a LED class

We’ll use the LED class we created in another tutorial on Arduino OOP. So, this will also be an opportunity for you to work on how to create an Arduino library with classes.

Library folder structure

Documents/
└── Arduino/
    └── libraries/
        ├── examples/
            └── blink_led/
                └── blink_led.ino
        └── Led/
            ├── Led.h
            └── Led.cpp

Led.h

#ifndef LED_H
#define LED_H

#include <Arduino.h>

class Led {
  
  private:
    byte pin;
    
  public:
    // Setup pin LED and call init()
    Led(byte pin);

    // Setup the pin led as OUTPUT
    // and power off the LED - default state
    void init();
    
    // Power on the LED
    void on();

    // Power off the LED
    void off();
};

#endif

Led.cpp

#include "Led.h"

Led::Led(byte pin) {
  this->pin = pin;
  init();
}

void Led::init() {
  pinMode(pin, OUTPUT);
  off();
}

void Led::on() {
  digitalWrite(pin, HIGH);
}

void Led::off() {
  digitalWrite(pin, LOW);
}

Example file blink_led.ino

#include <Led.h>

// Use the built-in LED
#define LED_PIN 13

// Create a Led object
// This will set the pin to OUTPUT
Led led(LED_PIN);

void setup() { }

void loop() {
    // Power on the LED
    led.on();
    delay(1000);
    // Power off the LED
    led.off();
    delay(1000);
}

After writing those files and setting up the Led library folder, you can now restart your Arduino IDE and test the blink_led.ino example.