diff --git a/CH341SER_2.EXE b/CH341SER_2.EXE new file mode 100644 index 0000000..fb6529c Binary files /dev/null and b/CH341SER_2.EXE differ diff --git a/CH34x_Mac_Driver_V1.6.zip b/CH34x_Mac_Driver_V1.6.zip new file mode 100644 index 0000000..34d8e96 Binary files /dev/null and b/CH34x_Mac_Driver_V1.6.zip differ diff --git a/LICENSE b/LICENSE index bef852e..d74a59c 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2022 Xinyuan-LilyGO +Copyright (c) 2021 Xinyuan-LilyGO Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 8caf3e9..ae53724 100644 --- a/README.md +++ b/README.md @@ -1 +1,37 @@ -# T-keyboard \ No newline at end of file +

🌟LILYGO T-keyboard🌟

+ +## **English | [中文](./README_CN.MD)** + + + +

Quick start:

+ +**USE Arduino IDE** + +1. Install the current upstream Arduino IDE at the 1.8 level or later. The current version is at the [Arduino website](http://www.arduino.cc/en/main/software). +2. Start Arduino and open Preferences window. In additional board manager add url: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json .separating them with commas. +3. Select Tools -> Board -> ESP32C3 Dev Module +4. If you do not have a driver installed, you need to install it (Window:ch341ser2.exe, MAC:ch34x_mac_driver_v1.6.zip [New driver reference](https://github.com/LilyGO/LILYGO-T-OI/issues/3#issuecomment-907645945 )) +5. Need to install the following dependencies + - [ESP32-BLE-Keyboard](https://github.com/T-vK/ESP32-BLE-Keyboard/tree/0.3.0) + - [T-0.99TFT](https://github.com/Xinyuan-LilyGO/T-0.99TFT) + + + +

Product 📷:

+ +| Product | Product Link | +| :--------: | :------------: | +| T-keyboard | [AliExpress]() | + +## Pinout + +![](image/) + + + + + + + + diff --git a/README_CN.MD b/README_CN.MD new file mode 100644 index 0000000..0628ee9 --- /dev/null +++ b/README_CN.MD @@ -0,0 +1,23 @@ +

🌟LILYGO T-keyboard🌟

+ +## **English | [中文](./README_CN.MD)** + + +

快速开始:

+ +1. 安装1.8以上的[Arduino IDE](http://www.arduino.cc/en/main/software). +2. 打开Arduino IDE 在文件->首选项->附加开发板管理器网站添加 https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json .最后用以逗号隔开。(由于这个网站服务器在国外，可能比较慢或者不成功。也可以参考[LilyGo-Document](https://github.com/Xinyuan-LilyGO/LilyGo-Document)来搭建) +3. 选择"工具"->开发板 -> ESP32C3 Dev Module +4. 如果没有安装驱动(Window系统:ch341ser2.exe, 苹果系统：ch34x_mac_driver_v1.6.zip) +5. 需要安装的库 + - [ESP32-BLE-Keyboard](https://github.com/T-vK/ESP32-BLE-Keyboard/tree/0.3.0) + - [T-0.99TFT](https://github.com/Xinyuan-LilyGO/T-0.99TFT) + +

Product 📷:

+ +| Product | Product Link | +| :------------: | :------------: | +| [T-keyboard]() | [AliExpress]() | + +## Pinout +![](image/) diff --git a/frimware/README.md b/frimware/README.md new file mode 100644 index 0000000..4c8d849 --- /dev/null +++ b/frimware/README.md @@ -0,0 +1,6 @@ +

🌟LILYGO T-OI-PLUS🌟

+ +[Flash Download Tool](https://www.espressif.com/en/support/download/other-tools) + +![](../image/) + diff --git a/lib/ESP32-BLE-Keyboard-0.3.0/BleKeyboard.cpp b/lib/ESP32-BLE-Keyboard-0.3.0/BleKeyboard.cpp new file mode 100644 index 0000000..8b77b98 --- /dev/null +++ b/lib/ESP32-BLE-Keyboard-0.3.0/BleKeyboard.cpp @@ -0,0 +1,507 @@ +#if defined(USE_NIMBLE) +#include +#include +#include +#include +#else +#include +#include +#include +#include "BLE2902.h" +#include "BLEHIDDevice.h" +#endif // USE_NIMBLE +#include "HIDTypes.h" +#include +#include "sdkconfig.h" + +#include "BleKeyboard.h" + +#if defined(CONFIG_ARDUHAL_ESP_LOG) + #include "esp32-hal-log.h" + #define LOG_TAG "" +#else + #include "esp_log.h" + static const char* LOG_TAG = "BLEDevice"; +#endif + + +// Report IDs: +#define KEYBOARD_ID 0x01 +#define MEDIA_KEYS_ID 0x02 + +static const uint8_t _hidReportDescriptor[] = { + USAGE_PAGE(1), 0x01, // USAGE_PAGE (Generic Desktop Ctrls) + USAGE(1), 0x06, // USAGE (Keyboard) + COLLECTION(1), 0x01, // COLLECTION (Application) + // ------------------------------------------------- Keyboard + REPORT_ID(1), KEYBOARD_ID, // REPORT_ID (1) + USAGE_PAGE(1), 0x07, // USAGE_PAGE (Kbrd/Keypad) + USAGE_MINIMUM(1), 0xE0, // USAGE_MINIMUM (0xE0) + USAGE_MAXIMUM(1), 0xE7, // USAGE_MAXIMUM (0xE7) + LOGICAL_MINIMUM(1), 0x00, // LOGICAL_MINIMUM (0) + LOGICAL_MAXIMUM(1), 0x01, // Logical Maximum (1) + REPORT_SIZE(1), 0x01, // REPORT_SIZE (1) + REPORT_COUNT(1), 0x08, // REPORT_COUNT (8) + HIDINPUT(1), 0x02, // INPUT (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position) + REPORT_COUNT(1), 0x01, // REPORT_COUNT (1) ; 1 byte (Reserved) + REPORT_SIZE(1), 0x08, // REPORT_SIZE (8) + HIDINPUT(1), 0x01, // INPUT (Const,Array,Abs,No Wrap,Linear,Preferred State,No Null Position) + REPORT_COUNT(1), 0x05, // REPORT_COUNT (5) ; 5 bits (Num lock, Caps lock, Scroll lock, Compose, Kana) + REPORT_SIZE(1), 0x01, // REPORT_SIZE (1) + USAGE_PAGE(1), 0x08, // USAGE_PAGE (LEDs) + USAGE_MINIMUM(1), 0x01, // USAGE_MINIMUM (0x01) ; Num Lock + USAGE_MAXIMUM(1), 0x05, // USAGE_MAXIMUM (0x05) ; Kana + HIDOUTPUT(1), 0x02, // OUTPUT (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile) + REPORT_COUNT(1), 0x01, // REPORT_COUNT (1) ; 3 bits (Padding) + REPORT_SIZE(1), 0x03, // REPORT_SIZE (3) + HIDOUTPUT(1), 0x01, // OUTPUT (Const,Array,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile) + REPORT_COUNT(1), 0x06, // REPORT_COUNT (6) ; 6 bytes (Keys) + REPORT_SIZE(1), 0x08, // REPORT_SIZE(8) + LOGICAL_MINIMUM(1), 0x00, // LOGICAL_MINIMUM(0) + LOGICAL_MAXIMUM(1), 0x65, // LOGICAL_MAXIMUM(0x65) ; 101 keys + USAGE_PAGE(1), 0x07, // USAGE_PAGE (Kbrd/Keypad) + USAGE_MINIMUM(1), 0x00, // USAGE_MINIMUM (0) + USAGE_MAXIMUM(1), 0x65, // USAGE_MAXIMUM (0x65) + HIDINPUT(1), 0x00, // INPUT (Data,Array,Abs,No Wrap,Linear,Preferred State,No Null Position) + END_COLLECTION(0), // END_COLLECTION + // ------------------------------------------------- Media Keys + USAGE_PAGE(1), 0x0C, // USAGE_PAGE (Consumer) + USAGE(1), 0x01, // USAGE (Consumer Control) + COLLECTION(1), 0x01, // COLLECTION (Application) + REPORT_ID(1), MEDIA_KEYS_ID, // REPORT_ID (3) + USAGE_PAGE(1), 0x0C, // USAGE_PAGE (Consumer) + LOGICAL_MINIMUM(1), 0x00, // LOGICAL_MINIMUM (0) + LOGICAL_MAXIMUM(1), 0x01, // LOGICAL_MAXIMUM (1) + REPORT_SIZE(1), 0x01, // REPORT_SIZE (1) + REPORT_COUNT(1), 0x10, // REPORT_COUNT (16) + USAGE(1), 0xB5, // USAGE (Scan Next Track) ; bit 0: 1 + USAGE(1), 0xB6, // USAGE (Scan Previous Track) ; bit 1: 2 + USAGE(1), 0xB7, // USAGE (Stop) ; bit 2: 4 + USAGE(1), 0xCD, // USAGE (Play/Pause) ; bit 3: 8 + USAGE(1), 0xE2, // USAGE (Mute) ; bit 4: 16 + USAGE(1), 0xE9, // USAGE (Volume Increment) ; bit 5: 32 + USAGE(1), 0xEA, // USAGE (Volume Decrement) ; bit 6: 64 + USAGE(2), 0x23, 0x02, // Usage (WWW Home) ; bit 7: 128 + USAGE(2), 0x94, 0x01, // Usage (My Computer) ; bit 0: 1 + USAGE(2), 0x92, 0x01, // Usage (Calculator) ; bit 1: 2 + USAGE(2), 0x2A, 0x02, // Usage (WWW fav) ; bit 2: 4 + USAGE(2), 0x21, 0x02, // Usage (WWW search) ; bit 3: 8 + USAGE(2), 0x26, 0x02, // Usage (WWW stop) ; bit 4: 16 + USAGE(2), 0x24, 0x02, // Usage (WWW back) ; bit 5: 32 + USAGE(2), 0x83, 0x01, // Usage (Media sel) ; bit 6: 64 + USAGE(2), 0x8A, 0x01, // Usage (Mail) ; bit 7: 128 + HIDINPUT(1), 0x02, // INPUT (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position) + END_COLLECTION(0) // END_COLLECTION +}; + +BleKeyboard::BleKeyboard(std::string deviceName, std::string deviceManufacturer, uint8_t batteryLevel) + : hid(0) + , deviceName(std::string(deviceName).substr(0, 15)) + , deviceManufacturer(std::string(deviceManufacturer).substr(0,15)) + , batteryLevel(batteryLevel) {} + +void BleKeyboard::begin(void) +{ + BLEDevice::init(deviceName); + BLEServer* pServer = BLEDevice::createServer(); + pServer->setCallbacks(this); + + hid = new BLEHIDDevice(pServer); + inputKeyboard = hid->inputReport(KEYBOARD_ID); // <-- input REPORTID from report map + outputKeyboard = hid->outputReport(KEYBOARD_ID); + inputMediaKeys = hid->inputReport(MEDIA_KEYS_ID); + + outputKeyboard->setCallbacks(this); + + hid->manufacturer()->setValue(deviceManufacturer); + + hid->pnp(0x02, 0xe502, 0xa111, 0x0210); + hid->hidInfo(0x00, 0x01); + + BLESecurity* pSecurity = new BLESecurity(); + + pSecurity->setAuthenticationMode(ESP_LE_AUTH_BOND); + + hid->reportMap((uint8_t*)_hidReportDescriptor, sizeof(_hidReportDescriptor)); + hid->startServices(); + + onStarted(pServer); + + advertising = pServer->getAdvertising(); + advertising->setAppearance(HID_KEYBOARD); + advertising->addServiceUUID(hid->hidService()->getUUID()); + advertising->setScanResponse(false); + advertising->start(); + hid->setBatteryLevel(batteryLevel); + + ESP_LOGD(LOG_TAG, "Advertising started!"); +} + +void BleKeyboard::end(void) +{ +} + +bool BleKeyboard::isConnected(void) { + return this->connected; +} + +void BleKeyboard::setBatteryLevel(uint8_t level) { + this->batteryLevel = level; + if (hid != 0) + this->hid->setBatteryLevel(this->batteryLevel); +} + +//must be called before begin in order to set the name +void BleKeyboard::setName(std::string deviceName) { + this->deviceName = deviceName; +} + +/** + * @brief Sets the waiting time (in milliseconds) between multiple keystrokes in NimBLE mode. + * + * @param ms Time in milliseconds + */ +void BleKeyboard::setDelay(uint32_t ms) { + this->_delay_ms = ms; +} + +void BleKeyboard::sendReport(KeyReport* keys) +{ + if (this->isConnected()) + { + this->inputKeyboard->setValue((uint8_t*)keys, sizeof(KeyReport)); + this->inputKeyboard->notify(); +#if defined(USE_NIMBLE) + // vTaskDelay(delayTicks); + this->delay_ms(_delay_ms); +#endif // USE_NIMBLE + } +} + +void BleKeyboard::sendReport(MediaKeyReport* keys) +{ + if (this->isConnected()) + { + this->inputMediaKeys->setValue((uint8_t*)keys, sizeof(MediaKeyReport)); + this->inputMediaKeys->notify(); +#if defined(USE_NIMBLE) + //vTaskDelay(delayTicks); + this->delay_ms(_delay_ms); +#endif // USE_NIMBLE + } +} + +extern +const uint8_t _asciimap[128] PROGMEM; + +#define SHIFT 0x80 +const uint8_t _asciimap[128] = +{ + 0x00, // NUL + 0x00, // SOH + 0x00, // STX + 0x00, // ETX + 0x00, // EOT + 0x00, // ENQ + 0x00, // ACK + 0x00, // BEL + 0x2a, // BS Backspace + 0x2b, // TAB Tab + 0x28, // LF Enter + 0x00, // VT + 0x00, // FF + 0x00, // CR + 0x00, // SO + 0x00, // SI + 0x00, // DEL + 0x00, // DC1 + 0x00, // DC2 + 0x00, // DC3 + 0x00, // DC4 + 0x00, // NAK + 0x00, // SYN + 0x00, // ETB + 0x00, // CAN + 0x00, // EM + 0x00, // SUB + 0x00, // ESC + 0x00, // FS + 0x00, // GS + 0x00, // RS + 0x00, // US + + 0x2c, // ' ' + 0x1e|SHIFT, // ! + 0x34|SHIFT, // " + 0x20|SHIFT, // # + 0x21|SHIFT, // $ + 0x22|SHIFT, // % + 0x24|SHIFT, // & + 0x34, // ' + 0x26|SHIFT, // ( + 0x27|SHIFT, // ) + 0x25|SHIFT, // * + 0x2e|SHIFT, // + + 0x36, // , + 0x2d, // - + 0x37, // . + 0x38, // / + 0x27, // 0 + 0x1e, // 1 + 0x1f, // 2 + 0x20, // 3 + 0x21, // 4 + 0x22, // 5 + 0x23, // 6 + 0x24, // 7 + 0x25, // 8 + 0x26, // 9 + 0x33|SHIFT, // : + 0x33, // ; + 0x36|SHIFT, // < + 0x2e, // = + 0x37|SHIFT, // > + 0x38|SHIFT, // ? + 0x1f|SHIFT, // @ + 0x04|SHIFT, // A + 0x05|SHIFT, // B + 0x06|SHIFT, // C + 0x07|SHIFT, // D + 0x08|SHIFT, // E + 0x09|SHIFT, // F + 0x0a|SHIFT, // G + 0x0b|SHIFT, // H + 0x0c|SHIFT, // I + 0x0d|SHIFT, // J + 0x0e|SHIFT, // K + 0x0f|SHIFT, // L + 0x10|SHIFT, // M + 0x11|SHIFT, // N + 0x12|SHIFT, // O + 0x13|SHIFT, // P + 0x14|SHIFT, // Q + 0x15|SHIFT, // R + 0x16|SHIFT, // S + 0x17|SHIFT, // T + 0x18|SHIFT, // U + 0x19|SHIFT, // V + 0x1a|SHIFT, // W + 0x1b|SHIFT, // X + 0x1c|SHIFT, // Y + 0x1d|SHIFT, // Z + 0x2f, // [ + 0x31, // bslash + 0x30, // ] + 0x23|SHIFT, // ^ + 0x2d|SHIFT, // _ + 0x35, // ` + 0x04, // a + 0x05, // b + 0x06, // c + 0x07, // d + 0x08, // e + 0x09, // f + 0x0a, // g + 0x0b, // h + 0x0c, // i + 0x0d, // j + 0x0e, // k + 0x0f, // l + 0x10, // m + 0x11, // n + 0x12, // o + 0x13, // p + 0x14, // q + 0x15, // r + 0x16, // s + 0x17, // t + 0x18, // u + 0x19, // v + 0x1a, // w + 0x1b, // x + 0x1c, // y + 0x1d, // z + 0x2f|SHIFT, // { + 0x31|SHIFT, // | + 0x30|SHIFT, // } + 0x35|SHIFT, // ~ + 0 // DEL +}; + + +uint8_t USBPutChar(uint8_t c); + +// press() adds the specified key (printing, non-printing, or modifier) +// to the persistent key report and sends the report. Because of the way +// USB HID works, the host acts like the key remains pressed until we +// call release(), releaseAll(), or otherwise clear the report and resend. +size_t BleKeyboard::press(uint8_t k) +{ + uint8_t i; + if (k >= 136) { // it's a non-printing key (not a modifier) + k = k - 136; + } else if (k >= 128) { // it's a modifier key + _keyReport.modifiers |= (1<<(k-128)); + k = 0; + } else { // it's a printing key + k = pgm_read_byte(_asciimap + k); + if (!k) { + setWriteError(); + return 0; + } + if (k & 0x80) { // it's a capital letter or other character reached with shift + _keyReport.modifiers |= 0x02; // the left shift modifier + k &= 0x7F; + } + } + + // Add k to the key report only if it's not already present + // and if there is an empty slot. + if (_keyReport.keys[0] != k && _keyReport.keys[1] != k && + _keyReport.keys[2] != k && _keyReport.keys[3] != k && + _keyReport.keys[4] != k && _keyReport.keys[5] != k) { + + for (i=0; i<6; i++) { + if (_keyReport.keys[i] == 0x00) { + _keyReport.keys[i] = k; + break; + } + } + if (i == 6) { + setWriteError(); + return 0; + } + } + sendReport(&_keyReport); + return 1; +} + +size_t BleKeyboard::press(const MediaKeyReport k) +{ + uint16_t k_16 = k[1] | (k[0] << 8); + uint16_t mediaKeyReport_16 = _mediaKeyReport[1] | (_mediaKeyReport[0] << 8); + + mediaKeyReport_16 |= k_16; + _mediaKeyReport[0] = (uint8_t)((mediaKeyReport_16 & 0xFF00) >> 8); + _mediaKeyReport[1] = (uint8_t)(mediaKeyReport_16 & 0x00FF); + + sendReport(&_mediaKeyReport); + return 1; +} + +// release() takes the specified key out of the persistent key report and +// sends the report. This tells the OS the key is no longer pressed and that +// it shouldn't be repeated any more. +size_t BleKeyboard::release(uint8_t k) +{ + uint8_t i; + if (k >= 136) { // it's a non-printing key (not a modifier) + k = k - 136; + } else if (k >= 128) { // it's a modifier key + _keyReport.modifiers &= ~(1<<(k-128)); + k = 0; + } else { // it's a printing key + k = pgm_read_byte(_asciimap + k); + if (!k) { + return 0; + } + if (k & 0x80) { // it's a capital letter or other character reached with shift + _keyReport.modifiers &= ~(0x02); // the left shift modifier + k &= 0x7F; + } + } + + // Test the key report to see if k is present. Clear it if it exists. + // Check all positions in case the key is present more than once (which it shouldn't be) + for (i=0; i<6; i++) { + if (0 != k && _keyReport.keys[i] == k) { + _keyReport.keys[i] = 0x00; + } + } + + sendReport(&_keyReport); + return 1; +} + +size_t BleKeyboard::release(const MediaKeyReport k) +{ + uint16_t k_16 = k[1] | (k[0] << 8); + uint16_t mediaKeyReport_16 = _mediaKeyReport[1] | (_mediaKeyReport[0] << 8); + mediaKeyReport_16 &= ~k_16; + _mediaKeyReport[0] = (uint8_t)((mediaKeyReport_16 & 0xFF00) >> 8); + _mediaKeyReport[1] = (uint8_t)(mediaKeyReport_16 & 0x00FF); + + sendReport(&_mediaKeyReport); + return 1; +} + +void BleKeyboard::releaseAll(void) +{ + _keyReport.keys[0] = 0; + _keyReport.keys[1] = 0; + _keyReport.keys[2] = 0; + _keyReport.keys[3] = 0; + _keyReport.keys[4] = 0; + _keyReport.keys[5] = 0; + _keyReport.modifiers = 0; + _mediaKeyReport[0] = 0; + _mediaKeyReport[1] = 0; + sendReport(&_keyReport); +} + +size_t BleKeyboard::write(uint8_t c) +{ + uint8_t p = press(c); // Keydown + release(c); // Keyup + return p; // just return the result of press() since release() almost always returns 1 +} + +size_t BleKeyboard::write(const MediaKeyReport c) +{ + uint16_t p = press(c); // Keydown + release(c); // Keyup + return p; // just return the result of press() since release() almost always returns 1 +} + +size_t BleKeyboard::write(const uint8_t *buffer, size_t size) { + size_t n = 0; + while (size--) { + if (*buffer != '\r') { + if (write(*buffer)) { + n++; + } else { + break; + } + } + buffer++; + } + return n; +} + +void BleKeyboard::onConnect(BLEServer* pServer) { + this->connected = true; +} + +void BleKeyboard::onDisconnect(BLEServer* pServer) { + this->connected = false; +#if !defined(USE_NIMBLE) + advertising->start(); +#endif // !USE_NIMBLE +} + +void BleKeyboard::onWrite(BLECharacteristic* me) { + uint8_t* value = (uint8_t*)(me->getValue().c_str()); + (void)value; + ESP_LOGI(LOG_TAG, "special keys: %d", *value); +} + +void BleKeyboard::delay_ms(uint64_t ms) { + uint64_t m = esp_timer_get_time(); + if(ms){ + uint64_t e = (m + (ms * 1000)); + if(m > e){ //overflow + while(esp_timer_get_time() > e) { } + } + while(esp_timer_get_time() < e) {} + } +} \ No newline at end of file diff --git a/lib/ESP32-BLE-Keyboard-0.3.0/BleKeyboard.h b/lib/ESP32-BLE-Keyboard-0.3.0/BleKeyboard.h new file mode 100644 index 0000000..4fdeaa5 --- /dev/null +++ b/lib/ESP32-BLE-Keyboard-0.3.0/BleKeyboard.h @@ -0,0 +1,150 @@ +#ifndef ESP32_BLE_KEYBOARD_H +#define ESP32_BLE_KEYBOARD_H +#include "sdkconfig.h" +#if defined(CONFIG_BT_ENABLED) + +#if defined(USE_NIMBLE) + +#include "NimBLECharacteristic.h" +#include "NimBLEHIDDevice.h" + +#define BLEDevice NimBLEDevice +#define BLEServerCallbacks NimBLEServerCallbacks +#define BLECharacteristicCallbacks NimBLECharacteristicCallbacks +#define BLEHIDDevice NimBLEHIDDevice +#define BLECharacteristic NimBLECharacteristic +#define BLEAdvertising NimBLEAdvertising +#define BLEServer NimBLEServer + +#else + +#include "BLEHIDDevice.h" +#include "BLECharacteristic.h" + +#endif // USE_NIMBLE + +#include "Print.h" + + +const uint8_t KEY_LEFT_CTRL = 0x80; +const uint8_t KEY_LEFT_SHIFT = 0x81; +const uint8_t KEY_LEFT_ALT = 0x82; +const uint8_t KEY_LEFT_GUI = 0x83; +const uint8_t KEY_RIGHT_CTRL = 0x84; +const uint8_t KEY_RIGHT_SHIFT = 0x85; +const uint8_t KEY_RIGHT_ALT = 0x86; +const uint8_t KEY_RIGHT_GUI = 0x87; + +const uint8_t KEY_UP_ARROW = 0xDA; +const uint8_t KEY_DOWN_ARROW = 0xD9; +const uint8_t KEY_LEFT_ARROW = 0xD8; +const uint8_t KEY_RIGHT_ARROW = 0xD7; +const uint8_t KEY_BACKSPACE = 0xB2; +const uint8_t KEY_TAB = 0xB3; +const uint8_t KEY_RETURN = 0xB0; +const uint8_t KEY_ESC = 0xB1; +const uint8_t KEY_INSERT = 0xD1; +const uint8_t KEY_DELETE = 0xD4; +const uint8_t KEY_PAGE_UP = 0xD3; +const uint8_t KEY_PAGE_DOWN = 0xD6; +const uint8_t KEY_HOME = 0xD2; +const uint8_t KEY_END = 0xD5; +const uint8_t KEY_CAPS_LOCK = 0xC1; +const uint8_t KEY_F1 = 0xC2; +const uint8_t KEY_F2 = 0xC3; +const uint8_t KEY_F3 = 0xC4; +const uint8_t KEY_F4 = 0xC5; +const uint8_t KEY_F5 = 0xC6; +const uint8_t KEY_F6 = 0xC7; +const uint8_t KEY_F7 = 0xC8; +const uint8_t KEY_F8 = 0xC9; +const uint8_t KEY_F9 = 0xCA; +const uint8_t KEY_F10 = 0xCB; +const uint8_t KEY_F11 = 0xCC; +const uint8_t KEY_F12 = 0xCD; +const uint8_t KEY_F13 = 0xF0; +const uint8_t KEY_F14 = 0xF1; +const uint8_t KEY_F15 = 0xF2; +const uint8_t KEY_F16 = 0xF3; +const uint8_t KEY_F17 = 0xF4; +const uint8_t KEY_F18 = 0xF5; +const uint8_t KEY_F19 = 0xF6; +const uint8_t KEY_F20 = 0xF7; +const uint8_t KEY_F21 = 0xF8; +const uint8_t KEY_F22 = 0xF9; +const uint8_t KEY_F23 = 0xFA; +const uint8_t KEY_F24 = 0xFB; + +typedef uint8_t MediaKeyReport[2]; + +const MediaKeyReport KEY_MEDIA_NEXT_TRACK = {1, 0}; +const MediaKeyReport KEY_MEDIA_PREVIOUS_TRACK = {2, 0}; +const MediaKeyReport KEY_MEDIA_STOP = {4, 0}; +const MediaKeyReport KEY_MEDIA_PLAY_PAUSE = {8, 0}; +const MediaKeyReport KEY_MEDIA_MUTE = {16, 0}; +const MediaKeyReport KEY_MEDIA_VOLUME_UP = {32, 0}; +const MediaKeyReport KEY_MEDIA_VOLUME_DOWN = {64, 0}; +const MediaKeyReport KEY_MEDIA_WWW_HOME = {128, 0}; +const MediaKeyReport KEY_MEDIA_LOCAL_MACHINE_BROWSER = {0, 1}; // Opens "My Computer" on Windows +const MediaKeyReport KEY_MEDIA_CALCULATOR = {0, 2}; +const MediaKeyReport KEY_MEDIA_WWW_BOOKMARKS = {0, 4}; +const MediaKeyReport KEY_MEDIA_WWW_SEARCH = {0, 8}; +const MediaKeyReport KEY_MEDIA_WWW_STOP = {0, 16}; +const MediaKeyReport KEY_MEDIA_WWW_BACK = {0, 32}; +const MediaKeyReport KEY_MEDIA_CONSUMER_CONTROL_CONFIGURATION = {0, 64}; // Media Selection +const MediaKeyReport KEY_MEDIA_EMAIL_READER = {0, 128}; + + +// Low level key report: up to 6 keys and shift, ctrl etc at once +typedef struct +{ + uint8_t modifiers; + uint8_t reserved; + uint8_t keys[6]; +} KeyReport; + +class BleKeyboard : public Print, public BLEServerCallbacks, public BLECharacteristicCallbacks +{ +private: + BLEHIDDevice* hid; + BLECharacteristic* inputKeyboard; + BLECharacteristic* outputKeyboard; + BLECharacteristic* inputMediaKeys; + BLEAdvertising* advertising; + KeyReport _keyReport; + MediaKeyReport _mediaKeyReport; + std::string deviceName; + std::string deviceManufacturer; + uint8_t batteryLevel; + bool connected = false; + uint32_t _delay_ms = 7; + void delay_ms(uint64_t ms); + +public: + BleKeyboard(std::string deviceName = "ESP32 Keyboard", std::string deviceManufacturer = "Espressif", uint8_t batteryLevel = 100); + void begin(void); + void end(void); + void sendReport(KeyReport* keys); + void sendReport(MediaKeyReport* keys); + size_t press(uint8_t k); + size_t press(const MediaKeyReport k); + size_t release(uint8_t k); + size_t release(const MediaKeyReport k); + size_t write(uint8_t c); + size_t write(const MediaKeyReport c); + size_t write(const uint8_t *buffer, size_t size); + void releaseAll(void); + bool isConnected(void); + void setBatteryLevel(uint8_t level); + void setName(std::string deviceName); + void setDelay(uint32_t ms); +protected: + virtual void onStarted(BLEServer *pServer) { }; + virtual void onConnect(BLEServer* pServer) override; + virtual void onDisconnect(BLEServer* pServer) override; + virtual void onWrite(BLECharacteristic* me) override; + +}; + +#endif // CONFIG_BT_ENABLED +#endif // ESP32_BLE_KEYBOARD_H diff --git a/lib/ESP32-BLE-Keyboard-0.3.0/README.md b/lib/ESP32-BLE-Keyboard-0.3.0/README.md new file mode 100644 index 0000000..623a126 --- /dev/null +++ b/lib/ESP32-BLE-Keyboard-0.3.0/README.md @@ -0,0 +1,156 @@ +# ESP32 BLE Keyboard library + +This library allows you to make the ESP32 act as a Bluetooth Keyboard and control what it does. +You might also be interested in: +- [ESP32-BLE-Mouse](https://github.com/T-vK/ESP32-BLE-Mouse) +- [ESP32-BLE-Gamepad](https://github.com/lemmingDev/ESP32-BLE-Gamepad) + + +## Features + + - [x] Send key strokes + - [x] Send text + - [x] Press/release individual keys + - [x] Media keys are supported + - [ ] Read Numlock/Capslock/Scrolllock state + - [x] Set battery level (basically works, but doesn't show up in Android's status bar) + - [x] Compatible with Android + - [x] Compatible with Windows + - [x] Compatible with Linux + - [x] Compatible with MacOS X (not stable, some people have issues, doesn't work with old devices) + - [x] Compatible with iOS (not stable, some people have issues, doesn't work with old devices) + +## Installation +- (Make sure you can use the ESP32 with the Arduino IDE. [Instructions can be found here.](https://github.com/espressif/arduino-esp32#installation-instructions)) +- [Download the latest release of this library from the release page.](https://github.com/T-vK/ESP32-BLE-Keyboard/releases) +- In the Arduino IDE go to "Sketch" -> "Include Library" -> "Add .ZIP Library..." and select the file you just downloaded. +- You can now go to "File" -> "Examples" -> "ESP32 BLE Keyboard" and select any of the examples to get started. + +## Example + +``` C++ +/** + * This example turns the ESP32 into a Bluetooth LE keyboard that writes the words, presses Enter, presses a media key and then Ctrl+Alt+Delete + */ +#include + +BleKeyboard bleKeyboard; + +void setup() { + Serial.begin(115200); + Serial.println("Starting BLE work!"); + bleKeyboard.begin(); +} + +void loop() { + if(bleKeyboard.isConnected()) { + Serial.println("Sending 'Hello world'..."); + bleKeyboard.print("Hello world"); + + delay(1000); + + Serial.println("Sending Enter key..."); + bleKeyboard.write(KEY_RETURN); + + delay(1000); + + Serial.println("Sending Play/Pause media key..."); + bleKeyboard.write(KEY_MEDIA_PLAY_PAUSE); + + delay(1000); + + Serial.println("Sending Ctrl+Alt+Delete..."); + bleKeyboard.press(KEY_LEFT_CTRL); + bleKeyboard.press(KEY_LEFT_ALT); + bleKeyboard.press(KEY_DELETE); + delay(100); + bleKeyboard.releaseAll(); + + } + Serial.println("Waiting 5 seconds..."); + delay(5000); +} +``` + +## API docs +The BleKeyboard interface is almost identical to the Keyboard Interface, so you can use documentation right here: +https://www.arduino.cc/reference/en/language/functions/usb/keyboard/ + +Just remember that you have to use `bleKeyboard` instead of just `Keyboard` and you need these two lines at the top of your script: +``` +#include +BleKeyboard bleKeyboard; +``` + +In addition to that you can send media keys (which is not possible with the USB keyboard library). Supported are the following: +- KEY_MEDIA_NEXT_TRACK +- KEY_MEDIA_PREVIOUS_TRACK +- KEY_MEDIA_STOP +- KEY_MEDIA_PLAY_PAUSE +- KEY_MEDIA_MUTE +- KEY_MEDIA_VOLUME_UP +- KEY_MEDIA_VOLUME_DOWN +- KEY_MEDIA_WWW_HOME +- KEY_MEDIA_LOCAL_MACHINE_BROWSER // Opens "My Computer" on Windows +- KEY_MEDIA_CALCULATOR +- KEY_MEDIA_WWW_BOOKMARKS +- KEY_MEDIA_WWW_SEARCH +- KEY_MEDIA_WWW_STOP +- KEY_MEDIA_WWW_BACK +- KEY_MEDIA_CONSUMER_CONTROL_CONFIGURATION // Media Selection +- KEY_MEDIA_EMAIL_READER + +There is also Bluetooth specific information that you can set (optional): +Instead of `BleKeyboard bleKeyboard;` you can do `BleKeyboard bleKeyboard("Bluetooth Device Name", "Bluetooth Device Manufacturer", 100);`. (Max lenght is 15 characters, anything beyond that will be truncated.) +The third parameter is the initial battery level of your device. To adjust the battery level later on you can simply call e.g. `bleKeyboard.setBatteryLevel(50)` (set battery level to 50%). +By default the battery level will be set to 100%, the device name will be `ESP32 Bluetooth Keyboard` and the manufacturer will be `Espressif`. +There is also a `setDelay` method to set a delay between each key event. E.g. `bleKeyboard.setDelay(10)` (10 milliseconds). The default is `8`. +This feature is meant to compensate for some applications and devices that can't handle fast input and will skip letters if too many keys are sent in a small time frame. + +## NimBLE-Mode +The NimBLE mode enables a significant saving of RAM and FLASH memory. + +### Comparison (SendKeyStrokes.ino at compile-time) + +**Standard** +``` +RAM: [= ] 9.3% (used 30548 bytes from 327680 bytes) +Flash: [======== ] 75.8% (used 994120 bytes from 1310720 bytes) +``` + +**NimBLE mode** +``` +RAM: [= ] 8.3% (used 27180 bytes from 327680 bytes) +Flash: [==== ] 44.2% (used 579158 bytes from 1310720 bytes) +``` + +### Comparison (SendKeyStrokes.ino at run-time) + +| | Standard | NimBLE mode | difference +|---|--:|--:|--:| +| `ESP.getHeapSize()` | 296.804 | 321.252 | **+ 24.448** | +| `ESP.getFreeHeap()` | 143.572 | 260.764 | **+ 117.192** | +| `ESP.getSketchSize()` | 994.224 | 579.264 | **- 414.960** | + +### How to activate NimBLE mode? + +ArduinoIDE: Before including the library, insert the line `#define USE_NIMBLE` +```C++ +#define USE_NIMBLE +#include +``` + +PlatformIO: Change your `platformio.ini` to the following settings +```ini +lib_deps = + NimBLE-Arduino + +build-flags = + -D USE_NIMBLE +``` + +## Credits + +Credits to [chegewara](https://github.com/chegewara) and [the authors of the USB keyboard library](https://github.com/arduino-libraries/Keyboard/) as this project is heavily based on their work! +Also, credits to [duke2421](https://github.com/T-vK/ESP32-BLE-Keyboard/issues/1) who helped a lot with testing, debugging and fixing the device descriptor! +And credits to [sivar2311](https://github.com/sivar2311) for adding NimBLE support, greatly reducing the memory footprint, fixing advertising issues and for adding the `setDelay` method. diff --git a/lib/ESP32-BLE-Keyboard-0.3.0/examples/SendKeyStrokes/SendKeyStrokes.ino b/lib/ESP32-BLE-Keyboard-0.3.0/examples/SendKeyStrokes/SendKeyStrokes.ino new file mode 100644 index 0000000..0b35b00 --- /dev/null +++ b/lib/ESP32-BLE-Keyboard-0.3.0/examples/SendKeyStrokes/SendKeyStrokes.ino @@ -0,0 +1,41 @@ +/** + * This example turns the ESP32 into a Bluetooth LE keyboard that writes the words, presses Enter, presses a media key and then Ctrl+Alt+Delete + */ +#include + +BleKeyboard bleKeyboard; + +void setup() { + Serial.begin(115200); + Serial.println("Starting BLE work!"); + bleKeyboard.begin(); +} + +void loop() { + if(bleKeyboard.isConnected()) { + Serial.println("Sending 'Hello world'..."); + bleKeyboard.print("Hello world"); + + delay(1000); + + Serial.println("Sending Enter key..."); + bleKeyboard.write(KEY_RETURN); + + delay(1000); + + Serial.println("Sending Play/Pause media key..."); + bleKeyboard.write(KEY_MEDIA_PLAY_PAUSE); + + delay(1000); + + Serial.println("Sending Ctrl+Alt+Delete..."); + bleKeyboard.press(KEY_LEFT_CTRL); + bleKeyboard.press(KEY_LEFT_ALT); + bleKeyboard.press(KEY_DELETE); + delay(100); + bleKeyboard.releaseAll(); + } + + Serial.println("Waiting 5 seconds..."); + delay(5000); +} diff --git a/lib/ESP32-BLE-Keyboard-0.3.0/keywords.txt b/lib/ESP32-BLE-Keyboard-0.3.0/keywords.txt new file mode 100644 index 0000000..0aa35b7 --- /dev/null +++ b/lib/ESP32-BLE-Keyboard-0.3.0/keywords.txt @@ -0,0 +1,24 @@ +####################################### +# Syntax Coloring Map For ESP32 BLE Keyboard +####################################### +# Class +####################################### + +BleKeyboard KEYWORD1 + +####################################### +# Methods and Functions +####################################### + +begin KEYWORD2 +end KEYWORD2 +write KEYWORD2 +press KEYWORD2 +release KEYWORD2 +releaseAll KEYWORD2 +setBatteryLevel KEYWORD2 +isConnected KEYWORD2 + +####################################### +# Constants +####################################### diff --git a/lib/ESP32-BLE-Keyboard-0.3.0/library.properties b/lib/ESP32-BLE-Keyboard-0.3.0/library.properties new file mode 100644 index 0000000..49e8b57 --- /dev/null +++ b/lib/ESP32-BLE-Keyboard-0.3.0/library.properties @@ -0,0 +1,9 @@ +name=ESP32 BLE Keyboard +version=0.3.0 +author=T-vK +maintainer=T-vK +sentence=Bluetooth LE Keyboard library for the ESP32. +paragraph=Bluetooth LE Keyboard library for the ESP32. +category=Communication +url=https://github.com/T-vK/ESP32-BLE-Keyboard +architectures=esp32