GS32Buttons

Библиотека событийно-ориентированной обработки кнопок для контроллеров ESP32 и совместимых платформ Arduino.

Предназначена для удобного управления одиночными кнопками и группами кнопок. Поддерживает отслеживание одиночных и двойных кликов, удержаний, фиксацию нажатия при старте системы, а также регистрацию длительности состояний с использованием колбэков и лямбда-выражений C++.

Основные возможности

• Централизованное управление несколькими кнопками через единый объект-менеджер.
• Событийная модель на базе std::function (поддержка лямбда-функций с захватом контекста).
• Фильтрация аппаратного дребезга контактов (Debounce).
• Определение состояния зажатия кнопки при подаче питания / перезагрузке микроконтроллера (onBootPress).
• Фиксация событий:
  • Изменение состояния (нажата / отпущена) с передачей времени нахождения в предыдущем состоянии.
  • Одиночный клик (onSingleClick).
  • Двойной клик (onDoubleClick).
  • Длительное удержание (onLongPress).
• Гибкая настройка временных интервалов индивидуально для каждой кнопки.

Установка

1. Скачайте репозиторий или папку с библиотекой.
2. Поместите папку GS32Buttons в директорию libraries вашего Arduino IDE (обычно находится по пути C:\Users\<Имя_Пользователя>\Documents\Arduino\libraries\).
3. Перезапустите Arduino IDE.

Быстрый старт

Пример регистрации трех кнопок с обработкой различных событий.

#include "GS32Buttons.h"

// Создаем менеджер кнопок
GS32Buttons btnGroup;

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

    // 1. Кнопка 12: Обработка одиночного и двойного клика
    auto& btn12 = btnGroup.add(12);
    btn12.onSingleClick([](GS32Button& b) {
        Serial.printf("Кнопка %d: Одиночный клик\n", b.getPin());
    });
    btn12.onDoubleClick([](GS32Button& b) {
        Serial.printf("Кнопка %d: Двойной клик\n", b.getPin());
    });

    // 2. Кнопка 13: Долгое удержание и старт системы
    auto& btn13 = btnGroup.add(13);
    btn13.onLongPress([](GS32Button& b) {
        Serial.printf("Кнопка %d: Долгое удержание\n", b.getPin());
    });
    btn13.onBootPress([](GS32Button& b) {
        Serial.printf("Кнопка %d была зажата при запуске платы!\n", b.getPin());
    });

    // 3. Кнопка 14: Отслеживание всех изменений состояния
    btnGroup.add(14).onClick([](GS32Button& b, bool pressed, uint32_t duration) {
        Serial.printf("Кнопка %d %s (Прошлое состояние длилось %u мс)\n",
                      b.getPin(), pressed ? "НАЖАТА" : "ОТПУЩЕНА", duration);
    });

    // Инициализируем все добавленные кнопки
    btnGroup.begin();
    Serial.println("Система готова.");
}

void loop() {
    // Непрерывный опрос состояния кнопок
    btnGroup.tick();
}

Документация API

Класс GS32Buttons (Менеджер кнопок)

Управляет коллекцией кнопок и выполняет их групповую инициализацию и опрос.

Методы:

• GS32Button& add(uint8_t pin, bool pullup = true, uint32_t debounceMs = 30)
  Добавляет новую кнопку в менеджер.
  Параметры:

  • pin (uint8_t): Номер GPIO пина.
  • pullup (bool, опционально): true — подтяжка к VCC (INPUT_PULLUP), false — INPUT. По умолчанию: true.
  • debounceMs (uint32_t, опционально): Время фильтрации дребезга в миллисекундах. По умолчанию: 30.
    Возвращает: Ссылку на созданный объект GS32Button для настройки события.

• void begin()
  Инициализирует режимы работы пинов всех добавленных кнопок и считывает их стартовые состояния. Вызывается в setup().

• void tick()
  Опрашивает текущее состояние всех кнопок. Вызывается в loop().

---

Класс GS32Button (Объект кнопки)

Содержит логику обработки состояния конкретной кнопки.

Методы настройки таймаутов:

• void setDoubleClickTime(uint32_t ms) — устанавливает максимальный интервал между нажатиями для распознавания двойного клика (по умолчанию: 300 мс).
• void setLongPressTime(uint32_t ms) — устанавливает минимальное время удержания кнопки для срабатывания события onLongPress (по умолчанию: 1000 мс).

Методы подписки на события:

• void onClick(StateCallback cb)
  Событие изменения состояния (нажатие или отпускание).
  Сигнатура колбэка: void(GS32Button& btn, bool pressed, uint32_t duration)

• void onSingleClick(ButtonCallback cb)
  Событие одиночного клика. Вызывается после истечения таймаута ожидания второго клика.
  Сигнатура колбэка: void(GS32Button& btn)

• void onDoubleClick(ButtonCallback cb)
  Событие двойного клика.
  Сигнатура колбэка: void(GS32Button& btn)

• void onLongPress(ButtonCallback cb)
  Событие удержания кнопки. Вызывается сразу по истечении заданного интервала времени, не дожидаясь отпускания.
  Сигнатура колбэка: void(GS32Button& btn)

• void onBootPress(ButtonCallback cb)
  Событие обнаружения зажатия кнопки в момент вызова begin(). Используется для организации режимов сброса настройки, сервисных меню и прочего.
  Сигнатура колбэка: void(GS32Button& btn)

Информационные методы:

• uint8_t getPin() const — возвращает номер GPIO пина кнопки.
• bool isPressed() const — возвращает текущее логическое состояние (нажата — true, отпущена — false).

Лицензия

Этот проект является частью экосистемы GS32Bios и распространяется под лицензией MIT. Вы можете свободно использовать, модифицировать и распространять данный код в своих некоммерческих и коммерческих проектах.