easyhid-ng

A simple Python interface to the HIDAPI library.

This is a modernized fork published as python-easyhid-ng for use with the PySpaceMouse package.

Credits

• Original library by ahtn
• macOS M1/M2/M3 fixes by bglopez
• Modernized for Python 3.8+ by JakubAndrysek

Thanks to all maintainers for their contributions!

Installation

pip install easyhid-ng

Requirements

This library requires the hidapi native library to be installed on your system.

macOS

Install hidapi using Homebrew:

brew install hidapi

For Apple Silicon (M1/M2/M3): You need to add hidapi to your library path:

# Check your hidapi version
brew info hidapi

# Add to your shell config (.bashrc or .zshrc) - replace version number as needed:
export DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/hidapi/0.14.0/lib:$DYLD_LIBRARY_PATH

Linux

# Debian/Ubuntu
sudo apt install libhidapi-hidraw0

# Fedora
sudo dnf install hidapi

Windows

1. Download the latest hidapi release
2. Extract and copy hidapi.dll (from x64 or x86 folder) to a location in your PATH
3. Or add the folder containing hidapi.dll to your system PATH environment variable

Usage

from easyhid import Enumeration

# Stores an enumeration of all the connected USB HID devices
en = Enumeration()

# Return a list of devices based on the search parameters
devices = en.find(manufacturer="Company", product="Widget", interface=3)

# Print a description of the devices found
for dev in devices:
    print(dev.description())

# Open a device
dev.open()

# Write some bytes to the device
dev.write(bytearray([0, 1, 2, 3]))

# Read some bytes
print(dev.read())

# Close a device
dev.close()

Context Manager

You can also use devices as context managers:

from easyhid import Enumeration

en = Enumeration()
devices = en.find(vid=0x1234, pid=0x5678)

if devices:
    with devices[0] as dev:
        dev.write(bytearray([0x00, 0x01]))
        data = dev.read(size=64, timeout=1000)

Examples

See the examples folder for complete examples:

• list_devices.py - List all connected HID devices with detailed information

python examples/list_devices.py

API Reference

Enumeration

Create an enumeration of all connected HID devices.

en = Enumeration(vid=0, pid=0)  # 0 = any

Methods:

• find(vid, pid, serial, interface, path, release_number, manufacturer, product, usage, usage_page) - Filter devices
• show() - Print descriptions of all devices

HIDDevice

Represents a single HID device.

Properties:

• path - Device path
• vendor_id - USB Vendor ID
• product_id - USB Product ID
• serial_number - Device serial number
• manufacturer_string - Manufacturer name
• product_string - Product name
• release_number - Device release number
• interface_number - Interface number
• usage_page - HID usage page
• usage - HID usage

Methods:

• open() - Open the device
• close() - Close the device
• write(data, report_id=0) - Write data to the device
• read(size=64, timeout=None) - Read data from the device
• send_feature_report(data, report_id=0) - Send a feature report
• get_feature_report(size, report_id=0) - Get a feature report
• is_open() - Check if device is open
• is_connected() - Check if device is still connected
• description() - Get device description string

Troubleshooting

ModuleNotFoundError: No module named 'easyhid'

Install the library:

pip install easyhid-ng

AttributeError: function/symbol 'hid_enumerate' not found

The HIDAPI native library is not installed. Follow the installation instructions above for your OS.

OSError: cannot load library 'hidapi.dll' (Windows)

Download hidapi.dll from the hidapi releases and add it to your PATH.

Testing HIDAPI Installation

You can verify hidapi is working using hidapitester:

# List connected devices
./hidapitester --list

# Read from a device
./hidapitester --vidpid 1234/5678 --open --read-input

License

MIT License - see LICENSE for details.