hidapi Python Wrapper

Warnings

• gotcha The `hidapi` Python package requires the underlying native `hidapi` library to be installed on your system. `pip install hidapi` only installs the Python bindings, not the C library itself. Users often encounter `IOError` or `OSError` if the native library is missing or improperly configured.
  Fix: On Linux (Debian/Ubuntu), install `libusb-1.0-0-dev` and `libudev-dev` (or `libhidapi-hidraw0`/`libhidapi-libusb0`). On macOS, install `hidapi` via Homebrew (`brew install hidapi`). On Windows, ensure `hidapi.dll` is in a directory listed in your system's PATH, or beside your executable. The specific `hidapi.dll` might need to match your Python's architecture (32-bit vs 64-bit).
• gotcha On Linux, accessing HID devices typically requires special permissions. Without them, `hid.open()` calls will fail with `IOError`.
  Fix: Run your Python script with `sudo` (not recommended for production). A better solution is to create a udev rule file (`.rules` in `/etc/udev/rules.d/`) to grant appropriate access to your user or a specific group for the target device's Vendor/Product ID. Remember to reload udev rules (`sudo udevadm control --reload-rules && sudo udevadm trigger`) and potentially replug the device.
• gotcha When reading or writing HID reports, the first byte often represents the 'Report ID'. If your device uses numbered reports, this byte will be the Report ID. If not, it's typically `0x00`. Misinterpreting this can lead to incorrect data parsing or writing issues.
  Fix: Consult your device's HID Report Descriptor to understand whether it uses numbered reports and what the expected report structure is. Adjust your `read()` and `write()` calls to account for the Report ID byte if present.

Install

• pip install hidapi Basic installation
• sudo apt-get install python3-dev libusb-1.0-0-dev libudev-dev && pip install hidapi Linux (Debian/Ubuntu) with system dependencies
• brew install hidapi && pip install hidapi macOS with Homebrew and system dependencies

Imports

• hid

  import hid

  The PyPI package is 'hidapi', but the import module name is 'hid'.
• device

  h = hid.device()

  Instantiate the device object directly from the 'hid' module.

Quickstart

This quickstart enumerates all connected HID devices, then attempts to connect to a specified device (using environment variables for Vendor ID and Product ID, or placeholders if not set). It demonstrates enabling non-blocking mode, writing data, and reading data from the device. Users should replace `VENDOR_ID` and `PRODUCT_ID` with their specific device's identifiers and adjust `data_to_write` and read sizes according to their device's HID report descriptor.

import hid
import os
import time

# --- Enumerate devices (useful for finding VID/PID) ---
print('Enumerating HID devices:')
for device_dict in hid.enumerate():
    print('---')
    for key, value in device_dict.items():
        print(f'{key}: {value}')
print('---\n')

# --- Connect, read, and write (example with placeholder VID/PID) ---
# Replace with your device's Vendor ID and Product ID.
# On Linux, you may need appropriate udev rules or root privileges.
# On Windows, you might need hidapi.dll in your PATH.
VENDOR_ID = int(os.environ.get('HIDAPI_VENDOR_ID', '0x0000'), 16) # Example: 0x534C for Trezor
PRODUCT_ID = int(os.environ.get('HIDAPI_PRODUCT_ID', '0x0000'), 16) # Example: 0x0001 for Trezor One

if VENDOR_ID == 0x0000 or PRODUCT_ID == 0x0000:
    print('Warning: Please set HIDAPI_VENDOR_ID and HIDAPI_PRODUCT_ID environment variables for a real test.')
    print('Falling back to placeholder values; device opening may fail.')

try:
    print(f'Attempting to open device VID: {hex(VENDOR_ID)}, PID: {hex(PRODUCT_ID)}')
    h = hid.device()
    h.open(VENDOR_ID, PRODUCT_ID)

    print(f'Manufacturer: {h.get_manufacturer_string()}')
    print(f'Product: {h.get_product_string()}')
    print(f'Serial No: {h.get_serial_number_string()}')

    h.set_nonblocking(1) # Enable non-blocking mode

    # Example: Write some data (replace with actual device commands)
    print('Writing example data...')
    # Ensure data length matches device report size, padded with zeros if needed.
    # The first byte might be a Report ID, or 0 if not used by the device.
    data_to_write = [0, 63, 35, 35] + [0] * 60 # Example 64-byte report
    h.write(data_to_write)
    time.sleep(0.05)

    # Example: Read data
    print('Reading data...')
    read_data = []
    while True:
        d = h.read(64) # Read up to 64 bytes
        if d:
            read_data.extend(d)
        else:
            break
    
    if read_data:
        print(f'Read data: {read_data}')
    else:
        print('No data read.')

    print('Closing the device.')
    h.close()

except IOError as ex:
    print(f'Error opening or communicating with device: {ex}')
    print('Ensure the device is connected and permissions are correct.')
except Exception as e:
    print(f'An unexpected error occurred: {e}')