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

[mcuee]

There is an example device for hidraw from umockdev project. Maybe we can integrate it for CI under Linux.
https://github.com/martinpitt/umockdev/tree/main/devices/hidraw

[mcuee]

Ref: libusb project uses umockdev for Linux testing using a container.
https://github.com/libusb/libusb/blob/master/tests/umockdev.c
https://github.com/libusb/libusb/blob/master/.github/workflows/linux.yml

[Youw]

The alternative: uhid.
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 am not so sure if this is possible or not.
https://github.com/vpelletier/python-functionfs

[mcuee]

BTW, other than CI, it is also good to see if we have some known good HID device or FW to test HIDAPI.

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

Just wondering what is the test device you are using to test HIDAPI?

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

[Youw]

Unfortunately I don't have any devices dedicated for testing, only a few of my peripherals, and a few devices from my employer (I'm under NDA not to disclose what those are), which have a few fixed input/output/interrupt reports, that I usually use for some sanity testing.

[Youw]

Yeah, would be great to have 1-2 FW samples for some well known simple/cheap device to be able to test most (all?) of the HIDAPI.

[mcuee]

@todbot has some test firmware for hidapitester which can be used for hidapi testing as well.
https://github.com/todbot/hidapitester/tree/master/test_hardware

1. ProMicroRawHID -- USB AVR Atmega32U4
2. TeensyRawHID -- can be used by different Teensy boards (USB AVR and Arm Cortex M MCUs)
3. two tinyusb examples which can be used by many ARM core MCU development boards including STM32 and Raspberry Pi Pico, as well as non-ARM core MCUs like ESP32 S2/S3 or MSP430

TinyUSB
https://github.com/hathach/tinyusb

node-hid has some examples as well.
https://github.com/node-hid/node-hid#examples

[mcuee]

Jan Axelson has quite some HID examples for things like Cypress EZ-USB FX2LP and Microchip USB PIC.
http://janaxelson.com/hidpage.htm

[mcuee]

Simple test for Jan Axelson FX2HID example (0925:1234) -- loop back of Input/Output report (no report ID) using hidapitest.

For this FW, I have to explicitly send output report ID 0.

PS C:\work\hid\hidapitester> .\hidapitester --vidpid 0925:1234 --list-detail
0925/1234: CYPRESS - EZ-USB FX2 HID USBHIDIO
  vendorId:      0x0925
  productId:     0x1234
  usagePage:     0xFFA0
  usage:         0x0001
  serial_number:
  interface:     0
  path: \\?\HID#VID_0925&PID_1234#7&21072e4a&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}

PS C:\work\hid\hidapitester> .\hidapitester --vidpid 0925:1234 --open --send-output 0,8,9 --read-input
Opening device, vid/pid: 0x0925/0x1234
Writing output report of 64-bytes...wrote 3 bytes:
 00 08 09 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
Reading 64-byte input report 0, 250 msec timeout...read 2 bytes:
 08 09 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
Closing device
PS C:\work\hid\hidapitester> .\hidapitester --vidpid 0925:1234 --open -l 3 --send-output 0,8,9 --read-input
Opening device, vid/pid: 0x0925/0x1234
Writing output report of 3-bytes...wrote 3 bytes:
 00 08 09
Reading 3-byte input report 0, 250 msec timeout...read 2 bytes:
 08 09 00
Closing device

Her USB PIC generic HID example has feature report loopback as well.

PS C:\work\hid\hidapitester> .\hidapitester --vidpid 0925:7001 --list-detail
0925/7001: Microchip Technology Inc. - Generic HID
  vendorId:      0x0925
  productId:     0x7001
  usagePage:     0xFFA0
  usage:         0x0001
  serial_number:
  interface:     0
  path: \\?\HID#VID_0925&PID_7001#7&1e741593&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}

PS C:\work\hid\hidapitester> .\hidapitester --vidpid 0925:7001 --open -l 3 --send-output 0,1,2 --read-input
Opening device, vid/pid: 0x0925/0x7001
Writing output report of 3-bytes...wrote 3 bytes:
 00 01 02
