EmbedderShop

Для электронщиков и радиолюбителей

Категории

Пишем свою Arduino-библиотеку: структура, примеры, best practices

Пишем свою Arduino-библиотеку: структура, примеры, best practices
Блог 05.09.2025

Arduino славится тем, что для неё существует огромное количество готовых библиотек. Но иногда нужного решения нет, либо хочется оформить повторяющийся код так, чтобы его можно было удобно подключать в разных проектах. В этом случае на помощь приходит создание собственной Arduino-библиотеки.

Разберёмся, как правильно это сделать: от структуры папок до хороших практик.

1. Зачем писать библиотеку?

Библиотека удобна, если:

  • один и тот же код используется в разных проектах;
  • вы хотите скрыть «внутреннюю кухню» и оставить только понятный интерфейс;
  • проект слишком большой, и его стоит разделить на модули;
  • есть желание поделиться кодом с сообществом Arduino.

2. Структура библиотеки

Минимальная структура библиотеки выглядит так:

MyLibrary/
  ├── examples/
  │     └── BasicUsage/BasicUsage.ino
  ├── MyLibrary.h
  ├── MyLibrary.cpp
  └── library.properties
  • MyLibrary.h — заголовочный файл с объявлениями функций и классов.
  • MyLibrary.cpp — файл с реализацией функций.
  • library.properties — метаданные библиотеки (название, версия, автор и т.п.).
  • examples/ — примеры использования, которые будут видны в Arduino IDE через Файл → Примеры.

3. Простейший пример библиотеки

Допустим, мы хотим сделать библиотеку для управления светодиодом.

Файл MyLibrary.h

#ifndef MYLIBRARY_H
#define MYLIBRARY_H

#include <Arduino.h>

class MyLibrary {
  public:
    MyLibrary(uint8_t pin);   // конструктор
    void on();                // включить светодиод
    void off();               // выключить светодиод
    void toggle();             // переключить состояние

  private:
    uint8_t _pin;
    bool _state;
};

#endif

Файл MyLibrary.cpp

#include "MyLibrary.h"

MyLibrary::MyLibrary(uint8_t pin) {
  _pin = pin;
  _state = false;
  pinMode(_pin, OUTPUT);
}

void MyLibrary::on() {
  digitalWrite(_pin, HIGH);
  _state = true;
}

void MyLibrary::off() {
  digitalWrite(_pin, LOW);
  _state = false;
}

void MyLibrary::toggle() {
  _state = !_state;
  digitalWrite(_pin, _state ? HIGH : LOW);
}

Файл examples/BasicUsage/BasicUsage.ino

#include <MyLibrary.h>

MyLibrary led(13); // встроенный светодиод на пине 13

void setup() {}

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

4. Файл library.properties

Это «паспорт» библиотеки. Пример:

name=MyLibrary
version=1.0.0
author=Иван Иванов
maintainer=Иван Иванов <ivan@example.com>
sentence=Простая библиотека для управления светодиодом.
paragraph=Демонстрирует структуру Arduino-библиотеки и базовые практики.
category=Device Control
url=https://github.com/username/MyLibrary
architectures=*

5. Best practices

Чтобы библиотека была удобной и полезной, придерживайся следующих рекомендаций:

  • Используй #ifndef / #define или #pragma once в заголовочных файлах, чтобы избежать двойного включения.
  • Минимизируй глобальные переменные — лучше инкапсулировать всё в классе.
  • Добавляй примеры — без примеров библиотека будет сложна для понимания.
  • Следи за совместимостью — не используй жёстко привязанные пины внутри кода. Пусть пользователь указывает их сам.
  • Документируй код — хотя бы в формате комментариев ///.
  • Оптимизируй память — особенно важно для AVR-плат (Uno, Nano). Используй F() для строк, где это возможно.
  • Соблюдай версионирование — семантическая версия (1.0.0, 1.1.0) помогает понять, что изменилось.

6. Куда дальше?

Когда библиотека готова:

  • протестируй её в разных проектах;
  • загрузи в GitHub или другой репозиторий;
  • при желании опубликуй в Library Manager Arduino IDE.
Tag :