initial commit

adafruit_hid/__init__.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2017 Scott Shawcroft for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""
+`adafruit_hid`
+====================================================
+
+This driver simulates USB HID devices.
+
+* Author(s): Scott Shawcroft, Dan Halbert
+
+Implementation Notes
+--------------------
+**Software and Dependencies:**
+* Adafruit CircuitPython firmware for the supported boards:
+  https://github.com/adafruit/circuitpython/releases
+"""
+
+# imports
+from __future__ import annotations
+
+try:
+    from typing import Sequence
+    import usb_hid
+except ImportError:
+    pass
+
+__version__ = "0.0.0+auto.0"
+__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_HID.git"
+
+
+def find_device(
+    devices: Sequence[usb_hid.Device], *, usage_page: int, usage: int
+) -> usb_hid.Device:
+    """Search through the provided sequence of devices to find the one with the matching
+    usage_page and usage."""
+    if hasattr(devices, "send_report"):
+        devices = [devices]  # type: ignore
+    for device in devices:
+        if (
+            device.usage_page == usage_page
+            and device.usage == usage
+            and hasattr(device, "send_report")
+        ):
+            return device
+    raise ValueError("Could not find matching HID device.")

adafruit_hid/consumer_control.py

@@ -0,0 +1,106 @@
+# SPDX-FileCopyrightText: 2018 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""
+`adafruit_hid.consumer_control.ConsumerControl`
+====================================================
+
+* Author(s): Dan Halbert
+"""
+
+import sys
+
+if sys.implementation.version[0] < 3:
+    raise ImportError(
+        "{0} is not supported in CircuitPython 2.x or lower".format(__name__)
+    )
+
+# pylint: disable=wrong-import-position
+import struct
+import time
+from . import find_device
+
+try:
+    from typing import Sequence
+    import usb_hid
+except ImportError:
+    pass
+
+
+class ConsumerControl:
+    """Send ConsumerControl code reports, used by multimedia keyboards, remote controls, etc."""
+
+    def __init__(self, devices: Sequence[usb_hid.Device]) -> None:
+        """Create a ConsumerControl object that will send Consumer Control Device HID reports.
+
+        Devices can be a sequence of devices that includes a Consumer Control device or a CC device
+        itself. A device is any object that implements ``send_report()``, ``usage_page`` and
+        ``usage``.
+        """
+        self._consumer_device = find_device(devices, usage_page=0x0C, usage=0x01)
+
+        # Reuse this bytearray to send consumer reports.
+        self._report = bytearray(2)
+
+        # Do a no-op to test if HID device is ready.
+        # If not, wait a bit and try once more.
+        try:
+            self.send(0x0)
+        except OSError:
+            time.sleep(1)
+            self.send(0x0)
+
+    def send(self, consumer_code: int) -> None:
+        """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(ConsumerControlCode.VOLUME_INCREMENT)
+
+            # Advance to next track (song).
+            consumer_control.send(ConsumerControlCode.SCAN_NEXT_TRACK)
+        """
+        self.press(consumer_code)
+        self.release()
+
+    def press(self, consumer_code: int) -> None:
+        """Send a report to indicate that the given key has been pressed.
+        Only one consumer control action can be pressed at a time, so any one
+        that was previously pressed will be released.
+
+        :param consumer_code: a 16-bit consumer control code.
+
+        Examples::
+
+            from adafruit_hid.consumer_control_code import ConsumerControlCode
+
+            # Raise volume for 0.5 seconds
+            consumer_control.press(ConsumerControlCode.VOLUME_INCREMENT)
+            time.sleep(0.5)
+            consumer_control.release()
+        """
+        struct.pack_into("<H", self._report, 0, consumer_code)
+        self._consumer_device.send_report(self._report)
+
+    def release(self) -> None:
+        """Send a report indicating that the consumer control key has been
+        released. Only one consumer control key can be pressed at a time.
+
+        Examples::
+
+            from adafruit_hid.consumer_control_code import ConsumerControlCode
+
+            # Raise volume for 0.5 seconds
+            consumer_control.press(ConsumerControlCode.VOLUME_INCREMENT)
+            time.sleep(0.5)
+            consumer_control.release()
+        """
+        self._report[0] = self._report[1] = 0x0
+        self._consumer_device.send_report(self._report)

adafruit_hid/consumer_control_code.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2018 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""
+`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
+    https://www.usb.org/sites/default/files/hut1_21_0.pdf#page=118.
+    """
+
+    # 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"""
+    MUTE = 0xE2
+    """Mute"""
+    VOLUME_DECREMENT = 0xEA
+    """Decrease volume"""
+    VOLUME_INCREMENT = 0xE9
+    """Increase volume"""
+    BRIGHTNESS_DECREMENT = 0x70
+    """Decrease Brightness"""
+    BRIGHTNESS_INCREMENT = 0x6F
+    """Increase Brightness"""