Repository navigation
v0.3.0
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 indocs/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,ACCEPTwith 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 andbcdUSB0x0210
(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 withbcdUSB0x0210 and no BOS,
the target did not enumerate the device. Not run: Windows. hw_bulk wait|newest|oldest,hw_control_rulesandhw_compositeagain on the same firmware; the
latency of ten runs indocs/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 andANSWERdescriptors
(MIMHID_DESC_*); they replaceDEVICE_CONFIG,NODE_BEGINandNODE_DATA. AtCOMMITthe 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
bcdUSB0x0201 or more. - Data frames name endpoints.
EP_IN(0x41..0x4F) andEP_OUT(0xC1..0xCF) carry the endpoint
number, not a node id. New commandsEP_CONFIG(0x1B, replacesQUEUE_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_LOSTbecameTRANSFER_LOST, which names the endpoint.
DESC_HID_REPORT(4),FEATURE(0x14) and the eventsSET_REPORT,SET_PROTOCOL,SET_IDLE,
OUTPUT_REPORT(5 to 8) are gone and not reused. - An
ANSWERrule has a capacity and a length (RULEbytes 14..15 and 16..17). The board reserves the
capacity,RULE_DATAsets any length up to it, so a shortened answer can grow again after the table
is rebuilt. - A
COMMITthat attaches is refused withNAK_STATEwhile the board is attached: it would change
the descriptors under a device the target has enumerated.mimhid_device_connecton a configured
Device sends nothing and returnsMIMHID_OK. PONG(MIMHID_PONG_MIN_LEN49): 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)
andmax_bos_bytes(47..48); the unique id starts at 49. The board's limits: 160 rules, 4096 bytes of
answers, 32ANSWER_LAST_SENTrules, 256 bytes of BOS (MIMHID_CONTROL_RULES,MIMHID_ANSWER_BYTES,
MIMHID_LAST_SENT_SLOTS,MIMHID_MAX_BOS_BYTES).
API
mimhid_node_opentakes 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, ...) aremimhid_node_open_profilewithmimhid_hid_node_config. Helpers
mimhid_hid_descriptor_bytesandmimhid_hid_descriptor_rule; examplesvendor_bulk.cand
hid_interface.c.- A Device can be given as bytes:
mimhid_device_set_descriptors/_clear_descriptors
(mimhid_device_descriptors), raw stringsmimhid_device_set_string/_clear_string(any index and
language), and the endpoint calls by addressmimhid_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 isMIMHID_EVENT_ENDPOINT_DATA
with node id 0. It is exclusive with Nodes (MIMHID_ERR_BUSYboth ways). Example
examples/c/device_from_descriptors.c. - BOS descriptor:
mimhid_device_set_bosfor a composed Device, or inmimhid_device_descriptors;
mimhid_board_limits.max_bos_bytes. A commit with a BOS and abcd_usbbelow 0x0201 is
MIMHID_ERR_PARAM. Exampleexamples/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; actionsMIMHID_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_datatakes any length up to the rule's capacity. - Endpoint calls of a Node:
mimhid_node_endpoint_write,_stall,_clear_stall,_flush,
_set_policy(replacingmimhid_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(replacingREPORT_LOST). iface.numberis the realbInterfaceNumber. The numbers in use are 0, 1, 2, ... without a gap;
otherwise the commit fails withMIMHID_ERR_PARAMbefore 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_nodesandmimhid_board_limits.max_hid_interfacesare removed
(max_answer_bytesand 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(nowMIMHID_DESC_DATA_CHUNK),
MIMHID_DEVFLAG_SERIAL_FROM_ID(nowMIMHID_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_REPORTof an Input report returns the last report sent with that Report ID.- A
GET_IDLEstraight after aSET_IDLEmay still return the old value for one round trip. MIMHID_EVENT_OUTPUT_REPORT/_FEATURE_REPORTfor aSET_REPORTarrive 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
COMMITapplies the staged rules withreport_all0; the library sendsRULES_APPLYwith it
straight after an attach when it is set.
Firmware
- The firmware builds no descriptor and has no HID driver (
CFG_TUD_HIDis 0). Every interface runs
on a generic driver (firmware/common/generic.c, TinyUSB 0.18.0'susbd_edpt_*); what HID asks of
endpoint 0 is a table of control rules (control.c: two copies,RULES_APPLYswaps them and
RULE_DATAchanges an answer in place, bothNAK_BUSYwhile an answer is being sent). The ESP32-S3
port'shid_device.cis removed. - A BOS descriptor is served by
tud_descriptor_bos_cb; none is a stall. firmware/tests/itfs_probe.cis nowport_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 withkeep_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, andmimhid_device_wait_readytimed 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 answersMIMHID_ERR_UNSUPPORTED.
Bindings, tests and documentation
- Bindings regenerated (Python, C#, Rust:
GenericNodeRef.writereplaces the descriptor Node of the Rust
crate);tests/abi/abi_layout.goldenupdated; 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 repeatedDESC_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.