usbd: Implement SET_REPORT support for OUT direction HID data.

Author: projectgus

micropython/usbd/hid.py

@@ -8,6 +8,7 @@
     split_bmRequestType,
     EP_IN_FLAG,
     STAGE_SETUP,
+    STAGE_DATA,
     REQ_TYPE_STANDARD,
     REQ_TYPE_CLASS,
 )
@@ -43,6 +44,7 @@ def __init__(
         self,
         report_descriptor,
         extra_descriptors=[],
+        set_report_buf=None,
         protocol=_INTERFACE_PROTOCOL_NONE,
         interface_str=None,
     ):
@@ -57,17 +59,34 @@ def __init__(
         #   descriptors, to append after the mandatory report descriptor. Most
         #   HID devices do not use these.
         #
+        # - set_report_buf is an optional writable buffer object (i.e.
+        #   bytearray), where SET_REPORT requests from the host can be
+        #   written. Only necessary if the report_descriptor contains Output
+        #   entries. If set, the size must be at least the size of the largest
+        #   Output entry.
+        #
         # - protocol can be set to a specific value as per HID v1.11 section 4.3 Protocols, p9.
         #
         # - interface_str is an optional string descriptor to associate with the HID USB interface.
         super().__init__(_INTERFACE_CLASS, _INTERFACE_SUBCLASS_NONE, protocol, interface_str)
         self.extra_descriptors = extra_descriptors
         self.report_descriptor = report_descriptor
+        self._set_report_buf = set_report_buf
         self._int_ep = None  # set during enumeration
 
     def get_report(self):
         return False
 
+    def handle_set_report(self, report_data, report_id, report_type):
+        # Override this function in order to handle SET REPORT requests from the host,
+        # where it sends data to the HID device.
+        #
+        # This function will only be called if the Report descriptor contains at least one Output entry,
+        # and the set_report_buf argument is provided to the constructor.
+        #
+        # Return True to complete the control transfer normally, False to abort it.
+        return True
+
     def send_report(self, report_data):
         # Helper function to send a HID report in the typical USB interrupt
         # endpoint associated with a HID interface.  return
@@ -115,36 +134,63 @@ def get_hid_descriptor(self):
 
     def handle_interface_control_xfer(self, stage, request):
         # Handle standard and class-specific interface control transfers for HID devices.
-        bmRequestType, bRequest, wValue, _, _ = request
+        bmRequestType, bRequest, wValue, _, wLength = request
 
         recipient, req_type, _ = split_bmRequestType(bmRequestType)
 
-        if stage != STAGE_SETUP:
-            return True  # allow request DATA/ACK stages to complete normally
-
-        if req_type == REQ_TYPE_STANDARD:
-            # HID Spec p48: 7.1 Standard Requests
-            if bRequest == _REQ_CONTROL_GET_DESCRIPTOR:
-                desc_type = wValue >> 8
-                if desc_type == _DESC_HID_TYPE:
-                    return self.get_hid_descriptor()
-                if desc_type == _DESC_REPORT_TYPE:
-                    return self.report_descriptor
-        elif req_type == REQ_TYPE_CLASS:
-            # HID Spec p50: 7.2 Class-Specific Requests
-            if bRequest == _REQ_CONTROL_GET_REPORT:
-                return False  # Unsupported for now
-            if bRequest == _REQ_CONTROL_GET_IDLE:
-                return bytes([self.idle_rate])
-            if bRequest == _REQ_CONTROL_GET_PROTOCOL:
-                return bytes([self.protocol])
-            if bRequest == _REQ_CONTROL_SET_IDLE:
-                self.idle_rate = wValue >> 8
-                return b""
-            if bRequest == _REQ_CONTROL_SET_PROTOCOL:
-                self.protocol = wValue
-                return b""
-        return False  # Unsupported
+        if stage == STAGE_SETUP:
+            if req_type == REQ_TYPE_STANDARD:
+                # HID Spec p48: 7.1 Standard Requests
+                if bRequest == _REQ_CONTROL_GET_DESCRIPTOR:
+                    desc_type = wValue >> 8
+                    if desc_type == _DESC_HID_TYPE:
+                        return self.get_hid_descriptor()
+                    if desc_type == _DESC_REPORT_TYPE:
+                        return self.report_descriptor
+            elif req_type == REQ_TYPE_CLASS:
+                # HID Spec p50: 7.2 Class-Specific Requests
+                if bRequest == _REQ_CONTROL_GET_REPORT:
+                    print("GET_REPORT?")
+                    return False  # Unsupported for now
+                if bRequest == _REQ_CONTROL_GET_IDLE:
+                    return bytes([self.idle_rate])
+                if bRequest == _REQ_CONTROL_GET_PROTOCOL:
+                    return bytes([self.protocol])
+                if bRequest == _REQ_CONTROL_SET_IDLE:
+                    self.idle_rate = wValue >> 8
+                    return b""
+                if bRequest == _REQ_CONTROL_SET_PROTOCOL:
+                    self.protocol = wValue
+                    return b""
+                if bRequest == _REQ_CONTROL_SET_REPORT:
+                    # Return the _set_report_buf to be filled with the
+                    # report data
+                    if not self._set_report_buf:
+                        return False
+                    elif wLength >= len(self._set_report_buf):
+                        # Saves an allocation if the size is exactly right (or will be a short read)
+                        return self._set_report_buf
+                    else:
+                        # Otherwise, need to wrap the buffer in a memoryview of the correct length
+                        #
+                        # TODO: check this is correct, maybe TinyUSB won't mind if we ask for more
+                        # bytes than the host has offered us.
+                        return memoryview(self._set_report_buf)[:wLength]
+            return False  # Unsupported
+
+        if stage == STAGE_DATA:
+            if req_type == REQ_TYPE_CLASS:
+                if bRequest == _REQ_CONTROL_SET_REPORT and self._set_report_buf:
+                    report_id = wValue & 0xFF
+                    report_type = wValue >> 8
+                    report_data = self._set_report_buf
+                    if wLength < len(report_data):
+                        # as above, need to truncate the buffer if we read less
+                        # bytes than what was provided
+                        report_data = memoryview(self._set_report_buf)[:wLength]
+                    self.handle_set_report(report_data, report_id, report_type)
+
+        return True  # allow DATA/ACK stages to complete normally
 
 
 # Basic 3-button mouse HID Report Descriptor.