hid_error implementation for libusb

Youw commented 1 month ago

This is initial implementation.

hid_error is set correctly for most of the API functions;
refactored iconv routines - common code for utf16 and utf8 to wchar_t implementation;
hid_libusb_error to have libusb error code when possible;

Closes: #690 Fixes: #684

Youw commented 1 month ago

@mcuee if you could test this one as well - would be perfect.

mcuee commented 1 month ago

@mcuee if you could test this one as well - would be perfect.

Yes I will carry out the test later today.

mcuee commented 1 month ago

First simple test -- looks good. Tested under Ubuntu Linux 20.04.

1) git main:

mcuee@UbuntuSwift3 ~/build/hid/hidapi (master)$ sudo ./hidtest/hidtest-libusb 
hidapi test/example tool. Compiled with hidapi version 0.15.0, runtime version 0.15.0.
Compile-time version matches runtime version of hidapi.

Device Found
  type: 04d8 003f
  path: 3-3:1.0
  serial_number: (null)
  Manufacturer: Microchip Technology Inc.
  Product:      Simple HID Device Demo
  Release:      2
  Interface:    0
  Usage (page): 0x0 (0x0)
  Bus type: 1 (USB)

  Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29, 
0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81, 
0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0, 
Device Found
  type: 1ea7 0064
  path: 3-1:1.0
  serial_number: (null)
  Manufacturer: (null)
  Product:      2.4G Mouse
  Release:      200
  Interface:    0
  Usage (page): 0x0 (0x0)
  Bus type: 1 (USB)

  Report Descriptor: (105 bytes)
0x06, 0xb5, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x85, 0xb5, 0x09, 
0x02, 0x15, 0x00, 0x26, 0xff, 0x00, 0x75, 0x08, 0x95, 0x07, 
0x81, 0x02, 0x09, 0x02, 0x15, 0x00, 0x26, 0xff, 0x00, 0x75, 
0x08, 0x95, 0x07, 0x91, 0x02, 0xc0, 0x05, 0x01, 0x09, 0x02, 
0xa1, 0x01, 0x85, 0x02, 0x09, 0x01, 0xa1, 0x00, 0x05, 0x09, 
0x19, 0x01, 0x29, 0x08, 0x15, 0x00, 0x25, 0x01, 0x95, 0x08, 
0x75, 0x01, 0x81, 0x02, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 
0x16, 0x01, 0xf8, 0x26, 0xff, 0x07, 0x75, 0x0c, 0x95, 0x02, 
0x81, 0x06, 0x09, 0x38, 0x15, 0x81, 0x25, 0x7f, 0x75, 0x08, 
0x95, 0x01, 0x81, 0x06, 0x05, 0x0c, 0x0a, 0x38, 0x02, 0x95, 
0x01, 0x81, 0x06, 0xc0, 0xc0, 
Manufacturer String: Microchip Technology Inc.
Product String: Simple HID Device Demo
Serial Number String: (1033)   Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29, 
0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81, 
0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0, 
Device Found
  type: 04d8 003f
  path: 3-3:1.0
  serial_number: (null)
  Manufacturer: Microchip Technology Inc.
  Product:      Simple HID Device Demo
  Release:      2
  Interface:    0
  Usage (page): 0x1 (0xff00)
  Bus type: 1 (USB)

Indexed String 1: Microchip Technology Inc.
Unable to send a feature report.
Unable to get a feature report: hid_error is not implemented yet
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
read() timeout

2) This PR

mcuee@UbuntuSwift3 ~/build/hid/hidapi_pr698 (implement-hid-error)$ sudo ./hidtest/hidtest-libusb 
[sudo] password for mcuee: 
hidapi test/example tool. Compiled with hidapi version 0.15.0, runtime version 0.15.0.
Compile-time version matches runtime version of hidapi.

Device Found
  type: 04d8 003f
  path: 3-3:1.0
  serial_number: (null)
  Manufacturer: Microchip Technology Inc.
  Product:      Simple HID Device Demo
  Release:      2
  Interface:    0
  Usage (page): 0x0 (0x0)
  Bus type: 1 (USB)

  Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29, 
