Create Your Own Arduino Library

In this tutorial I’ll show you how to create your own Arduino library.

You’ll see, this might be much simpler than you thought! Very simply put, an Arduino library is a bunch of Cpp files that you have to organize in a certain way. Then you import it, use it, and that’s it.

Creating an Arduino library is a great way to write reusable code for your projects, and also to help other Arduino developers in their own projects.

Let’s get started!

Step 1: Write your Arduino library code

Starting code

Let’s start with a very simple program, and from that create a library step by step.

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


You are learning Arduino programming?

Check out Arduino Programming For Beginners and learn step by step.


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

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

void loop() {}

Here we’ll make the addTwoInts() function a part of a library named my_library.

For now, all the code is in the same file, which isn’t really practical for separating the library from the main code.

Separating the library code from the rest

Let’s create 2 files: a Cpp and a header file.

To do that, find where your Arduino sketch is located. Usually it’s inside the “My Documents/Arduino” folder, unless you changed the default location. Also, you can find where is your current sketch file directly from the Arduino IDE: click on “Sketch” > “Show Sketch Folder”.

Arduino IDE - Show Sketch Folder

In this folder, you should already have a .ino file. If you named your project MyProgram, then the file is called MyProgram.ino, and is located inside the MyProgram/ folder.

Create 2 new files: my_library.h and my_library.cpp. Then restart your Arduino IDE, or close/open your current sketch. You should now see 3 files.

Arduino Separate Header and Cpp files

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”. For example, if you have a temperature_sensor.h file, you can use “TEMPERATURE_SENSOR_H”.

Then, don’t forget to include the Arduino library. On your main program it’s automatically added for you if you forget it, but not on other files or libraries.

Finally, you have the prototype of your function. The implementation will be done in the Cpp file.

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.

Now, let’s use this function in our sketch again.

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

All right, now that we have separated the code, let’s create a real Arduino library! Separating the code you want to put into your library is only the first step.

Step 2: Package your Arduino library

Let’s use the my_library.cpp and my_library.h files that we just created.

Place your library files into the Arduino libraries folder

First, you have to know where to put your library. As for your Arduino sketches, there is a specific folder for libraries.

Go again in your Arduino folder (“My Documents/Arduino” or similar), and find a folder named libraries/. If you can’t find it, you’ll have to create it. This folder path will be “My Documents/Arduino/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/
└── Arduino/
    └── libraries/
        └── my_library/
            ├── my_library.h
            └── my_library.cpp

Then, restart your Arduino IDE. Don’t forget this, as it doesn’t automatically detect changes in the file architecture.

On your main .ino code (now, in your sketch folder, you only have your .ino file again), change this line #include "my_library.h" to this: #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 <>.

You can run your code, it should compile and work. You have successfully created your first Arduino library! Quite easy, isn’t it?

If you want to modify your library after you’ve put the files into your libraries/ folder, use any other text editor (for example Visual Studio Code). You won’t be able to direclty open those files in the Arduino IDE – unless you copy and paste the files into an existing project, modify the files, and put them back into the libraries/ folder.

Now, this library is quite basic and easy to use. But if you write something more complex, it may be more difficult for others to understand how to use it.

Remember, creating a library means that other people might actually use it!

Add examples to your Arduino library

A great way to provide a quick introduction to your library is to create a code example using your library. If you remember, when you started on Arduino, you may have used some code examples such as the famous Blink.ino, to teach you how to blink a LED.

It’s very simple to add examples to your libraries.

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/
└── Arduino/
    └── libraries/
        └── my_library/
            ├── examples/
                ├── add_two_ints/
                    ├── add_two_ints.ino
            ├── my_library.h
            └── my_library.cpp

Here’s the code example:

/*
 * 
 * Explanation of what your example does
 * 
 */

#include <my_library.h>

void setup() 
{
  // Setup Serial communication to print result on Serial Monitor
  Serial.begin(9600);

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

  // Check result
  Serial.println(result);
}

void loop() {}

Now, how to see your example from the Arduino IDE?

Simply restart your IDE, and your example is now showing in the menu!

Arduino IDE - Open Custom Library Example

You can click on it, compile it, and run it on your Arduino board. This example will make things easier for anyone who wants to learn how to use your library.

Step 3: Share your Arduino library

It’s great to have a library that you can use on your own computer, in your own programs. But the true purpose of a library is to be shared.

Export the library

To export and share your library, create an archive of the my_library/ folder, located into Arduino/libraries/.

Then, you just have to share it with other people you know, or online. You can easily find websites to host your library archives (usually a few KiloBytes). Now, the hard part is to make people get to know your library exists!

Once someone gets your library, there are 2 ways to install it on their Arduino environment (and this can be useful for you too, when you install libraries developed by other people).

You can try it on your own computer. Export your library into an archive, and place it somewhere else in your computer. Also remove the my_library/ folder. Now, if you restart your Arduino IDE, you won’t be able to use the library or open the examples. So, you’ll have to import it.

Manually import the library

Once you get the library, just 3 steps are required before you can use it:

  1. Extract the archive.
  2. Place the library folder in Arduino/libraries/.
  3. Restart the Arduino IDE.

Import the library through the Arduino IDE

This will work only if you have created a .zip archive (not .rar or other extensions).

Simply open the Arduino IDE, click on “Sketch” > “Include Library” > “Add .ZIP Library…”, and browse to find your .zip archive.

Arduino IDE - Add zip Library

The Arduino IDE will extract the archive, place the library in the Arduino/libraries/folder, and update itself so you don’t need to restart it.

Another example: a library for a LED class

The code example I provided above is really small. The purpose was to focus on the library itself and not the code.

Now, let’s use a more real-world example. 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

And the files:

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

Here I have put comments on each method of the class. Documenting your code is always a good idea.

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

/*
 * 
 * This examples shows how to blink a LED
 * using the Led class from the Led library
 * 
 */

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

Going further with your Arduino library

In this tutorial you have seen how to create your own Arduino library, how to add examples to it, how to package it, and how to export it.

Here is what you can do next:

  • Add a license to your library. I won’t tell you which license to use here because it depends on what you want to do. Some common open source licenses: MIT, BSD, Apache, GPL, … Adding a license means that you’ll add a comment header to every files in your library, stating the license agreements.
  • Host your code on GitHub if you’re going open source. This might be a good idea to share your code, so you can get feedback from other developers and improve your library, as well as increasing the awareness around it.
  • Communicate about your library: on the Arduino forum, on your own website, etc.
  • Add more documentation and more examples. The clearer your library, the easier it will be for new users to use it efficiently and keep it in their code.

Note: before creating your own library – unless you do it for an educational purpose, first check if someone else has already published a library that meets your needs. If yes, you’ll have to check the license to see if you can use it. It’s important not to reinvent the wheel for everything you create. This way you’ll progress faster on your projects!

Did you find this tutorial useful?

Do you want to learn how to program with Arduino?

If yes, this course is for you:

Arduino Programming For Beginners Course

>> Arduino Programming For Beginners <<

LEARN HOW TO PROGRAM ROBOTS

Did you find this tutorial useful?

Do you want to become better at programming robots, with Arduino, Raspberry Pi, or ROS2?

If yes, subscribe to receive exclusive content and special offers!