Standardize device object format with node-hid

[MadLittleMods]

Standardize device object format with node-hid

From a discussion with @lange ☝️ November 23, 2017 7:44 PM

Current state of things

Current [email protected]

{
  locationId: 0,
  vendorId: 5824,
  productId: 1155,
  deviceName: 'Teensy USB Serial (COM3)',
  manufacturer: 'PJRC.COM, LLC.',
  serialNumber: '',
  deviceAddress: 11
}

Current [email protected]

{
  vendorId: 1226,
  productId: 34,
  path: '\\\\?\\hid#vid_04ca&pid_0022#7&1d7596e&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}',
  manufacturer: 'LITEON Technology',
  product: 'USB Keyboard',
  release: 265,
  interface: -1,
  usagePage: 1,
  usage: 6
}

---

Changes

Will require a major version bump!

• Remove locationId
  • Seems like the added path property would cover this but would need to test if it remains the same across reboot
  • Currently, only defined on macOS and described as "The locationID uniquely identifies the device and will remain the same, even across reboots, so long as the bus topology doesn't change."
  • This could be implmented on Windows with the <instance-specific-ID> portion of the "Device instance ID/path", see Extract Serial Number from Device Instance ID/Path on Windows. #50 (comment)
• Maintain vendorId
• Maintain productId
• Rename deviceName to product
• Maintain manufacturer
• Maintain serialNumber
• Maintain deviceAddress ❔
  • This isn't in node-hid but still seems relevant to keep
  • Not implemented on Linux (it could lsusb gives IDs)
• Add path
  • macOS: IOService:/AppleACPIPlatformExpert/PCI0@0/AppleACPIPCI/XHC1@14/XHC1@14000000/HS12@14400000/Apple Internal Keyboard / Trackpad@14400000/Keyboard / Boot@1/AppleUSBTopCaseHIDDriver@14400000,1
  • Windows: \\\\?\\hid#vid_046d&pid_c24e&mi_00#7&28c04a4b&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}
  • Linux: 0001:0002:00 (not sure what this is from)
• Add release (also known as the revision)
  • Windows: can be grabbed from the <device-ID> -> &REV_XXX portion of the "Device instance ID/path"), see Extract Serial Number from Device Instance ID/Path on Windows. #50 (comment)
• Add interface
  • Seems to only apply to composite USB devices
  • On Windows, we can get this from the <device-ID> -> &MI_XX portion of the "Device instance ID/path")
  • On Linux, this does seem to be available under lsusb -v
  • On macOS, this seems to always be -1 with node-hid ???

---

To get detailed info about USB devices on your system

