![Foo](https://img.shields.io/badge/ПОДПИСАТЬСЯ-НА%20ОБНОВЛЕНИЯ-brightgreen.svg?style=social&logo=telegram&color=blue)
EasyHID
Библиотека для программной реализации USB клавиатуры и мышки на некоторых МК AVR и платах на их основе
- Буквенные клавиши
- Мультимедийные клавиши
- Системные клавиши и сочетания
- Буферизация нажатий
- Движение мышки и нажатие её кнопок
Видео по библиотеке
Смотреть на YouTube
Совместимость
МК AVR с тактированием 16 МГц !!!
- ATmega328 (плата Nano, Uno, Mini)
- ATmega168/88/48/8
- ATtiny88 (плата MH-ET) работает через USB на плате!
- ATtiny167 (плата Digispark PRO) работает через USB на плате!
- ATtiny48
Важные моменты
- Библиотека конфликтует со встроенными функциями
attachInterrupt()
и detachInterrupt()
, см. пример MultimediaRemote
- Не используйте длинный (более 1 метра) USB кабель!
- Для корректной работы необходимо запитать микроконтроллер от того же USB кабеля, который используется для эмуляции USB. То есть запуск должен происходить при подключении USB кабеля к хосту
У МЕНЯ НЕ РАБОТАЕТ!
Библиотека работает очень стабильно на перечисленных выше платах, поэтому:
- Проверить подключение
- Прочитать "важные моменты" выше
- Попробовать другую Ардуину, желательно от другого продавца/изготовителя. Работа USB очень чувствительна к частоте тактирования, если на плате стоит дешевый "кварц" - может не работать
Содержание
Установка
- БИБЛИОТЕКА НЕДОСТУПНА В МЕНЕДЖЕРЕ БИБЛИОТЕК из-за структуры проекта. Если кто то сможет запустить код из папки src - кидайте пулл реквест!
- Скачать библиотеку .zip архивом для ручной установки:
- Распаковать и положить в C:\Program Files (x86)\Arduino\libraries (Windows x64)
- Распаковать и положить в C:\Program Files\Arduino\libraries (Windows x32)
- Распаковать и положить в Документы/Arduino/libraries/
- (Arduino IDE) автоматическая установка из .zip: Скетч/Подключить библиотеку/Добавить .ZIP библиотеку… и указать скачанный архив
- Читай более подробную инструкцию по установке библиотек здесь
Обновление
- Рекомендую всегда обновлять библиотеку: в новых версиях исправляются ошибки и баги, а также проводится оптимизация и добавляются новые фичи
- Через менеджер библиотек IDE: найти библиотеку как при установке и нажать "Обновить"
- Вручную: удалить папку со старой версией, а затем положить на её место новую. "Замену" делать нельзя: иногда в новых версиях удаляются файлы, которые останутся при замене и могут привести к ошибкам!
Подключение
Arduino UNO/NANO/PRO MINI (ATmega328p/168p) 16 MHz
![scheme](https://github.com/GyverLibs/EasyHID/raw/main/docs/sch1.png)
Компоненты
- Стабилитрон - любой маломощный на 3.6V
- Резистор 100 Ом - можно заменить на другой в диапазоне 47.. 200 Ом
- Резистор 1.5 кОм - можно заменить на другой в диапазоне 1.2.. 2.2 кОм
- Диод - любой обычный кремниевый (с падением 0.7V)
Пины
Порт и пин можно задать в файле usbconfig.h. Стандартные:
Использование
HID
HID.begin(); // Инициализация шины USB
HID.end(); // Отключение шины USB
HID.tick(); // Поллинг шины (вызывать не реже, чем раз в 10мс)
HID.isConnected(); // (bool) Статус шины
HID.isNumLock(); // (bool) Проверка numLock
HID.isCapsLock(); // (bool) Проверка capsLock
HID.isScrollLock(); // (bool) Проверка scrollLock
Mouse
Mouse.move(int16_t x, int16_t y); // Двигаем курсор
Mouse.click(uint8_t btn); // Кликаем на клавишу
Mouse.press(uint8_t btn); // Зажимаем клавишу
Mouse.releaseAll(); // Отпускаем все
// КОНСТАНТЫ КНОПОК
MOUSE_LEFT
MOUSE_RIGHT
MOUSE_MIDDLE
Keyboard
Keyboard.press(uint8_t key1, ... key5); // Нажатие до пяти кнопок
Keyboard.click(uint8_t key1, ... key5); // Клик до пяти кнопок
Keyboard.release(uint8_t key1, ... key5); // Отпускание до пяти кнопок
Keyboard.releaseAll(); // Отпустить все ранее нажатые
Keyboard.clickMultimediaKey(uint8_t key); // Кликнуть мультимедиа клавишу
Keyboard.clickSystemKey(uint8_t key); // Кликнуть системную клавишу
Keyboard.write(uint8_t data); // Напечатать символ
Keyboard.print(); // Напечатать любой тип данных (из Print.h)
Keyboard.println(); // Напечатать любой тип данных (из Print.h)
Константы клавиш
Обычные (press/click/release)
```cpp
KEY_1
KEY_2
KEY_3
KEY_4
KEY_5
KEY_6
KEY_7
KEY_8
KEY_9
KEY_0
KEY_A
KEY_B
KEY_C
KEY_D
KEY_E
KEY_F
KEY_G
KEY_H
KEY_I
KEY_J
KEY_K
KEY_L
KEY_M
KEY_N
KEY_O
KEY_P
KEY_Q
KEY_R
KEY_S
KEY_T
KEY_U
KEY_V
KEY_W
KEY_X
KEY_Y
KEY_Z
KEY_COMMA
KEY_PERIOD
KEY_MINUS
KEY_EQUAL
KEY_BACKSLASH
KEY_SQBRAK_LEFT
KEY_SQBRAK_RIGHT
KEY_SLASH
KEY_F1
KEY_F2
KEY_F3
KEY_F4
KEY_F5
KEY_F6
KEY_F7
KEY_F8
KEY_F9
KEY_F10
KEY_F11
KEY_F12
KEY_APP
KEY_ENTER
KEY_BACKSPACE
KEY_ESC
KEY_TAB
KEY_SPACE
KEY_INSERT
KEY_HOME
KEY_PAGE_UP
KEY_DELETE
KEY_END
KEY_PAGE_DOWN
KEY_PRINTSCREEN
KEY_ARROW_RIGHT
KEY_ARROW_LEFT
KEY_ARROW_DOWN
KEY_ARROW_UP
KEY_LEFT_CONTROL
KEY_LEFT_SHIFT
KEY_LEFT_ALT
KEY_LEFT_WIN
KEY_RIGHT_CONTROL
KEY_RIGHT_SHIFT
KEY_RIGHT_ALT
KEY_RIGHT_WIN
```
Мультимедийные (clickMultimediaKey)
```cpp
KEY_VOL_UP
KEY_VOL_DOWN
KEY_NEXT_TRACK
KEY_PREV_TRACK
KEY_STOP
KEY_PLAYPAUSE
KEY_MUTE
KEY_BASSBOOST
KEY_LOUDNESS
KEY_KB_EXECUTE
KEY_KB_HELP
KEY_KB_MENU
KEY_KB_SELECT
KEY_KB_STOP
KEY_KB_AGAIN
KEY_KB_UNDO
KEY_KB_CUT
KEY_KB_COPY
KEY_KB_PASTE
KEY_KB_FIND
```
Системные (clickSystemKey)
```cpp
KEY_POWER
KEY_SLEEP
KEY_WAKE
```
Примеры
Смотри более расширенные примеры в папке examples!
Клавиатура
#include <EasyHID.h>
void setup() {
HID.begin(); // Инициализация USB
}
void loop() {
static uint32_t timer = millis(); // Миллис - таймер (НЕ DELAY!!!)
if (millis() - timer >= 1000) { // Каждые 1000 мс
timer = millis();
Keyboard.press(KEY_1); // Зажимаем клавишу '1'
Keyboard.releaseAll(); // Отпускаем все клавиши
Keyboard.click(KEY_SPACE); // Кликаем пробел (press + releaseAll)
Keyboard.write('-'); // Выводим тире
Keyboard.println(" Hello world!"); // Печать в println
}
HID.tick(); // Вызываем тикер не реже чем каждые 10 мс!
}
Мышь
#include <EasyHID.h>
void setup() {
HID.begin(); // Инициализация USB
}
void loop() {
static uint8_t count = 0; // Направление
static uint32_t timer = millis(); // Миллис - таймер (НЕ DELAY!!!)
if (millis() - timer >= 1000) { // Каждые 1000 мс
timer = millis();
switch (count) {
case 0: Mouse.move(100, 0); break; // Двигаем мышкой на X-Y пикс.
case 1: Mouse.move(0, 100); break;
case 2: Mouse.move(-100, 0); break;
case 3: Mouse.move(0, -100); break;
}
// Mouse.click(); // Можно кликнуть ЛКМ
// Mouse.click(MOUSE_MIDDLE); // Или RIGHT, LEFT, MIDDLE
if (++count > 3) count = 0; // Циклический сдвиг от 0 до 3
}
HID.tick(); // Вызываем тикер не реже чем каждые 10 мс!
}
Версии
- v1.0
- v2.0
- Добавлена буферизация клавиш (до 5 штук одновременно нажатых)
- Добавлен release(), от одной до 5 клавиш
- Работают системные клавиши и сочетания
- Добавлена поддержка платы Digispark PRO на базе ATtiny167
- Добавлена поддержка платы MH-ET на базе ATtiny88
- Теперь если в схеме задействована активная подтяжка (см. схему) надо перед подключением либы дописать #define EASYHID_SOFT_DETACH
- Добавлен метод end(): отключает USB, корректно воспринимается компом без ошибки только при использовании схемы с активным pullup
- Добавлены более удобные константы
- v2.1 - небольшая оптимизация
- v2.2 - пофикшен баг с ATmega328
- v2.2.1 - пофикшен баг
- v2.3 - добавлена поддержка ATmega8
- v2.4 - добавлена поддержка Arduino IDE 2.0
- v2.5 - вызов метод move для мышки теперь не сбрасывает клик
- v2.6
- Убран функционал SOFT_DETACH, вводящий пользователей в заблуждение. (см. схемы)
- Добавлены новые схемы подключения
- Исправлены ошибки некорректной работы индикаторов ScrolLock, CapsLock, NumLock
- Добавлены сканкоды KEY_CAPS_LOCK, KEY_SCROLL_LOCK и KEY_NUM_LOCK
- v2.7:
- Курсор мыши теперь можно двигать на расстояние int16_t (было int8_t)
- Исправлен баг с клавишами-модификаторами при вызове метода Keyboard.release(), теперь корректно работают любые сочетания
Баги и обратная связь
При нахождении багов создавайте Issue, а лучше сразу пишите на почту alex@alexgyver.ru
Библиотека открыта для доработки и ваших Pull Request'ов!
При сообщении о багах или некорректной работе библиотеки нужно обязательно указывать:
- Версия библиотеки
- Какой используется МК
- Версия SDK (для ESP)
- Версия Arduino IDE
- Корректно ли работают ли встроенные примеры, в которых используются функции и конструкции, приводящие к багу в вашем коде
- Какой код загружался, какая работа от него ожидалась и как он работает в реальности
- В идеале приложить минимальный код, в котором наблюдается баг. Не полотно из тысячи строк, а минимальный код