HIDAPI testing device with known good firmware, including using Virtual HID device for CI Testing

[mcuee]

This is a clean-up of #590.

• HIDAPI testing device with known good firmware, including using Virtual HID device for CI Testing #590

It will be good to have a list of known-good firmware to test hidapi. It is also good to have virtual HID device for CI.

[mcuee]

For CI, it is good to use uhid.

From Youw:

• HIDAPI testing device with known good firmware, including using Virtual HID device for CI Testing #590

In one of the issues there was a sample. The sample implementation actually has several issues/bugs, but the overall aproach is fine.

[mcuee]

I tend to think the two examples from hidapitester can be of good use to hidapi project testing.
https://github.com/todbot/hidapitester/tree/master/test_hardware

1. ProMicroRawHID: this should work on many Microchip Atmega32U4 based boards like Arduino Micro and Leonardo. The underlying library seems to have a problem with Feature report but it is not difficult to fix.
   https://github.com/todbot/hidapitester/blob/master/test_hardware/ProMicroRawHID/ProMicroRawHID.ino

Reference: the library is said to support USB AVR and SAMD21.
https://github.com/NicoHood/HID

2. hidtest_tinyusb: this should work on many tinyusb supported boards. I have only tested SAMD21 based boards but maybe it can work with other boards as well with some minor changes.
   https://github.com/todbot/hidapitester/blob/master/test_hardware/hidtest_tinyusb/hidtest_tinyusb.ino

Reference:
https://github.com/adafruit/Adafruit_TinyUSB_Arduino
This is the underlying library which should work with Raspberry Pico and ESP32 S2/S3/C3/C6 with USB support and Microchip SAMD21 based boards as well as Nodic nRF52 based boards.

3. Maybe we can adapt hidtest.c to work with one of them and use Readme to document the example code for another one.

[mcuee]

For HID over I2C/SPI, I tend to think it is difficult to do under Windows as a driver may be needed.
https://learn.microsoft.com/en-us/windows-hardware/drivers/hid/hid-over-i2c-guide
https://learn.microsoft.com/en-us/windows-hardware/drivers/hid/hid-over-spi

There are some examples of HID over I2C for Linux (using things as Raspberry Pi 4/400 as Linux host)
https://github.com/benedekkupper/stm32-i2c-hid.git (STM32)
https://github.com/NordicPlayground/nrf52-i2c-hid-demo (Nodic NRF52).

For HID over SPI, it seems to me the support under Linux is quite new.

[mcuee]

For libusb, here is the reference, it can be the same for USB HID device development. But for Bluetooth/BLE and even I2C/SPI HID device, we need different tools.

https://github.com/libusb/libusb/wiki/FAQ#do-you-have-a-list-of-known-good-devices-to-test-libusb

• Highly recommended -- Cypress FX3 SuperSpeed Explorer Kit or other FX3 based boards https://www.cypress.com/documentation/development-kitsboards/cyusb3kit-003-ez-usb-fx3-superspeed-explorer-kit
• Cypress FX2LP
• Arm Cortex M MCU based development board like ST STM32 (eg: Bluepill and Blackpill, Discovery or Nucleo boards), Microchip SAM MCU, Raspberry Pi Pico, etc
• Other USB MCU like Microhip PIC or AVR, TI MSP 430, etc
• Linux USB Gadget devices (eg: using Raspberry Pi Zero or Raspberry Pi 4B/400)
• libusb-1.0.26 has the umockdev based testing under Linux

Other than vendor provided USB stacks (sometimes with proprietary licenses), there are also Opensource MCU USB stacks.

• tinyusb - https://github.com/hathach/tinyusb
• cherryusb - https://github.com/sakumisu/CherryUSB
• lufa - https://github.com/abcminiuser/lufa
• m-stack for PIC16/18/24/32 - https://github.com/signal11/m-stack.git
• libopencm3 for ARM Cortex-M3 - http://libopencm3.org/
• libusb_stm32 - https://github.com/dmitrystu/libusb_stm32.git
• PIC16/18 USB stack - https://github.com/johnnydrazzi/USB-Stack
• fx2lib for EZUSB FX2LP - https://github.com/djmuhlestein/fx2lib

For me I usually use whatever HID device I have with me like the following for general test using hidtest.

1. Logitech USB Receiver
2. Plantronics USB Headset
3. My laptop has built-in I2C HID device (Synaptics Touch Pad)
4. USB Mouse/Keyboard
5. Bluetooth Mouse (Microsoft 3600 and maybe others)
6. Logitech Dual Action USB Gamepad
7. Wireless Xbox Gamepad (old version)
8. ESP32S based BLE HID example

For more real tests with hidapitester or simple test codes. I do not know much about the FW development other than simple modifications of the USB PIC USB codes and maybe a little bit with USB AVRs.

1. Microchip PIC18F87J50 with custom HID FW (8 bit USB PIC18 MCU). I have USB PIC24 and PIC32 board as well but seldom use them.
2. Cypress EZ-USB FX2LP breadout board
3. Arduino Leonardo and Pro Micro based HID example (8 bit USB AVR MCU)
4. Arduino M0 clone (Atmel SAMD21)
5. Teensy 2.0 and 2.0+ based HID example (8 bit USB AVR MCU)
6. Various STM32 MCU demo boards
7. Raspberry Pi Pico using C++ or MicroPython or CircuitPython
8. ESP32C3/S2/S3 based boards using C or MicroPython or CircuitPython
9. BBC Micro:bit v2 (Nordic nRF52833) using C or MicroPython or CircuitPython

Then I use some HID devices to test hidapi indirectly using avrdude and OpenOCD (CMSIS DAP v1 compliant adapters).

[mcuee]

A very good input from @JoergAtGithub in the #590 discussion

It should be a device, where you can program any HID ReportDescriptor, PhysicalDescriptor and StringDescriptor on low-level (byte-wise). Not something where you configure everything on high-level, because for testing it makes a difference how we order the items in the ReportDescriptor.

I think typical MCU development boards can do the above. However, I have not seen many examples for Physical Descritors and complex HID Report Descriptors.

[mcuee]

For virtual HID device, Linux has uhid, FreeBSD has uhidd.
https://wiki.freebsd.org/uhidd

There is a project which deals with virtual HID device under macOS here:
https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice

Windows has the Virtual HID Framework (VHF) as well but I guess it is not easy to have someone to help out writing one for testing.
https://learn.microsoft.com/en-us/windows-hardware/drivers/hid/virtual-hid-framework--vhf-

[mcuee]

Linux uhid documentation
https://kernel.org/doc/Documentation/hid/uhid.txt

Linux uhid examples:

Kernel uhid example
https://github.com/torvalds/linux/blob/master/samples/uhid/uhid-example.c

rust
https://docs.rs/tokio-linux-uhid/latest/tokio_linux_uhid/

Virtual Bluetooth HID device
https://github.com/4ndrej/hidclient.git
https://github.com/Alkaid-Benetnash/EmuBTHID.git

[mcuee]

hid-tool project is also interesting with hid-record and hid-replay.
https://gitlab.freedesktop.org/libevdev/hid-tools

[benedekkupper]

If this is still relevant, I can be of help. I have MCU firmware for HID over I2C, USB and BLE:
https://github.com/benedekkupper/stm32-i2c-hid
https://github.com/IntergatedCircuits/c2usb-zephyr-examples
They all use the same device side API, so a single implementation can be used on all targets. The former is specific to STM32, the latter is using generic Zephyr RTOS subsystems, so quite portable.