# 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](https://github.com/JakubAndrysek/pyspacemouse) package.

## Credits

- Original library by [ahtn](https://github.com/ahtn/python-easyhid)
- macOS M1/M2/M3 fixes by [bglopez](https://github.com/bglopez/python-easyhid)
- Modernized for Python 3.8+ by [JakubAndrysek](https://github.com/JakubAndrysek)

Thanks to all maintainers for their contributions!

## Installation

```bash
pip install easyhid-ng
```

### Requirements

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

#### macOS

Install hidapi using Homebrew:

```bash
brew install hidapi
```

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

```bash
# 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

```bash
# Debian/Ubuntu
sudo apt install libhidapi-hidraw0

# Fedora
sudo dnf install hidapi
```

#### Windows

1. Download the latest [hidapi release](https://github.com/libusb/hidapi/releases)
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

```python
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:

```python
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](examples/) folder for complete examples:

- [`list_devices.py`](examples/list_devices.py) - List all connected HID devices with detailed information

```bash
python examples/list_devices.py
```

## API Reference

### `Enumeration`

Create an enumeration of all connected HID devices.

```python
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:
```bash
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](https://github.com/libusb/hidapi/releases) and add it to your PATH.

### Testing HIDAPI Installation

You can verify hidapi is working using [hidapitester](https://github.com/todbot/hidapitester):

```bash
# List connected devices
./hidapitester --list

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

## License

MIT License - see [LICENSE](LICENSE) for details.
