wip

Author: dhalbert

locale/circuitpython.pot

@@ -103,14 +103,6 @@ msgstr ""
 msgid "%q must be %d-%d"
 msgstr ""
 
-#: shared-bindings/usb_hid/Device.c
-msgid "%q must be 0-255"
-msgstr ""
-
-#: shared-bindings/usb_hid/Device.c
-msgid "%q must be 1-255"
-msgstr ""
-
 #: py/argcheck.c
 msgid "%q must be >= %d"
 msgstr ""
@@ -127,10 +119,6 @@ msgstr ""
 msgid "%q must be >= 1"
 msgstr ""
 
-#: shared-bindings/usb_hid/Device.c
-msgid "%q must be None or between 1 and len(report_descriptor)-1"
-msgstr ""
-
 #: py/argcheck.c
 msgid "%q must be a string"
 msgstr ""
@@ -168,6 +156,10 @@ msgstr ""
 msgid "%q() takes %d positional arguments but %d were given"
 msgstr ""
 
+#: shared-bindings/usb_hid/Device.c
+msgid "%q, %q, and %q must all be the same length"
+msgstr ""
+
 #: ports/esp32s2/bindings/espidf/__init__.c ports/esp32s2/esp_error.c
 #, c-format
 msgid "%s error 0x%x"
@@ -1518,6 +1510,11 @@ msgstr ""
 msgid "Missing jmp_pin. Instruction %d jumps on pin"
 msgstr ""
 
+#: shared-module/usb_hid/Device.c
+#, c-format
+msgid "More than %d report ids not supported"
+msgstr ""
+
 #: shared-bindings/busio/UART.c shared-bindings/displayio/Group.c
 msgid "Must be a %q subclass."
 msgstr ""

py/argcheck.c

