Document incorporation of KeyboardioHID as a driver in NEWS.md

Signed-off-by: Michael Richters <gedankenexperimenter@gmail.com>

bin/iwyu.py

@@ -232,10 +232,6 @@ def main():
     virtual_model01_dir = os.path.join(virtual_hardware_dir, 'variants', 'model01')
     logging.debug("Using virtual Model01 dir: %s", virtual_model01_dir)
 
-    virtual_keyboardiohid_dir = os.path.join(
-        virtual_hardware_dir, 'libraries', 'KeyboardioHID', 'src')
-    logging.debug("Using virtual KeyboardioHID dir: %s", virtual_keyboardiohid_dir)
-
     # ----------------------------------------------------------------------
     # Create the long list of options passed to `clang` via `include-what-you-use`.
     # First, we tell it we're using C++:
@@ -283,7 +279,6 @@ def main():
         kaleidoscope_src_dir,
         virtual_arduino_core_dir,
         virtual_model01_dir,
-        virtual_keyboardiohid_dir,
     ]
     # Include plugin source dirs for plugins that depend on other plugins:
     includes += glob.glob(os.path.join(kaleidoscope_dir, 'plugins', '*', 'src'))

docs/NEWS.md

@@ -12,6 +12,16 @@ See [UPGRADING.md](UPGRADING.md) for more detailed instructions about upgrading
 
 ## New features
 
+### KeyboardioHID converted to a driver
+
+The KeyboardioHID library used by most Kaleidoscope keyboards as the interface
+is no longer a separate Arduino library in a separate repository.  It has been
+incorporated into the main Kaleidoscope repository as a driver, but is
+functionally unchanged.  This will make it easier for developers to synchronize
+changes at different levels in the codebase.  No new features were introduced,
+and this should not directly affect end users, but it is a major reorganization
+of the codebase.
+
 ### OneShot public functions
 
 The OneShot plugin now allows other plugins to control the OneShot state of

plugins/Kaleidoscope-AutoShift/src/kaleidoscope/plugin/AutoShift.cpp

@@ -21,7 +21,7 @@
 #include "kaleidoscope/KeyEvent.h"         // for KeyEvent
 #include "kaleidoscope/KeyEventTracker.h"  // for KeyEventTracker
 #include "kaleidoscope/Runtime.h"          // for Runtime, Runtime_
-#include "kaleidoscope/key_defs.h"         // for Key, Key_0, Key_1, Key_A, Key_F1, Key_F12, Key...
+#include "kaleidoscope/key_defs.h"         // for Key, HID_KEYBOARD_FIRST_MODIFIER, Key_0, Key_1
 #include "kaleidoscope/keyswitch_state.h"  // for keyToggledOn, keyIsInjected
 
 // IWYU pragma: no_include "HIDAliases.h"

plugins/Kaleidoscope-Hardware-Dygma-Raise/src/kaleidoscope/device/dygma/Raise.cpp

@@ -20,7 +20,6 @@
 
 #include <Kaleidoscope-EEPROM-Settings.h>
 #include <Kaleidoscope-LEDControl.h>
-#include <KeyboardioHID.h>
 #include <Wire.h>
 
 #include "kaleidoscope/Runtime.h"

plugins/Kaleidoscope-Hardware-Keyboardio-Model01/src/kaleidoscope/device/keyboardio/Model01.cpp

@@ -25,7 +25,6 @@
 #include <stdint.h>  // for uint8_t
 
 #ifndef KALEIDOSCOPE_VIRTUAL_BUILD
-#include <KeyboardioHID.h>
 #include <avr/wdt.h>
 #endif  // ifndef KALEIDOSCOPE_VIRTUAL_BUILD
 

plugins/Kaleidoscope-OneShot/src/kaleidoscope/plugin/OneShot.h

@@ -25,7 +25,7 @@
 #include "kaleidoscope/KeyEvent.h"              // for KeyEvent
 #include "kaleidoscope/Runtime.h"               // for Runtime, Runtime_
 #include "kaleidoscope/event_handler_result.h"  // for EventHandlerResult
-#include "kaleidoscope/key_defs.h"              // for Key
+#include "kaleidoscope/key_defs.h"              // for Key, HID_KEYBOARD_FIRST_MODIFIER
 #include "kaleidoscope/plugin.h"                // for Plugin
 
 // IWYU pragma: no_include "HIDAliases.h"

plugins/Kaleidoscope-Qukeys/src/kaleidoscope/plugin/Qukeys.h

@@ -27,7 +27,7 @@
 #include "kaleidoscope/KeyEvent.h"              // for KeyEvent
 #include "kaleidoscope/KeyEventTracker.h"       // for KeyEventTracker
 #include "kaleidoscope/event_handler_result.h"  // for EventHandlerResult
-#include "kaleidoscope/key_defs.h"              // for Key, Key_Transparent
+#include "kaleidoscope/key_defs.h"              // for Key, Key_Transparent, HID_KEYBOARD_FIRST_...
 #include "kaleidoscope/plugin.h"                // for Plugin
 
 // IWYU pragma: no_include "HIDAliases.h"

src/kaleidoscope/device/virtual/DefaultHIDReportConsumer.cpp

@@ -18,22 +18,18 @@
 
 #include "kaleidoscope/device/virtual/DefaultHIDReportConsumer.h"
 
-// From KeyboardioHID:
+#include <stdint.h>      // for uint8_t
-#include <HID-Settings.h>          // for HID_REPORTID_NKRO_KEYBOARD
+#include <virtual_io.h>  // for logUSBEvent_key...
-#include <MultiReport/Keyboard.h>  // for HID_KeyboardReport_Data_t, (anonymous u...
-// From system:
-#include <stdint.h>  // for uint8_t
-// From Arduino core:
-#include <virtual_io.h>  // for logUSBEvent_keyboard
 
-// From Kaleidoscope:
+#include "kaleidoscope/device/virtual/Logging.h"                          // for log_info, logging
-#include "kaleidoscope/device/virtual/Logging.h"  // for log_info, logging
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"          // for HID_REPORTID_NK...
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Keyboard.h"  // for HID_KeyboardRep...
 
 #undef min
 #undef max
 
