Клавиатуры, FLASH-I2C

Общие сведения:

Модуль - Клавиатура, I2C-flash - является устройством ввода данных с подключением по шине I2С.

Модуль относится к серии «Flash», а значит к одной шине I2C можно подключить более 100 модулей, так как их адрес на шине I2C (по умолчанию 0x09), хранящийся в энергонезависимой памяти, можно менять программно.

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

Видео:

Редактируется ...

Спецификация:

Напряжение питания: 3,3 В или 5 В (постоянного тока), поддерживаются оба напряжения.
Потребляемый ток: до 10 мА (при включении всех светодиодов).
Интерфейс: I2C.
Скорость шины I2C: 100 кбит/с.
Адрес на шине I2C: устанавливается программно (по умолчанию 0x09).
Уровень логической 1 на линиях шины I2C: Vcc (толерантны к 5 В).
Количество кнопок со светодиодами: зависит от типа модуля (на картинке 8 кнопок 4x2).
Количество уровней яркости светодиодов: 7.
Размер буфера FIFO: 255 байт (1 байт хранит код символа 1 кнопки).
Рабочая температура: от -20 до +70 °С.
Габариты: 78,74 х 39,37 мм (для модуля с 8 кнопками 4x2).
Вес: 26 г (для модуля с 8 кнопками 4x2).

Подключение:

Перед подключением модуля ознакомьтесь с разделом "Смена адреса модуля на шине I2C" в данной статье.

С обратной стороны платы, по бокам, расположены разъемы для подключения клавиатуры к шине I2C. Шина подключается к любому разъему I2C, а второй разъем можно использовать для подключения следующей клавиатуры, или других устройств.

SCL - вход/выход линии тактирования шины I2C.
SDA - вход/выход линии данных шины I2C.
Vcc - вход питания 3,3 или 5 В.
GND - общий вывод питания.

Модуль удобно подключать 2 способами, в зависимости от ситуации:

Способ - 1 : Используя проводной шлейф и Piranha UNO

Используя провода «Папа — Мама», подключаем напрямую к контроллеру Piranha UNO.

Способ - 2 : Используя проводной шлейф и Shield

Используя 3-х проводной шлейф, к Trema Shield, Trema-Power Shield, Motor Shield, Trema Shield NANO и тд.

Питание:

Входное напряжение питания модуля 3,3В или 5В постоянного тока (поддерживаются оба напряжения питания), подаётся на выводы Vcc и GND любого разъема.

Подробнее о модуле:

Модуль построен на базе микроконтроллера STM32F030F4 и снабжен собственным стабилизатором напряжения. Модуль самостоятельно опрашивает кнопки клавиатуры, обрабатывает полученные данные и по запросу выводит состояния кнопок, события совершённые с кнопками, а так же предоставляет возможность управлять светодиодами кнопок.

Модуль позволяет:

Менять свой адрес на шине I2C.
Управлять внутренней подтяжкой линий шины I2C (по умолчанию включена).
Получать текущее состояние кнопок клавиатуры (нажата / отпущена / удерживается).
Получать наличие событий кнопок клавиатуры (нажималась / отпускалась / изменилась).
Получать время удержания или простоя кнопок клавиатуры.
Управлять светодиодами кнопок (включить / выключить).
Задавать яркость свечения светодиодов кнопок.
Задавать режимы светодиодной анимации, при которых светодиоды будут самостоятельно реагировать на события или изменение состояний кнопок (доступно несколько режимов).
Получать историю нажатий кнопок прочитав последовательности их нажатий из буфера FIFO.
Определять количество данных в буфере FIFO или очистить буфер.
Задавать время по которому коды удерживаемых кнопок будут попадать в буфер FIFO.

Специально для работы с модулем - Клавиатура, I2C-flash, нами разработана библиотека iarduino_I2C_Keyboard которая позволяет реализовать все функции модуля.

Подробнее про установку библиотеки читайте в нашей инструкции.

Смена адреса модуля на шине I2C:

По умолчанию все модули FLASH-I2C имеют установленный адрес 0х09. Если вы планируете подключать более 1 модуля на шину I2C, необходимо изменить адреса модулей таким образом, чтобы каждый из них был уникальным. Более подробно о том, как изменить адрес, а также о многом другом, что касается работы FLASH-I2C модулей, вы можете прочесть в этой статье.

В первой строке скетча необходимо записать в переменную newAddress адрес, который будет присвоен модулю. После этого подключите модуль к контроллеру и загрузите скетч. Адрес может быть от 0х07 до 0х7F.

uint8_t newAddress = 0x09;                        // Назначаемый модулю адрес (0x07 < адрес < 0x7F).
                                                  //
#include <Wire.h>                                 // Подключаем библиотеку для работы с аппаратной шиной I2C.
#include <iarduino_I2C_Keyboard.h>                // Подключаем библиотеку для работы с клавиатурой I2C-flash.
iarduino_I2C_Keyboard kbd(false, 4, 2);           // Объявляем объект kbd для работы с функциями и методами библиотеки iarduino_I2C_Keyboard, указав количество кнопок в линии (4) и количество линий с кнопками (2).
                                                  // Если при объявлении объекта указать адрес, например, kbd(0xBB, 4, 2), то пример будет работать с тем модулем, адрес которого был указан.
void setup(){                                     //
    Serial.begin(9600);                           //
    if( kbd.begin() ){                            // Инициируем работу с клавиатурой.
        Serial.print("Найден модуль с адр. 0x");  //
        Serial.println( kbd.getAddress(), HEX );  // Выводим текущий адрес модуля.
        if( kbd.changeAddress(newAddress) ){      // Меняем адрес модуля на newAddress.
            Serial.print("Адрес изменён на 0x");  //
            Serial.println(kbd.getAddress(),HEX); // Выводим текущий адрес модуля.
        }else{                                    //
            Serial.println("Адрес не изменён!");  //
        }                                         //
    }else{                                        //
        Serial.println("Модуль не найден!");      //
    }                                             //
}                                                 //
                                                  //
void loop(){}                                     //

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

Смена и сортировка адресов на шине I2C:

Изменить адрес любого I2C модуля серии «Flash» можно аппаратно, используя установщик адресов FLASH-I2C. Это модуль подключаемый к шине I2C, на плате которого размещён дисплей и кнопки управления, при помощи которых можно узнать количество любых устройств на шине I2C, и менять адреса модулей Flash-I2C не отключая их от шины, что значительно сократит время сборки ваших проектов. Модуль оснащён разъемом USB через который можно запитать как сам модуль, так и шину I2C, или можно запитать шину I2C без использования разъема USB на плате модуля. Установщик адресов пригодиться в проектах с большим количеством модулей Flash-I2C.

Изменить адрес любого I2C модуля серии «Flash» можно программно, о том как это сделать рассказано в статье Wiki - Программная установка адресов модулей FLASH-I2C. В этой статье рассмотрены примеры с использованием библиотеки iarduino_I2C_Address, которая позволяет получать адреса любых устройств на шине I2C, менять адреса модулей Flash-I2C не отключая их от шины, получать название, номер модели, версию прошивки модулей Flash-I2C, а главное - автоматически сортировать адреса модулей Flash-I2C даже если на шине есть устройства с одинаковыми адресами.

Примеры:

В данном разделе раскрыты примеры работы с модулем по шине I2C с использованием библиотеки iarduino_I2C_Keyboard. Сама библиотека содержит больше примеров, доступных из меню Arduino IDE: Файл / Примеры / iarduino_I2C_Keyboard.

Все примеры приведены для клавиатуры, кнопки которой расположены в 2 ряда, по 4 кнопки в каждом ряду. Если у Вашей клавиатуры другое количество или расположение кнопок, просто укажите это при объявлении объекта:

kbd( адрес, количество кнопок в ряду, количество рядов);.

Получение символов введённых с клавиатуры:

Пример для клавиатуры, кнопки которой расположены в 2 ряда, по 4 кнопки в каждом ряду, позволяет присвоить символы клавишам и увидеть текст введённый с клавиатуры.

#include <Wire.h>                                 // Подключаем библиотеку для работы с аппаратной шиной I2C.
#include <iarduino_I2C_Keyboard.h>                // Подключаем библиотеку для работы с клавиатурой I2C-flash.
iarduino_I2C_Keyboard kbd(0x09, 4, 2);            // Объявляем объект kbd для работы с функциями и методами библиотеки iarduino_I2C_Keyboard, указывая адрес модуля на шине I2C, количество кнопок в линии, количество линий с кнопками.
                                                  // Если объявить объект без указания адреса, например, kbd(false, 4, 2), то адрес будет найден автоматически.
void setup(){                                     //
    Serial.begin(9600);                           // Инициируем передачу данных по шине UART на скорости 9600 бит/сек.
    kbd.begin();                                  // Инициируем работу с клавиатурой.
    kbd.setEncoding("abcd0123");                  // Присваиваем символы всем кнопкам клавиатуры. По умолчанию кнопкам присвоены символы "12345678".
    kbd.setEncoding(4, 1, 'f');                   // Символ можно присвоить каждой кнопке по отдельности (присвоить 4 кнопке, в 1 ряду, символ 'f').
    kbd.setEncoding(4, 2, '\n');                  // Символ можно присвоить каждой кнопке по отдельности (присвоить 4 кнопке, в 2 ряду, символ новой строки '\n').
    kbd.flush();                                  // Чистим буфер истории нажатых кнопок.
}                                                 //
                                                  //
void loop(){                                      //
//  Получаем и выводим символы с клавиатуры:      //
    if( kbd.available() ){                        // Если в буфере истории нажатий кнопок есть символы (функция available возвращает количество символов в буфере), то ...
        Serial.print( kbd.readChar() );           // Выводим очередной символ из буфера истории нажатий кнопок.
    }                                             //
}                                                 //

После загрузки данного примера, в мониторе последовательного порта будут появляться символы нажатых клавиш. Каждой клавише можно присвоить один символ, обратившись к функции setEncoding(). По умолчанию клавишам присвоены символы 1,2,3,4,5,6,7,8. Для клавиатур с 10 кнопками, по умолчанию, клавишам присвоены символы 1,2,3,4,5,6,7,8,9,0.

При нажатии клавиши, её код добавляется в буфер истории нажатых клавиш клавиатуры (буфер FIFO). При удержании клавиши, её код многократно добавляется в буфер. Количество кодов (байт) находящихся в буфере истории можно узнать функцией available(). При чтении символа из буфера истории функцией readChar(), прочитанный символ исчезает из буфера. Обратившись к функции flush() можно очистить всю историю нажатых клавиш, но в приведённом примере эта функция ничего не делает, так как при подаче питания буфер пуст. Размер буфера позволяет хранить историю последних 255 нажатых клавиш.

В примере Arduino IDE: Файл / Примеры / iarduino I2C Keyboard (клавиатура) / 4x2 / printString предложен вариант получения данных не символами, а целыми строками.

Добавление светодиодной анимации:

Пример для клавиатуры, кнопки которой расположены в 2 ряда, по 4 кнопки в каждом ряду, позволяет анимировать действия светодиодной подсветкой клавиш.

#include <Wire.h>                                 // Подключаем библиотеку для работы с аппаратной шиной I2C.
#include <iarduino_I2C_Keyboard.h>                // Подключаем библиотеку для работы с клавиатурой I2C-flash.
iarduino_I2C_Keyboard kbd(0x09,4,2);              // Объявляем объект kbd для работы с функциями и методами библиотеки iarduino_I2C_Keyboard, указывая адрес модуля на шине I2C, количество кнопок в линии, количество линий с кнопками.
                                                  // Если объявить объект без указания адреса, например, kbd(false, 4, 2), то адрес будет найден автоматически.
void setup(){                                     //
    Serial.begin(9600);                           // Инициируем передачу данных по шине UART на скорости 9600 бит/сек.
    kbd.begin();                                  // Инициируем работу с клавиатурой.
    kbd.setEncoding("abcdefg\n");                 // Присваиваем символы всем кнопкам клавиатуры (последней кнопке присваиваем символ новой строки '\n'). По умолчанию кнопкам присвоены символы "12345678".
    kbd.setAnimation(7);                          // Включаем светодиодную анимацию № 7. Светодиоды информируют о добавлении кода своей кнопки в буфер истории нажатых клавиш.
}                                                 //
                                                  //