Reading 3-byte input report 0, 250 msec timeout...read 2 bytes:
 01 02 00
Closing device

S C:\work\hid\hidapitester> .\hidapitester --vidpid 0925:7001 --open -l 3 --send-feature 0,1,2 --read-feature 0
Opening device, vid/pid: 0x0925/0x7001
Writing 3-byte feature report...wrote 3 bytes:
 00 01 02
Reading 3-byte feature report, report_id 0...read 3 bytes:
 00 01 02
Closing device

I have done the modification of the generic HID FW to add report ID (Input 1, Output 2, Feature OUT 3, Feature IN 4). I used that to test libusb Windows HID backend many year ago during the initial stage of the libusb Windows backend development.

PS C:\work\hid\hidapitester> .\hidapitester --vidpid 0925:7001 --open -l 3 --send-output 2,8,9 --read-input 1
Opening device, vid/pid: 0x0925/0x7001
Writing output report of 3-bytes...wrote 3 bytes:
 02 08 09
Reading 3-byte input report 0, 250 msec timeout...read 3 bytes:
 01 08 09
Closing device

PS C:\work\hid\hidapitester> .\hidapitester --vidpid 0925:7001 --open -l 3 --send-feature 3,6,7 --read-feature 4
Opening device, vid/pid: 0x0925/0x7001
Writing 3-byte feature report...wrote 3 bytes:
 03 06 07
Reading 3-byte feature report, report_id 4...read 3 bytes:
 04 06 07
Closing device

[mcuee]

Simple test using hidapitester for the Microchip Simple HID demo (which is the base for the FW used in hidtest). I am using the mla version for the 8bit/16bit USB PICs.

1)  toggle LED
PS C:\work\hid\hidapitester> .\hidapitester --vidpid 04d8:003f --open -l 2 --send-output 0x01,0x80
Opening device, vid/pid: 0x04D8/0x003F
Writing output report of 2-bytes...wrote 65 bytes:
 01 80
Closing device
2) read button status
PS C:\work\hid\hidapitester> .\hidapitester --vidpid 04d8:003f --open -l 2 --send-output 0x01,0x81 --read-input
Opening device, vid/pid: 0x04D8/0x003F
Writing output report of 2-bytes...wrote 65 bytes:
 01 81
Reading 2-byte input report 0, 250 msec timeout...read 2 bytes:
 81 01
Closing device

[mcuee]

@Youw

For libusb testing, I usually recommend Cypress EZ-USB FX3 (SuperSpeed). Then EZ-USB FX2LP (High-Speed).
https://github.com/libusb/libusb/wiki/FAQ#do-you-have-a-list-of-known-good-devices-to-test-libusb

I think for HIDAPI testing, maybe FX3 is a bit overkill but you may want to get cheap EZ-USB FX2LP breakout from online marketplace like AliExpress at about US$5. For example, I have the following board.

I just did a simple modification of Jan Axelson's fx2hid example to extend the Input/Output report size to 64 bytes.

PS C:\work\hid\hidapitester> .\hidapitester --vidpid 0925:1234 --open -l 65 --send-output 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64  --read-input
Opening device, vid/pid: 0x0925/0x1234
Writing output report of 65-bytes...wrote 65 bytes:
 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F
 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F
 40
Reading 65-byte input report 0, 250 msec timeout...read 64 bytes:
 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20
 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 40
 00
Closing device

fx2hid_64bytes.zip
Target.zip

Edit: take note that in order to develop high speed HID USB device using FX2LP with wMaxPacketSize > 64 Bytes, we can not use EP1IN or EP1OUT, as their buf size is only 64 bytes. We should probably use EP2 and EP6 (buffer size equals to 512 Bytes or 1024 Bytes). So the modification is not as simple. But if we just need to get report size >64 bytes, then it is still possible to use EP1 IN and EP1 OUT. We need to handle the fragamentation in firmware.