Merge pull request #333 from keyboardio/f/attach-detach

Wrap KeyboardHardware.detachFromHost and .attachToHost

UPGRADING.md

@@ -28,6 +28,18 @@ While `millis()` should continue to work forever, plugins and user code should,
 as a general rule, use `Kaleidoscope.millisAtCycleStart()` rather than
 `millis()`.
 
+### Kaleidoscope.detachFromHost() and Kaleidoscope.attachToHost()
+
+These two require changes to the Hardware plugins, as they wrap functionality
+provided by it. The intent of these methods is to allow one to apply some
+configuration changes between detach and attach - because we only sever the link
+between device and host, power remains connected, and the device does not
+reboot. A quick way to re-initialize the endpoints.
+
+See the [Kaleidoscope-USB-Quriks][plugin:USB-Quriks] plugin for a use-case.
+
+ [plugin:USB-Quirks]: https://github.com/keyboardio/Kaleidoscope-USB-Quirks
+
 ### KALEIDOSCOPE_API_VERSION bump
 
 `KALEIDOSCOPE_API_VERSION` has been bumped to **2** due to the plugin API

src/Kaleidoscope.h

@@ -82,6 +82,25 @@ class Kaleidoscope_ {
   void setup(void);
   void loop(void);
 
+  /** Detaching from / attaching to the host.
+   *
+   * These two functions wrap the hardware plugin's similarly named functions.
+   * We wrap them, because we'd like plugins and user-code not having to use
+   * `KeyboardHardware` directly.
+   *
+   * The methods themselves implement detaching from / attaching to the host,
+   * without rebooting the device, and remaining powered in between.
+   *
+   * Intended to be used in cases where we want to change some settings between
+   * detach and attach.
+   */
+  void detachFromHost() {
+    KeyboardHardware.detachFromHost();
+  }
+  void attachToHost() {
+    KeyboardHardware.attachToHost();
+  }
+
   /** Returns the timer as it was at the start of the cycle.
    * The goal of this method is two-fold:
    *  - To reduce the amount of calls to millis(), providing something cheaper.