Skip to content

v0.3.0

Choose a tag to compare

@github-actions github-actions released this 12 Nov 06:29
· 52 commits to main since this release

Not hardware-verified as tests/hw/README.md defines it; what was run
on a board is listed under "Run on a board" below.
The wire protocol and the C ABI change: a
0.2.1 board and this library do not talk to each other. The board becomes a generic USB device: the
host composes every descriptor, or is given them as bytes, and the firmware has no HID driver.

Run on a board

2026-11-12, a Raspberry Pi Pico (RP2040), a Prolific PL2303 adapter, the target the same Linux
machine (a VMware guest, both USB devices passed through). Not run: a second machine as the target,
Windows or macOS, the mimhid_verify_* programs (they type into the target, which here is the
session), the other boards.

  • Discovery and the rate search (7,812,500 baud, no errors on the link counters in any run).
  • A keyboard profile Node: enumerated by Linux, 10 runs of 400 presses and 400 releases with the
    event device grabbed, none lost; latency in docs/LATENCY.md, not different from 0.2.1.
  • A vendor Node with bulk IN and OUT: transfers of 1 to 292 bytes with their boundaries, a
    zero-length packet, 262,100 bytes without loss under the wait policy, 200 packets from the target,
    the drop-newest and drop-oldest policies with a target that does not read, stall and clear.
  • An HID interface written by hand: every control rule action answered to the host (ANSWER,
    ANSWER_LAST_SENT, ACCEPT with a data stage, ASK, a stall for a request no rule matches), a
    rule's bytes replaced, and an Output report on the OUT endpoint.
  • A composite device opened in one batch: a keyboard profile and a two-interface Node with an
    interface association.
  • A device given as bytes (tests/hw/hw_bytes bytes): the device, configuration and BOS descriptors and
    two strings read back by Linux byte for byte, the vendor request answered by a rule of the Device,
    bulk IN with its boundaries and a zero-length packet, bulk OUT as events of node 0 (a transfer of 70
    bytes is two packets), Halt and clear. A composed Device with a BOS descriptor and bcdUSB 0x0210
    (hw_bytes bos). The BOS of both names the Microsoft OS 2.0 capability, so the target asks for its
    descriptor set and the Device has a rule that answers; without it, or with bcdUSB 0x0210 and no BOS,
    the target did not enumerate the device. Not run: Windows.
  • hw_bulk wait|newest|oldest, hw_control_rules and hw_composite again on the same firmware; the
    latency of ten runs in docs/LATENCY.md.
  • mimhid_device_enter_bootloader, used to write the firmware some forty times.

Wire protocol

  • The host sends every descriptor as bytes. DESC_RESET (0x10), DESC_BEGIN (0x11) and
    DESC_DATA (0x12) carry the device, configuration, string, BOS and ANSWER descriptors
    (MIMHID_DESC_*); they replace DEVICE_CONFIG, NODE_BEGIN and NODE_DATA. At COMMIT the board
    walks the staged configuration once and refuses one that does not hold together (NAK_DESCRIPTOR, the
    previous configuration kept; docs/PROTOCOL.md).
  • A BOS descriptor is a descriptor kind (MIMHID_DESC_BOS, 6) the board serves byte for byte; it needs
    bcdUSB 0x0201 or more.
  • Data frames name endpoints. EP_IN (0x41..0x4F) and EP_OUT (0xC1..0xCF) carry the endpoint
    number, not a node id. New commands EP_CONFIG (0x1B, replaces QUEUE_DEPTH: address, depth, policy
    drop-newest, drop-oldest or wait), EP_STALL (0x1E), EP_FLUSH (0x1F), RULE (0x18, was
    CONTROL_CONFIG), RULES_APPLY (0x21), RULE_DATA (0x22), BOOTLOADER (0x20); new events
    EV_EP_DONE, EV_EP_HALT; REPORT_LOST became TRANSFER_LOST, which names the endpoint.
    DESC_HID_REPORT (4), FEATURE (0x14) and the events SET_REPORT, SET_PROTOCOL, SET_IDLE,
    OUTPUT_REPORT (5 to 8) are gone and not reused.
  • An ANSWER rule has a capacity and a length (RULE bytes 14..15 and 16..17). The board reserves the
    capacity, RULE_DATA sets any length up to it, so a shortened answer can grow again after the table
    is rebuilt.
  • A COMMIT that attaches is refused with NAK_STATE while the board is attached: it would change
    the descriptors under a device the target has enumerated. mimhid_device_connect on a configured
    Device sends nothing and returns MIMHID_OK.
  • PONG (MIMHID_PONG_MIN_LEN 49): bytes 4, 5, 21..22 and 25..26 are reserved, zero; new fields
    max_endpoint_number (34), max_interfaces_any, max_config_descriptor_bytes, max_strings,
    max_transfer_bytes, endpoint_queue_slots, transfer_types (36 to 44), max_answer_bytes (45..46)
    and max_bos_bytes (47..48); the unique id starts at 49. The board's limits: 160 rules, 4096 bytes of
    answers, 32 ANSWER_LAST_SENT rules, 256 bytes of BOS (MIMHID_CONTROL_RULES, MIMHID_ANSWER_BYTES,
    MIMHID_LAST_SENT_SLOTS, MIMHID_MAX_BOS_BYTES).