void loop(){                                      //
//  Получаем и выводим символы с клавиатуры:      //
    if( kbd.available() ){                        // Если в буфере истории нажатий кнопок есть символы (функция available возвращает количество символов в буфере), то ...
        Serial.print( kbd.readChar() );           // Выводим очередной символ из буфера истории нажатий кнопок.
    }                                             //
}                                                 //

Данный пример, как и предыдущий, выводит символы нажатых кнопок в монитор последовательного порта. Обращением к функции setAnimation() с параметром 7, мы включаем светодиодную анимацию добавления кодов нажатых клавиш в буфер истории. Измените номер анимации с 7 на 1-6, для просмотра всех вариантов. Обращение к функции setAnimation() с параметром 0 приводит к отключению светодиодной анимации.

Чтение состояний и событий кнопок клавиатуры:

Пример для клавиатуры, кнопки которой расположены в 2 ряда, по 4 кнопки в каждом ряду, позволяет работать с клавиатурой как с набором отдельных кнопок.

#include <Wire.h>                                                   // Подключаем библиотеку для работы с аппаратной шиной I2C.
#include <iarduino_I2C_Keyboard.h>                                  // Подключаем библиотеку для работы с клавиатурой I2C-flash.
iarduino_I2C_Keyboard kbd(0x09,4,2);                                // Объявляем объект kbd для работы с функциями и методами библиотеки iarduino_I2C_Keyboard, указывая адрес модуля на шине I2C, количество кнопок в линии, количество линий с кнопками.
                                                                    // Если объявить объект без указания адреса, например, kbd(false, 4, 2), то адрес будет найден автоматически.
void setup(){                                                       //
    Serial.begin(9600);                                             // Инициируем передачу данных по шине UART на скорости 9600 бит/сек.
    kbd.begin();                                                    // Инициируем работу с клавиатурой.
    kbd.setEncoding(4,1,'f');                                       // Присваиваем 4 кнопке в 1 ряду символ 'f'.
}                                                                   // (по умолчанию кнопкам присвоены символы "12345678").
                                                                    //
void loop(){                                                        //
//  Выполняем действия по состояниям и событиям кнопок:             //
    if(kbd.getKey(1,1,KEY_PUSHED  )){Serial.println("открыть"   );} // Если 1 кнопка в 1 ряду нажимается,    то выводим сообщение "открыть".
    if(kbd.getKey(2,1,KEY_PUSHED  )){Serial.println("включить"  );} // Если 2 кнопка в 1 ряду нажимается,    то выводим сообщение "включить".
    if(kbd.getKey(3,1,KEY_PUSHED  )){Serial.println("начать"    );} // Если 3 кнопка в 1 ряду нажимается,    то выводим сообщение "начать".
    if(kbd.getKey('f',KEY_PUSHED  )){Serial.println("вперёд"    );} // Если 4 кнопка в 1 ряду нажимается,    то выводим сообщение "вперёд".
    if(kbd.getKey(1,2,KEY_RELEASED)){Serial.println("закрыть"   );} // Если 1 кнопка в 2 ряду отпускается,   то выводим сообщение "закрыть".
    if(kbd.getKey(2,2,KEY_CHANGED )){Serial.println("выключить" );} // Если 2 кнопка в 2 ряду нажимается или отпускается, то выводим сообщение "выключить".
    if(kbd.getKey(3,2,KEY_STATE   )){Serial.println("остановить");} // Если 3 кнопки в 2 ряда нажата,        то выводим сообщение "остановить".
    if(kbd.getKey(4,2,KEY_TRIGGER )){Serial.println("назад"     );} // Если 4 кнопка в 2 ряду переключилась, то выводим сообщение "назад".
}                                                                   //

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

Событием является момент нажатия KEY_PUSHED, отпускания KEY_RELEASED, или изменения KEY_CHANGED кнопки. События приводят к однократной реакции на них. Если два раза нажать на 1 кнопку в 1 ряду, то и в мониторе появятся две надписи "открыть", вне зависимости от того как долго эта кнопка находилась в нажатом состоянии.

Состояния кнопки могут длиться неопределённое время. Например, состояние кнопки - нажата KEY_STATE, будет продолжаться всё время пока кнопку удерживают в нажатом состоянии. Состояния приводят к многократной реакции на них. Если нажать и отпустить 3 кнопку во 2 ряду, то в мониторе появятся столько надписей "остановить", сколько успеет вывести скетч пока кнопка нажата.

Обратите внимание на то, что обращаться к кнопке можно не только по её номеру и ряду, но и по присвоенному ей символу, как это сделано в примере с 4 кнопкой 1 ряда. Если вместо номера и ряда, или символа, указать KEY_ALL, то результатом будет число состоящее из флагов состояний или событий всех кнопок клавиатуры (см. следующий пример).

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

Пример для клавиатуры, кнопки которой расположены в 2 ряда, по 4 кнопки в каждом ряду.

#include <Wire.h>                                                   // Подключаем библиотеку для работы с аппаратной шиной I2C.
#include <iarduino_I2C_Keyboard.h>                                  // Подключаем библиотеку для работы с клавиатурой I2C-flash.
iarduino_I2C_Keyboard kbd(0x09,4,2);                                // Объявляем объект kbd для работы с функциями и методами библиотеки iarduino_I2C_Keyboard, указывая адрес модуля на шине I2C, количество кнопок в линии, количество линий с кнопками.
                                                                    // Если объявить объект без указания адреса, например, kbd(false, 4, 2), то адрес будет найден автоматически.
void setup(){                                                       //
    Serial.begin(9600);                                             // Инициируем передачу данных по шине UART на скорости 9600 бит/сек.
    kbd.begin();                                                    // Инициируем работу с клавиатурой.
}                                                                   //
                                                                    //
