hidapi icon indicating copy to clipboard operation
hidapi copied to clipboard
verified publisher icon libusb

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

Open mcuee opened this issue 2 years ago • 8 comments

This is a clean-up of #590.

  • #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 avatar Jun 16 '23 22:06 mcuee

For CI, it is good to use uhid.

From Youw:

  • https://github.com/libusb/hidapi/discussions/590?converting=1#discussioncomment-6201603

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

mcuee avatar Jun 16 '23 22:06 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

  1. 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.

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

mcuee avatar Jun 16 '23 22:06 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 avatar Jun 16 '23 22:06 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 avatar Jun 16 '23 23:06 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 avatar Jun 16 '23 23:06 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 avatar Jun 22 '23 14:06 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 avatar Jun 22 '23 15:06 mcuee

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

mcuee avatar Jun 22 '23 15:06 mcuee