0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81, 
0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0, 
Device Found
  type: 1ea7 0064
  path: 3-1:1.0
  serial_number: (null)
  Manufacturer: (null)
  Product:      2.4G Mouse
  Release:      200
  Interface:    0
  Usage (page): 0x0 (0x0)
  Bus type: 1 (USB)

  Report Descriptor: (105 bytes)
0x06, 0xb5, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x85, 0xb5, 0x09, 
0x02, 0x15, 0x00, 0x26, 0xff, 0x00, 0x75, 0x08, 0x95, 0x07, 
0x81, 0x02, 0x09, 0x02, 0x15, 0x00, 0x26, 0xff, 0x00, 0x75, 
0x08, 0x95, 0x07, 0x91, 0x02, 0xc0, 0x05, 0x01, 0x09, 0x02, 
0xa1, 0x01, 0x85, 0x02, 0x09, 0x01, 0xa1, 0x00, 0x05, 0x09, 
0x19, 0x01, 0x29, 0x08, 0x15, 0x00, 0x25, 0x01, 0x95, 0x08, 
0x75, 0x01, 0x81, 0x02, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 
0x16, 0x01, 0xf8, 0x26, 0xff, 0x07, 0x75, 0x0c, 0x95, 0x02, 
0x81, 0x06, 0x09, 0x38, 0x15, 0x81, 0x25, 0x7f, 0x75, 0x08, 
0x95, 0x01, 0x81, 0x06, 0x05, 0x0c, 0x0a, 0x38, 0x02, 0x95, 
0x01, 0x81, 0x06, 0xc0, 0xc0, 
Manufacturer String: Microchip Technology Inc.
Product String: Simple HID Device Demo
Serial Number String: (1033)   Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29, 
0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81, 
0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0, 
Device Found
  type: 04d8 003f
  path: 3-3:1.0
  serial_number: (null)
  Manufacturer: Microchip Technology Inc.
  Product:      Simple HID Device Demo
  Release:      2
  Interface:    0
  Usage (page): 0x1 (0xff00)
  Bus type: 1 (USB)

Indexed String 1: Microchip Technology Inc.
Unable to send a feature report.
Unable to get a feature report: hid_get_feature_report: (LIBUSB_ERROR_PIPE) Pipe erro
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
read() timeout

mcuee commented 1 month ago

Tested under FreeBSD 14.1 and this PR is good as well.

mcuee@freebsd14:~/build/hidapi_pr698 $ sudo ./hidtest/hidtest
hidapi test/example tool. Compiled with hidapi version 0.15.0, runtime version 0.15.0.
Compile-time version matches runtime version of hidapi.

Device Found
  type: 04d8 003f
  path: 0-4:1.0
  serial_number: (null)
  Manufacturer: Microchip Technology Inc.
  Product:      Simple HID Device Demo
  Release:      2
  Interface:    0
  Usage (page): 0x0 (0x0)
  Bus type: 1 (USB)

  Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29,
