GS32IR

Библиотека событийно-ориентированной обработки сигналов ИК-пультов дистанционного управления с поддержкой нескольких протоколов (NEC, SAMSUNG) для микроконтроллеров ESP32 и совместимых платформ Arduino.

Основана на концепции «виртуальных кнопок» пульта. Позволяет связывать HEX-коды кнопок пульта с виртуальными объектами и использовать для них событийную модель: события нажатия (press), удержания (hold) и отпускания (release).

Особенности библиотеки

• Собственная оптимизированная реализация ИК-декодера, работающая полностью на аппаратных прерываниях по спадающему фронту (FALLING).
• Одновременная поддержка и автоопределение двух самых распространенных 32-битных ИК-протоколов: NEC (большинство пультов) и SAMSUNG (телевизоры и бытовая техника Samsung).
• Возможность жесткой фильтрации принимаемого протокола на этапе инициализации приемника или привязки конкретной кнопки.
• Событийная модель на базе std::function и лямбда-выражений C++.
• Корректная и помехоустойчивая обработка оригинальных пакетов повтора (Repeat Code) для обоих протоколов.
• Автоматическое определение момента отпускания кнопки пульта (Release Timeout) при прекращении отправки сигналов повтора с пульта (> 220 мс).
• Встроенный универсальный сканер (onAnyKey) для считывания кодов неизвестных пультов с указанием их протокола.

Архитектура работы ИК-клавиш

При удержании кнопки пульта ИК-передатчик непрерывно шлет пакеты повтора. Библиотека программно объединяет входящие прерывания в логические состояния:

1. onPress: Срабатывает один раз при первом успешном декодировании кода клавиши.
2. onHold: Срабатывает циклически при каждом приеме сигнала повтора (примерно каждые 110 мс для NEC / Samsung).
3. onRelease: Срабатывает автоматически, если от пульта не поступало никаких сигналов в течение 220 мс.

Установка

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

Пример использования

#include "GS32IR.h"

// Пин подключения выхода ИК-приемника (TSOP)
const uint8_t IR_PIN = 16;

// Экземпляр ИК-приемника
GS32IR ir;

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

    // Инициализируем приемник. Режим IR_PROT_ANY позволяет ловить и NEC, и SAMSUNG пульты
    ir.begin(IR_PIN, IR_PROT_ANY);

    // 1. Универсальный сканер для определения кодов кнопок
    ir.onAnyKey([](uint32_t code, uint8_t state, IRProtocol protocol) {
        const char* stateStr = "";
        switch (state) {
            case 0: stateStr = "НАЖАТА"; break;
            case 1: stateStr = "УДЕРЖИВАЕТСЯ"; break;
            case 2: stateStr = "ОТПУЩЕНА"; break;
        }
        Serial.printf("[SCAN] Протокол: %s | Код: 0x%08X | Состояние: %s\n",
                      protocolToString(protocol), code, stateStr);
    });

    // 2. Регистрация конкретной кнопки пульта NEC (например, кнопка POWER)
    auto& necBtn = ir.addKey(0x00FF629D, IR_PROT_NEC);
    necBtn.onPress([](GS32IRKey& k) {
        Serial.println(">>> Сработало действие: Пульт NEC - Кнопка POWER");
    });

    // 3. Регистрация конкретной кнопки пульта SAMSUNG (например, кнопка MUTE)
    auto& samsungBtn = ir.addKey(0xE0E0F00F, IR_PROT_SAMSUNG);
    samsungBtn.onPress([](GS32IRKey& k) {
        Serial.println(">>> Сработало действие: Пульт Samsung - Кнопка MUTE");
    });
    samsungBtn.onRelease([](GS32IRKey& k) {
        Serial.println(">>> Отпущена кнопка MUTE на пульте Samsung");
    });

    Serial.println("Система ИК-приемника запущена.");
}

void loop() {
    // Вызывать в каждом цикле loop для обработки таймаутов отпускания
    ir.tick();
}

Справочник API

Перечисление IRProtocol (Поддерживаемые протоколы)

enum IRProtocol : uint8_t {
    IR_PROT_ANY = 0,     // Любой из поддерживаемых протоколов
    IR_PROT_NEC = 1,     // Только протокол NEC
    IR_PROT_SAMSUNG = 2  // Только протокол SAMSUNG
};

Вспомогательная функция:

• const char* protocolToString(IRProtocol prot)
  Преобразует значение перечисления IRProtocol в текстовую строку ("NEC", "SAMSUNG", "UNKNOWN").

Класс GS32IR (Класс приемника)

Координирует работу прерываний, декодирует сигнал и управляет виртуальными клавишами.

Методы:

• void begin(uint8_t pin, IRProtocol filterProtocol = IR_PROT_ANY)
  Инициализирует пин ИК-приемника в режиме INPUT_PULLUP и вешает аппаратное прерывание.
  Параметры:

  • pin (uint8_t): Пин подключения ИК-датчика (TSOP).
  • filterProtocol (IRProtocol, опционально): Ограничивает декодирование только выбранным протоколом. По умолчанию IR_PROT_ANY.

• GS32IRKey& addKey(uint32_t code, IRProtocol protocol = IR_PROT_ANY)
  Регистрирует виртуальную кнопку пульта.
  Параметры:

  • code (uint32_t): HEX-код кнопки пульта.
  • protocol (IRProtocol, опционально): Указывает протокол, к которому принадлежит данный код.
    Возвращает: Ссылку на созданный объект виртуальной кнопки GS32IRKey.

• void onAnyKey(IRGenericCallback cb)
  Устанавливает глобальный перехватчик событий. Удобно использовать в качестве ИК-сканера.
  Сигнатура колбэка: void(uint32_t code, uint8_t state, IRProtocol protocol), где state равен:

  • 0 — Нажатие
  • 1 — Удержание (повтор)
  • 2 — Отпускание

• void tick()
  Опрашивает буфер прерываний, вызывает обработчики событий и рассчитывает логику отпускания по таймаутам. Должен находиться в главном цикле loop().

• uint32_t getActiveCode() const
  Возвращает HEX-код активной (нажатой / удерживаемой в данный момент) кнопки. Возвращает 0, если ничего не нажато.

• IRProtocol getActiveProtocol() const
  Возвращает протокол активной в данный момент кнопки.

• bool isHolding() const
  Возвращает true, если кнопка удерживается пальцем (поступили сигналы повтора).

Класс GS32IRKey (Класс виртуальной клавиши)

Описывает логическое поведение конкретной кнопки пульта.

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

• void onPress(KeyCallback cb) — Событие первичного нажатия кнопки.
• void onHold(KeyCallback cb) — Событие циклического удержания кнопки (вызывается при каждом сигнале повторения).
• void onRelease(KeyCallback cb) — Событие автоматического отпускания кнопки (срабатывает, если сигналы повтора не поступали 220 мс).

Сигнатура всех колбэков: void(GS32IRKey& key)

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

• uint32_t getCode() const — Возвращает HEX-код этой клавиши.
• IRProtocol getProtocol() const — Возвращает заданный при создании клавиши протокол.

Лицензия

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