API

  • mimhid_node_open takes interfaces of any class, HID included (mimhid_node_config: interfaces,
    bulk and interrupt endpoints, class descriptors, an interface association, control rules). Profile
    Nodes (keyboard, mouse, ...) are mimhid_node_open_profile with mimhid_hid_node_config. Helpers
    mimhid_hid_descriptor_bytes and mimhid_hid_descriptor_rule; examples vendor_bulk.c and
    hid_interface.c.
  • A Device can be given as bytes: mimhid_device_set_descriptors / _clear_descriptors
    (mimhid_device_descriptors), raw strings mimhid_device_set_string / _clear_string (any index and
    language), and the endpoint calls by address mimhid_device_endpoint_set_policy, _write, _stall,
    _clear_stall, _flush. The library checks the bytes without reading any class and names the field
    and the byte offset of what is wrong. The OUT data of such a device is MIMHID_EVENT_ENDPOINT_DATA
    with node id 0. It is exclusive with Nodes (MIMHID_ERR_BUSY both ways). Example
    examples/c/device_from_descriptors.c.
  • BOS descriptor: mimhid_device_set_bos for a composed Device, or in mimhid_device_descriptors;
    mimhid_board_limits.max_bos_bytes. A commit with a BOS and a bcd_usb below 0x0201 is
    MIMHID_ERR_PARAM. Example examples/c/winusb_bulk.c (the Microsoft OS 2.0 platform capability and
    the vendor request that answers it): not run on Windows.
  • Control rules replace control routing: mimhid_device_set_control_rules, mimhid_device_set_rule_data,
    mimhid_node_set_rule_data; actions MIMHID_CONTROL_ANSWER, _ANSWER_LAST_SENT, _ACCEPT, _ASK
    (timeout_ms, when_late), _STALL; the rules of the Nodes come first, then the Device's. A request
    no rule matches is stalled apart from the standard requests of the stack. New flag
    MIMHID_CONTROL_FLAG_ACCEPTED. mimhid_*_set_rule_data takes any length up to the rule's capacity.
  • Endpoint calls of a Node: mimhid_node_endpoint_write, _stall, _clear_stall, _flush,
    _set_policy (replacing mimhid_node_set_queue_depth); a profile Node's IN endpoint takes them too, with
    any of the three policies; a write longer than the board's frame limit is split, and a timeout of 0 is
    accepted with a drop policy. mimhid_device_add_string / _remove_string. New events
    MIMHID_EVENT_ENDPOINT_DATA, _ENDPOINT_HALT, _TRANSFER_LOST (replacing REPORT_LOST).
  • iface.number is the real bInterfaceNumber. The numbers in use are 0, 1, 2, ... without a gap;
    otherwise the commit fails with MIMHID_ERR_PARAM before anything is sent, the missing number in
    mimhid_error_detail.offset. Open Nodes in number order (or in one batch) and close the highest first.
  • Limits: the 16-Node limit is gone (up to 65534 within the board's limits);
    mimhid_device_info.max_nodes and mimhid_board_limits.max_hid_interfaces are removed
    (max_answer_bytes and the new fields replace them).
  • Removed: mimhid_node_open_raw, mimhid_report_send, mimhid_device_set_control_routing,
    MIMHID_CONTROL_MAX_RULES, MIMHID_HID_ITFS, MIMHID_NODE_DATA_CHUNK (now MIMHID_DESC_DATA_CHUNK),
    MIMHID_DEVFLAG_SERIAL_FROM_ID (now MIMHID_DESC_F_SERIAL_FROM_ID).
  • Changed for the target and the program:
    • A Feature report read with no answer set is stalled (it was an empty answer).
    • GET_REPORT of an Input report returns the last report sent with that Report ID.
    • A GET_IDLE straight after a SET_IDLE may still return the old value for one round trip.
    • MIMHID_EVENT_OUTPUT_REPORT / _FEATURE_REPORT for a SET_REPORT arrive when its data stage has.
    • Nodes on a shared interface that use the wait policy count against the first live Node of it.
    • A Device with no Node holds no rules: they are kept until the first commit; inside a batch a change
      of rules marks the Device for the commit at the end.
    • A COMMIT applies the staged rules with report_all 0; the library sends RULES_APPLY with it
      straight after an attach when it is set.

Firmware

  • The firmware builds no descriptor and has no HID driver (CFG_TUD_HID is 0). Every interface runs
    on a generic driver (firmware/common/generic.c, TinyUSB 0.18.0's usbd_edpt_*); what HID asks of
    endpoint 0 is a table of control rules (control.c: two copies, RULES_APPLY swaps them and
    RULE_DATA changes an answer in place, both NAK_BUSY while an answer is being sent). The ESP32-S3
    port's hid_device.c is removed.
  • A BOS descriptor is served by tud_descriptor_bos_cb; none is a stall.
  • firmware/tests/itfs_probe.c is now port_probe.c.

A board a program left attached

  • The board leaves the bus before every configuration, the first of a Device too. A program that
    ended without closing its Device (or closed it with keep_attached) leaves the board on the
    target's bus. The next program's first configuration used to reach a board that was attached:
    its descriptors changed under a device the target had already enumerated, the target never saw
    the new device, and mimhid_device_wait_ready timed out. Found on a Raspberry Pi Pico; the
    simulated board now enumerates only when the pull-up appears, as a real one does.

Entering the bootloader

  • mimhid_device_enter_bootloader (BOOTLOADER, 0x20): the board takes its USB device off the
    target and restarts into the chip's own bootloader, so new firmware can be written without the
    BOOTSEL button. Run on a Raspberry Pi Pico (RP2040). The other ports have it too and were built
    but not run: the STM32F4 resets into its system memory bootloader, the ESP32-S3 into the ROM's
    download mode (written, not built: no ESP-IDF here), and the nRF52840 into the bootloader its
    board carries in flash, when the build states the value that bootloader looks for
    (MIMHID_NRF_BOOTLOADER_GPREGRET); without one the board answers MIMHID_ERR_UNSUPPORTED.

Bindings, tests and documentation

  • Bindings regenerated (Python, C#, Rust: GenericNodeRef.write replaces the descriptor Node of the Rust
    crate); tests/abi/abi_layout.golden updated; versions 0.3.0 (CMake, Cargo, pyproject, csproj).
  • Tests: the composer against the descriptors captured from the previous firmware builder, the
    descriptor walker (every refusal and its offset), the firmware's commit walk, the byte device and BOS
    against the simulated board, a repeated DESC_DATA, a serial number made from the chip id, a gap in the
    interface numbers, more than 16 Nodes, the least queue depth of an interface, an answer that shrinks and
    grows again, an attach refused while attached, and the loss counts of a held endpoint.
  • Documentation read against the code: node and interface limits, interface numbering, queue depths, the
    removed calls, and the descriptors a board serves (docs/LIMITS.md).

Firmware Binary Third-Party Notices

The host library (libmimhid) is licensed under the MIT License and has no third-party runtime library dependencies.

Prebuilt microcontroller firmware images (mimhid_firmware-*) incorporate third-party SDK and USB stack components under permissive licenses:

Firmware asset Third-party components & licenses
mimhid_firmware-rp2040-*, mimhid_firmware-rp2350-* TinyUSB 0.18.0 (MIT), Raspberry Pi Pico SDK 2.2.0 (BSD-3-Clause, Copyright (c) 2020 Raspberry Pi (Trading) Ltd.), Arm CMSIS Core (Apache-2.0), Newlib C runtime
mimhid_firmware-nrf52840-* TinyUSB 0.18.0 (MIT), Nordic Semiconductor nrfx (BSD-3-Clause, Copyright (c) 2017-2024 Nordic Semiconductor ASA), Arm CMSIS 5 (Apache-2.0), Newlib C runtime
mimhid_firmware-stm32f4-* TinyUSB 0.18.0 (MIT), STMicroelectronics cmsis_device_f4 & stm32f4xx_hal_driver (BSD-3-Clause / Apache-2.0, Copyright (c) 2016-2019 STMicroelectronics), Arm CMSIS 5 (Apache-2.0), Newlib C runtime
mimhid_firmware-esp32s3-* TinyUSB 0.18.0 (MIT), Espressif ESP-IDF v5.4.2 (Apache-2.0, Copyright 2015-2025 Espressif Systems), Amazon FreeRTOS Kernel (MIT), Newlib C runtime

Complete copyright notices, license texts, and warranty disclaimers for all firmware binaries are provided in the release asset mimhid_firmware-THIRD_PARTY_NOTICES-0.3.0.txt and in THIRD_PARTY_NOTICES.md / NOTICE.