0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81,
0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0,
Manufacturer String: Microchip Technology Inc.
Product String: Simple HID Device Demo
Serial Number String: (1033  Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29,
0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81,
0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0,
Device Found
  type: 04d8 003f
  path: 0-4:1.0
  serial_number: (null)
  Manufacturer: Microchip Technology Inc.
  Product:      Simple HID Device Demo
  Release:      2
  Interface:    0
  Usage (page): 0x1 (0xff00)
  Bus type: 1 (USB)

Indexed String 1: Microchip Technology Inc.
Unable to send a feature report.
Unable to get a feature report: hid_get_feature_report: (LIBUSB_ERROR_NO_DEVICE) No devic
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
read() timeout

mcuee commented 1 month ago

hid_error is not used by hidapitester so I can not test using hidapitester as of now.

https://github.com/todbot/hidapitester/issues/24

Anyway, it is good that git main and this PR works fine under FreeBSD 14.1 Release using hidapitester as well.

mcuee@freebsd14:~/build/hidapitester $ sudo ./hidapitester --vidpid 04d8/003f --open --send-output 0x00,0x80
Opening device, vid/pid: 0x04D8/0x003F
Writing output report of 64-bytes...wrote 64 bytes:
 00 80 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
mcuee@freebsd14:~/build/hidapitester $ sudo ./hidapitester --vidpid 04d8/003f --open --send-output 0x00,0x80
Opening device, vid/pid: 0x04D8/0x003F
Writing output report of 64-bytes...wrote 64 bytes:
 00 80 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

mcuee@freebsd14:~/build/hidapitester $ sudo ./hidapitester --vidpid 04d8/003f --open --send-output 0x00,0x81 --read-input
Opening device, vid/pid: 0x04D8/0x003F
Writing output report of 64-bytes...wrote 64 bytes:
 00 81 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
Reading up to 64-byte input report, 250 msec timeout...read 64 bytes:
 81 01 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

mcuee@freebsd14:~/build/hidapitester $ sudo ./hidapitester --vidpid 04d8/003f --open --get-report-descriptor
Opening device, vid/pid: 0x04D8/0x003F
Report Descriptor:
 06 00 FF 09 01 A1 01 19 01 29 40 15 01 25 40 75 08 95 40 81 00 19 01 29 40 91 00 C0
Closing device
mcuee@freebsd14:~/build/hidapitester $ sudo ./hidapitester --vidpid 04d8/003f --list-detail
04D8/003F: Microchip Technology Inc. - Simple HID Device Demo
  vendorId:      0x04D8
  productId:     0x003F
  usagePage:     0x0000
  usage:         0x0000
  serial_number: (null)
  interface:     0
  path: 0-4:1.0

mcuee@freebsd14:~/build/hidapitester $ sudo ./hidapitester --vidpid 04d8/003f --list-usages
04D8/003F / 0000/0000  Microchip Technology Inc. - Simple HID Device Demo

mcuee commented 1 month ago

@Youw

I think this PR is good to go.

Youw commented 1 month ago

@matheusmoreira would you check as well?

Youw commented 1 month ago

Oh, from the logs I actually see one issue - looks like an error message is cut by one symbol:

Unable to get a feature report: hid_get_feature_report: (LIBUSB_ERROR_PIPE) Pipe erro

Unable to get a feature report: hid_get_feature_report: (LIBUSB_ERROR_NO_DEVICE) No devic

I'll double-check this one.

Youw commented 1 month ago

Now we should be good

mcuee commented 1 month ago

Now we should be good

Yes it is good now.

mcuee@UbuntuSwift3 ~/build/hid/hidapi_pr698 (implement-hid-error)$ sudo ./hidtest/hidtest-libusb 
hidapi test/example tool. Compiled with hidapi version 0.15.0, runtime version 0.15.0.
Compile-time version matches runtime version of hidapi.

Device Found
  type: 04d8 003f
  path: 3-2.4:1.0
  serial_number: (null)
  Manufacturer: Microchip Technology Inc.
  Product:      Simple HID Device Demo
  Release:      2
  Interface:    0
  Usage (page): 0x0 (0x0)
  Bus type: 1 (USB)

  Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29, 
0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81, 
0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0, 
Device Found
  type: 1ea7 0064
  path: 3-1:1.0
  serial_number: (null)
  Manufacturer: (null)
  Product:      2.4G Mouse
  Release:      200
  Interface:    0
  Usage (page): 0x0 (0x0)
  Bus type: 1 (USB)

  Report Descriptor: (105 bytes)
0x06, 0xb5, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x85, 0xb5, 0x09, 
0x02, 0x15, 0x00, 0x26, 0xff, 0x00, 0x75, 0x08, 0x95, 0x07, 
0x81, 0x02, 0x09, 0x02, 0x15, 0x00, 0x26, 0xff, 0x00, 0x75, 
0x08, 0x95, 0x07, 0x91, 0x02, 0xc0, 0x05, 0x01, 0x09, 0x02, 
0xa1, 0x01, 0x85, 0x02, 0x09, 0x01, 0xa1, 0x00, 0x05, 0x09, 
0x19, 0x01, 0x29, 0x08, 0x15, 0x00, 0x25, 0x01, 0x95, 0x08, 
0x75, 0x01, 0x81, 0x02, 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 
0x16, 0x01, 0xf8, 0x26, 0xff, 0x07, 0x75, 0x0c, 0x95, 0x02, 
0x81, 0x06, 0x09, 0x38, 0x15, 0x81, 0x25, 0x7f, 0x75, 0x08, 
0x95, 0x01, 0x81, 0x06, 0x05, 0x0c, 0x0a, 0x38, 0x02, 0x95, 
0x01, 0x81, 0x06, 0xc0, 0xc0, 
Manufacturer String: Microchip Technology Inc.
Product String: Simple HID Device Demo
Serial Number String: (1033)   Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29, 
0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81, 
0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0, 
Device Found
  type: 04d8 003f
  path: 3-2.4:1.0
  serial_number: (null)
  Manufacturer: Microchip Technology Inc.
  Product:      Simple HID Device Demo
  Release:      2
  Interface:    0
  Usage (page): 0x1 (0xff00)
  Bus type: 1 (USB)

Indexed String 1: Microchip Technology Inc.
Unable to send a feature report.
Unable to get a feature report: hid_get_feature_report: (LIBUSB_ERROR_PIPE) Pipe error
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
read() timeout

mcuee commented 1 month ago

It is also good under FreeBSD 14.1 release.

mcuee@freebsd14:~/build/hidapi_pr698 $ sudo ./hidtest/hidtest 
hidapi test/example tool. Compiled with hidapi version 0.15.0, runtime version 0.15.0.
Compile-time version matches runtime version of hidapi.

Device Found
  type: 04d8 003f
  path: 0-4:1.0
  serial_number: (null)
  Manufacturer: Microchip Technology Inc.
  Product:      Simple HID Device Demo
  Release:      2
  Interface:    0
  Usage (page): 0x0 (0x0)
  Bus type: 1 (USB)

  Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29, 
0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81, 
0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0, 
Manufacturer String: Microchip Technology Inc.
Product String: Simple HID Device Demo
Unable to read serial number string
Serial Number String: (0) 
  Report Descriptor: (28 bytes)
0x06, 0x00, 0xff, 0x09, 0x01, 0xa1, 0x01, 0x19, 0x01, 0x29, 
0x40, 0x15, 0x01, 0x25, 0x40, 0x75, 0x08, 0x95, 0x40, 0x81, 
0x00, 0x19, 0x01, 0x29, 0x40, 0x91, 0x00, 0xc0, 
Device Found
  type: 04d8 003f
  path: 0-4:1.0
  serial_number: (null)
  Manufacturer: Microchip Technology Inc.
  Product:      Simple HID Device Demo
  Release:      2
  Interface:    0
  Usage (page): 0x1 (0xff00)
  Bus type: 1 (USB)

Indexed String 1: Microchip Technology Inc.
Unable to send a feature report.
Unable to get a feature report: hid_get_feature_report: (LIBUSB_ERROR_NO_DEVICE) No device
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
waiting...
read() timeout

matheusmoreira commented 1 month ago

Working for me as well on Arch Linux. The new function that just returns the libusb error code is perfect for my needs.

Youw commented 1 month ago

I assume you've tried the new hid_libusb_error?

matheusmoreira commented 1 month ago

Yeah. It's still incomplete but the feature report functions set the libusb error states which are what I need. Would you consider a similar error code based API for hid as well? It's much easier to use than strings.

Youw commented 1 month ago

Would you consider a similar error code based API for hid as well?

Not for v0.x, no.

It's much easier to use than strings.

HIDAPI was never designed to diagnose what went wrong, only an indication that something happened and as string for logging purpose only.

still incomplete

Can you elaborate? I've tried to cover all failure cases.

matheusmoreira commented 1 month ago

It's just that I saw some TODO lines in the source code and assumed there were still failure cases left to cover. If they have all been handled then it looks good for merging as far as I can tell.

Youw commented 1 month ago

Ah those - right, still there. For the global state (hid_enumerate/hid_open/etc.).

Youw commented 1 month ago

This PR actually has non-obvious side-effect (related to #688).

Because with hid_error implementation, when calling hid_read concurently to other functions (e.g. hid_write) from different threads, in some cases (e.g. device disconnected) the error might be attempted to set in different threads causing a race-condition. W/o hid_error implementation that de-facto wasn't an issue for libusb implementation.

libusb / hidapi

hid_error implementation for libusb #698