-#include <sstream>  // for operator<<, stringstream, basic_ostream
+#include <sstream>  // for operator<<, str...
-#include <string>   // for char_traits, operator+, basic_string
+#include <string>   // for char_traits
 
 namespace kaleidoscope {
 

src/kaleidoscope/device/virtual/Virtual.cpp

@@ -19,23 +19,19 @@
 
 #include "kaleidoscope/device/virtual/Virtual.h"
 
-// From Arduino:
+#include <EEPROM.h>      // for EEPROMClass, EERef
-#include <EEPROM.h>  // for EEPROMClass, EERef
-// From KeyboardioHID:
-#include <HIDReportObserver.h>  // for HIDReportObserver
-// From system:
 #include <stdint.h>      // for uint8_t, uint16_t
 #include <stdlib.h>      // for exit, size_t
-#include <virtual_io.h>  // for getLineOfInput, isInte...
+#include <virtual_io.h>  // for getLineOfInput
 #include <sstream>       // for operator<<, string
-#include <string>        // for operator==, char_traits
+#include <string>        // for operator==, char_t...
-
+
-// From Kaleidoscope:
+#include "kaleidoscope/KeyAddr.h"                                      // for MatrixAddr, Matrix...
-#include "kaleidoscope/KeyAddr.h"                                  // for MatrixAddr, MatrixAddr...
+#include "kaleidoscope/device/virtual/DefaultHIDReportConsumer.h"      // for DefaultHIDReportCo...
-#include "kaleidoscope/device/virtual/DefaultHIDReportConsumer.h"  // for DefaultHIDReportConsumer
+#include "kaleidoscope/device/virtual/Logging.h"                       // for log_error, logging
-#include "kaleidoscope/device/virtual/Logging.h"                   // for log_error, logging
+#include "kaleidoscope/driver/hid/keyboardio/usb/HIDReportObserver.h"  // for HIDReportObserver
-#include "kaleidoscope/key_defs.h"                                 // for Key_NoKey
+#include "kaleidoscope/key_defs.h"                                     // for Key_NoKey
-#include "kaleidoscope/keyswitch_state.h"                          // for IS_PRESSED, WAS_PRESSED
+#include "kaleidoscope/keyswitch_state.h"                              // for IS_PRESSED, WAS_PR...
 
 // FIXME: This relates to virtual/cores/arduino/EEPROM.h.
 //        EEPROM static data must be defined here as only

src/kaleidoscope/device/virtual/VirtualHID.cpp

@@ -22,13 +22,12 @@
 // library KeyboardioHID. It replaces all hardware related stuff
 // with stub implementations.
 
-#include <stddef.h>  // for NULL
+#include <PluggableUSB.h>  // for USBSetup, EP_TYPE_...
-#include <stdint.h>  // for uint8_t
+#include <stddef.h>        // for NULL
+#include <stdint.h>        // for uint8_t
 
-// From KeyboardioHID:
+#include "kaleidoscope/driver/hid/keyboardio/usb/HIDReportObserver.h"  // for HIDReportObserver
-#include "HID.h"                // for HID_, HIDSubDescriptor, HID_::(anonymous), HID, HID_REPOR...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID_.h"               // for HID_, HIDSubDescri...
-#include "HIDReportObserver.h"  // for HIDReportObserver
-#include "PluggableUSB.h"       // for USBSetup, EP_TYPE_INTERRUPT_IN, PluggableUSBModule
 
 #if defined(USBCON)
 

src/kaleidoscope/driver/hid/keyboardio/AbsoluteMouse.h

@@ -17,10 +17,11 @@
 
 #pragma once
 
-#include <KeyboardioHID.h>  // for SingleAbsoluteMouse_, SingleAbso...
+#include <stdint.h>  // for uin...
-#include <stdint.h>         // for uint8_t, int8_t, uint16_t
 
-#include "kaleidoscope/driver/hid/base/AbsoluteMouse.h"  // for AbsoluteMouse, AbsoluteMouseProps
+#include "kaleidoscope/driver/hid/base/AbsoluteMouse.h"                               // for Abs...
+#include "kaleidoscope/driver/hid/keyboardio/usb/DeviceAPIs/AbsoluteMouseAPI.h"       // for Abs...
+#include "kaleidoscope/driver/hid/keyboardio/usb/SingleReport/SingleAbsoluteMouse.h"  // for Sin...
 
 // IWYU pragma: no_include "DeviceAPIs/AbsoluteMouseAPI.hpp"
 

src/kaleidoscope/driver/hid/keyboardio/Keyboard.h

@@ -17,11 +17,13 @@
 
 #pragma once
 
-#include <KeyboardioHID.h>  // for BootKeyboard, BootKeyboard_, Keyboard
+#include <stdint.h>  // for uint8_t
-#include <stdint.h>         // for uint8_t, uint16_t
 
-// From Kaleidoscope:
+#include "kaleidoscope/driver/hid/base/Keyboard.h"                               // for Keyboard
-#include "kaleidoscope/driver/hid/base/Keyboard.h"  // for Keyboard, KeyboardProps
+#include "kaleidoscope/driver/hid/keyboardio/usb/BootKeyboard/BootKeyboard.h"    // for BootKeyb...
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/ConsumerControl.h"  // for Consumer...
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Keyboard.h"         // for Keyboard
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/SystemControl.h"    // for SystemCo...
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/hid/keyboardio/Mouse.h

@@ -17,11 +17,10 @@
 
 #pragma once
 
-#include <KeyboardioHID.h>  // for HID_MouseReport_Data_t, (anonymous union...
+#include <stdint.h>  // for int8_t, uint8_t
-#include <stdint.h>         // for int8_t, uint8_t
 
-// From Kaleidoscope:
+#include "kaleidoscope/driver/hid/base/Mouse.h"                        // for Mouse, MouseProps
-#include "kaleidoscope/driver/hid/base/Mouse.h"  // for Mouse, MouseProps
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Mouse.h"  // for HID_MouseReport_Da...
 
 namespace kaleidoscope {
 namespace driver {

src/kaleidoscope/driver/hid/keyboardio/usb/BootKeyboard/BootKeyboard.cpp

@@ -0,0 +1,403 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/BootKeyboard/BootKeyboard.h"
+
+#include <string.h>  // for memcmp, memcpy
+
+#include "Arduino.h"                                                      // for PROGMEM
+#include "kaleidoscope/driver/hid/keyboardio/usb/DescriptorPrimitives.h"  // for D_REPORT_COUNT
+#include "kaleidoscope/driver/hid/keyboardio/usb/HIDAliases.h"            // for HID_KEYBOARD_FI...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HIDReportObserver.h"     // for HIDReportObserver
+
+// See Appendix B of USB HID spec
+static const uint8_t boot_keyboard_hid_descriptor_[] PROGMEM = {
+  // clang-format off
+  //  Keyboard
+  D_USAGE_PAGE, D_PAGE_GENERIC_DESKTOP,
+  D_USAGE, D_USAGE_KEYBOARD,
+
+  D_COLLECTION, D_APPLICATION,
+  // Modifiers
+  D_USAGE_PAGE, D_PAGE_KEYBOARD,
+  D_USAGE_MINIMUM, 0xe0,
+  D_USAGE_MAXIMUM, 0xe7,
+  D_LOGICAL_MINIMUM, 0x0,
+  D_LOGICAL_MAXIMUM, 0x1,
+  D_REPORT_SIZE, 0x1,
+  D_REPORT_COUNT, 0x8,
+  D_INPUT, (D_DATA | D_VARIABLE | D_ABSOLUTE),
+
+  // Reserved byte
+  D_REPORT_COUNT, 0x1,
+  D_REPORT_SIZE, 0x8,
+  D_INPUT, (D_CONSTANT),
+
+  // LEDs
+  D_REPORT_COUNT, 0x5,
+  D_REPORT_SIZE, 0x1,
+  D_USAGE_PAGE, D_PAGE_LEDS,
+  D_USAGE_MINIMUM, 0x1,
+  D_USAGE_MAXIMUM, 0x5,
+  D_OUTPUT, (D_DATA | D_VARIABLE | D_ABSOLUTE),
+  // Pad LEDs up to a byte
+  D_REPORT_COUNT, 0x1,
+  D_REPORT_SIZE, 0x3,
+  D_OUTPUT, (D_CONSTANT),
+
+  // Non-modifiers
+  D_REPORT_COUNT, 0x6,
+  D_REPORT_SIZE, 0x8,
+  D_LOGICAL_MINIMUM, 0x0,
+  D_LOGICAL_MAXIMUM, 0xff,
+  D_USAGE_PAGE, D_PAGE_KEYBOARD,
+  D_USAGE_MINIMUM, 0x0,
+  D_USAGE_MAXIMUM, 0xff,
+  D_INPUT, (D_DATA | D_ARRAY | D_ABSOLUTE),
+  D_END_COLLECTION
+  // clang-format off
+};
+
+#ifdef ARCH_HAS_CONFIGURABLE_EP_SIZES
+static const uint8_t BOOT_KEYBOARD_EP_SIZE = 8;
+#else
+static const uint8_t BOOT_KEYBOARD_EP_SIZE = USB_EP_SIZE;
+#endif
+
+
+BootKeyboard_::BootKeyboard_(uint8_t protocol_)
+  : PluggableUSBModule(1, 1, epType), default_protocol(protocol_), protocol(protocol_), idle(1), leds(0) {
+#ifdef ARCH_HAS_CONFIGURABLE_EP_SIZES
+  epType[0] = EP_TYPE_INTERRUPT_IN(BOOT_KEYBOARD_EP_SIZE);  // This is an 8 byte report, so ask for an 8 byte buffer, so reports aren't split
+#else
+  epType[0] = EP_TYPE_INTERRUPT_IN;
+#endif
+  PluggableUSB().plug(this);
+}
+
+int BootKeyboard_::getInterface(uint8_t *interfaceCount) {
+  *interfaceCount += 1;  // uses 1
+  HIDDescriptor hidInterface = {
+    D_INTERFACE(pluggedInterface, 1, USB_DEVICE_CLASS_HUMAN_INTERFACE, HID_SUBCLASS_BOOT_INTERFACE, HID_PROTOCOL_KEYBOARD),
+    D_HIDREPORT(sizeof(boot_keyboard_hid_descriptor_)),
+    D_ENDPOINT(USB_ENDPOINT_IN(pluggedEndpoint), USB_ENDPOINT_TYPE_INTERRUPT, BOOT_KEYBOARD_EP_SIZE, 0x01)};
+  return USB_SendControl(0, &hidInterface, sizeof(hidInterface));
+}
+
+int BootKeyboard_::getDescriptor(USBSetup &setup) {
+  // Check if this is a HID Class Descriptor request
+  if (setup.bmRequestType != REQUEST_DEVICETOHOST_STANDARD_INTERFACE) {
+    return 0;
+  }
+  if (setup.wValueH != HID_REPORT_DESCRIPTOR_TYPE) {
+    return 0;
+  }
+
+  // In a HID Class Descriptor wIndex cointains the interface number
+  if (setup.wIndex != pluggedInterface) {
+    return 0;
+  }
+
+  // Reset the protocol on reenumeration. Normally the host should not assume the state of the protocol
+  // due to the USB specs, but Windows and Linux just assumes its in report mode.
+  protocol = default_protocol;
+
+  return USB_SendControl(TRANSFER_PGM, boot_keyboard_hid_descriptor_, sizeof(boot_keyboard_hid_descriptor_));
+}
+
+
+void BootKeyboard_::begin() {
+  // Force API to send a clean report.
+  // This is important for and HID bridge where the receiver stays on,
+  // while the sender is resetted.
+  releaseAll();
+  sendReport();
+}
+
+
+void BootKeyboard_::end() {
+  releaseAll();
+  sendReport();
+}
+
+
+bool BootKeyboard_::setup(USBSetup &setup) {
+  if (pluggedInterface != setup.wIndex) {
+    return false;
+  }
+
+  uint8_t request     = setup.bRequest;
+  uint8_t requestType = setup.bmRequestType;
+
+  if (requestType == REQUEST_DEVICETOHOST_CLASS_INTERFACE) {
+    if (request == HID_GET_REPORT) {
+      // TODO(anyone): HID_GetReport();
+      return true;
+    }
+    if (request == HID_GET_PROTOCOL) {
+      // TODO(anyone) improve
+#ifdef __AVR__
+      UEDATX = protocol;
+#endif
+#ifdef ARDUINO_ARCH_SAM
+      USBDevice.armSend(0, &protocol, 1);
+#endif
+      return true;
+    }
+    if (request == HID_GET_IDLE) {
+      // TODO(anyone) improve
+#ifdef __AVR__
+      UEDATX = idle;
+#endif
+#ifdef ARDUINO_ARCH_SAM
+      USBDevice.armSend(0, &idle, 1);
+#endif
+      return true;
+    }
+  }
+
+  if (requestType == REQUEST_HOSTTODEVICE_CLASS_INTERFACE) {
+    if (request == HID_SET_PROTOCOL) {
+      protocol = setup.wValueL;
+      return true;
+    }
+    if (request == HID_SET_IDLE) {
+      // We currently ignore SET_IDLE, because we don't really do anything with it, and implementing
+      // it causes issues on OSX, such as key chatter. Other operating systems do not suffer if we
+      // force this to zero, either.
+#if 0
+      idle = setup.wValueL;
+#else
+      idle = 0;
+#endif
+      return true;
+    }
+    if (request == HID_SET_REPORT) {
+      // Check if data has the correct length afterwards
+      int length = setup.wLength;
+
+      if (setup.wValueH == HID_REPORT_TYPE_OUTPUT) {
+        if (length == sizeof(leds)) {
+          // ------------------------------------------------------------
+          // Workaround for a bug in the GD32 core:
+          //
+          // On GD32, when we call `USV_RecvControl`, it casts the (void*) pointer
+          // we give it to `uint16_t*`, which means that it will alway write an even
+          // number of bytes to that pointer.  Because we don't want to overwrite
+          // the next byte in memory past `leds`, we use a temporary array that is
+          // guaranteed to be big enough, and copy the data from that:
+          uint8_t raw_report_data[2];
+          USB_RecvControl(&raw_report_data, length);
+          leds = raw_report_data[0];
+          // Once the GD32 core bug is fixed, we can replace the above code with the
+          // original code below:
+          /* ------------------------------------------------------------
+          USB_RecvControl(&leds, length);
+          // ------------------------------------------------------------ */
+          return true;
+        }
+      } else if (setup.wValueH == HID_REPORT_TYPE_INPUT) {
+        // Input (set HID report)
+        if (length == sizeof(report_)) {
+          USB_RecvControl(&report_, length);
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
+uint8_t BootKeyboard_::getLeds() {
+  return leds;
+}
+
+uint8_t BootKeyboard_::getProtocol() {
+  return protocol;
+}
+
+void BootKeyboard_::setProtocol(uint8_t protocol) {
+  this->protocol = protocol;
+}
+
+int BootKeyboard_::sendReport() {
+  if (memcmp(&last_report_, &report_, sizeof(report_))) {
+    // if the two reports are different, send a report
+    int returnCode = USB_Send(pluggedEndpoint | TRANSFER_RELEASE, &report_, sizeof(report_));
+    HIDReportObserver::observeReport(HID_REPORTID_KEYBOARD, &report_, sizeof(report_), returnCode);
+    memcpy(&last_report_, &report_, sizeof(report_));
+    return returnCode;
+  }
+  return -1;
+}
+
+// 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 BootKeyboard_::press(uint8_t k) {
+  uint8_t done = 0;
+
+  if ((k >= HID_KEYBOARD_FIRST_MODIFIER) && (k <= HID_KEYBOARD_LAST_MODIFIER)) {
+    // it's a modifier key
+    report_.modifiers |= (0x01 << (k - HID_KEYBOARD_FIRST_MODIFIER));
+  } else {
+    // it's some other key:
+    // Add k to the key report only if it's not already present
+    // and if there is an empty slot.
+    for (uint8_t i = 0; i < sizeof(report_.keycodes); i++) {
+      if (report_.keycodes[i] != k) {    // is k already in list?
+        if (0 == report_.keycodes[i]) {  // have we found an empty slot?
+          report_.keycodes[i] = k;
+          done                = 1;
+          break;
+        }
+      } else {
+        done = 1;
+        break;
+      }
+    }
+    // use separate variable to check if slot was found
+    // for style reasons - we do not know how the compiler
+    // handles the for() index when it leaves the loop
+    if (0 == done) {
+      return 0;
+    }
+  }
+  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 BootKeyboard_::release(uint8_t k) {
+  if ((k >= HID_KEYBOARD_FIRST_MODIFIER) && (k <= HID_KEYBOARD_LAST_MODIFIER)) {
+    // it's a modifier key
+    report_.modifiers = report_.modifiers & (~(0x01 << (k - HID_KEYBOARD_FIRST_MODIFIER)));
+  } else {
+    // it's some other key:
+    // 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 (uint8_t i = 0; i < sizeof(report_.keycodes); i++) {
+      if (report_.keycodes[i] == k) {
+        report_.keycodes[i] = 0;
+      }
+    }
+
+    // rearrange the keys list so that the free (= 0x00) are at the
+    // end of the keys list - some implementations stop for keys at the
+    // first occurence of an 0x00 in the keys list
+    // so (0x00)(0x01)(0x00)(0x03)(0x02)(0x00) becomes
+    //    (0x03)(0x02)(0x01)(0x00)(0x00)(0x00)
+    uint8_t current = 0, nextpos = 0;
+
+    while (current < sizeof(report_.keycodes)) {
+      if (report_.keycodes[current]) {
+        uint8_t tmp               = report_.keycodes[nextpos];
+        report_.keycodes[nextpos] = report_.keycodes[current];
+        report_.keycodes[current] = tmp;
+        ++nextpos;
+      }
+      ++current;
+    }
+  }
+
+  return 1;
+}
+
+
+void BootKeyboard_::releaseAll() {
+  memset(&report_.bytes, 0x00, sizeof(report_.bytes));
+}
+
+
+/* Returns true if the non-modifer key passed in will be sent during this key report
+ * Returns false in all other cases
+ * */
+bool BootKeyboard_::isKeyPressed(uint8_t k) {
+  for (uint8_t i = 0; i < sizeof(report_.keycodes); i++) {
+    if (report_.keycodes[i] == k) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/* Returns true if the non-modifer key passed in was sent during the previous key report
+ * Returns false in all other cases
+ * */
+bool BootKeyboard_::wasKeyPressed(uint8_t k) {
+  for (uint8_t i = 0; i < sizeof(report_.keycodes); i++) {
+    if (last_report_.keycodes[i] == k) {
+      return true;
+    }
+  }
+  return false;
+}
+
+
+/* Returns true if the modifer key passed in will be sent during this key report
+ * Returns false in all other cases
+ * */
+bool BootKeyboard_::isModifierActive(uint8_t k) {
+  if (k >= HID_KEYBOARD_FIRST_MODIFIER && k <= HID_KEYBOARD_LAST_MODIFIER) {
+    k = k - HID_KEYBOARD_FIRST_MODIFIER;
+    return !!(report_.modifiers & (1 << k));
+  }
+  return false;
+}
+
+/* Returns true if the modifer key passed in was being sent during the previous key report
+ * Returns false in all other cases
+ * */
+bool BootKeyboard_::wasModifierActive(uint8_t k) {
+  if (k >= HID_KEYBOARD_FIRST_MODIFIER && k <= HID_KEYBOARD_LAST_MODIFIER) {
+    k = k - HID_KEYBOARD_FIRST_MODIFIER;
+    return !!(last_report_.modifiers & (1 << k));
+  }
+  return false;
+}
+
+/* Returns true if any modifier key will be sent during this key report
+ * Returns false in all other cases
+ * */
+bool BootKeyboard_::isAnyModifierActive() {
+  return report_.modifiers > 0;
+}
+
+/* Returns true if any modifier key was being sent during the previous key report
+ * Returns false in all other cases
+ * */
+bool BootKeyboard_::wasAnyModifierActive() {
+  return last_report_.modifiers > 0;
+}
+
+__attribute__((weak))
+BootKeyboard_ BootKeyboard;

src/kaleidoscope/driver/hid/keyboardio/usb/BootKeyboard/BootKeyboard.h

@@ -0,0 +1,84 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+// Include guard
+#pragma once
+
+#include <stddef.h>  // for size_t
+#include <stdint.h>  // for uint8_t
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"  // for USBSetup, EPTYPE_DESCRI...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID_.h"          // for HID_REPORT_PROTOCOL
+
+typedef union {
+  // Low level key report: up to 6 keys and shift, ctrl etc at once
+  struct {
+    uint8_t modifiers;
+    uint8_t reserved;
+    uint8_t keycodes[6];
+  };
+  uint8_t bytes[8];
+} HID_BootKeyboardReport_Data_t;
+
+
+class BootKeyboard_ : public PluggableUSBModule {
+ public:
+  explicit BootKeyboard_(uint8_t protocol_ = HID_REPORT_PROTOCOL);
+  size_t press(uint8_t k);
+  void begin();
+  void end();
+  size_t release(uint8_t k);
+  void releaseAll();
+
+  int sendReport();
+
+  bool isModifierActive(uint8_t k);
+  bool wasModifierActive(uint8_t k);
+  bool isAnyModifierActive();
+  bool wasAnyModifierActive();
+  bool isKeyPressed(uint8_t k);
+  bool wasKeyPressed(uint8_t k);
+
+  uint8_t getLeds();
+  uint8_t getProtocol();
+  void setProtocol(uint8_t protocol);
+
+  uint8_t default_protocol;
+
+ protected:
+  HID_BootKeyboardReport_Data_t report_, last_report_;
+
+  // Implementation of the PUSBListNode
+  int getInterface(uint8_t *interfaceCount);
+  int getDescriptor(USBSetup &setup);
+  bool setup(USBSetup &setup);
+
+  EPTYPE_DESCRIPTOR_SIZE epType[1];
+  uint8_t protocol;
+  uint8_t idle;
+
+  uint8_t leds;
+};
+extern BootKeyboard_ BootKeyboard;

src/kaleidoscope/driver/hid/keyboardio/usb/DescriptorPrimitives.h

@@ -0,0 +1,144 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#pragma once
+
+#define D_MULTIBYTE(n)     (n + 0x01)
+
+#define D_USAGE_PAGE       0x05
+#define D_USAGE            0x09
+
+
+#define D_REPORT_ID        0x85
+
+#define D_USAGE_MINIMUM    0x19
+#define D_USAGE_MAXIMUM    0x29
+
+#define D_LOGICAL_MINIMUM  0x15
+#define D_LOGICAL_MAXIMUM  0x25
+
+#define D_PHYSICAL_MINIMUM 0x35
+#define D_PHYSICAL_MAXIMUM 0x45
+
+#define D_REPORT_SIZE      0x75
+#define D_REPORT_COUNT     0x95
+
+#define D_PUSH             0xa4
+#define D_POP              0xb4
+
+// USB HID DCD 1.11 section 6.2.2.4 -  Main items
+//
+// each of these are the type description + 0x01 for a single byte item
+#define D_INPUT          0x81
+#define D_OUTPUT         0x91
+#define D_FEATURE        0xb1
+#define D_COLLECTION     0xa1
+#define D_END_COLLECTION 0xc0
+
+// The bits that make up inputs, outputs and features
+
+// Bit 0
+#define D_DATA     0b00000000
+#define D_CONSTANT 0b00000001
+// Bit 1
+#define D_ARRAY    0b00000000
+#define D_VARIABLE 0b00000010
+// Bit 2
+#define D_ABSOLUTE 0b00000000
+#define D_RELATIVE 0b00000100
+// Bit 3
+#define D_NO_WRAP 0b00000000
+#define D_WRAP    0b00001000
+// Bit 4
+#define D_LINEAR     0b00000000
+#define D_NON_LINEAR 0b00010000
+// Bit 5
+#define D_PREFERRED_STATE 0b00000000
+#define D_NO_PREFERRED    0b00100000
+// Bit 6
+#define D_NO_NULL_POSITION 0b00000000
+#define D_NULL_STATE       0b01000000
+// Bit 7
+#define D_NON_VOLATILE 0b00000000
+#define D_VOLATILE     0b01000000
+// Bit 8
+#define D_BIT_FIELD      0b00000000
+#define D_BUFFERED_BYTES 0b10000000
+
+
+// Collection types
+
+
+#define D_PHYSICAL       0x00  // (group of axes)
+#define D_APPLICATION    0x01  // (mouse, keyboard)
+#define D_LOGICAL        0x02  // (interrelated data)
+#define D_REPORT         0x03
+#define D_NAMED_ARRAY    0x04
+#define D_USAGE_SWITCH   0x05
+#define D_USAGE_MODIFIER 0x06
+// 0x07-0x7f - Reserved
+// 0x80-0xff - Vendor define
+
+
+#define D_PAGE_GENERIC_DESKTOP 0x01
+#define D_PAGE_SIMULATION      0x02
+#define D_PAGE_VR              0x03
+#define D_PAGE_SPORT           0x04
+#define D_PAGE_GAME            0x05
+#define D_PAGE_GENERIC_DEVICE  0x06
+#define D_PAGE_KEYBOARD        0x07
+#define D_PAGE_LEDS            0x08
+#define D_PAGE_BUTTON          0x09
+#define D_PAGE_ORDINAL         0x0A
+#define D_PAGE_TELEPHONY       0x0B
+#define D_PAGE_CONSUMER        0x0C
+#define D_PAGE_DIGITIZER       0x0D
+#define D_PAGE_RESERVED        0x0E
+#define D_PAGE_PID             0x0F
+#define D_PAGE_UNICODE         0x10
+// 0x11-13 RESERVED
+#define D_PAGE_ALPHANUMERIC_DISPLAY 0x14
+#define D_PAGE_MEDICAL_INSTRUMENTS  0x40
+// 0x80-83 MONITOR
+// 0x84-87 POWER
+#define D_PAGE_BAR_CODE_SCANNER 0x8C
+#define D_PAGE_SCALE            0x8D
+#define D_PAGE_MSR              0x8E
+// 0x8F RESERVED POINT OF SALE
+#define D_PAGE_CAMERA_CONTROL 0x90
+#define D_PAGE_ARCADE         0x91
+
+
+// Generic Desktop Usages HUT Section 4 p27
+
+
+#define D_USAGE_POINTER 0x01
+#define D_USAGE_MOUSE   0x02
+// 0x03 is reserved
+#define D_USAGE_JOYSTICK  0x04
+#define D_USAGE_GAMEPAD   0x05
+#define D_USAGE_KEYBOARD  0x06
+#define D_USAGE_KEYPAD    0x07
+#define D_USAGE_MULITAXIS 0x08

src/kaleidoscope/driver/hid/keyboardio/usb/DeviceAPIs/AbsoluteMouseAPI.h

@@ -0,0 +1,106 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+// Include guard
+#pragma once
+
+#include <stdint.h>  // for uint8_t, uint16_t
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/DescriptorPrimitives.h"  // for D_DATA, D_INPUT
+#include "kaleidoscope/driver/hid/keyboardio/usb/MouseButtons.h"          // for MOUSE_LEFT
+
+// clang-format off
+
+#define DESCRIPTOR_ABS_MOUSE_BUTTONS \
+  /* 8 Buttons */                                                         \
+  D_USAGE_PAGE, D_PAGE_BUTTON,             /* USAGE_PAGE (Button) */      \
+  D_USAGE_MINIMUM, 0x01,                   /* USAGE_MINIMUM (Button 1) */ \
+  D_USAGE_MAXIMUM, 0x08,                   /* USAGE_MAXIMUM (Button 8) */ \
+  D_LOGICAL_MINIMUM, 0x00,                 /* LOGICAL_MINIMUM (0) */      \
+  D_LOGICAL_MAXIMUM, 0x01,                 /* LOGICAL_MAXIMUM (1) */      \
+  D_REPORT_COUNT, 0x08,                    /* REPORT_COUNT (8) */         \
+  D_REPORT_SIZE, 0x01,                     /* REPORT_SIZE (1) */          \
+  D_INPUT, (D_DATA|D_VARIABLE|D_ABSOLUTE),
+
+# define DESCRIPTOR_ABS_MOUSE_XY \
+  /* X, Y */                                                                     \
+  D_USAGE_PAGE, D_PAGE_GENERIC_DESKTOP,       /* USAGE_PAGE (Generic Desktop) */ \
+  D_USAGE, 0x30,                              /* USAGE (X) */                    \
+  D_USAGE, 0x31,                              /* USAGE (Y) */                    \
+  D_MULTIBYTE(D_LOGICAL_MINIMUM), 0x00, 0x00, /* Logical Minimum (0) */          \
+  D_MULTIBYTE(D_LOGICAL_MAXIMUM), 0xFF, 0x7f, /* Logical Maximum (32767) */      \
+  D_REPORT_SIZE, 0x10,                        /* Report Size (16), */            \
+  D_REPORT_COUNT, 0x02,                       /* Report Count (2), */            \
+  D_INPUT, (D_DATA|D_VARIABLE|D_ABSOLUTE),    /* Input (Data, Variable, Absolute) */
+
+#define DESCRIPTOR_ABS_MOUSE_WHEEL \
+  /* Wheel */                                                               \
+  D_USAGE, 0x38,                            /* USAGE (Wheel) */             \
+  D_LOGICAL_MINIMUM, 0x81,                  /* LOGICAL_MINIMUM (-127) */    \
+  D_LOGICAL_MAXIMUM, 0x7f,                  /* LOGICAL_MAXIMUM (127) */     \
+  D_REPORT_SIZE, 0x08,                      /* REPORT_SIZE (8) */           \
+  D_REPORT_COUNT, 0x01,                     /* REPORT_COUNT (1) */          \
+  D_INPUT, (D_DATA|D_VARIABLE|D_RELATIVE),
+
+// clang-format on
+
+#pragma pack(push, 1)
+typedef union {
+  // Absolute mouse report: 8 buttons, 2 absolute axis, wheel
+  struct {
+    uint8_t buttons;
+    uint16_t xAxis;
+    uint16_t yAxis;
+    int8_t wheel;
+  };
+} HID_MouseAbsoluteReport_Data_t;
+#pragma pack(pop)
+
+class AbsoluteMouseAPI {
+ public:
+  inline AbsoluteMouseAPI();
+  inline void begin();
+  inline void end();
+
+  inline void click(uint8_t b = MOUSE_LEFT);
+  inline void moveTo(uint16_t x, uint16_t y, int8_t wheel = 0);
+  inline void move(int x, int y, int8_t wheel = 0);
+  inline void press(uint8_t b = MOUSE_LEFT);
+  inline void release(uint8_t b = MOUSE_LEFT);
+  inline bool isPressed(uint8_t b = MOUSE_LEFT);
+
+  // Sending is public in the base class for advanced users.
+  virtual void sendReport(void *data, int length) {}
+
+ protected:
+  uint16_t x_axis_;
+  uint16_t y_axis_;
+  uint8_t buttons_;
+
+  inline void buttons(uint8_t b);
+  inline int16_t qadd16(int16_t base, int16_t increment);
+};
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/DeviceAPIs/AbsoluteMouseAPI.hpp"  // IWYU pragma: export

src/kaleidoscope/driver/hid/keyboardio/usb/DeviceAPIs/AbsoluteMouseAPI.hpp

@@ -0,0 +1,103 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#pragma once
+
+AbsoluteMouseAPI::AbsoluteMouseAPI()
+  : x_axis_(0), y_axis_(0), buttons_(0) {}
+
+void AbsoluteMouseAPI::buttons(uint8_t b) {
+  if (b != buttons_) {
+    buttons_ = b;
+    moveTo(x_axis_, y_axis_, 0);
+  }
+}
+
+int16_t AbsoluteMouseAPI::qadd16(int16_t base, int16_t increment) {
+  // Separate between subtracting and adding
+  if (increment < 0) {
+    // Subtracting more would cause an undefined overflow
+    if ((int16_t)0x8000 - increment > base)
+      base = 0x8000;
+    else
+      base += increment;
+  } else {
+    // Adding more would cause an undefined overflow
+    if ((int16_t)0x7FFF - increment < base)
+      base = 0x7FFF;
+    else
+      base += increment;
+  }
+  return base;
+}
+
+void AbsoluteMouseAPI::begin() {
+  // release all buttons
+  end();
+}
+
+void AbsoluteMouseAPI::end() {
+  buttons_ = 0;
+  moveTo(x_axis_, y_axis_, 0);
+}
+
+void AbsoluteMouseAPI::click(uint8_t b) {
+  buttons_ = b;
+  moveTo(x_axis_, y_axis_, 0);
+  buttons_ = 0;
+  moveTo(x_axis_, y_axis_, 0);
+}
+
+void AbsoluteMouseAPI::moveTo(uint16_t x, uint16_t y, signed char wheel) {
+  x_axis_ = x;
+  y_axis_ = y;
+  HID_MouseAbsoluteReport_Data_t report;
+  report.buttons = buttons_;
+  report.xAxis   = x;
+  report.yAxis   = y;
+  report.wheel   = wheel;
+  sendReport(&report, sizeof(report));
+}
+
+void AbsoluteMouseAPI::move(int x, int y, signed char wheel) {
+  moveTo(qadd16(x_axis_, x), qadd16(y_axis_, y), wheel);
+}
+
+void AbsoluteMouseAPI::press(uint8_t b) {
+  // press LEFT by default
+  buttons(buttons_ | b);
+}
+
+void AbsoluteMouseAPI::release(uint8_t b) {
+  // release LEFT by default
+  buttons(buttons_ & ~b);
+}
+
+bool AbsoluteMouseAPI::isPressed(uint8_t b) {
+  // check LEFT by default
+  if ((b & buttons_) > 0)
+    return true;
+  return false;
+}

src/kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h

@@ -0,0 +1,162 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+// Include guard
+#pragma once
+
+
+// IWYU pragma: no_include "PluggableUSB.h"
+
+#define HID_REPORTID_NONE 0
+
+#ifndef HID_REPORTID_MOUSE
+#define HID_REPORTID_MOUSE 1
+#endif
+
+#ifndef HID_REPORTID_KEYBOARD
+#define HID_REPORTID_KEYBOARD 2
+#endif
+
+/* Commented out so that IWYU won't remove it:
+   -------------------------------------------
+#ifndef HID_REPORTID_RAWHID
+// This will not work properly in most cases.
+// The number is just kept from the old number counting.
+//#define HID_REPORTID_RAWHID 3
+#endif
+// ------------------------------------------- */
+
+#ifndef HID_REPORTID_CONSUMERCONTROL
+#define HID_REPORTID_CONSUMERCONTROL 4
+#endif
+
+#ifndef HID_REPORTID_SYSTEMCONTROL
+#define HID_REPORTID_SYSTEMCONTROL 5
+#endif
+
+#ifndef HID_REPORTID_GAMEPAD
+#define HID_REPORTID_GAMEPAD 6
+#endif
+
+#ifndef HID_REPORTID_MOUSE_ABSOLUTE
+#define HID_REPORTID_MOUSE_ABSOLUTE 7
+#endif
+
+#ifndef HID_REPORTID_NKRO_KEYBOARD
+#define HID_REPORTID_NKRO_KEYBOARD 8
+#endif
+
+
+// Nico has submitted these definitions upstream, but they're not merged yet
+// HID Request Type HID1.11 Page 51 7.2.1 Get_Report Request
+#define HID_REPORT_TYPE_INPUT   1
+#define HID_REPORT_TYPE_OUTPUT  2
+#define HID_REPORT_TYPE_FEATURE 3
+
+// Controls whether to pack messages or not. When set, any sends will be delayed
+// until packing is toggled off, and sent then. This is a no-op on AVR, but is
+// required for SAMD. We place a forward-declaration here to be able to avoid
+// architecture-specific ifdefs elsewhere in the code.
+void USB_PackMessages(bool pack);
+
+#if defined(ARDUINO_ARCH_AVR)
+
+#include <PluggableUSB.h>  // IWYU pragma: export
+
+#define EPTYPE_DESCRIPTOR_SIZE uint8_t
+
+#elif defined(ARDUINO_ARCH_SAM)
+
+#include <PluggableUSB.h>
+
+// clang-format off
+#define EPTYPE_DESCRIPTOR_SIZE uint32_t
+#define EP_TYPE_INTERRUPT_IN  (UOTGHS_DEVEPTCFG_EPSIZE_512_BYTE |  \
+                               UOTGHS_DEVEPTCFG_EPDIR_IN |         \
+                               UOTGHS_DEVEPTCFG_EPTYPE_BLK |       \
+                               UOTGHS_DEVEPTCFG_EPBK_1_BANK |      \
+                               UOTGHS_DEVEPTCFG_NBTRANS_1_TRANS |  \
+                               UOTGHS_DEVEPTCFG_ALLOC)
+#define EP_TYPE_INTERRUPT_OUT (UOTGHS_DEVEPTCFG_EPSIZE_512_BYTE |  \
+                               UOTGHS_DEVEPTCFG_EPTYPE_BLK |       \
+                               UOTGHS_DEVEPTCFG_EPBK_1_BANK |      \
+                               UOTGHS_DEVEPTCFG_NBTRANS_1_TRANS |  \
+                               UOTGHS_DEVEPTCFG_ALLOC)
+#define USB_EP_SIZE            EPX_SIZE
+#define USB_SendControl        USBD_SendControl
+#define USB_Available          USBD_Available
+#define USB_Recv               USBD_Recv
+#define USB_Send               USBD_Send
+#define USB_Flush              USBD_Flush
+// clang-format on
+
+#elif defined(ARDUINO_ARCH_SAMD)
+
+#include <PluggableUSB.h>
+
+#define EPTYPE_DESCRIPTOR_SIZE uint32_t
+#define EP_TYPE_INTERRUPT_IN   USB_ENDPOINT_TYPE_INTERRUPT | USB_ENDPOINT_IN(0);
+#define EP_TYPE_INTERRUPT_OUT  USB_ENDPOINT_TYPE_INTERRUPT | USB_ENDPOINT_OUT(0);
+#define USB_EP_SIZE            EPX_SIZE
+//#define USB_SendControl      USBDevice.sendControl -> real C++ functions to take care of PGM overloading
+#define USB_Available          USBDevice.available
+#define USB_Recv               USBDevice.recv
+#define USB_RecvControl        USBDevice.recvControl
+#define USB_Send               USBDevice.send
+#define USB_Flush              USBDevice.flush
+
+int USB_SendControl(void *y, uint8_t z);
+int USB_SendControl(uint8_t x, const void *y, uint8_t z);
+
+#define TRANSFER_PGM           0
+#define TRANSFER_RELEASE       0
+
+#elif defined(ARDUINO_ARCH_GD32)
+
+#include "USBCore.h"
+
+#define EPTYPE_DESCRIPTOR_SIZE unsigned int
+
+
+// Should eventually get defined upstream
+#ifndef USB_DEVICE_CLASS_HUMAN_INTERFACE
+#define USB_DEVICE_CLASS_HUMAN_INTERFACE 0x03
+#endif
+
+#define ARCH_HAS_CONFIGURABLE_EP_SIZES
+
+constexpr uint16_t EP_TYPE_INTERRUPT_IN(uint8_t buffer_size) {
+  return EPDesc(USB_TRX_IN, USB_EP_ATTR_INT, buffer_size).val;
+}
+constexpr uint16_t EP_TYPE_INTERRUPT_OUT(uint8_t buffer_size) {
+  return EPDesc(USB_TRX_OUT, USB_EP_ATTR_INT, buffer_size).val;
+}
+
+
+#else
+
+#error "Unsupported architecture"
+
+#endif

src/kaleidoscope/driver/hid/keyboardio/usb/HIDAliases.h

@@ -0,0 +1,33 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#pragma once
+
+#include "kaleidoscope/HIDTables.h"  // for HID_KEYBOARD_LEFT_CONTROL, HID_KEYBOARD_NO_EVENT
+
+#define HID_FIRST_KEY               HID_KEYBOARD_NO_EVENT
+#define HID_LAST_KEY                HID_KEYPAD_HEXADECIMAL
+#define HID_KEYBOARD_FIRST_MODIFIER HID_KEYBOARD_LEFT_CONTROL
+#define HID_KEYBOARD_LAST_MODIFIER  HID_KEYBOARD_RIGHT_GUI

src/kaleidoscope/driver/hid/keyboardio/usb/HIDReportObserver.cpp

@@ -0,0 +1,27 @@
+/*
+Copyright (c) 2015-2019 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/HIDReportObserver.h"
+
+HIDReportObserver::SendReportHook HIDReportObserver::send_report_hook_ = nullptr;

src/kaleidoscope/driver/hid/keyboardio/usb/HIDReportObserver.h

@@ -0,0 +1,51 @@
+/*
+Copyright (c) 2015-2019 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#pragma once
+
+#include <stdint.h>  // for uint8_t
+
+class HIDReportObserver {
+ public:
+  typedef void (*SendReportHook)(uint8_t id, const void *data, int len, int result);
+
+  static void observeReport(uint8_t id, const void *data, int len, int result) {
+    if (send_report_hook_) {
+      (*send_report_hook_)(id, data, len, result);
+    }
+  }
+
+  static SendReportHook currentHook() {
+    return send_report_hook_;
+  }
+
+  static SendReportHook resetHook(SendReportHook new_hook) {
+    auto previous_hook = send_report_hook_;
+    send_report_hook_  = new_hook;
+    return previous_hook;
+  }
+
+ private:
+  static SendReportHook send_report_hook_;
+};

src/kaleidoscope/driver/hid/keyboardio/usb/HID_.cpp

@@ -0,0 +1,223 @@
+/*
+   Copyright (c) 2015, Arduino LLC
+   Original code (pre-library): Copyright (c) 2011, Peter Barrett
+
+   Permission to use, copy, modify, and/or distribute this software for
+   any purpose with or without fee is hereby granted, provided that the
+   above copyright notice and this permission notice appear in all copies.
+
+   THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+   WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+   WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR
+   BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
+   OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+   WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+   ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
+   SOFTWARE.
+ */
+
+#ifndef KEYBOARDIOHID_BUILD_WITHOUT_HID
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID_.h"
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/HIDReportObserver.h"
+
+#if defined(USBCON)
+
+HID_ &HID() {
+  static HID_ obj;
+  return obj;
+}
+
+int HID_::getInterface(uint8_t *interfaceCount) {
+  *interfaceCount += 1;  // uses 1
+  HIDDescriptor hidInterface = {
+    D_INTERFACE(pluggedInterface, 1, USB_DEVICE_CLASS_HUMAN_INTERFACE, HID_SUBCLASS_NONE, HID_PROTOCOL_NONE),
+    D_HIDREPORT(descriptorSize),
+    D_ENDPOINT(USB_ENDPOINT_IN(pluggedEndpoint), USB_ENDPOINT_TYPE_INTERRUPT, USB_EP_SIZE, 0x01)};
+  return USB_SendControl(0, &hidInterface, sizeof(hidInterface));
+}
+
+int HID_::getDescriptor(USBSetup &setup) {
+  // Check if this is a HID Class Descriptor request
+  if (setup.bmRequestType != REQUEST_DEVICETOHOST_STANDARD_INTERFACE) {
+    return 0;
+  }
+  if (setup.wValueH != HID_REPORT_DESCRIPTOR_TYPE) {
+    return 0;
+  }
+
+  // In a HID Class Descriptor wIndex cointains the interface number
+  if (setup.wIndex != pluggedInterface) {
+    return 0;
+  }
+
+  int total = 0;
+  HIDSubDescriptor *node;
+  USB_PackMessages(true);
+  for (node = rootNode; node; node = node->next) {
+    int res = USB_SendControl(TRANSFER_PGM, node->data, node->length);
+    if (res == -1)
+      return -1;
+    total += res;
+  }
+
+  // Reset the protocol on reenumeration. Normally the host should not assume the state of the protocol
+  // due to the USB specs, but Windows and Linux just assumes its in report mode.
+  protocol = HID_REPORT_PROTOCOL;
+
+  USB_PackMessages(false);
+  return total;
+}
+
+__attribute__((weak))
+uint8_t
+HID_::getShortName(char *name) {
+  name[0] = 'k';
+  name[1] = 'b';
+  name[2] = 'i';
+  name[3] = 'o';
+  name[4] = '0';
+  name[5] = '1';
+  return 6;
+}
+
+void HID_::AppendDescriptor(HIDSubDescriptor *node) {
+  if (!rootNode) {
+    rootNode = node;
+  } else {
+    HIDSubDescriptor *current = rootNode;
+    while (current->next) {
+      current = current->next;
+    }
+    current->next = node;
+  }
+  descriptorSize += node->length;
+}
+
+int HID_::SendReport(uint8_t id, const void *data, int len) {
+  auto result = SendReport_(id, data, len);
+  HIDReportObserver::observeReport(id, data, len, result);
+  return result;
+}
+
+int HID_::SendReport_(uint8_t id, const void *data, int len) {
+  /* On SAMD, we need to send the whole report in one batch; sending the id, and
+   * the report itself separately does not work, the report never arrives. Due
+   * to this, we merge the two into a single buffer, and send that.
+   *
+   * While the same would work for other architectures, AVR included, doing so
+   * costs RAM, which is something scarce on AVR. So on that platform, we opt to
+   * send the id and the report separately instead. */
+#ifdef ARDUINO_ARCH_SAMD
+  uint8_t p[64];
+  p[0] = id;
+  memcpy(&p[1], data, len);
+  return USB_Send(pluggedEndpoint, p, len + 1);
+#else
+  auto ret = USB_Send(pluggedEndpoint, &id, 1);
+  if (ret < 0) return ret;
+  auto ret2 = USB_Send(pluggedEndpoint | TRANSFER_RELEASE, data, len);
+  if (ret2 < 0) return ret2;
+  return ret + ret2;
+#endif
+}
+
+bool HID_::setup(USBSetup &setup) {
+  if (pluggedInterface != setup.wIndex) {
+    return false;
+  }
+
+  uint8_t request     = setup.bRequest;
+  uint8_t requestType = setup.bmRequestType;
+
+  if (requestType == REQUEST_DEVICETOHOST_CLASS_INTERFACE) {
+    if (request == HID_GET_REPORT) {
+      // TODO(anyone): HID_GetReport();
+      return true;
+    }
+    if (request == HID_GET_PROTOCOL) {
+      // TODO(anyone): Send8(protocol);
+      return true;
+    }
+    if (request == HID_GET_IDLE) {
+      // TODO(anyone): Send8(idle);
+    }
+  }
+
+  if (requestType == REQUEST_HOSTTODEVICE_CLASS_INTERFACE) {
+    if (request == HID_SET_PROTOCOL) {
+      // The USB Host tells us if we are in boot or report mode.
+      // This only works with a real boot compatible device.
+      protocol = setup.wValueL;
+      return true;
+    }
+    if (request == HID_SET_IDLE) {
+      idle = setup.wValueH;
+      return true;
+    }
+    if (request == HID_SET_REPORT) {
+      uint16_t length = setup.wLength;
+
+      // ------------------------------------------------------------
+      // Workaround for a bug in the GD32 core:
+      //
+      // On GD32, when we call `USV_RecvControl`, it casts the (void*) pointer
+      // we give it to `uint16_t*`, which means that it will alway write an even
+      // number of bytes to that pointer.  Because we might be trying to just
+      // read the `leds` byte, and we don't want to overwrite the next byte in
+      // memory, instead of giving it the pointer to the `setReportData` member
+      // variable directly, we have it write into to temporary `raw_report_data`
+      // array that's guaranteed to be big enough, then copy the data from that
+      // array into `setReportData`:
+      uint8_t raw_report_data[sizeof(setReportData) + 1];
+      if (length == sizeof(setReportData)) {
+        USB_RecvControl(&raw_report_data, length);
+        setReportData.reportId = raw_report_data[0];
+        setReportData.leds     = raw_report_data[1];
+      } else if (length == sizeof(setReportData.leds)) {
+        USB_RecvControl(&raw_report_data, length);
+        setReportData.reportId = 0;
+        setReportData.leds     = raw_report_data[0];
+      }
+      // Once the GD32 core bug is fixed, we can replace the above code with the
+      // original code below:
+      /* ------------------------------------------------------------
+      if (length == sizeof(setReportData)) {
+        USB_RecvControl(&setReportData, length);
+      } else if (length == sizeof(setReportData.leds)) {
+        USB_RecvControl(&setReportData.leds, length);
+        setReportData.reportId = 0;
+      }
+      // ------------------------------------------------------------ */
+    }
+  }
+
+  return false;
+}
+
+HID_::HID_()
+  : PluggableUSBModule(1, 1, epType),
+    rootNode(NULL),
+    descriptorSize(0),
+    protocol(HID_REPORT_PROTOCOL),
+    idle(1) {
+  setReportData.reportId = 0;
+  setReportData.leds     = 0;
+
+#ifdef ARCH_HAS_CONFIGURABLE_EP_SIZES
+  epType[0] = EP_TYPE_INTERRUPT_IN(USB_EP_SIZE);
+#else
+  epType[0] = EP_TYPE_INTERRUPT_IN;
+#endif
+
+  PluggableUSB().plug(this);
+}
+
+int HID_::begin() {
+  return 0;
+}
+
+#endif /* if defined(USBCON) */
+
+#endif /* ifndef KEYBOARDIOHID_BUILD_WITHOUT_HID */

src/kaleidoscope/driver/hid/keyboardio/usb/HID_.h

@@ -0,0 +1,134 @@
+/*
+  Copyright (c) 2015, Arduino LLC
+  Original code (pre-library): Copyright (c) 2011, Peter Barrett
+
+  Permission to use, copy, modify, and/or distribute this software for
+  any purpose with or without fee is hereby granted, provided that the
+  above copyright notice and this permission notice appear in all copies.
+
+  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+  WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR
+  BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
+  OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+  WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+  ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
+  SOFTWARE.
+ */
+
+#pragma once
+
+#include <Arduino.h>  // for highByte, lowByte
+#include <stddef.h>   // for NULL
+#include <stdint.h>   // for uint8_t, uint16_t
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"  // for USBSetup, EPTYPE_DESCRI...
+
+#if defined(USBCON)
+
+#define _USING_HID
+
+// HID 'Driver'
+// ------------
+#define HID_GET_REPORT               0x01
+#define HID_GET_IDLE                 0x02
+#define HID_GET_PROTOCOL             0x03
+#define HID_SET_REPORT               0x09
+#define HID_SET_IDLE                 0x0A
+#define HID_SET_PROTOCOL             0x0B
+
+#define HID_HID_DESCRIPTOR_TYPE      0x21
+#define HID_REPORT_DESCRIPTOR_TYPE   0x22
+#define HID_PHYSICAL_DESCRIPTOR_TYPE 0x23
+
+// HID subclass HID1.11 Page 8 4.2 Subclass
+#define HID_SUBCLASS_NONE           0
+#define HID_SUBCLASS_BOOT_INTERFACE 1
+
+// HID Keyboard/Mouse bios compatible protocols HID1.11 Page 9 4.3 Protocols
+#define HID_PROTOCOL_NONE     0
+#define HID_PROTOCOL_KEYBOARD 1
+#define HID_PROTOCOL_MOUSE    2
+
+// Normal or bios protocol (Keyboard/Mouse) HID1.11 Page 54 7.2.5 Get_Protocol Request
+// "protocol" variable is used for this purpose.
+#define HID_BOOT_PROTOCOL   0
+#define HID_REPORT_PROTOCOL 1
+
+// HID Request Type HID1.11 Page 51 7.2.1 Get_Report Request
+#define HID_REPORT_TYPE_INPUT   1
+#define HID_REPORT_TYPE_OUTPUT  2
+#define HID_REPORT_TYPE_FEATURE 3
+
+#pragma pack(push, 1)
+typedef struct {
+  uint8_t len;    // 9
+  uint8_t dtype;  // 0x21
+  uint8_t addr;
+  uint8_t versionL;  // 0x101
+  uint8_t versionH;  // 0x101
+  uint8_t country;
+  uint8_t desctype;  // 0x22 report
+  uint8_t descLenL;
+  uint8_t descLenH;
+} HIDDescDescriptor;
+
+typedef struct {
+  InterfaceDescriptor hid;
+  HIDDescDescriptor desc;
+  EndpointDescriptor in;
+} HIDDescriptor;
+#pragma pack(pop)
+
+class HIDSubDescriptor {
+ public:
+  HIDSubDescriptor *next = NULL;
+  HIDSubDescriptor(const void *d, const uint16_t l)
+    : data(d), length(l) {}
+
+  const void *data;
+  const uint16_t length;
+};
+
+class HID_ : public PluggableUSBModule {
+ public:
+  HID_();
+  int begin();
+  int SendReport(uint8_t id, const void *data, int len);
+  void AppendDescriptor(HIDSubDescriptor *node);
+  uint8_t getLEDs() {
+    return setReportData.leds;
+  }
+
+ protected:
+  // Implementation of the PluggableUSBModule
+  int getInterface(uint8_t *interfaceCount);
+  int getDescriptor(USBSetup &setup);
+  bool setup(USBSetup &setup);
+  uint8_t getShortName(char *name);
+
+  int SendReport_(uint8_t id, const void *data, int len);
+
+ private:
+  EPTYPE_DESCRIPTOR_SIZE epType[1];
+
+  HIDSubDescriptor *rootNode;
+  uint16_t descriptorSize;
+
+  uint8_t protocol;
+  uint8_t idle;
+  struct {
+    uint8_t reportId;
+    uint8_t leds;
+  } setReportData;
+};
+
+// Replacement for global singleton.
+// This function prevents static-initialization-order-fiasco
+// https://isocpp.org/wiki/faq/ctors#static-init-order-on-first-use
+HID_ &HID();
+
+#define D_HIDREPORT(length) \
+  { 9, 0x21, 0x01, 0x01, 0, 1, 0x22, lowByte(length), highByte(length) }
+
+#endif  // USBCON

src/kaleidoscope/driver/hid/keyboardio/usb/MouseButtons.h

@@ -0,0 +1,35 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#pragma once
+
+#define MOUSE_LEFT   (1 << 0)
+#define MOUSE_RIGHT  (1 << 1)
+#define MOUSE_MIDDLE (1 << 2)
+#define MOUSE_PREV   (1 << 3)
+#define MOUSE_NEXT   (1 << 4)
+// actually this mouse report has 8 buttons (for smaller descriptor)
+// but the last 3 wont do anything from what I tested
+#define MOUSE_ALL (MOUSE_LEFT | MOUSE_RIGHT | MOUSE_MIDDLE | MOUSE_PREV | MOUSE_NEXT)

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/AbsoluteMouse.cpp

@@ -0,0 +1,62 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/AbsoluteMouse.h"
+
+#include <Arduino.h>  // for PROGMEM
+#include <stdint.h>   // for uint8_t
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/DescriptorPrimitives.h"  // for D_APPLICATION
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"          // for HID_REPORTID_MO...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID_.h"                  // for HID, HID_, HIDS...
+
+static const uint8_t absolute_mouse_hid_descriptor_[] PROGMEM = {
+  // clang-format off
+  // Mouse absolute
+  D_USAGE_PAGE, D_PAGE_GENERIC_DESKTOP,      // USAGE_PAGE (Generic Desktop)   54
+  D_USAGE, D_USAGE_MOUSE,                    // USAGE (Mouse)
+  D_COLLECTION, D_APPLICATION,               // COLLECTION (Application)
+  D_REPORT_ID, HID_REPORTID_MOUSE_ABSOLUTE,  //  REPORT_ID
+
+  DESCRIPTOR_ABS_MOUSE_BUTTONS
+  DESCRIPTOR_ABS_MOUSE_XY
+  DESCRIPTOR_ABS_MOUSE_WHEEL
+
+  D_END_COLLECTION                           // End
+  // clang-format off
+};
+
+AbsoluteMouse_::AbsoluteMouse_() {
+  static HIDSubDescriptor node(absolute_mouse_hid_descriptor_,
+                               sizeof(absolute_mouse_hid_descriptor_));
+  HID().AppendDescriptor(&node);
+}
+
+
+void AbsoluteMouse_::sendReport(void *data, int length) {
+  HID().SendReport(HID_REPORTID_MOUSE_ABSOLUTE, data, length);
+}
+
+AbsoluteMouse_ AbsoluteMouse;

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/AbsoluteMouse.h

@@ -0,0 +1,40 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+// Include guard
+#pragma once
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/DeviceAPIs/AbsoluteMouseAPI.h"  // for Absolute...
+
+class AbsoluteMouse_ : public AbsoluteMouseAPI {
+ public:
+  AbsoluteMouse_();
+
+ protected:
+  // Sending is public in the base class for advanced users.
+  virtual void sendReport(void *data, int length);
+};
+
+extern AbsoluteMouse_ AbsoluteMouse;

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/ConsumerControl.cpp

@@ -0,0 +1,117 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/ConsumerControl.h"
+
+#include <Arduino.h>  // for PROGMEM
+#include <string.h>   // for memset, memcmp
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/DescriptorPrimitives.h"  // for D_MULTIBYTE
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"          // for HID_REPORTID_CO...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID_.h"                  // for HID, HID_, HIDS...
+
+static const uint8_t consumer_control_hid_descriptor_[] PROGMEM = {
+  // clang-format off
+  // Consumer Control (Sound/Media keys)
+  D_USAGE_PAGE, 0x0C,                          // usage page (consumer device)
+  D_USAGE, 0x01,                               // usage -- consumer control
+  D_COLLECTION, D_APPLICATION,                 // collection (application)
+  D_REPORT_ID, HID_REPORTID_CONSUMERCONTROL,   // report id
+  // 4 Media Keys
+  D_LOGICAL_MINIMUM, 0x00,                     // logical minimum
+  D_MULTIBYTE(D_LOGICAL_MAXIMUM), 0xFF, 0x03,  // logical maximum (3ff)
+  D_USAGE_MINIMUM, 0x00,                       // usage minimum (0)
+  D_MULTIBYTE(D_USAGE_MAXIMUM), 0xFF, 0x03,    // usage maximum (3ff)
+  D_REPORT_COUNT, 0x04,                        // report count (4)
+  D_REPORT_SIZE, 0x10,                         // report size (16)
+  D_INPUT, 0x00,                               // input
+  D_END_COLLECTION                             // end collection
+  // clang-format on
+};
+
+ConsumerControl_::ConsumerControl_() {
+  static HIDSubDescriptor node(consumer_control_hid_descriptor_,
+                               sizeof(consumer_control_hid_descriptor_));
+  HID().AppendDescriptor(&node);
+}
+
+void ConsumerControl_::begin() {
+  // release all buttons
+  end();
+}
+
+void ConsumerControl_::end() {
+  memset(&report_, 0, sizeof(report_));
+  sendReport();
+}
+
+void ConsumerControl_::write(uint16_t m) {
+  press(m);
+  release(m);
+}
+
+void ConsumerControl_::press(uint16_t m) {
+  // search for a free spot
+  for (uint8_t i = 0; i < sizeof(HID_ConsumerControlReport_Data_t) / 2; i++) {
+    if (report_.keys[i] == 0x00) {
+      report_.keys[i] = m;
+      break;
+    }
+  }
+}
+
+void ConsumerControl_::release(uint16_t m) {
+  // search and release the keypress
+  for (uint8_t i = 0; i < sizeof(HID_ConsumerControlReport_Data_t) / 2; i++) {
+    if (report_.keys[i] == m) {
+      report_.keys[i] = 0x00;
+      // no break to delete multiple keys
+    }
+  }
+}
+
+void ConsumerControl_::releaseAll() {
+  memset(&report_, 0, sizeof(report_));
+}
+
+void ConsumerControl_::sendReportUnchecked() {
+  HID().SendReport(HID_REPORTID_CONSUMERCONTROL, &report_, sizeof(report_));
+}
+
+void ConsumerControl_::sendReport() {
+  // If the last report is different than the current report, then we need to
+  // send a report.  We guard sendReport like this so that calling code doesn't
+  // end up spamming the host with empty reports if sendReport is called in a
+  // tight loop.
+
+  // if the previous report is the same, return early without a new report.
+  if (memcmp(&last_report_, &report_, sizeof(report_)) == 0)
+    return;
+
+  sendReportUnchecked();
+  memcpy(&last_report_, &report_, sizeof(report_));
+}
+
+ConsumerControl_ ConsumerControl;

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/ConsumerControl.h

@@ -0,0 +1,63 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+// Include guard
+#pragma once
+
+#include <stdint.h>  // for uint16_t
+
+typedef union {
+  // Every usable Consumer key possible, up to 4 keys presses possible
+  uint16_t keys[4];
+  struct {
+    uint16_t key1;
+    uint16_t key2;
+    uint16_t key3;
+    uint16_t key4;
+  };
+} HID_ConsumerControlReport_Data_t;
+
+
+class ConsumerControl_ {
+ public:
+  ConsumerControl_();
+  void begin();
+  void end();
+  void write(uint16_t m);
+  void press(uint16_t m);
+  void release(uint16_t m);
+  void releaseAll();
+
+  // Sending is public in the base class for advanced users.
+  void sendReport();
+
+ protected:
+  HID_ConsumerControlReport_Data_t report_;
+  HID_ConsumerControlReport_Data_t last_report_;
+
+ private:
+  void sendReportUnchecked();
+};
+extern ConsumerControl_ ConsumerControl;

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Gamepad.cpp

@@ -0,0 +1,157 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Gamepad.h"
+
+#include <Arduino.h>  // for PROGMEM
+#include <string.h>   // for memset
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/DescriptorPrimitives.h"  // for D_USAGE, D_ABSO...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"          // for HID_REPORTID_GA...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID_.h"                  // for HID, HID_, HIDS...
+
+static const uint8_t gamepad_hid_descriptor_[] PROGMEM = {
+  // clang-format off
+  // Gamepad with 32 buttons and 6 axis
+  D_USAGE_PAGE, D_PAGE_GENERIC_DESKTOP,         // USAGE_PAGE (Generic Desktop)
+  D_USAGE, D_USAGE_JOYSTICK,                    // USAGE (Joystick)
+  D_COLLECTION, D_APPLICATION,                  // COLLECTION (Application)
+  D_REPORT_ID, HID_REPORTID_GAMEPAD,            // REPORT_ID
+  // 32 Buttons
+  D_USAGE_PAGE, D_PAGE_BUTTON,                  // USAGE_PAGE (Button)
+  D_USAGE_MINIMUM, 0x01,                        // USAGE_MINIMUM (Button 1)
+  D_USAGE_MAXIMUM, 0x20,                        // USAGE_MAXIMUM (Button 32)
+  D_LOGICAL_MINIMUM, 0x00,                      // LOGICAL_MINIMUM (0)
+  D_LOGICAL_MAXIMUM, 0x01,                      // LOGICAL_MAXIMUM (1)
+  D_REPORT_SIZE, 0x01,                          // REPORT_SIZE (1)
+  D_REPORT_COUNT, 0x20,                         // REPORT_COUNT (32)
+  D_INPUT, (D_DATA | D_VARIABLE | D_ABSOLUTE),  // INPUT (Data,Var,Abs)
+  // 4 16bit Axis
+  D_USAGE_PAGE, D_PAGE_GENERIC_DESKTOP,         // USAGE_PAGE (Generic Desktop)
+  D_COLLECTION, D_PHYSICAL,                     // COLLECTION (Physical)
+  D_USAGE, 0x30,                                // USAGE (X)
+  D_USAGE, 0x31,                                // USAGE (Y)
+  D_USAGE, 0x33,                                // USAGE (Rx)
+  D_USAGE, 0x34,                                // USAGE (Ry)
+  D_MULTIBYTE(D_LOGICAL_MINIMUM), 0x00, 0x80,   // LOGICAL_MINIMUM (-32768)
+  D_MULTIBYTE(D_LOGICAL_MAXIMUM), 0xFF, 0x7F,   // LOGICAL_MAXIMUM (32767)
+  D_REPORT_SIZE, 0x10,                          // REPORT_SIZE (16)
+  D_REPORT_COUNT, 0x04,                         // REPORT_COUNT (4)
+  D_INPUT, (D_DATA | D_VARIABLE | D_ABSOLUTE),  // INPUT (Data,Var,Abs)
+  // 2 8bit Axis
+  D_USAGE, 0x32,                                // USAGE (Z)
+  D_USAGE, 0x35,                                // USAGE (Rz)
+  D_LOGICAL_MINIMUM, 0x80,                      // LOGICAL_MINIMUM (-128)
+  D_LOGICAL_MAXIMUM, 0x7F,                      // LOGICAL_MAXIMUM (127)
+  D_REPORT_SIZE, 0x08,                          // REPORT_SIZE (8)
+  D_REPORT_COUNT, 0x02,                         // REPORT_COUNT (2)
+  D_INPUT, (D_DATA | D_VARIABLE | D_ABSOLUTE),  // INPUT (Data,Var,Abs)
+  D_END_COLLECTION,                             // END_COLLECTION
+  // 2 Hat Switches
+  D_USAGE_PAGE, D_PAGE_GENERIC_DESKTOP,         // USAGE_PAGE (Generic Desktop)
+  D_USAGE, 0x39,                                // USAGE (Hat switch)
+  D_USAGE, 0x39,                                // USAGE (Hat switch)
+  D_LOGICAL_MINIMUM, 0x01,                      // LOGICAL_MINIMUM (1)
+  D_LOGICAL_MAXIMUM, 0x08,                      // LOGICAL_MAXIMUM (8)
+  D_REPORT_COUNT, 0x02,                         // REPORT_COUNT (2)
+  D_REPORT_SIZE, 0x04,                          // REPORT_SIZE (4)
+  D_INPUT, (D_DATA | D_VARIABLE | D_ABSOLUTE),  // INPUT (Data,Var,Abs)
+  D_END_COLLECTION                              // END_COLLECTION
+  // clang-format on
+};
+
+Gamepad_::Gamepad_() {
+  static HIDSubDescriptor node(gamepad_hid_descriptor_,
+                               sizeof(gamepad_hid_descriptor_));
+  HID().AppendDescriptor(&node);
+}
+
+void Gamepad_::begin() {
+  // release all buttons
+  end();
+}
+
+void Gamepad_::end() {
+  memset(&report_, 0x00, sizeof(report_));
+  sendReport(&report_, sizeof(report_));
+}
+
+void Gamepad_::write() {
+  sendReport(&report_, sizeof(report_));
+}
+
+void Gamepad_::press(uint8_t b) {
+  report_.buttons |= (uint32_t)1 << (b - 1);
+}
+
+void Gamepad_::release(uint8_t b) {
+  report_.buttons &= ~((uint32_t)1 << (b - 1));
+}
+
+void Gamepad_::releaseAll() {
+  memset(&report_, 0x00, sizeof(report_));
+}
+
+void Gamepad_::buttons(uint32_t b) {
+  report_.buttons = b;
+}
+
+void Gamepad_::xAxis(int16_t a) {
+  report_.xAxis = a;
+}
+
+void Gamepad_::yAxis(int16_t a) {
+  report_.yAxis = a;
+}
+
+void Gamepad_::zAxis(int8_t a) {
+  report_.zAxis = a;
+}
+
+void Gamepad_::rxAxis(int16_t a) {
+  report_.rxAxis = a;
+}
+
+void Gamepad_::ryAxis(int16_t a) {
+  report_.ryAxis = a;
+}
+
+void Gamepad_::rzAxis(int8_t a) {
+  report_.rzAxis = a;
+}
+
+void Gamepad_::dPad1(int8_t d) {
+  report_.dPad1 = d;
+}
+
+void Gamepad_::dPad2(int8_t d) {
+  report_.dPad2 = d;
+}
+
+void Gamepad_::sendReport(void *data, int length) {
+  HID().SendReport(HID_REPORTID_GAMEPAD, data, length);
+}
+
+Gamepad_ Gamepad;

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Gamepad.h

@@ -0,0 +1,124 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+// Include guard
+#pragma once
+
+#include <stdint.h>  // for uint8_t, int16_t, int8_t, uint32_t
+
+// Dpad directions
+#define GAMEPAD_DPAD_CENTERED   0
+#define GAMEPAD_DPAD_UP         1
+#define GAMEPAD_DPAD_UP_RIGHT   2
+#define GAMEPAD_DPAD_RIGHT      3
+#define GAMEPAD_DPAD_DOWN_RIGHT 4
+#define GAMEPAD_DPAD_DOWN       5
+#define GAMEPAD_DPAD_DOWN_LEFT  6
+#define GAMEPAD_DPAD_LEFT       7
+#define GAMEPAD_DPAD_UP_LEFT    8
+
+
+typedef union {
+  // 32 Buttons, 6 Axis, 2 D-Pads
+  uint32_t buttons;
+
+  struct {
+    uint8_t button1 : 1;
+    uint8_t button2 : 1;
+    uint8_t button3 : 1;
+    uint8_t button4 : 1;
+    uint8_t button5 : 1;
+    uint8_t button6 : 1;
+    uint8_t button7 : 1;
+    uint8_t button8 : 1;
+
+    uint8_t button9 : 1;
+    uint8_t button10 : 1;
+    uint8_t button11 : 1;
+    uint8_t button12 : 1;
+    uint8_t button13 : 1;
+    uint8_t button14 : 1;
+    uint8_t button15 : 1;
+    uint8_t button16 : 1;
+
+    uint8_t button17 : 1;
+    uint8_t button18 : 1;
+    uint8_t button19 : 1;
+    uint8_t button20 : 1;
+    uint8_t button21 : 1;
+    uint8_t button22 : 1;
+    uint8_t button23 : 1;
+    uint8_t button24 : 1;
+
+    uint8_t button25 : 1;
+    uint8_t button26 : 1;
+    uint8_t button27 : 1;
+    uint8_t button28 : 1;
+    uint8_t button29 : 1;
+    uint8_t button30 : 1;
+    uint8_t button31 : 1;
+    uint8_t button32 : 1;
+
+    int16_t xAxis;
+    int16_t yAxis;
+
+    int16_t rxAxis;
+    int16_t ryAxis;
+
+    int8_t zAxis;
+    int8_t rzAxis;
+
+    uint8_t dPad1 : 4;
+    uint8_t dPad2 : 4;
+  };
+} HID_GamepadReport_Data_t;
+
+class Gamepad_ {
+ public:
+  Gamepad_();
+
+  void begin();
+  void end();
+  void write();
+  void press(uint8_t b);
+  void release(uint8_t b);
+  void releaseAll();
+
+  void buttons(uint32_t b);
+  void xAxis(int16_t a);
+  void yAxis(int16_t a);
+  void zAxis(int8_t a);
+  void rxAxis(int16_t a);
+  void ryAxis(int16_t a);
+  void rzAxis(int8_t a);
+  void dPad1(int8_t d);
+  void dPad2(int8_t d);
+
+  void sendReport(void *data, int length);
+
+ protected:
+  HID_GamepadReport_Data_t report_;
+};
+extern Gamepad_ Gamepad;

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Keyboard.cpp

@@ -0,0 +1,284 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Keyboard.h"
+
+#include <Arduino.h>  // for PROGMEM, byte
+#include <string.h>   // for memcmp, memcpy
+
+#include "kaleidoscope/HIDTables.h"                                       // for HID_KEYBOARD_A_...
+#include "kaleidoscope/driver/hid/keyboardio/usb/DescriptorPrimitives.h"  // for D_REPORT_COUNT
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"          // for HID_REPORTID_NK...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HIDAliases.h"            // for HID_KEYBOARD_FI...
+
+static const uint8_t nkro_keyboard_hid_descriptor_[] PROGMEM = {
+  // clang-format off
+  // NKRO Keyboard
+  D_USAGE_PAGE, D_PAGE_GENERIC_DESKTOP,
+  D_USAGE, D_USAGE_KEYBOARD,
+  D_COLLECTION, D_APPLICATION,
+  D_REPORT_ID, HID_REPORTID_NKRO_KEYBOARD,
+  D_USAGE_PAGE, D_PAGE_KEYBOARD,
+
+  // Key modifier byte
+  D_USAGE_MINIMUM, HID_KEYBOARD_FIRST_MODIFIER,
+  D_USAGE_MAXIMUM, HID_KEYBOARD_LAST_MODIFIER,
+  D_LOGICAL_MINIMUM, 0x00,
+  D_LOGICAL_MAXIMUM, 0x01,
+  D_REPORT_SIZE, 0x01,
+  D_REPORT_COUNT, 0x08,
+  D_INPUT, (D_DATA | D_VARIABLE | D_ABSOLUTE),
+
+  // 5 LEDs for num lock etc, 3 left for advanced, custom usage
+  D_USAGE_PAGE, D_PAGE_LEDS,
+  D_USAGE_MINIMUM, 0x01,
+  D_USAGE_MAXIMUM, 0x08,
+  D_REPORT_COUNT, 0x08,
+  D_REPORT_SIZE, 0x01,
+  D_OUTPUT, (D_DATA | D_VARIABLE | D_ABSOLUTE),
+
+  // NKRO Keyboard
+  D_USAGE_PAGE, D_PAGE_KEYBOARD,
+
+  // Padding 4 bits, to skip NO_EVENT & 3 error states.
+  D_REPORT_SIZE, 0x04,
+  D_REPORT_COUNT, 0x01,
+  D_INPUT, (D_CONSTANT),
+
+  D_USAGE_MINIMUM, HID_KEYBOARD_A_AND_A,
+  D_USAGE_MAXIMUM, HID_LAST_KEY,
+  D_LOGICAL_MINIMUM, 0x00,
+  D_LOGICAL_MAXIMUM, 0x01,
+  D_REPORT_SIZE, 0x01,
+  D_REPORT_COUNT, (HID_LAST_KEY - HID_KEYBOARD_A_AND_A),
+  D_INPUT, (D_DATA | D_VARIABLE | D_ABSOLUTE),
+
+  // Padding (3 bits) to round up the report to byte boundary.
+  D_REPORT_SIZE, 0x03,
+  D_REPORT_COUNT, 0x01,
+  D_INPUT, (D_CONSTANT),
+
+  D_END_COLLECTION,
+  // clang-format on
+};
+
+Keyboard_::Keyboard_() {
+  static HIDSubDescriptor node(nkro_keyboard_hid_descriptor_,
+                               sizeof(nkro_keyboard_hid_descriptor_));
+  HID().AppendDescriptor(&node);
+}
+
+void Keyboard_::begin() {
+  // Force API to send a clean report.  This is important for and HID bridge
+  // where the receiver stays on, while the sender is resetted.
+  releaseAll();
+  sendReportUnchecked();
+}
+
+
+void Keyboard_::end() {
+  releaseAll();
+  sendReportUnchecked();
+}
+
+int Keyboard_::sendReportUnchecked() {
+  return HID().SendReport(HID_REPORTID_NKRO_KEYBOARD,
+                          &last_report_,
+                          sizeof(last_report_));
+}
+
+// Sending the current HID report to the host:
+//
+// Depending on the differences between the current and previous HID reports, we
+// might need to send one or two extra reports to guarantee that the host will
+// process the changes in the correct order. There are two important scenarios
+// to consider:
+//
+// 1. If a non-modifier keycode toggles off in the same report as a modifier
+// changes, the host might process the modifier change first. For example, if
+// both `shift` and `4` toggle off in the same report (most likely from a
+// `LSHIFT(Key_4)` key being released), and that key has been held long enough
+// to trigger character repeat, we could end up with a plain `4` in the output
+// at the end of the repeat: `$$$$4` instead of `$$$$$`.
+//
+// 2. If a non-modifier keycode toggles on in the same report as a modifier
+// changes, the host might process the non-modifer first. For example, pressing
+// and holding an `LSHIFT(Key_4)` key might result in `4$$$` rather than `$$$$`.
+//
+// Therefore, each call to `sendReport()` must send (up to) three reports to the
+// host to guarantee the correct order of processing:
+//
+// 1. A report with toggled-off non-modifiers removed.
+// 2. A report with changes to modifiers.
+// 3. A report with toggled-on non-modifiers added.
+
+int Keyboard_::sendReport() {
+  // If the new HID report differs from the previous one both in active modifier
+  // keycodes and non-modifier keycodes, we will need to send at least one extra
+  // report. First, we compare the modifiers bytes of the two reports.
+  const uint8_t old_modifiers = last_report_.modifiers;
+  const uint8_t new_modifiers = report_.modifiers;
+
+  const uint8_t changed_modifiers = old_modifiers ^ new_modifiers;
+
+  if (changed_modifiers != 0) {
+    // There was at least one modifier change (toggled on or off), remove any
+    // non-modifiers from the stored previous report that toggled off in the new
+    // report, and send it to the host.
+    bool non_modifiers_toggled_off = false;
+    for (uint8_t i = 0; i < KEY_BYTES; ++i) {
+      byte released_keycodes = last_report_.keys[i] & ~(report_.keys[i]);
+      if (released_keycodes != 0) {
+        last_report_.keys[i] &= ~released_keycodes;
+        non_modifiers_toggled_off = true;
+      }
+    }
+    if (non_modifiers_toggled_off) {
+      sendReportUnchecked();
+    }
+    // Next, update the modifiers byte of the stored previous report, and send
+    // it.
+    last_report_.modifiers = new_modifiers;
+    sendReportUnchecked();
+  }
+
+  // Finally, copy the new report to the previous one, and send it.
+  if (memcmp(last_report_.keys, report_.keys, sizeof(report_.keys)) != 0) {
+    memcpy(last_report_.keys, report_.keys, sizeof(report_.keys));
+    return sendReportUnchecked();
+  }
+  // A note on return values: Kaleidoscope doesn't actually check the return
+  // value of `sendReport()`, so this function could be changed to return
+  // void. It would be nice if we could do something to recover from an error
+  // here, but it's not at all clear what that should be. Also note that if the
+  // extra reports above return an error, there's not much we can do to try to
+  // recover. We could try to send the report again, but that would be likely to
+  // fail as well.
+  return -1;
+}
+
+/* Returns true if the modifer key passed in will be sent during this key report
+ * Returns false in all other cases
+ * */
+bool Keyboard_::isModifierActive(uint8_t k) {
+  if (k >= HID_KEYBOARD_FIRST_MODIFIER && k <= HID_KEYBOARD_LAST_MODIFIER) {
+    k = k - HID_KEYBOARD_FIRST_MODIFIER;
+    return !!(report_.modifiers & (1 << k));
+  }
+  return false;
+}
+
+/* Returns true if the modifer key passed in was being sent during the previous key report
+ * Returns false in all other cases
+ * */
+bool Keyboard_::wasModifierActive(uint8_t k) {
+  if (k >= HID_KEYBOARD_FIRST_MODIFIER && k <= HID_KEYBOARD_LAST_MODIFIER) {
+    k = k - HID_KEYBOARD_FIRST_MODIFIER;
+    return !!(last_report_.modifiers & (1 << k));
+  }
+  return false;
+}
+
+/* Returns true if *any* modifier will be sent during this key report
+ * Returns false in all other cases
+ * */
+bool Keyboard_::isAnyModifierActive() {
+  return report_.modifiers > 0;
+}
+
+/* Returns true if *any* modifier was being sent during the previous key report
+ * Returns false in all other cases
+ * */
+bool Keyboard_::wasAnyModifierActive() {
+  return last_report_.modifiers > 0;
+}
+
+
+/* Returns true if the non-modifier key passed in will be sent during this key report
+ * Returns false in all other cases
+ * */
+bool Keyboard_::isKeyPressed(uint8_t k) {
+  if (k <= HID_LAST_KEY) {
+    uint8_t bit = 1 << (uint8_t(k) % 8);
+    return !!(report_.keys[k / 8] & bit);
+  }
+  return false;
+}
+
+/* Returns true if the non-modifer key passed in was sent during the previous key report
+ * Returns false in all other cases
+ * */
+bool Keyboard_::wasKeyPressed(uint8_t k) {
+
+  if (k <= HID_LAST_KEY) {
+    uint8_t bit = 1 << (uint8_t(k) % 8);
+    return !!(last_report_.keys[k / 8] & bit);
+  }
+  return false;
+}
+
+
+size_t Keyboard_::press(uint8_t k) {
+  // If the key is in the range of 'printable' keys
+  if (k <= HID_LAST_KEY) {
+    uint8_t bit = 1 << (uint8_t(k) % 8);
+    report_.keys[k / 8] |= bit;
+    return 1;
+  } else if (k >= HID_KEYBOARD_FIRST_MODIFIER && k <= HID_KEYBOARD_LAST_MODIFIER) {
+    // It's a modifier key
+    // Convert key into bitfield (0 - 7)
+    k = k - HID_KEYBOARD_FIRST_MODIFIER;
+    report_.modifiers |= (1 << k);
+    return 1;
+  }
+
+  // No empty/pressed key was found
+  return 0;
+}
+
+size_t Keyboard_::release(uint8_t k) {
+  // If we're releasing a printable key
+  if (k <= HID_LAST_KEY) {
+    uint8_t bit = 1 << (k % 8);
+    report_.keys[k / 8] &= ~bit;
+    return 1;
+  } else if (k >= HID_KEYBOARD_FIRST_MODIFIER && k <= HID_KEYBOARD_LAST_MODIFIER) {
+    // It's a modifier key
+    // Convert key into bitfield (0 - 7)
+    k = k - HID_KEYBOARD_FIRST_MODIFIER;
+    report_.modifiers &= ~(1 << k);
+    return 1;
+  }
+
+  // No empty/pressed key was found
+  return 0;
+}
+
+void Keyboard_::releaseAll() {
+  // Release all keys
+  memset(&report_.allkeys, 0x00, sizeof(report_.allkeys));
+}
+
+Keyboard_ Keyboard;

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Keyboard.h

@@ -0,0 +1,74 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+// Include guard
+#pragma once
+
+#include <stddef.h>  // for size_t
+#include <stdint.h>  // for uint8_t
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID_.h"  // for HID, HID_
+
+#define KEY_BYTES 28
+
+typedef union {
+  // Modifiers + keymap
+  struct {
+    uint8_t modifiers;
+    uint8_t keys[KEY_BYTES];
+  };
+  uint8_t allkeys[1 + KEY_BYTES];
+} HID_KeyboardReport_Data_t;
+
+
+class Keyboard_ {
+ public:
+  Keyboard_();
+  void begin();
+  void end();
+
+  size_t press(uint8_t k);
+  size_t release(uint8_t k);
+  void releaseAll();
+  int sendReport();
+
+  bool isKeyPressed(uint8_t k);
+  bool wasKeyPressed(uint8_t k);
+  bool isModifierActive(uint8_t k);
+  bool wasModifierActive(uint8_t k);
+  bool isAnyModifierActive();
+  bool wasAnyModifierActive();
+
+  uint8_t getLEDs() {
+    return HID().getLEDs();
+  }
+
+ private:
+  HID_KeyboardReport_Data_t report_;
+  HID_KeyboardReport_Data_t last_report_;
+
+  int sendReportUnchecked();
+};
+extern Keyboard_ Keyboard;

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Mouse.cpp

@@ -0,0 +1,151 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Mouse.h"
+
+#include <Arduino.h>  // for PROGMEM
+#include <string.h>   // for memset
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/DescriptorPrimitives.h"  // for D_USAGE, D_USAG...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"          // for HID_REPORTID_MOUSE
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID_.h"                  // for HID, HID_, HIDS...
+
+static const uint8_t mouse_hid_descriptor_[] PROGMEM = {
+  // clang-format off
+  // Mouse relative
+  D_USAGE_PAGE, D_PAGE_GENERIC_DESKTOP,         // USAGE_PAGE (Generic Desktop)
+  D_USAGE, D_USAGE_MOUSE,                       // USAGE (Mouse)
+  D_COLLECTION, D_APPLICATION,                  // COLLECTION (Application)
+  D_REPORT_ID, HID_REPORTID_MOUSE,              // REPORT_ID (Mouse)
+
+  // 8 Buttons
+  D_USAGE_PAGE, D_PAGE_BUTTON,                  // USAGE_PAGE (Button)
+  D_USAGE_MINIMUM, 0x01,                        // USAGE_MINIMUM (Button 1)
+  D_USAGE_MAXIMUM, 0x08,                        // USAGE_MAXIMUM (Button 8)
+  D_LOGICAL_MINIMUM, 0x00,                      // LOGICAL_MINIMUM (0)
+  D_LOGICAL_MAXIMUM, 0x01,                      // LOGICAL_MAXIMUM (1)
+  D_REPORT_COUNT, 0x08,                         // REPORT_COUNT (8)
+  D_REPORT_SIZE, 0x01,                          // REPORT_SIZE (1)
+  D_INPUT, (D_DATA | D_VARIABLE | D_ABSOLUTE),  // INPUT (Data,Var,Abs)
+
+  // X, Y, Wheel
+  D_USAGE_PAGE, D_PAGE_GENERIC_DESKTOP,         // USAGE_PAGE (Generic Desktop)
+  D_USAGE, 0x30,                                // USAGE (X)
+  D_USAGE, 0x31,                                // USAGE (Y)
+  D_USAGE, 0x38,                                // USAGE (Wheel)
+  D_LOGICAL_MINIMUM, 0x81,                      // LOGICAL_MINIMUM (-127)
+  D_LOGICAL_MAXIMUM, 0x7f,                      // LOGICAL_MAXIMUM (127)
+  D_REPORT_SIZE, 0x08,                          // REPORT_SIZE (8)
+  D_REPORT_COUNT, 0x03,                         // REPORT_COUNT (3)
+  D_INPUT, (D_DATA | D_VARIABLE | D_RELATIVE),  // INPUT (Data,Var,Rel)
+
+  // Horizontal wheel
+  D_USAGE_PAGE, D_PAGE_CONSUMER,                // USAGE_PAGE (Consumer)
+  D_PAGE_ORDINAL, 0x38, 0x02,                   // PAGE (AC Pan)
+  D_LOGICAL_MINIMUM, 0x81,                      // LOGICAL_MINIMUM (-127)
+  D_LOGICAL_MAXIMUM, 0x7f,                      // LOGICAL_MAXIMUM (127)
+  D_REPORT_SIZE, 0x08,                          // REPORT_SIZE (8)
+  D_REPORT_COUNT, 0x01,                         // REPORT_COUNT (1)
+  D_INPUT, (D_DATA | D_VARIABLE | D_RELATIVE),  // INPUT (Data,Var,Rel)
+
+  // End
+  D_END_COLLECTION                              // END_COLLECTION
+  // clang-format on
+};
+
+Mouse_::Mouse_() {
+  static HIDSubDescriptor node(mouse_hid_descriptor_,
+                               sizeof(mouse_hid_descriptor_));
+  HID().AppendDescriptor(&node);
+}
+
+void Mouse_::begin() {
+  end();
+}
+
+void Mouse_::end() {
+  releaseAll();
+  sendReport();
+}
+
+void Mouse_::click(uint8_t b) {
+  // If one or more of the buttons to be clicked was already pressed, we need to
+  // send a report to release it first, to guarantee that this will be a "click"
+  // and not merely a release.
+  if (report_.buttons & b) {
+    release(b);
+    sendReport();
+  }
+  // Next, send a report with the button(s) pressed:
+  press(b);
+  sendReport();
+  // Finally, send the report with the button(s) released:
+  release(b);
+  sendReport();
+}
+
+void Mouse_::move(int8_t x, int8_t y, int8_t v_wheel, int8_t h_wheel) {
+  report_.xAxis  = x;
+  report_.yAxis  = y;
+  report_.vWheel = v_wheel;
+  report_.hWheel = h_wheel;
+}
+
+void Mouse_::releaseAll() {
+  memset(&report_, 0, sizeof(report_));
+}
+
+void Mouse_::press(uint8_t b) {
+  report_.buttons |= b;
+}
+
+void Mouse_::release(uint8_t b) {
+  report_.buttons &= ~b;
+}
+
+bool Mouse_::isPressed(uint8_t b) {
+  if ((b & report_.buttons) > 0)
+    return true;
+  return false;
+}
+
+void Mouse_::sendReportUnchecked() {
+  HID().SendReport(HID_REPORTID_MOUSE, &report_, sizeof(report_));
+}
+
+void Mouse_::sendReport() {
+  // If the button state has not changed, and neither the cursor nor the wheel
+  // is being told to move, there is no need to send a report.  This check
+  // prevents us from sending lots of no-op reports if the caller is in a loop
+  // and not checking or buggy.
+  if (report_.buttons != prev_report_buttons_ ||
+      report_.xAxis != 0 || report_.yAxis != 0 ||
+      report_.vWheel != 0 || report_.hWheel != 0) {
+    sendReportUnchecked();
+    prev_report_buttons_ = report_.buttons;
+  }
+}
+
+Mouse_ Mouse;

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Mouse.h

@@ -0,0 +1,79 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+// Include guard
+#pragma once
+
+#include <stdint.h>  // for int8_t, uint8_t
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/MouseButtons.h"  // for MOUSE_LEFT
+
+typedef union {
+  // Mouse report: 8 buttons, position, wheel
+  struct {
+    uint8_t buttons;
+    int8_t xAxis;
+    int8_t yAxis;
+    int8_t vWheel;
+    int8_t hWheel;
+  };
+} HID_MouseReport_Data_t;
+
+
+class Mouse_ {
+ public:
+  Mouse_();
+  void begin();
+  void end();
+  // Note: the following `click()` method is unlike the `move()`, `press()`, and
+  // `release()` methods, in that it doesn't merely modify the pending report,
+  // but also calls `sendReport()` at least twice.
+  void click(uint8_t b = MOUSE_LEFT);
+  void move(int8_t x, int8_t y, int8_t v_wheel = 0, int8_t h_wheel = 0);
+  void press(uint8_t b = MOUSE_LEFT);      // press LEFT by default
+  void release(uint8_t b = MOUSE_LEFT);    // release LEFT by default
+  bool isPressed(uint8_t b = MOUSE_LEFT);  // check LEFT by default
+
+  /** getReport returns the current report.
+   *
+   * The current report is the one to be send next time sendReport() is called.
+   *
+   * @returns A copy of the report.
+   */
+  const HID_MouseReport_Data_t getReport() {
+    return report_;
+  }
+  void sendReport();
+
+  void releaseAll();
+
+ protected:
+  HID_MouseReport_Data_t report_;
+  uint8_t prev_report_buttons_ = 0;
+
+ private:
+  void sendReportUnchecked();
+};
+extern Mouse_ Mouse;

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/SystemControl.cpp

@@ -0,0 +1,105 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/SystemControl.h"
+
+#include <Arduino.h>  // for PROGMEM
+
+#include "kaleidoscope/HIDTables.h"                                       // for HID_SYSTEM_WAKE_UP
+#include "kaleidoscope/driver/hid/keyboardio/usb/DescriptorPrimitives.h"  // for D_ABSOLUTE, D_A...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"          // for HID_REPORTID_SY...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID_.h"                  // for HID, HID_, HIDS...
+
+static const uint8_t system_control_hid_descriptor_[] PROGMEM = {
+  // clang-format off
+  // TODO(anyone) limit to system keys only?
+  // System Control (Power Down, Sleep, Wakeup, ...)
+  D_USAGE_PAGE, D_PAGE_GENERIC_DESKTOP,        // USAGE_PAGE (Generic Desktop)
+  D_USAGE, 0x80,                               // USAGE (System Control)
+  D_COLLECTION, D_APPLICATION,                 // COLLECTION (Application)
+  D_REPORT_ID, HID_REPORTID_SYSTEMCONTROL,     // REPORT_ID
+  // 1 system key
+  D_LOGICAL_MINIMUM, 0x00,                     // LOGICAL_MINIMUM (0)
+  D_MULTIBYTE(D_LOGICAL_MAXIMUM), 0xff, 0x00,  // LOGICAL_MAXIMUM (255)
+  D_USAGE_MINIMUM, 0x00,                       // USAGE_MINIMUM (Undefined)
+  D_USAGE_MAXIMUM, 0xff,                       // USAGE_MAXIMUM (System Menu Down)
+  D_REPORT_COUNT, 0x01,                        // REPORT_COUNT (1)
+  D_REPORT_SIZE, 0x08,                         // REPORT_SIZE (8)
+  D_INPUT, (D_DATA | D_ARRAY | D_ABSOLUTE),    // INPUT (Data,Ary,Abs)
+  D_END_COLLECTION                             // END_COLLECTION
+  // clang-format on
+};
+
+SystemControl_::SystemControl_() {
+  static HIDSubDescriptor node(system_control_hid_descriptor_,
+                               sizeof(system_control_hid_descriptor_));
+  HID().AppendDescriptor(&node);
+}
+
+void SystemControl_::begin() {
+  // release all buttons
+  end();
+}
+
+void SystemControl_::end() {
+  uint8_t report = 0x00;
+  sendReport(&report, sizeof(report));
+}
+
+void SystemControl_::write(uint8_t s) {
+  press(s);
+  release();
+}
+
+void SystemControl_::release() {
+  begin();
+}
+
+void SystemControl_::releaseAll() {
+  begin();
+}
+
+void SystemControl_::press(uint8_t s) {
+  if (s == HID_SYSTEM_WAKE_UP) {
+#ifdef __AVR__
+    USBDevice.wakeupHost();
+#endif
+#ifdef ARDUINO_ARCH_SAMD
+    // This is USBDevice_SAMD21G18x.wakeupHost(). But we can't include that
+    // header, because it redefines a few symbols, and causes linking
+    // errors. So we simply reimplement the same thing here.
+    USB->DEVICE.CTRLB.bit.UPRSM = 1;
+#endif
+  } else {
+    sendReport(&s, sizeof(s));
+  }
+}
+
+
+void SystemControl_::sendReport(void *data, int length) {
+  HID().SendReport(HID_REPORTID_SYSTEMCONTROL, data, length);
+}
+
+SystemControl_ SystemControl;

src/kaleidoscope/driver/hid/keyboardio/usb/MultiReport/SystemControl.h

@@ -0,0 +1,53 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+// Include guard
+#pragma once
+
+#include <stdint.h>  // for uint8_t
+
+typedef union {
+  // Every usable system control key possible
+  uint8_t key;
+} HID_SystemControlReport_Data_t;
+
+
+class SystemControl_ {
+ public:
+  void begin();
+  void end();
+  void write(uint8_t s);
+  void press(uint8_t s);
+  void release();
+  void releaseAll();
+  void sendReport(void *data, int length);
+
+  SystemControl_();
+
+ protected:
+};
+
+
+extern SystemControl_ SystemControl;

src/kaleidoscope/driver/hid/keyboardio/usb/SingleReport/SingleAbsoluteMouse.cpp

@@ -0,0 +1,137 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/SingleReport/SingleAbsoluteMouse.h"
+
+#include <Arduino.h>  // for PROGMEM
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/DescriptorPrimitives.h"         // for D_APPLIC...
+#include "kaleidoscope/driver/hid/keyboardio/usb/DeviceAPIs/AbsoluteMouseAPI.h"  // for Absolute...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HIDReportObserver.h"            // for HIDRepor...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID_.h"                         // for HIDDescr...
+
+static const uint8_t _hidSingleReportDescriptorAbsoluteMouse[] PROGMEM = {
+  // clang-format off
+  D_USAGE_PAGE, D_PAGE_GENERIC_DESKTOP,  // USAGE_PAGE (Generic Desktop) 54
+  D_USAGE, D_USAGE_MOUSE,                // USAGE (Mouse)
+  D_COLLECTION, D_APPLICATION,           // COLLECTION (Application)
+
+  DESCRIPTOR_ABS_MOUSE_BUTTONS
+  DESCRIPTOR_ABS_MOUSE_XY
+  DESCRIPTOR_ABS_MOUSE_WHEEL
+  D_END_COLLECTION                       // End
+  // clang-format on
+};
+
+#ifdef ARCH_HAS_CONFIGURABLE_EP_SIZES
+static const uint8_t SINGLE_ABSOLUTEMOUSE_EP_SIZE = 6;
+#else
+static const uint8_t SINGLE_ABSOLUTEMOUSE_EP_SIZE = USB_EP_SIZE;
+#endif
+
+
+SingleAbsoluteMouse_::SingleAbsoluteMouse_()
+  : PluggableUSBModule(1, 1, epType), protocol(HID_REPORT_PROTOCOL), idle(1) {
+
+#ifdef ARCH_HAS_CONFIGURABLE_EP_SIZES
+  epType[0] = EP_TYPE_INTERRUPT_IN(SINGLE_ABSOLUTEMOUSE_EP_SIZE);
+#else
+  epType[0] = EP_TYPE_INTERRUPT_IN;
+#endif
+
+  PluggableUSB().plug(this);
+}
+
+int SingleAbsoluteMouse_::getInterface(uint8_t *interfaceCount) {
+  *interfaceCount += 1;  // uses 1
+  HIDDescriptor hidInterface = {
+    D_INTERFACE(pluggedInterface, 1, USB_DEVICE_CLASS_HUMAN_INTERFACE, HID_SUBCLASS_NONE, HID_PROTOCOL_NONE),
+    D_HIDREPORT(sizeof(_hidSingleReportDescriptorAbsoluteMouse)),
+    D_ENDPOINT(USB_ENDPOINT_IN(pluggedEndpoint), USB_ENDPOINT_TYPE_INTERRUPT, SINGLE_ABSOLUTEMOUSE_EP_SIZE, 0x01)};
+  return USB_SendControl(0, &hidInterface, sizeof(hidInterface));
+}
+
+int SingleAbsoluteMouse_::getDescriptor(USBSetup &setup) {
+  // Check if this is a HID Class Descriptor request
+  if (setup.bmRequestType != REQUEST_DEVICETOHOST_STANDARD_INTERFACE) {
+    return 0;
+  }
+  if (setup.wValueH != HID_REPORT_DESCRIPTOR_TYPE) {
+    return 0;
+  }
+
+  // In a HID Class Descriptor wIndex cointains the interface number
+  if (setup.wIndex != pluggedInterface) {
+    return 0;
+  }
+
+  // Reset the protocol on reenumeration. Normally the host should not assume the state of the protocol
+  // due to the USB specs, but Windows and Linux just assumes its in report mode.
+  protocol = HID_REPORT_PROTOCOL;
+
+  return USB_SendControl(TRANSFER_PGM, _hidSingleReportDescriptorAbsoluteMouse, sizeof(_hidSingleReportDescriptorAbsoluteMouse));
+}
+
+bool SingleAbsoluteMouse_::setup(USBSetup &setup) {
+  if (pluggedInterface != setup.wIndex) {
+    return false;
+  }
+
+  uint8_t request     = setup.bRequest;
+  uint8_t requestType = setup.bmRequestType;
+
+  if (requestType == REQUEST_DEVICETOHOST_CLASS_INTERFACE) {
+    if (request == HID_GET_REPORT) {
+      // TODO(anyone): HID_GetReport();
+      return true;
+    }
+    if (request == HID_GET_PROTOCOL) {
+      // TODO(anyone): Send8(protocol);
+      return true;
+    }
+  }
+
+  if (requestType == REQUEST_HOSTTODEVICE_CLASS_INTERFACE) {
+    if (request == HID_SET_PROTOCOL) {
+      protocol = setup.wValueL;
+      return true;
+    }
+    if (request == HID_SET_IDLE) {
+      idle = setup.wValueL;
+      return true;
+    }
+    if (request == HID_SET_REPORT) {
+    }
+  }
+
+  return false;
+}
+
+void SingleAbsoluteMouse_::sendReport(void *data, int length) {
+  auto result = USB_Send(pluggedEndpoint | TRANSFER_RELEASE, data, length);
+  HIDReportObserver::observeReport(HID_REPORTID_MOUSE_ABSOLUTE, data, length, result);
+}
+
+SingleAbsoluteMouse_ SingleAbsoluteMouse;

src/kaleidoscope/driver/hid/keyboardio/usb/SingleReport/SingleAbsoluteMouse.h

@@ -0,0 +1,53 @@
+/*
+Copyright (c) 2014-2015 NicoHood
+Copyright (c) 2015-2018 Keyboard.io, Inc
+
+See the readme for credit to other people.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+// Include guard
+#pragma once
+
+#include <stdint.h>  // for uint8_t
+
+#include "kaleidoscope/driver/hid/keyboardio/usb/DeviceAPIs/AbsoluteMouseAPI.h"  // for Absolute...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"                 // for USBSetup
+
+
+class SingleAbsoluteMouse_ : public PluggableUSBModule, public AbsoluteMouseAPI {
+ public:
+  SingleAbsoluteMouse_();
+  uint8_t getLeds();
+  uint8_t getProtocol();
+
+ protected:
+  // Implementation of the PUSBListNode
+  int getInterface(uint8_t *interfaceCount);
+  int getDescriptor(USBSetup &setup);
+  bool setup(USBSetup &setup);
+
+  EPTYPE_DESCRIPTOR_SIZE epType[1];
+  uint8_t protocol;
+  uint8_t idle;
+
+  inline void sendReport(void *data, int length) override;
+};
+extern SingleAbsoluteMouse_ SingleAbsoluteMouse;

src/kaleidoscope/driver/hid/keyboardio/usb/arch/avr.cpp

@@ -0,0 +1,8 @@
+#include <Arduino.h>  // IWYU pragma: keep
+
+#ifdef ARDUINO_ARCH_AVR
+
+void USB_PackMessages(bool pack) {
+}
+
+#endif

src/kaleidoscope/driver/hid/keyboardio/usb/arch/gd32.cpp

@@ -0,0 +1,8 @@
+#include <Arduino.h>  // IWYU pragma: keep
+
+#ifdef ARDUINO_ARCH_GD32
+
+void USB_PackMessages(bool pack) {
+}
+
+#endif

src/kaleidoscope/driver/hid/keyboardio/usb/arch/samd.cpp

@@ -0,0 +1,17 @@
+#include <Arduino.h>  // IWYU pragma: keep
+
+#ifdef ARDUINO_ARCH_SAMD
+
+int USB_SendControl(void *b, unsigned char c) {
+  USBDevice.sendControl(b, c);
+}
+
+int USB_SendControl(uint8_t a, const void *b, uint8_t c) {
+  USBDevice.sendControl(b, c);
+}
+
+void USB_PackMessages(bool pack) {
+  USBDevice.packMessages(pack);
+}
+
+#endif

testing/AbsoluteMouseReport.cpp

@@ -19,8 +19,8 @@
 #include <cstring>  // for memcpy
 #include <vector>   // for vector
 
-#include "MouseButtons.h"          // for MOUSE_LEFT, MOUSE_MIDDLE, MOUSE_NEXT, MOUSE_PREV, MOUS...
+#include "kaleidoscope/Runtime.h"                                 // for Runtime, Runtime_
-#include "kaleidoscope/Runtime.h"  // for Runtime, Runtime_
+#include "kaleidoscope/driver/hid/keyboardio/usb/MouseButtons.h"  // for MOUSE_LEFT, MOUSE_MIDDLE
 
 namespace kaleidoscope {
 namespace testing {

testing/AbsoluteMouseReport.h

@@ -16,11 +16,11 @@
 
 #pragma once
 
-#include <cstdint>  // for uint16_t, uint32_t, uint8_t, int8_t
+#include <cstdint>  // for uint16_t
 #include <vector>   // for vector
 
-#include "DeviceAPIs/AbsoluteMouseAPI.h"  // for HID_MouseAbsoluteReport_Data_t
+#include "kaleidoscope/driver/hid/keyboardio/usb/DeviceAPIs/AbsoluteMouseAPI.h"  // for HID_Mous...
-#include "HID-Settings.h"                 // for HID_REPORTID_MOUSE_ABSOLUTE
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"                 // for HID_REPO...
 
 namespace kaleidoscope {
 namespace testing {

testing/ConsumerControlReport.h

@@ -16,11 +16,11 @@
 
 #pragma once
 
-#include <cstdint>  // for uint32_t, uint16_t, uint8_t
+#include <cstdint>  // for uint32_t
 #include <vector>   // for vector
 
-#include "HID-Settings.h"                 // for HID_REPORTID_CONSUMERCONTROL
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"                 // for HID_REPO...
-#include "MultiReport/ConsumerControl.h"  // for HID_ConsumerControlReport_Data_t
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/ConsumerControl.h"  // for HID_Cons...
 
 namespace kaleidoscope {
 namespace testing {

testing/ExpectedMouseReport.cpp

@@ -16,8 +16,8 @@
 
 #include "testing/ExpectedMouseReport.h"
 
-#include "MultiReport/Mouse.h"    // for (anonymous union)::(anonymous)
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Mouse.h"  // for (anonymous union):...
-#include "testing/MouseReport.h"  // for MouseReport::ReportData
+#include "testing/MouseReport.h"                                       // for MouseReport::Repor...
 
 namespace kaleidoscope {
 namespace testing {

testing/HIDState.cpp

@@ -21,8 +21,8 @@
 #include <utility>  // IWYU pragma: keep
 #include <vector>   // for vector
 
-#include "HID-Settings.h"      // for HID_REPORTID_CONSUMERCONTROL, HID_REPORTID_GAMEPAD, HID_RE...
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"  // for HID_REPORTID_CONSUMERCO...
-#include "testing/iostream.h"  // for operator<<, char_traits, cout, ostream, basic_ostream
+#include "testing/iostream.h"                                     // for operator<<, char_traits
 
 #define LOG(x) std::cout
 

testing/KeyboardReport.h

@@ -19,8 +19,8 @@
 #include <cstdint>  // for uint8_t, uint32_t
 #include <vector>   // for vector
 
-#include "HID-Settings.h"          // for HID_REPORTID_NKRO_KEYBOARD
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"          // for HID_REPORTID_NK...
-#include "MultiReport/Keyboard.h"  // for HID_KeyboardReport_Data_t
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Keyboard.h"  // for HID_KeyboardRep...
 
 namespace kaleidoscope {
 namespace testing {

testing/MouseReport.h

@@ -16,11 +16,11 @@
 
 #pragma once
 
-#include <cstdint>  // for uint8_t, int8_t, uint32_t
+#include <cstdint>  // for uint8_t, int8_t
 
-#include "HID-Settings.h"       // for HID_REPORTID_MOUSE
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"       // for HID_REPORTID_MOUSE
-#include "MouseButtons.h"       // for MOUSE_LEFT, MOUSE_MIDDLE, MOUSE_NEXT, MOUSE_PREV, MOUSE_R...
+#include "kaleidoscope/driver/hid/keyboardio/usb/MouseButtons.h"       // for MOUSE_LEFT, MOUSE_...
-#include "MultiReport/Mouse.h"  // for HID_MouseReport_Data_t
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/Mouse.h"  // for HID_MouseReport_Da...
 
 namespace kaleidoscope {
 namespace testing {

testing/SystemControlReport.h

@@ -16,11 +16,11 @@
 
 #pragma once
 
-#include <cstdint>  // for uint8_t, uint32_t
+#include <cstdint>  // for uint8_t
 #include <vector>   // for vector
 
-#include "HID-Settings.h"               // for HID_REPORTID_SYSTEMCONTROL
+#include "kaleidoscope/driver/hid/keyboardio/usb/HID-Settings.h"               // for HID_REPORT...
-#include "MultiReport/SystemControl.h"  // for HID_SystemControlReport_Data_t
+#include "kaleidoscope/driver/hid/keyboardio/usb/MultiReport/SystemControl.h"  // for HID_System...
 
 namespace kaleidoscope {
 namespace testing {

testing/VirtualDeviceTest.cpp

@@ -22,13 +22,13 @@
 #include <bitset>  // for bitset
 #include <vector>  // for vector
 
-#include "HIDReportObserver.h"       // for HIDReportObserver
+#include "kaleidoscope/Runtime.h"                                      // for Runtime, Runtime_
-#include "kaleidoscope/Runtime.h"    // for Runtime, Runtime_
+#include "kaleidoscope/driver/hid/keyboardio/usb/HIDReportObserver.h"  // for HIDReportObserver
-#include "testing/HIDState.h"        // for HIDState, HIDStateBuilder
+#include "testing/HIDState.h"                                          // for HIDState, HIDState...
-#include "testing/KeyboardReport.h"  // for KeyboardReport
+#include "testing/KeyboardReport.h"                                    // for KeyboardReport
-#include "testing/MouseReport.h"     // for MouseReport
+#include "testing/MouseReport.h"                                       // for MouseReport
-#include "testing/gtest.h"           // for Message, TestPartResult, EXPECT_EQ, ElementsAreArray
+#include "testing/gtest.h"                                             // for Message, TestPartR...
-#include "testing/iostream.h"        // for operator<<, basic_ostream, char_traits, string, cerr
+#include "testing/iostream.h"                                          // for operator<<, char_t...
 
 namespace kaleidoscope {
 namespace testing {

testing/makefiles/shared.mk

@@ -16,7 +16,6 @@ shared_includes := \
 		-I${top_dir}/src \
 		-I${top_dir}/plugins/Kaleidoscope-Hardware-Keyboardio-Model01/src \
 		-I${arduino_platform_path}/cores/arduino \
-		-I${arduino_platform_path}/libraries/KeyboardioHID/src \
 		-I${top_dir}/testing/googletest/googlemock/include \
 		-I${top_dir}/testing/googletest/googletest/include \