void loop(){                                                        //
    uint16_t i;                                                     // Объявляем переменную для получения флагов.
//  Выполняем действия по изменению состояния любой клавиши:        // (для клавиатур у которых до 8 кнопок включительно, тип i можно изменить на uint8_t).
    if( kbd.getKey(KEY_ALL, KEY_CHANGED) ){                         // Если изменилось состояние хотя бы одной кнопки, то ...
    i = kbd.getKey(KEY_ALL, KEY_STATE  );                           // Получаем флаги текущего состояния кнопок.
        if (    i     ) {Serial.print("Нажаты кнопки: "     );}     // Выводим текст если установлен хотя бы 1 флаг.
        else            {Serial.print("Все кнопки отпущены.");}     // Выводим текст если все флаги сброшены.
        if (i & bit(0)) {Serial.print("1,");}                       // Если установлен 0 бит (флаг состояния 1 кнопки 1 ряда), то выводим текст.
        if (i & bit(1)) {Serial.print("2,");}                       // Если установлен 1 бит (флаг состояния 2 кнопки 1 ряда), то выводим текст.
        if (i & bit(2)) {Serial.print("3,");}                       // Если установлен 2 бит (флаг состояния 3 кнопки 1 ряда), то выводим текст.
        if (i & bit(3)) {Serial.print("4,");}                       // Если установлен 3 бит (флаг состояния 4 кнопки 1 ряда), то выводим текст.
        if (i & bit(4)) {Serial.print("5,");}                       // Если установлен 4 бит (флаг состояния 1 кнопки 2 ряда), то выводим текст.
        if (i & bit(5)) {Serial.print("6,");}                       // Если установлен 5 бит (флаг состояния 2 кнопки 2 ряда), то выводим текст.
        if (i & bit(6)) {Serial.print("7,");}                       // Если установлен 6 бит (флаг состояния 3 кнопки 2 ряда), то выводим текст.
        if (i & bit(7)) {Serial.print("8,");}                       // Если установлен 7 бит (флаг состояния 4 кнопки 2 ряда), то выводим текст.
        Serial.print("\r\n");                                       //
    }                                                               //
}                                                                   //

В данном примере используется та же функция getKey() что и в предыдущем, но обращение к функции осуществляется с указанием параметра KEY_ALL - прочитать флаги всех кнопок сразу.

Чтение состояний и событий всех кнопок одним запросом выполняется быстрее чем чтение состояний и событий каждой кнопки по отдельности (как в предыдущем примере).

Управление светодиодами клавиатуры:

Пример для клавиатуры, кнопки которой расположены в 2 ряда, по 4 кнопки в каждом ряду.

#include <Wire.h>                                                   // Подключаем библиотеку для работы с аппаратной шиной I2C.
#include <iarduino_I2C_Keyboard.h>                                  // Подключаем библиотеку для работы с клавиатурой I2C-flash.
iarduino_I2C_Keyboard kbd(0x09,4,2);                                // Объявляем объект kbd для работы с функциями и методами библиотеки iarduino_I2C_Keyboard, указывая адрес модуля на шине I2C, количество кнопок в линии, количество линий с кнопками.
                                                                    // Если объявить объект без указания адреса, например, kbd(false, 4, 2), то адрес будет найден автоматически.
void setup(){                                                       //
    kbd.begin();                                                    // Инициируем работу с клавиатурой.
    kbd.setEncoding(3,1,'s');                                       // Присваиваем 3 кнопке в 1 ряду символ 's'.
}                                                                   // (по умолчанию кнопкам присвоены символы "12345678").
                                                                    //
void loop(){                                                        //
//  Управляем светодиодами по отдельности:                          //
    kbd.setLed(1,1,true);                        delay(500);        // Включаем светодиод 1 кнопки в 1 ряду.
    kbd.setLed(2,2,true); kbd.setLed(1,1,false); delay(500);        // Включаем светодиод 2 кнопки в 2 ряду и выключаем светодиод 1 кнопки в 1 ряду.
    kbd.setLed('s',true); kbd.setLed(2,2,false); delay(500);        // Включаем светодиод 3 кнопки в 1 ряду и выключаем светодиод 2 кнопки в 2 ряду.
    kbd.setLed(4,2,true); kbd.setLed(3,1,false); delay(500);        // Включаем светодиод 4 кнопки в 2 ряду и выключаем светодиод 3 кнопки в 1 ряду.
                          kbd.setLed(4,2,false); delay(500);        //                                        выключаем светодиод 4 кнопки в 2 ряду.
//  Управляем всеми светодиодами сразу:                             //
    kbd.setLed(LED_ALL, 0b10100101);             delay(500);        // Управляем всеми светодиодами. Биты 0-3 управляют светодиодами 1-4 в 1 ряду.
    kbd.setLed(LED_ALL, 0b01011010);             delay(500);        // Управляем всеми светодиодами. Биты 4-7 управляют светодиодами 1-4 в 2 ряду.
    kbd.setLed(LED_ALL, 0b00000000);             delay(500);        // Выключаем все светодиоды.
    kbd.setLed(LED_ALL, 0b11111111);             delay(500);        // Включаем  все светодиоды.
    kbd.setLed(LED_ALL, 0b00000000);             delay(500);        // Выключаем все светодиоды.
}                                                                   //

После загрузки данного примера, на клавиатуре, последовательно включатся по одному светодиоду «змейкой». Далее светодиоды дважды включатся в шахматном порядке, после чего все светодиоды выключатся, включатся и снова выключатся.

Так как управление светодиодами написано в теле функции loop(), то описанные действия будут повторяться пока есть питание.

Обратите внимание на то, что обращаться к светодиодам можно так же как и к их кнопкам: по номеру и ряду, по присвоенному символу, или ко всем светодиодам сразу LED_ALL.

Описание функций библиотеки:

В данном разделе описаны функции библиотеки iarduino_I2C_Keyboard для работы с модулем - Клавиатура, I2C-flash.

Данная библиотека может использовать как аппаратную, так и программную реализацию шины I2C. О том как выбрать тип шины I2C рассказано в статье Wiki - расширенные возможности библиотек iarduino для шины I2C.

Подключение библиотеки:

Если адрес модуля известен (в примере используется адрес 0x09):

#include <iarduino_I2C_Keyboard.h>     // Подключаем библиотеку для работы с модулем.
iarduino_I2C_Keyboard kbd(0x09,4,2);   // Создаём объект kbd для работы с функциями и методами библиотеки iarduino_I2C_Keyboard, указывая адрес модуля на шине I2C (0x09), количество кнопок в линии (4), количество линий с кнопками (2).

Если адрес модуля неизвестен (адрес будет найден автоматически):