@@ -197,7 +197,7 @@ mp_float_t mp_arg_validate_obj_float_non_negative(mp_obj_t float_in, mp_float_t
 
 size_t mp_arg_validate_length_with_name(mp_int_t i, size_t length, qstr arg_name, qstr length_name) {
     if (i != (mp_int_t)length) {
-        mp_raise_ValueError_varg(translate("%q length must be %q"), MP_QSTR_pressed, MP_QSTR_num_keys);
+        mp_raise_ValueError_varg(translate("%q length must be %q"), arg_name, length_name);
     }
     return (size_t)i;
 }

shared-bindings/usb_hid/Device.c

@@ -31,46 +31,53 @@
 //| class Device:
 //|     """HID Device specification"""
 //|
-//|     def __init__(self, *, descriptor: ReadableBuffer, usage_page: int, usage: int, in_report_length: int, out_report_length: int = 0, report_id_index: Optional[int]) -> None:
+//|     def __init__(self, *, descriptor: ReadableBuffer, usage_page: int, usage: int, in_report_lengths: Sequence[int], out_report_lengths: Sequence[int]) -> None:
 //|         """Create a description of a USB HID device. The actual device is created when you
 //|         pass a `Device` to `usb_hid.enable()`.
 //|
 //|         :param ReadableBuffer report_descriptor: The USB HID Report descriptor bytes. The descriptor is not
 //|           not verified for correctness; it is up to you to make sure it is not malformed.
 //|         :param int usage_page: The Usage Page value from the descriptor. Must match what is in the descriptor.
 //|         :param int usage: The Usage value from the descriptor. Must match what is in the descriptor.
-//|         :param int in_report_length: Size in bytes of the HID report sent to the host.
-//|           "In" is with respect to the host.
-//|         :param int out_report_length: Size in bytes of the HID report received from the host.
-//|           "Out" is with respect to the host. If no reports are expected, use 0.
-//|         :param int report_id_index: position of byte in descriptor that contains the Report ID.
-//|           A Report ID will be assigned when the device is created. If there is no
-//|           Report ID, use ``None``.
+//|         :param int report_ids: Sequence of report ids used by the descriptor.
+//|         :param int in_report_lengths: Sequence of sizes in bytes of the HIDs report sent to the host.
+//|           The sizes are in order of the ``report_ids``.
+//|           "IN" is with respect to the host.
+//|         :param int out_report_lengths: Size in bytes of the HID report received from the host.
+//|           The sizes are in order of the ``report_ids``.
+//|           "OUT" is with respect to the host.
+//|
+//|         ``report_ids``, ``in_report_lengths``, and ``out_report_lengths`` must all be the same length.
 //|         """
 //|         ...
 //|
 //|     KEYBOARD: Device
-//|     """Standard keyboard device supporting keycodes 0x00-0xDD, modifiers 0xE-0xE7, and five LED indicators."""
+//|     """Standard keyboard device supporting keycodes 0x00-0xDD, modifiers 0xE-0xE7, and five LED indicators.
+//|     Uses Report ID 1 for its IN and OUT reports.
+//|     """
 //|
 //|     MOUSE: Device
 //|     """Standard mouse device supporting five mouse buttons, X and Y relative movements from -127 to 127
-//|     in each report, and a relative mouse wheel change from -127 to 127 in each report."""
+//|     in each report, and a relative mouse wheel change from -127 to 127 in each report.
+//|     Uses Report ID 2 for its IN reports.
+//|     """
 //|
 //|     CONSUMER_CONTROL: Device
-//|     """Consumer Control device supporting sent values from 1-652, with no rollover."""
+//|     """Consumer Control device supporting sent values from 1-652, with no rollover.
+//|     Uses Report ID 3 for its IN reports."""
 //|
 
 STATIC mp_obj_t usb_hid_device_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     usb_hid_device_obj_t *self = m_new_obj(usb_hid_device_obj_t);
     self->base.type = &usb_hid_device_type;
-    enum { ARG_report_descriptor, ARG_usage_page, ARG_usage, ARG_in_report_length, ARG_out_report_length, ARG_report_id_index };
+    enum { ARG_report_descriptor, ARG_usage_page, ARG_usage, ARG_report_ids, ARG_in_report_lengths, ARG_out_report_lengths };
     static const mp_arg_t allowed_args[] = {
         { MP_QSTR_report_descriptor, MP_ARG_KW_ONLY | MP_ARG_REQUIRED | MP_ARG_OBJ },
         { MP_QSTR_usage_page, MP_ARG_KW_ONLY | MP_ARG_REQUIRED | MP_ARG_INT },
         { MP_QSTR_usage, MP_ARG_KW_ONLY | MP_ARG_REQUIRED | MP_ARG_INT },
-        { MP_QSTR_in_report_length, MP_ARG_KW_ONLY | MP_ARG_REQUIRED | MP_ARG_INT },
-        { MP_QSTR_out_report_length, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0 } },
-        { MP_QSTR_report_id_index, MP_ARG_KW_ONLY | MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = mp_const_none } },
+        { MP_QSTR_report_ids, MP_ARG_KW_ONLY | MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_in_report_lengths, MP_ARG_KW_ONLY | MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_out_report_lengths, MP_ARG_KW_ONLY | MP_ARG_REQUIRED | MP_ARG_OBJ },
     };
 
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
@@ -81,76 +88,128 @@ STATIC mp_obj_t usb_hid_device_make_new(const mp_obj_type_t *type, size_t n_args
     mp_obj_t descriptor = mp_obj_new_bytearray(descriptor_bufinfo.len, descriptor_bufinfo.buf);
 
     const mp_int_t usage_page_arg = args[ARG_usage_page].u_int;
-    if (usage_page_arg <= 0 || usage_page_arg > 255) {
-        mp_raise_ValueError_varg(translate("%q must be 1-255"), MP_QSTR_usage_page);
-    }
+    mp_arg_validate_int_range(usage_page_arg, 1, 255, MP_QSTR_usage_page);
     const uint8_t usage_page = usage_page_arg;
 
     const mp_int_t usage_arg = args[ARG_usage].u_int;
-    if (usage_arg <= 0 || usage_arg > 255) {
-        mp_raise_ValueError_varg(translate("%q must be 1-255"), MP_QSTR_usage);
-    }
+    mp_arg_validate_int_range(usage_arg, 1, 255, MP_QSTR_usage_page);
     const uint8_t usage = usage_arg;
 
-    const mp_int_t in_report_length_arg = args[ARG_in_report_length].u_int;
-    if (in_report_length_arg <= 0 || in_report_length_arg > 255) {
-        mp_raise_ValueError_varg(translate("%q must be 1-255"), MP_QSTR_in_report_length);
-    }
-    const uint8_t in_report_length = in_report_length_arg;
+    mp_obj_t report_ids = args[ARG_report_ids].u_obj;
+    mp_obj_t in_report_lengths = args[ARG_in_report_lengths].u_obj;
+    mp_obj_t out_report_lengths = args[ARG_out_report_lengths].u_obj;
 
-    const mp_int_t out_report_length_arg = args[ARG_out_report_length].u_int;
-    if (out_report_length_arg < 0 || out_report_length_arg > 255) {
-        mp_raise_ValueError_varg(translate("%q must be 0-255"), MP_QSTR_out_report_length);
+    size_t report_ids_count = (size_t)MP_OBJ_SMALL_INT_VALUE(mp_obj_len(report_ids));
+    if (MP_OBJ_SMALL_INT_VALUE(mp_obj_len(in_report_lengths)) != report_ids_count ||
+        MP_OBJ_SMALL_INT_VALUE(mp_obj_len(out_report_lengths)) != report_ids_count) {
+        mp_raise_ValueError_varg(translate("%q, %q, and %q must all be the same length"),
+            MP_QSTR_report_ids, MP_QSTR_in_report_lengths, MP_QSTR_out_report_lengths);
     }
-    const uint8_t out_report_length = out_report_length_arg;
-
-    const mp_obj_t report_id_index_arg = args[ARG_report_id_index].u_obj;
-    uint8_t report_id_index = 0;
-    if (report_id_index_arg != mp_const_none) {
-        const mp_int_t report_id_index_int = mp_obj_int_get_checked(report_id_index_arg);
-        if (report_id_index_int <= 0 || (uint32_t)report_id_index_int >= descriptor_bufinfo.len) {
-            mp_raise_ValueError_varg(translate("%q must be None or between 1 and len(report_descriptor)-1"),
-                MP_QSTR_report_id_index);
-        }
-        report_id_index = report_id_index_int;
+
+    uint8_t report_ids_array[report_ids_count];
+    uint8_t in_report_lengths_array[report_ids_count];
+    uint8_t out_report_lengths_array[report_ids_count];
+
+    // Validate the ids and lengths are all integers in range.
+    for (size_t i = 0; i < report_ids_count; i++) {
+        mp_obj_t i_obj = MP_OBJ_NEW_SMALL_INT(i);
+
+        report_ids_array[i] = (uint8_t)mp_arg_validate_int_range(
+            // It's not the actual argument that's out of range, but its elements.
+            // But the error message is close enough.
+            MP_OBJ_SMALL_INT_VALUE(mp_obj_subscr(report_ids, i_obj, MP_OBJ_SENTINEL)),
+            1, 255, MP_QSTR_report_ids);
+
+        in_report_lengths_array[i] = (uint8_t)mp_arg_validate_int_range(
+            MP_OBJ_SMALL_INT_VALUE(mp_obj_subscr(in_report_lengths_array, i_obj, MP_OBJ_SENTINEL)),
+            0, 255, MP_QSTR_in_report_lengths);
+
+        out_report_lengths_array[i] = (uint8_t)mp_arg_validate_int_range(
+            MP_OBJ_SMALL_INT_VALUE(mp_obj_subscr(out_report_lengths_array, i_obj, MP_OBJ_SENTINEL)),
+            0, 255, MP_QSTR_out_report_lengths);
     }
 
     common_hal_usb_hid_device_construct(
-        self, descriptor, usage_page, usage, in_report_length, out_report_length, report_id_index);
+        self, descriptor, usage_page, usage, report_ids_count, report_ids_array, in_report_lengths_array, out_report_lengths_array);
     return (mp_obj_t)self;
 }
 
 
-//|     def send_report(self, buf: ReadableBuffer) -> None:
-//|         """Send a HID report."""
+//|     def send_report(self, buf: ReadableBuffer, report_id: Optional[int] = None) -> None:
+//|         """Send an HID report.
+//|         """
 //|         ...
 //|
-STATIC mp_obj_t usb_hid_device_send_report(mp_obj_t self_in, mp_obj_t buffer) {
-    usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in);
+STATIC mp_obj_t usb_hid_device_send_report(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
+
+    enum { ARG_buf, ARG_report_id };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_buf, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_report_id, MP_ARG_OBJ, {.u_obj = mp_const_none} },
+    };
+
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
 
     mp_buffer_info_t bufinfo;
