Add Keyboard.send(); add ConsumerControl classes.

.gitignore

@@ -1,8 +1,9 @@
-__pycache__
-_build
-*.pyc
-.vscode
-*~
-.env
-build*
-bundles
+__pycache__
+_build
+*.pyc
+*.mpy
+.vscode
+*~
+.env
+build*
+bundles

README.rst

@@ -42,12 +42,17 @@ The ``Keycode`` class defines USB HID keycodes to send using ``Keyboard``.
     # Set up a keyboard device.
     kbd = Keyboard()
 
-    # Type control-x.
-    kbd.press(Keycode.CONTROL, Keycode.X)
-    kbd.release_all()
+    # Type lowercase 'a'. Presses the 'a' key and releases it.
+    kbd.send(Keycode.A)
 
     # Type capital 'A'.
-    kbd.press(Keycode.SHIFT, Keycode.A)
+    kbd.send(Keycode.SHIFT, Keycode.A)
+
+    # Type control-x.
+    kbd.send(Keycode.CONTROL, Keycode.X)
+
+    # You can also control press and release actions separately.
+    kbd.press(Keycode.CONTROL, Keycode.X)
     kbd.release_all()
 
     # Press and hold the shifted '1' key to get '!' (exclamation mark).
@@ -113,7 +118,23 @@ The ``Mouse`` class simulates a three-button mouse with a scroll wheel.
     m.move(x=50, y=20)
     m.release_all()       # or m.release(Mouse.LEFT_BUTTON)
 
+The ``ConsumerControl`` class emulates consumer control devices such as
+remote controls, or the multimedia keys on certain keyboards.
+
+*New in CircuitPython 3.0.*
+
+.. code-block:: python
+
+    from adafruit_hid.consumer_control import ConsumerControl
+    from adafruit_hid.consumer_control_code import ConsumerControlCode
+
+    cc = ConsumerControl()
+
+    # Raise volume.
+    cc.send(ConsumerCode.VOLUME_INCREMENT)
 
+    # Pause or resume playback.
+    cc.send(ConsumerCode.PLAY_PAUSE)
 
 Contributing
 ============

adafruit_hid/consumer_control.py

@@ -0,0 +1,74 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2018 Dan Halbert for Adafruit Industries
+#
+# 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.
+#
+
+"""
+`adafruit_hid.consumer_control.ConsumerControl`
+====================================================
+
+* Author(s): Dan Halbert
+"""
+
+import usb_hid
+
+class ConsumerControl:
+    """Send ConsumerControl code reports, used by multimedia keyboards, remote controls, etc.
+
+    *New in CircuitPython 3.0.*
+    """
+
+    def __init__(self):
+        """Create a ConsumerControl object that will send Consumer Control Device HID reports."""
+        self.hid_consumer = None
+        for device in usb_hid.devices:
+            if device.usage_page == 0x0C and device.usage == 0x01:
+                self.hid_consumer = device
+                break
+        if not self.hid_consumer:
+            raise IOError("Could not find an HID Consumer device.")
+
+        # Reuse this bytearray to send consumer reports.
+        self.report = bytearray(2)
+
+        # View bytes as a single 16-bit number.
+        self.usage_id = memoryview(self.report)[0:2]
+
+    def send(self, consumer_code):
+        """Send a report to do the specified consumer control action,
+        and then stop the action (so it will not repeat).
+
+        :param consumer_code: a 16-bit consumer control code.
+
+        Examples::
+
+            from adafruit_hid.consumer_control_code import ConsumerControlCode
+
+            # Raise volume.
+            consumer_control.send(ConsumerCode.VOLUME_INCREMENT)
+
+            # Advance to next track (song).
+            consumer_control.send(ConsumerCode.SCAN_NEXT_TRACK)
+        """
+        self.usage_id[0] = consumer_code
+        self.hid_consumer.send_report(self.report)
+        self.usage_id[0] = 0x0
+        self.hid_consumer.send_report(self.report)

adafruit_hid/consumer_control_code.py

@@ -0,0 +1,60 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2018 Dan Halbert for Adafruit Industries
+#
+# 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.
+#
+
+"""
+`adafruit_hid.consumer_control_code.ConsumerControlCode`
+====================================================
+
+* Author(s): Dan Halbert
+"""
+
+class ConsumerControlCode:
+    """USB HID Consumer Control Device constants.
+
+    This list includes a few common consumer control codes from
+    http://www.usb.org/developers/hidpage/Hut1_12v2.pdf#page=75.
+
+    *New in CircuitPython 3.0.*
+    """
+    #pylint: disable-msg=too-few-public-methods
+
+    RECORD = 0xB2
+    """Record"""
+    FAST_FORWARD = 0xB3
+    """Fast Forward"""
+    REWIND = 0xB4
+    """Rewind"""
+    SCAN_NEXT_TRACK = 0xB5
+    """Skip to next track"""
+    SCAN_PREVIOUS_TRACK = 0xB6
+    """Go back to previous track"""
+    STOP = 0xB7
+    """Stop"""
+    EJECT = 0xB8
+    """Eject"""
+    PLAY_PAUSE = 0xCD
+    """Play/Pause toggle"""
+    VOLUME_DECREMENT = 0xEA
+    """Decrease volume"""
+    VOLUME_INCREMENT = 0xE9
+    """Increase volume"""

adafruit_hid/keyboard.py

@@ -87,7 +87,7 @@ def press(self, *keycodes):
         """
         for keycode in keycodes:
             self._add_keycode_to_report(keycode)
-            self.hid_keyboard.send_report(self.report)
+        self.hid_keyboard.send_report(self.report)
 
     def release(self, *keycodes):
         """Send a USB HID report indicating that the given keys have been released.
@@ -103,14 +103,22 @@ def release(self, *keycodes):
         """
         for keycode in keycodes:
             self._remove_keycode_from_report(keycode)
-            self.hid_keyboard.send_report(self.report)
+        self.hid_keyboard.send_report(self.report)
 
     def release_all(self):
         """Release all pressed keys."""
         for i in range(8):
             self.report[i] = 0
         self.hid_keyboard.send_report(self.report)
 
+    def send(self, *keycodes):
+        """Press the given keycodes and then release all pressed keys.
+
+        :param keycodes: keycodes to send together
+        """
+        self.press(*keycodes)
+        self.release_all()
+
     def _add_keycode_to_report(self, keycode):
         """Add a single keycode to the USB HID report."""
         modifier = Keycode.modifier_bit(keycode)

examples/keyboard_shortcuts.py

@@ -19,12 +19,10 @@
 while True:
     # press ALT+TAB to swap windows
     if swap.value:
-        kbd.press(Keycode.ALT, Keycode.TAB)
-        kbd.release_all()
+        kbd.send(Keycode.ALT, Keycode.TAB)
 
     # press CTRL+K, which in a web browser will open the search dialog
     elif search.value:
-        kbd.press(Keycode.CONTROL, Keycode.K)
-        kbd.release_all()
+        kbd.send(Keycode.CONTROL, Keycode.K)
 
     time.sleep(0.1)