#include <iarduino_I2C_Keyboard.h>     // Подключаем библиотеку для работы с модулем.
iarduino_I2C_Keyboard kbd(false,4,2);  // Создаём объект kbd для работы с функциями и методами библиотеки iarduino_I2C_Keyboard, без адреса (false), но с указанием количества кнопок в линии (4), количества линий с кнопками (2).

При создании объекта без указания адреса, на шине должен находиться только один модуль.
Последние два параметра, передаваемые при объявлении объекта, определяют количество кнопок в ряду и количество рядов с кнопками на клавиатуре.
Примеры подключения библиотеки представленные выше, предназначены для клавиатуры 4x2 (по 4 кнопки в ряду, всего 2 ряда с кнопками).

Функция begin();

Назначение: Инициализация работы с модулем.
Синтаксис: begin();
Параметры: Нет.
Возвращаемое значение: bool - результат инициализации (true или false).
Примечание: По результату инициализации можно определить наличие модуля на шине.
Пример:

if( kbd.begin() ){ Serial.print( "Модуль найден и инициирован!" ); }
else             { Serial.print( "Модуль не найден на шине I2C" ); }

Функция reset();

Назначение: Перезагрузка модуля.
Синтаксис: reset();
Параметры: Нет.
Возвращаемое значение: bool - результат перезагрузки (true или false).
Пример:

if( kbd.reset() ){ Serial.print( "Модуль    перезагружен" ); }
else             { Serial.print( "Модуль не перезагружен" ); }

Функция changeAddress();

Назначение: Смена адреса модуля на шине I2C.
Синтаксис: changeAddress( АДРЕС );
Параметр:
- uint8_t АДРЕС - новый адрес модуля на шине I2C (целое число от 0x08 до 0x7E)
Возвращаемое значение: bool - результат смены адреса (true или false).
Примечание:

Адрес модуля сохраняется в энергонезависимую память, а значит будет действовать и после отключения питания.
Текущий адрес модуля можно узнать функцией getAddress().

Пример:

if( kbd.changeAddress(0x12) ){ Serial.print( "Адрес модуля изменён на 0x12" ); }
else                         { Serial.print( "Не удалось изменить адрес"    ); }

Функция getAddress();

Назначение: Запрос текущего адреса модуля на шине I2C.
Синтаксис: getAddress();
Параметры: Нет.
Возвращаемое значение: uint8_t АДРЕС - текущий адрес модуля на шине I2C (от 0x08 до 0x7E)
Примечание: Функция может понадобиться если адрес модуля не указан при создании объекта, а обнаружен библиотекой.
Пример:

Serial.print( "Адрес модуля на шине I2C = 0x" );
Serial.println( kbd.getAddress(), HEX );

Функция getVersion();

Назначение: Запрос версии прошивки модуля.
Синтаксис: getVersion();
Параметры: Нет
Возвращаемое значение: uint8_t ВЕРСИЯ - номер версии прошивки от 0 до 255.
Пример:

Serial.print( "Версия прошивки модуля " );
Serial.println( kbd.getVersion() );

Функция setPullI2C();

Назначение: Управление внутрисхемной подтяжкой линий шины I2C.
Синтаксис: setPullI2C( [ФЛАГ] );
Параметр:

bool ФЛАГ требующий установить внутрисхемную подтяжку линий шины I2C (true или false).

Возвращаемое значение:

bool - результат включения / отключения внутрисхемной подтяжки (true или false).

Примечание:

Вызов функции без параметра равносилен вызову функции с параметром true - установить.
Флаг установки внутрисхемной подтяжки сохраняется в энергонезависимую память модуля, а значит будет действовать и после отключения питания.
Внутрисхемная подтяжка линий шины I2C осуществляется до уровня 3,3 В, но допускает устанавливать внешние подтягивающие резисторы и иные модули с подтяжкой до уровня 3,3 В или 5 В, вне зависимости от состояния внутрисхемной подтяжки модуля.

Пример:

if( kbd.setPullI2C(true ) ){ Serial.print( "Внутрисхемная подтяжка установлена." ); }
if( kbd.setPullI2C(false) ){ Serial.print( "Внутрисхемная подтяжка отключена."   ); }

Функция getPullI2C();

Назначение: Запрос состояния внутрисхемной подтяжки линий шины I2C.
Синтаксис: getPullI2C();
Параметры: Нет.
Возвращаемое значение: bool - ФЛАГ включения внутрисхемной подтяжки (true или false).
Пример:

if( kbd.getPullI2C() ){ Serial.print( "Внутрисхемная подтяжка включена."  ); }
else                  { Serial.print( "Внутрисхемная подтяжка отключена." ); }

Функция available();

Назначение: Запрос количества кодов кнопок в буфере истории нажатий кнопок (FIFO).
Синтаксис: available();
Параметры: Нет.
Возвращаемое значение: uint8_t - КОЛИЧЕСТВО кодов нажатых кнопок (0-255) в буфере FIFO.
Примечание:
- Данная функция схожа по назначению с одноимённой функцией библиотеки Servo.
Пример:

Serial.print( "В буфере истории нажатых кнопок хранится " );
Serial.print( kbd.available()  );
Serial.print( " символов.\r\n" );

Функция readChar();

Назначение: Чтение одного символа из буфера истории нажатых кнопок (FIFO).
Синтаксис: readChar();
Параметры: Нет.
Возвращаемое значение: char - СИМВОЛ код кнопки которого был прочитан из буфера.
Примечание:

Данная функция схожа по назначению с функцией read() библиотеки Servo.
Функция читает из буфера код кнопки, возвращая символ ранее присвоенный этой кнопке.
Символы присваиваются кнопкам функцией setEncoding().
Если буфер истории нажатых кнопок пуст, то функция readChar() вернёт символ пробела.

Пример:

if( kbd.available() ){              // Если в буфере истории есть символы, то ...
    Serial.print( kbd.readChar() ); // Читаем 1 символ из буфера истории нажатий кнопок.
}

Функция readString();

Назначение: Чтение строки символов из буфера истории нажатых кнопок (FIFO).
Синтаксис: readString( СТРОКА, РАЗМЕР, [ФЛАГ] );
Параметры:

char* СТРОКА - получатель символов из буфера истории нажатых кнопок.
uint8_t РАЗМЕР - ограничение количества получаемых символов за раз.
bool ФЛАГ - добавления символа конца строки, после последнего прочитанного символа.