-    mp_get_buffer_raise(buffer, &bufinfo, MP_BUFFER_READ);
+    mp_get_buffer_raise(args[ARG_buf].u_obj, &bufinfo, MP_BUFFER_READ);
+
+    uint8_t report_id = 0;
+    if (args[ARG_report_id].u_obj != mp_const_none) {
+        const mp_int_t report_id_arg = mp_obj_int_get_checked(args[ARG_report_id].u_obj);
+        report_id = mp_arg_validate_int_range(report_id_arg, 1, 255, MP_QSTR_report_id);
+    }
 
-    common_hal_usb_hid_device_send_report(self, ((uint8_t *)bufinfo.buf), bufinfo.len);
+    common_hal_usb_hid_device_send_report(self, ((uint8_t *)bufinfo.buf), bufinfo.len, report_id);
     return mp_const_none;
 }
-MP_DEFINE_CONST_FUN_OBJ_2(usb_hid_device_send_report_obj, usb_hid_device_send_report);
+MP_DEFINE_CONST_FUN_OBJ_KW(usb_hid_device_send_report_obj, 2, usb_hid_device_send_report);
+
+//|     def get_last_received_report(self, report_id: Optional[int] = None) -> bytes:
+//|     """Get the last received HID OUT report for the given report ID.
+//|     The report ID may be omitted if there is no report ID, or only one report ID.
+//|     Return `None` if nothing received.
+//|     """
+//|         ...
+//|
+STATIC mp_obj_t usb_hid_device_get_last_received_report(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
+
+    enum { ARG_report_id };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_report_id, MP_ARG_OBJ, {.u_obj = mp_const_none} },
+    };
+
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+
+    uint8_t report_id = 0;
+    if (args[ARG_report_id].u_obj != mp_const_none) {
+        report_id = mp_obj_int_get_checked(args[ARG_report_id].u_obj);
+    }
+
+    return common_hal_usb_hid_device_get_last_received_report(self, report_id);
+}
+MP_DEFINE_CONST_FUN_OBJ_KW(usb_hid_device_get_last_received_report_obj, 1, usb_hid_device_get_last_received_report);
 
 //|     last_received_report: bytes
