How to Create a Custom Library in Arduino: Step-by-Step Guide

To create a custom library in Arduino, make a folder with your library name inside the Arduino 'libraries' folder, then add a .h header file and a .cpp source file defining your functions or classes. Include your library in sketches with #include <YourLibraryName.h> and use its features like built-in Arduino libraries.

Syntax

A custom Arduino library typically has two main files: a header file YourLibraryName.h and a source file YourLibraryName.cpp. The header file declares your functions or classes, and the source file defines their behavior.

Basic structure:

• YourLibraryName.h: Contains class/function declarations and include guards.
• YourLibraryName.cpp: Contains the actual code for the declared functions or classes.
• Place both files inside a folder named YourLibraryName in the Arduino libraries directory.

arduino

// YourLibraryName.h
#ifndef YourLibraryName_h
#define YourLibraryName_h

#include <Arduino.h>

class YourLibraryName {
  public:
    YourLibraryName();
    void begin();
    void doSomething();
};

#endif // YourLibraryName_h

Example

This example shows a simple custom library named SimpleLED that controls an LED on a specified pin. It has methods to initialize the pin and turn the LED on or off.

After creating the library files and placing them in the Arduino libraries folder, you can include and use it in your sketch.

arduino

// SimpleLED.h
#ifndef SimpleLED_h
#define SimpleLED_h

#include <Arduino.h>

class SimpleLED {
  public:
    SimpleLED(int pin);
    void begin();
    void on();
    void off();
  private:
    int _pin;
};

#endif // SimpleLED_h

// SimpleLED.cpp
#include "SimpleLED.h"

SimpleLED::SimpleLED(int pin) {
  _pin = pin;
}

void SimpleLED::begin() {
  pinMode(_pin, OUTPUT);
}

void SimpleLED::on() {
  digitalWrite(_pin, HIGH);
}

void SimpleLED::off() {
  digitalWrite(_pin, LOW);
}

// ExampleSketch.ino
#include <SimpleLED.h>

SimpleLED led(13);

void setup() {
  led.begin();
}

void loop() {
  led.on();
  delay(1000);
  led.off();
  delay(1000);
}

Output

The built-in LED on pin 13 blinks on and off every second.

Common Pitfalls

Common mistakes when creating Arduino libraries include:

• Not using include guards in the header file, which can cause multiple definition errors.
• Placing library files outside the Arduino libraries folder, so Arduino IDE cannot find them.
• Forgetting to include <Arduino.h> in the header file, which provides Arduino functions and types.
• Not matching the folder name with the library name exactly, causing include errors.
• Not restarting the Arduino IDE after adding the library folder, so it doesn't recognize the new library.

Example of a wrong header file missing include guards:

arduino

// Wrong: Missing include guards
#include <Arduino.h>

class BadLibrary {
  public:
    void doStuff();
};

// Right: With include guards
#ifndef BadLibrary_h
#define BadLibrary_h

#include <Arduino.h>

class BadLibrary {
  public:
    void doStuff();
};

#endif // BadLibrary_h

Quick Reference

Tips for creating Arduino libraries:

• Name your library folder and files consistently.
• Use include guards in header files.
• Include <Arduino.h> in headers for Arduino functions.
• Place your library folder inside the Arduino libraries directory.
• Restart the Arduino IDE after adding new libraries.
• Test your library with a simple sketch before complex use.

Key Takeaways

Create a folder with your library name inside the Arduino libraries directory.

Write a header file with include guards and a source file with function definitions.

Include in your header to access Arduino functions and types.

Restart the Arduino IDE after adding your library to make it available.

Test your library with a simple sketch to ensure it works correctly.