• Windows: Check Device Manager
• macOS: ioreg -p IOUSB -l -w 0 (from https://stackoverflow.com/a/29778245/796832)
• Linux: lsusb -v

[apla]

locationId should be preserved. It is available in linux by running udevadm info -e to get device path and then udevadm info -a --path=<device-path> to get detailed info on device.

Device path and device number is available via ATTRS{devnum} and ATTRS{devpath} on latter command output. I'm working on patch.

Why it is important? Actually, for linux and macOS we can get device path which uniquely identifies device on the bus. And devpath=3.4.4 for linux means root hub (3rd port) > hub (4th port) > hub (4th port) > device. Any composite device will have the same locationId/devpath which is very useful for usb modems (Huawei have three ttys on one device).

For example:

udevadm info -e

...
P: /devices/pci0000:00/0000:00:1a.7/usb1/1-3/1-3.4/1-3.4.4/1-3.4.4:1.0/ttyUSB0/t
ty/ttyUSB0
N: ttyUSB0
S: gsmmodem
S: serial/by-id/usb-HUAWEI_HUAWEI_MOBILE-if00-port0
S: serial/by-path/pci-0000:00:1a.7-usb-0:3.4.4:1.0-port0
E: DEVLINKS=/dev/serial/by-id/usb-HUAWEI_HUAWEI_MOBILE-if00-port0 /dev/gsmmodem /dev/serial/by-path/pci-0000:00:1a.7-usb-0:3.4.4:1.0-port0
E: DEVNAME=/dev/ttyUSB0
E: DEVPATH=/devices/pci0000:00/0000:00:1a.7/usb1/1-3/1-3.4/1-3.4.4/1-3.4.4:1.0/ttyUSB0/tty/ttyUSB0
E: ID_BUS=usb
E: ID_MM_CANDIDATE=1
E: ID_MM_HUAWEI_MODEM_PORT=1
E: ID_MODEL=HUAWEI_MOBILE
E: ID_MODEL_ENC=HUAWEI\x20MOBILE
E: ID_MODEL_FROM_DATABASE=Modem/Networkcard
E: ID_MODEL_ID=1506
E: ID_PATH=pci-0000:00:1a.7-usb-0:3.4.4:1.0
E: ID_PATH_TAG=pci-0000_00_1a_7-usb-0_3_4_4_1_0
E: ID_PCI_CLASS_FROM_DATABASE=Serial bus controller
E: ID_PCI_INTERFACE_FROM_DATABASE=EHCI
E: ID_PCI_SUBCLASS_FROM_DATABASE=USB controller
E: ID_REVISION=0001
E: ID_SERIAL=HUAWEI_HUAWEI_MOBILE
E: ID_TYPE=generic
E: ID_USB_DRIVER=option
E: ID_USB_INTERFACES=:ff0201:ff0202:ff0203:080650:
E: ID_USB_INTERFACE_NUM=00
E: ID_VENDOR=HUAWEI
E: ID_VENDOR_ENC=HUAWEI
E: ID_VENDOR_FROM_DATABASE=Huawei Technologies Co., Ltd.
E: ID_VENDOR_ID=12d1
E: MAJOR=188
E: MINOR=0
E: SUBSYSTEM=tty
E: TAGS=:systemd:
E: USEC_INITIALIZED=11283028422
...

udevadm info -a --path=/devices/pci0000:00/0000:00:1a.7/usb1/1-3/1-3.4/1-3.4.4/1-3.4.4:1.0/ttyUSB0/tty/ttyUSB0

  looking at device '/devices/pci0000:00/0000:00:1a.7/usb1/1-3/1-3.4/1-3.4.4/1-3
.4.4:1.0/ttyUSB0/tty/ttyUSB0':
    KERNEL=="ttyUSB0"
    SUBSYSTEM=="tty"
    DRIVER==""

  looking at parent device '/devices/pci0000:00/0000:00:1a.7/usb1/1-3/1-3.4/1-3.
4.4/1-3.4.4:1.0/ttyUSB0':
    KERNELS=="ttyUSB0"
    SUBSYSTEMS=="usb-serial"
    DRIVERS=="option1"
    ATTRS{port_number}=="0"

  looking at parent device '/devices/pci0000:00/0000:00:1a.7/usb1/1-3/1-3.4/1-3.
4.4/1-3.4.4:1.0':
    KERNELS=="1-3.4.4:1.0"
    SUBSYSTEMS=="usb"
    DRIVERS=="option"
    ATTRS{authorized}=="1"
    ATTRS{bAlternateSetting}==" 0"
    ATTRS{bInterfaceClass}=="ff"
    ATTRS{bInterfaceNumber}=="00"
    ATTRS{bInterfaceProtocol}=="01"
    ATTRS{bInterfaceSubClass}=="02"
    ATTRS{bNumEndpoints}=="03"
    ATTRS{supports_autosuspend}=="1"

  looking at parent device '/devices/pci0000:00/0000:00:1a.7/usb1/1-3/1-3.4/1-3.4.4':
    KERNELS=="1-3.4.4"
    SUBSYSTEMS=="usb"
    DRIVERS=="usb"
    ATTRS{authorized}=="1"
    ATTRS{avoid_reset_quirk}=="1"
    ATTRS{bConfigurationValue}=="1"
    ATTRS{bDeviceClass}=="00"
    ATTRS{bDeviceProtocol}=="00"
    ATTRS{bDeviceSubClass}=="00"
    ATTRS{bMaxPacketSize0}=="64"
    ATTRS{bMaxPower}=="500mA"
    ATTRS{bNumConfigurations}=="1"
    ATTRS{bNumInterfaces}==" 4"
    ATTRS{bcdDevice}=="0001"
    ATTRS{bmAttributes}=="80"
    ATTRS{busnum}=="1"
    ATTRS{configuration}==""
    ATTRS{devnum}=="19"
    ATTRS{devpath}=="3.4.4"
    ATTRS{idProduct}=="1506"
    ATTRS{idVendor}=="12d1"
    ATTRS{ltm_capable}=="no"
    ATTRS{manufacturer}=="HUAWEI"
    ATTRS{maxchild}=="0"
    ATTRS{product}=="HUAWEI MOBILE"
    ATTRS{quirks}=="0x10"
    ATTRS{removable}=="unknown"
    ATTRS{speed}=="480"
    ATTRS{urbnum}=="4128"
    ATTRS{version}==" 2.00"