-//|     """The HID OUT report as a `bytes`. (read-only). `None` if nothing received."""
+//|     """The HID OUT report as a `bytes`. (read-only). `None` if nothing received.
+//|     Same as `get_last_received_report()` with no argument.
 //|
-STATIC mp_obj_t usb_hid_device_obj_get_last_received_report(mp_obj_t self_in) {
+//|     Deprecated: will be removed in CircutPython 8.0.0. Use `get_last_received_report()` instead.
+//|     """
+//|
+STATIC mp_obj_t usb_hid_device_obj_get_last_received_report_property(mp_obj_t self_in) {
     usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in);
-    if (self->out_report_buffer == 0) {
-        return mp_const_none;
-    }
-    return mp_obj_new_bytes(self->out_report_buffer, self->out_report_length);
+
+    return common_hal_usb_hid_device_get_last_received_report(self, 0);
 }
-MP_DEFINE_CONST_FUN_OBJ_1(usb_hid_device_get_last_received_report_obj, usb_hid_device_obj_get_last_received_report);
+MP_DEFINE_CONST_FUN_OBJ_1(usb_hid_device_get_last_received_report_property_obj, usb_hid_device_obj_get_last_received_report_property);
 
 const mp_obj_property_t usb_hid_device_last_received_report_obj = {
     .base.type = &mp_type_property,
-    .proxy = {(mp_obj_t)&usb_hid_device_get_last_received_report_obj,
+    .proxy = {(mp_obj_t)&usb_hid_device_get_last_received_report_property_obj,
               MP_ROM_NONE,
               MP_ROM_NONE},
 };
@@ -192,13 +251,15 @@ const mp_obj_property_t usb_hid_device_usage_obj = {
 };
 
 STATIC const mp_rom_map_elem_t usb_hid_device_locals_dict_table[] = {
-    { MP_ROM_QSTR(MP_QSTR_send_report),          MP_ROM_PTR(&usb_hid_device_send_report_obj) },
-    { MP_ROM_QSTR(MP_QSTR_last_received_report), MP_ROM_PTR(&usb_hid_device_last_received_report_obj) },
-    { MP_ROM_QSTR(MP_QSTR_usage_page),           MP_ROM_PTR(&usb_hid_device_usage_page_obj) },
-    { MP_ROM_QSTR(MP_QSTR_usage),                MP_ROM_PTR(&usb_hid_device_usage_obj) },
-    { MP_ROM_QSTR(MP_QSTR_KEYBOARD),             MP_ROM_PTR(&usb_hid_device_keyboard_obj) },
-    { MP_ROM_QSTR(MP_QSTR_MOUSE),                MP_ROM_PTR(&usb_hid_device_mouse_obj) },
-    { MP_ROM_QSTR(MP_QSTR_CONSUMER_CONTROL),     MP_ROM_PTR(&usb_hid_device_consumer_control_obj) },
+    { MP_ROM_QSTR(MP_QSTR_send_report),              MP_ROM_PTR(&usb_hid_device_send_report_obj) },
+    { MP_ROM_QSTR(MP_QSTR_get_last_received_report), MP_ROM_PTR(&usb_hid_device_get_last_received_report_obj) },
+    { MP_ROM_QSTR(MP_QSTR_last_received_report),     MP_ROM_PTR(&usb_hid_device_last_received_report_obj) },
+    { MP_ROM_QSTR(MP_QSTR_usage_page),               MP_ROM_PTR(&usb_hid_device_usage_page_obj) },
+    { MP_ROM_QSTR(MP_QSTR_usage),                    MP_ROM_PTR(&usb_hid_device_usage_obj) },
+
+    { MP_ROM_QSTR(MP_QSTR_KEYBOARD),                 MP_ROM_PTR(&usb_hid_device_keyboard_obj) },
+    { MP_ROM_QSTR(MP_QSTR_MOUSE),                    MP_ROM_PTR(&usb_hid_device_mouse_obj) },
+    { MP_ROM_QSTR(MP_QSTR_CONSUMER_CONTROL),         MP_ROM_PTR(&usb_hid_device_consumer_control_obj) },
 };
 
 STATIC MP_DEFINE_CONST_DICT(usb_hid_device_locals_dict, usb_hid_device_locals_dict_table);

shared-bindings/usb_hid/Device.h

@@ -33,9 +33,11 @@
 
 extern const mp_obj_type_t usb_hid_device_type;
 
-void common_hal_usb_hid_device_construct(usb_hid_device_obj_t *self, mp_obj_t descriptor, uint8_t usage_page, uint8_t usage, uint8_t in_report_length, uint8_t out_report_length, uint8_t report_id_index);
-void common_hal_usb_hid_device_send_report(usb_hid_device_obj_t *self, uint8_t *report, uint8_t len);
+void common_hal_usb_hid_device_construct(usb_hid_device_obj_t *self, mp_obj_t report_descriptor, uint8_t usage_page, uint8_t usage, size_t report_ids_count,uint8_t *report_ids, uint8_t *in_report_lengths, uint8_t *out_report_lengths);
+void common_hal_usb_hid_device_send_report(usb_hid_device_obj_t *self, uint8_t *report, uint8_t len, uint8_t report_id);
+mp_obj_t common_hal_usb_hid_device_get_last_received_report(usb_hid_device_obj_t *self, uint8_t report_id);
 uint8_t common_hal_usb_hid_device_get_usage_page(usb_hid_device_obj_t *self);
 uint8_t common_hal_usb_hid_device_get_usage(usb_hid_device_obj_t *self);
+bool common_hal_usb_hid_device_valid_report_id(usb_hid_device_obj_t *self, uint8_t report_id);
 
 #endif  // MICROPY_INCLUDED_SHARED_BINDINGS_USB_HID_DEVICE_H