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

Activity

1. mcuee

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   enhancementNew feature or requestNew feature or request

   build system/CIAnything related to building the project or running on CIAnything related to building the project or running on CI

   on Jun 16, 2023
2. mcuee commented on Jun 16, 2023

   

   mcuee

   on Jun 16, 2023

   Last edited by mcuee

   MemberAuthor

   More actions

   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.
3. mcuee commented on Jun 16, 2023

   

   mcuee

   on Jun 16, 2023

   MemberAuthor

   More actions

   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.
4. mcuee commented on Jun 16, 2023

   

   mcuee

   on Jun 16, 2023

   MemberAuthor

   More actions

   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.
5. mcuee commented on Jun 16, 2023

   

   mcuee

   on Jun 16, 2023

   MemberAuthor

   More actions

   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).
6. mcuee commented on Jun 16, 2023

   

   mcuee

   on Jun 16, 2023

   Last edited by mcuee

   MemberAuthor

   More actions

   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.
7. mcuee commented on Jun 22, 2023

   

   mcuee

   on Jun 22, 2023

   MemberAuthor

   More actions

   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-
8. mcuee commented on Jun 22, 2023

   

   mcuee

   on Jun 22, 2023

   MemberAuthor

   More actions

   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
9. mcuee commented on Jun 22, 2023

   

   mcuee

   on Jun 22, 2023

   MemberAuthor

   More actions

   hid-tool project is also interesting with hid-record and hid-replay.
   https://gitlab.freedesktop.org/libevdev/hid-tools
10. benedekkupper commented on May 18, 2025

    

    benedekkupper

    on May 18, 2025

    More actions

    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.

    👍React with 👍1Reacted by mcuee
11. mcuee

    closed this as completedon May 21, 2025
12. libusb

    locked and limited conversation to collaborators on May 21, 2025
13. mcuee

    converted this issue into a discussion #743 on May 21, 2025