From f2316c51144658f9c6bf3afaa32a15ddc5515378 Mon Sep 17 00:00:00 2001
From: Gergely Nagy <algernon@keyboard.io>
Date: Fri, 8 Jun 2018 08:04:51 +0200
Subject: [PATCH] Wrap KeyboardHardware.detachFromHost and .attachToHost

We do not want user code having to deal with KeyboardHardware, so wrap
.detachFromHost and .attachToHost ourselves.

Signed-off-by: Gergely Nagy <algernon@keyboard.io>
---
 UPGRADING.md       | 12 ++++++++++++
 src/Kaleidoscope.h | 19 +++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/UPGRADING.md b/UPGRADING.md
index b89d24b8..52b1d4c1 100644
--- a/UPGRADING.md
+++ b/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
diff --git a/src/Kaleidoscope.h b/src/Kaleidoscope.h
index c3d262b6..9b2148ad 100644
--- a/src/Kaleidoscope.h
+++ b/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.