Возвращаемое значение: uint8_t - КОЛИЧЕСТВО прочитанных символов в строку получатель.
Примечание:

Если в буфере истории больше кодов кнопок, чем указано в параметре РАЗМЕР, то будет прочитано количество символов равное значению РАЗМЕР, а остальные символы можно прочитать из буфера историй позже.
Если в буфере истории меньше кодов кнопок, чем указано в параметре РАЗМЕР, то будут прочитаны все символы кнопок, коды которых находятся в буфере.
Если установлен флаг добавления символа конца строки, то значение РАЗМЕР должно быть на 1 символ меньше чем максимально допустимое число читаемых символов.
Вызов функции без флага равносилен вызову функции с установленным флагом.
Размер строки указанной в параметре СТРОКА должен быть равен или превышать значение РАЗМЕР.
Возвращаемое функцией количество прочитанных символов не включает добавление символа конца строки.

Пример:

char i[10];                   // Объявляем строку получатель символов.
if( kbd.available() ){        // Если в буфере истории есть символы, то ...
    kbd.readString(i,9,true); // Читаем до 9 символов включительно в строку i с добавлением
}                             // символа конца строки после последнего прочитанного символа.

Функция flush();

Назначение: Очистка буфера истории нажатых кнопок (FIFO).
Синтаксис: flush();
Параметры: Нет.
Возвращаемое значение: Нет.
Пример:

kbd.flush();

Функция setEncoding();

Назначение: Присвоение символа одной кнопке или символов всем кнопкам.
Синтаксис: setEncoding( НОМЕР, РЯД, СИМВОЛ );
Синтаксис: setEncoding( СТРОКА_СИМВОЛОВ );
Параметры:
- uint8_t НОМЕР - номер кнопки в ряду кнопок клавиатуры.
- uint8_t РЯД - ряд клавиатуры в котором находится кнопка.
- char СИМВОЛ - символ присваиваемый кнопке, номер и ряд которой был указан.
- char* СТРОКА_СИМВОЛОВ - строка, каждый символ которой присваивается кнопке.
Возвращаемое значение: Нет.
Примечание:
- Нажатие на любую кнопку приводит к записи кода нажатой кнопки в буфер истории нажатий кнопок. При чтении буфера, возвращаются не коды кнопок, а символы присвоенные им.
- По умолчанию кнопкам клавиатуры присвоены символы '1', '2', '3' ... '7', '8'.
- Если указан номер и ряд кнопки, то символ присваивается указанной кнопке.
- Если указана строка символов, то первый символ строки присваивается 1 кнопке 1 ряда, второй символ строки присваивается 2 кнопке 1 ряда и т.д. до последней кнопки последнего ряда.
- Допускается указывать строку символов типа String.
- Кнопкам можно присвоить только однобайтные символы, включая управляющие символы: '\r' - возврат каретки, '\n' - начало строки, '\t' - табуляция и т.д.
- Запрещается добавлять символ конца строки '\0' как часть строки символов присваиваемых кнопкам. Символ конца строки будет расценен как завершение самой строки символов, а кнопкам будут присвоены только те символы которые находятся до символа конца строки.
Пример:

kbd.setEncoding("abc\r\n\t12"); // Присваиваем символы всем кнопкам клавиатуры: 'a', 'b', 'c', '\r', '\n', '\t', '1', '2'.
kbd.setEncoding(3, 1, 'f');     // Присваиваем 3 кнопке 1 ряда символ 'f'.

Функция getEncoding();

Назначение: Получение символа присвоенного кнопке.
Синтаксис: getEncoding( НОМЕР, РЯД );
Параметры:

uint8_t НОМЕР - номер кнопки в ряду кнопок клавиатуры.
uint8_t РЯД - ряд клавиатуры в котором находится кнопка.

Возвращаемое значение: char - СИМВОЛ присвоенный кнопке.
Примечание:

Если вызвать функцию указав, вместо номера и ряда кнопки, только один параметр - символ присвоенный кнопке, то функция вернёт не символ, а порядковый номер той кнопки, которой был присвоен указанный символ.

Пример:

char i = kbd.getEncoding(4,2); // Получить символ присвоенный 4 кнопке во 2 ряду.
int  j = kbd.getEncoding('5'); // Получить порядковый номер кнопки которой присвоен символ '5'.

Функция setDelay();

Назначение: Установка времени задержки от нажатия на кнопку до принятия её удерживаемой для буфера истории нажатий кнопок.
Синтаксис: setDelay( ВРЕМЯ );
Параметр:

uint16_t ВРЕМЯ - значение от 100 до 25'500 мс.

Возвращаемое значение: Нет.
Примечание:

Откройте на компьютере текстовый редактор, нажмите и не отпускайте любую символьную клавишу Вашей компьютерной клавиатуры. Вы увидите как символ нажатой кнопки, сначала однократно появился в окне, а через несколько долей секунд начал повторно появляться заполняя окно текстового редактора. Аналогичным образом код нажатой кнопки сначала однократно попадает в буфер истории, а если кнопка не отпускается, то через некоторое время буфер истории начинает заполняться кодом удерживаемой кнопки. Это время и есть время задержки.
По умолчанию время задержки равно 500 мс = 0,5 сек.
Установленное время сохраняется в энергонезависимую память модуля, а значит будет действовать и после отключения питания.

Пример:

kbd.setDelay( 1000 ); // Начать заполнять буфер истории при удержании кнопки дольше 1000 мс.

Функция getDelay();

Назначение: Запрос времени задержки от нажатия на кнопку до принятия её удерживаемой.
Синтаксис: getDelay();
Параметры: Нет.
Возвращаемое значение: uint16_t - ВРЕМЯ задержки от 100 до 25'500 мс.
Примечание:

Время задержки от нажатия на кнопку до принятия её удерживаемой хранится в энергонезависимой памяти модуля.

Пример:

uint16_t i = kbd.getDelay(); // Получить время задержки до принятия кнопки удерживаемой.

Функция setPeriod();

Назначение: Установка периода заполнения буфера историй кодом удерживаемой кнопки.
Синтаксис: setPeriod( ПЕРИОД );
Параметр:

uint16_t ПЕРИОД - время (от 10 до 2'550 мс.) частоты заполнения буфера истории нажатых кнопок, кодом удерживаемой кнопки.

Возвращаемое значение: Нет.
Примечание:

Откройте на компьютере текстовый редактор, нажмите и не отпускайте любую символьную клавишу Вашей компьютерной клавиатуры. Вы увидите как символ нажатой кнопки, сначала однократно появился в окне, а через несколько долей секунд начал повторно появляться заполняя окно текстового редактора. Аналогичным образом код удерживаемой кнопки заполняет буфер истории. Период определяет с какой скоростью код удерживаемой кнопки попадает в буфер истории, чем меньше время периода, тем выше скорость.
По умолчанию период (время между повторными записями кода в буфер) равен 50 мс.
Установленный период сохраняется в энергонезависимую память модуля, а значит будет действовать и после отключения питания.

Пример:

kbd.setPeriod( 100 ); // Добавлять код удерживаемой кнопки в буфер истории каждые 100 мс.

Функция getPeriod();

Назначение: Запрос периода заполнения буфера историй кодом удерживаемой кнопки.
Синтаксис: getPeriod();
Параметры: Нет.
Возвращаемое значение: uint16_t - ПЕРИОД заполнения буфера кодом удерживаемой кнопки.
Примечание:

Период добавления кода удерживаемой кнопки в буфер FIFO истории хранится в энергонезависимой памяти модуля.

Пример:

uint16_t i = kbd.getPeriod(); // Получить период заполнения буфера истории нажатых кнопок.

Функция getKey();

Назначение: Запрос флага состояния, события или времени удержания кнопки.
Синтаксис: getKey( НОМЕР, РЯД, ТИП );
Синтаксис: getKey( СИМВОЛ, ТИП );
Параметры:

uint8_t НОМЕР - номер кнопки в ряду кнопок клавиатуры.
uint8_t РЯД - ряд клавиатуры в котором находится кнопка.
char СИМВОЛ - символ присвоенный кнопке.
uint8_t ТИП - тип запрошенного состояния или события кнопки, представлен 1 из значений:

KEY_PUSHED - запрос флага указывающего на то что кнопка нажималась.
KEY_RELEASED - запрос флага указывающего на то что кнопка отпускалась.
KEY_CHANGED - запрос флага указывающего что кнопка нажималась или отпускалась.
KEY_STATE - запрос флага текущего состояния кнопки (true - нажата, false - свободна).
KEY_TRIGGER - запрос флага триггера (переключателя). Флаг меняет свое состояние с каждым новым нажатием на кнопку.
KEY_HOLD_05 - запрос времени удержания кнопки в 1/2 долях секунд.

Возвращаемое значение: зависит от указанного значения ТИП.
Примечание:

Определить кнопку к которой относится запрос можно указав её НОМЕР и РЯД, или указав СИМВОЛ ранее присвоенный кнопке функцией setEncoding().
Если запрошен флаг (события или состояния), то возвращается значение true или false.
Если запрошено время удержания кнопки в 1/2 долях секунд, то возвращается значение от 0 - кнопка не удерживается до 7 - кнопка удерживается 7*1/2 секунд. Более точное время удержания кнопки можно получить обратившись к функции getTime().
Если вместо СИМВОЛА присвоенного кнопке указать значение KEY_ALL, то возвращается число состоящее из флагов запрошенных состояний или событий всех кнопок клавиатуры.

Пример:

bool     i = kbd.getKey(3,1, KEY_PUSHED );   // Узнать нажималась ли 3 кнопка в 1 ряду.
bool     j = kbd.getKey('s', KEY_PUSHED );   // Узнать нажималась ли кнопка которой был присвоен символ 's'.
bool     k = kbd.getKey(4,1, KEY_STATE  );   // Узнать нажата ли 4 кнопка в 1 ряду.
uint8_t  t = kbd.getKey(3,2, KEY_HOLD_05);   // Узнать как долго удерживается 3 кнопка во 2 ряду (время возвращается в 1/2 секунд).
uint16_t n = kbd.getKey(KEY_ALL, KEY_STATE); // Узнать нажата ли каждая кнопка клавиатуры. Значение n содержит флаги состояния каждой кнопки клавиатуры.

Функция getTime();

Назначение: Запрос времени удержания или простоя кнопки.
Синтаксис: getTime( НОМЕР, РЯД, ТИП );
Синтаксис: getTime( СИМВОЛ, ТИП );
Параметры:

uint8_t НОМЕР - номер кнопки в ряду кнопок клавиатуры.
uint8_t РЯД - ряд клавиатуры в котором находится кнопка.
char СИМВОЛ - символ присвоенный кнопке.
uint8_t ТИП - тип запрошенного времени, представлен одним из значений:

KEY_HOLD - запрошено время удержания кнопки.
KEY_FREE - запрошено время простоя кнопки.

Возвращаемое значение: uint16_t - ВРЕМЯ удержания или простоя кнопки от 100 до 25'500 мс.
Примечание:

Определить кнопку к которой относится запрос можно указав её НОМЕР и РЯД, или указав СИМВОЛ ранее присвоенный кнопке функцией setEncoding().
Если требуется получить время удержания кнопки до 3,5 секунд с точностью до 0,5 секунд, то лучше воспользоваться функцией getKey() указав тип запроса KEY_HOLD_05.

Пример:

uint16_t i = kbd.getTime(3,2, KEY_HOLD); // Узнать время удержания 3 кнопки во 2 ряду.
uint16_t j = kbd.getTime(4,2, KEY_FREE); // Узнать время простоя 4 кнопки во 2 ряду.
uint16_t k = kbd.getTime('d', KEY_FREE); // Узнать время простоя кнопки которой был присвоен символ 'd'.

Функция setLed();

Назначение: Установка состояния светодиода.
Синтаксис: setLed( НОМЕР, РЯД, ФЛАГ );
Синтаксис: setLed( СИМВОЛ, ФЛАГ );
Параметры:

uint8_t НОМЕР - номер светодиода в ряду светодиодов клавиатуры.
uint8_t РЯД - ряд клавиатуры в котором находится светодиод.
char СИМВОЛ - символ присвоенный кнопке светодиода.
uint16_t ФЛАГ - флаг устанавливаемого состояния (true - включён, false - выключен).

Возвращаемое значение: Нет.
Примечание:

Определить светодиод которому задаётся состояние можно указав его НОМЕР и РЯД, или указав СИМВОЛ ранее присвоенный кнопке светодиода функцией setEncoding().
Если вместо СИМВОЛА присвоенного кнопке светодиода указать значение LED_ALL, то можно установить состояние всех светодиодов клавиатуры, указав число биты которого являются флагами устанавливаемых состояний светодиодов.

Пример:

kbd.setLed(3,2, true ); // Включить  3 светодиод во 2 ряду.
kbd.setLed(4,2, false); // Выключить 4 светодиод во 2 ряду.
kbd.setLed('f', false); // Выключить светодиод кнопке которого был присвоен символ 'f'.
kbd.setLed(LED_ALL,0b10100101); // Включить светодиоды клавиатуры в шахматном порядке.

Функция getLed();

Назначение: Запрос состояния светодиода.
Синтаксис: getLed( НОМЕР, РЯД );
Синтаксис: getLed( СИМВОЛ );
Параметры:

uint8_t НОМЕР - номер светодиода в ряду светодиодов клавиатуры.
uint8_t РЯД - ряд клавиатуры в котором находится светодиод.
char СИМВОЛ - символ присвоенный кнопке светодиода.

Возвращаемое значение: uint16_t - ФЛАГ состояния светодиода (true - вкл, false - выкл).
Примечание:

Определить светодиод, состояние которого запрашивается, можно указав его НОМЕР и РЯД, или указав СИМВОЛ ранее присвоенный кнопке светодиода функцией setEncoding().
Если вместо СИМВОЛА присвоенного кнопке светодиода указать значение LED_ALL, то возвращаемым значение будет число, биты которого являются флагами текущих состояний всех светодиодов.

Пример:

bool     i = kbd.getLed(4,2);     // Узнать состояние 4 светодиода во 2 ряду.
bool     j = kbd.getLed('f');     // Узнать состояние светодиода кнопке которого был присвоен символ 'f'.
uint16_t f = kbd.getLed(LED_ALL); // Получить число, биты которого являются флагами состояний светодиодов.

Функция setLight();

Назначение: Установка яркости свечения светодиодов.
Синтаксис: setLight( ЯРКОСТЬ [, ГРУППА] );
Параметры:

uint8_t ЯРКОСТЬ - значение от 0 (выключены) до 7 (максимальная яркость).
uint8_t ГРУППА - определяет группу светодиодов для которой устанавливается яркость:

1 - применить яркость к 1 группе светодиодов.
2 - применить яркость ко 2 группе светодиодов.
LED_ALL - применить яркость ко всем светодиодам клавиатуры.

Возвращаемое значение: Нет.
Примечание:

Вызов функция без указания ГРУППЫ, равносилен вызову функции с указанием LED_ALL.
Функция задаёт яркость но не включает светодиоды группы (не меняет их состояние).
Для клавиатуры 4x2 светодиодами 1 группы являются все светодиоды верхней строки, а второй группы - светодиоды нижней строки.
Установленная яркость сохраняется в энергонезависимую память модуля, а значит будет действовать и после отключения питания.

Пример:

kbd.setLight(7);   // установить максимальную яркость свечения для всех светодиодов.
kbd.setLight(3,1); // установить среднюю яркость свечения для светодиодов 1 группы.

Функция getLight();

Назначение: Запрос установленной яркости свечения светодиодов.
Синтаксис: getLight( [ГРУППА] );
Параметр:

uint8_t ГРУППА - определяет группу светодиодов яркость которой запрашивается:

1 - запросить яркость установленную для 1 группы светодиодов.
2 - запросить яркость установленную для 2 группы светодиодов.

Возвращаемое значение: uint8_t ЯРКОСТЬ - значение от 0 до 7.
Примечание:

Вызов функция без указания ГРУППЫ, равносилен получению яркости 1 группы.
Для клавиатуры 4x2 светодиодами 1 группы являются все светодиоды верхней строки, а второй группы - светодиоды нижней строки.
Яркость групп светодиодов хранится в энергонезависимой памяти модуля.

Пример:

uint8_t i = kbd.getLight(1); // Получить яркость установленную для 1 группы светодиодов.
uint8_t j = kbd.getLight(2); // Получить яркость установленную для 2 группы светодиодов.

Функция setAnimation();

Назначение: Установка светодиодной анимации состояний и событий кнопок.
Синтаксис: setAnimation( НОМЕР [, ВРЕМЯ] );
Параметры:

uint8_t НОМЕР - значение от 1 до 7 определяет номер светодиодной анимации:

0 - отключить светодиодную анимацию.
1 - кратковременно включать светодиод при нажатии его кнопки.
2 - кратковременно включать светодиод при отпускании его кнопки.
3 - кратковременно включать светодиод при нажатии и отпускании его кнопки.
4 - включать светодиод пока его кнопка нажата.
5 - светодиод отражает состояние кнопки в режиме переключателя.
6 - включать светодиод если его кнопка удерживается нажатой дольше 0,5 сек.
7 - включать светодиод при каждом добавлении кода его кнопки в буфер FIFO.

uint8_t ВРЕМЯ - значение от 10 до 2'550 мс, определяет время свечения светодиодов при выполнении светодиодной анимации № 1-3.

Примечание:

Анимация выполняется на стороне клавиатуры, не задействуя ресурсы Arduino.
По умолчанию время свечения светодиодов при выполнении анимации №1-3 равно 200 мс.
В описании перечислены номера анимации для прошивки клавиатуры №4.

Возвращаемое значение: Нет.
Пример:

kbd.setAnimation(7);     // Установить светодиодную анимацию №7.
kbd.setAnimation(0);     // Отключить  светодиодную анимацию.
kbd.setAnimation(3,100); // установить светодиодную анимацию №3 с временем свечения светодиодов = 100 мс..

Функция getAnimation();

Назначение: Запрос номера установленной светодиодной анимации.
Синтаксис: getAnimation();
Параметры: Нет.
Возвращаемое значение: uint8_t НОМЕР - установленной светодиодной анимации.
Пример:

uint8_t i = kbd.getAnimation(); // Получить номер светодиодной анимации.