If you encounter any issues, you can find help in the following section.
- Install
easyhid
bypip install easyhid
.
AttributeError: function/symbol 'hid_enumerate' not found in library '': python3: undefined symbol: hid_enumerate
- HID library for your computer is not installed.
- Follow the instructions in requirements.
!!! info "External dependencies"
You don't have to install original 3Dconnexion driver 3DxWare 10
. This library works directly with hidapi
device interface.
If you are using a Mac with an M1 chip or newer, you may encounter issues when installing the dependencies.
Required dependency is hidapi
which you can install using Homebrew brew install hidapi
.
By default, the hidapi
library is installed in /opt/homebrew/Cellar/hidapi/0.14.0/lib
directory, and you need to add it to your DYLD_LIBRARY_PATH
environment variable.
It is possible to add it to your .bashrc
or .zshrc
file, but you can also add it directly in the terminal (only for the current session).
Replace 0.14.0
with the version you have installed on your system (brew info hidapi
).
export DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/hidapi/0.14.0/lib:$DYLD_LIBRARY_PATH
In case of changes in MacOS M1, architecture name, you have to use patched version of easyhid
library.
Updated version is not yet available on PyPi, so you have to uninstall the current version and install the patched version from GitHub.
pip install git+https://github.com/bglopez/python-easyhid.git
After this setup everything works correctly directly on MacOS M1. Tested on:
- MacBook Pro 14 (M1 Pro, 2021)
- ??? (add your device and feedback)
I have probably tested it also in Rosetta 2 mode, but right now it works directly on M1 chip with python from brew
.
If you are not sure if hidapi
is installed correctly, you can test it with the console tool hidapitester.
This tool provides a simple interface to test the communication with HID devices.
On GitHub, you can find the source code and precompiled binaries for Windows, Linux, and Mac OS.
Just download the binary for your system and run it in the terminal.
List connected devices:
./hidapitester --list
??? note "My output"
bash 046D/C626: 3Dconnexion - SpaceNavigator 045E/07A5: Microsoft - Microsoft 2.4GHz Transceiver v9.0 ...
Read data from the device (replace <VID/PID>
with the VID/PID of your device):
./hidapitester --vidpid <VID/PID> --open --read-input
??? note "My output"
bash ./hidapitester --vidpid 046D/C626 --open --read-input Opening device, vid/pid: 0x046D/0xC626 Reading 64-byte input report 0, 250 msec timeout...read 7 bytes: 01 76 00 00 00 FA FF 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
Read descriptor from the device (replace <VID/PID>
with the VID/PID of your device):
./hidapitester --vidpid <VID/PID> --open --get-report-descriptor
??? note "My output"
bash ./hidapitester --vidpid 046D/C626 --open --get-report-descriptor Opening device, vid/pid: 0x046D/0xC626 Report Descriptor: 05 01 09 08 A1 01 A1 00 85 01 16 A2 FE 26 5E 01 36 88 FA 46 78 05 55 0C 65 11 09 30 09 31 09 32 75 10 95 03 81 06 C0 A1 00 85 02 09 33 09 34 09 35 75 10 95 03 81 06 C0 A1 02 85 03 05 01 05 09 ... Closing device
!!! info "Error message - OSError: cannot load library 'hidapi.dll'"
bash Traceback (most recent call last): File "C:\Users\Student\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\easyhid\easyhid.py", line 53, in <module> hidapi = ffi.dlopen('hidapi.dll') File "C:\Users\Student\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\cffi\api.py", line 150, in dlopen lib, function_cache = _make_ffi_library(self, name, flags) File "C:\Users\Student\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\cffi\api.py", line 832, in _make_ffi_library backendlib = _load_backend_lib(backend, libname, flags) File "C:\Users\Student\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\cffi\api.py", line 827, in _load_backend_lib raise OSError(msg) OSError: cannot load library 'hidapi.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'hidapi.dll
??? info "Other error message - OSError: dlopen(None) cannot work on Windows for Python 3"
bash File "C:\Users\Student\Downloads\basicExample.py", line 1, in <module> import pyspacemouse File "C:\Users\Student\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\pyspacemouse\__init__.py", line 1, in <module> from .pyspacemouse import * File "C:\Users\Student\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\pyspacemouse\pyspacemouse.py", line 1, in <module> from easyhid import Enumeration, HIDException File "C:\Users\Student\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\easyhid\__init__.py", line 8, in <module> from easyhid.easyhid import * File "C:\Users\Student\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\easyhid\easyhid.py", line 55, in <module> hidapi = ffi.dlopen(ctypes.util.find_library('hidapi.dll')) File "C:\Users\Student\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\cffi\api.py", line 150, in dlopen lib, function_cache = _make_ffi_library(self, name, flags) File "C:\Users\Student\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\cffi\api.py", line 832, in _make_ffi_library backendlib = _load_backend_lib(backend, libname, flags) File "C:\Users\Student\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\cffi\api.py", line 821, in _load_backend_lib raise OSError("dlopen(None) cannot work on Windows for Python 3 " OSError: dlopen(None) cannot work on Windows for Python 3 (see http://bugs.python.org/issue23606)
If you are using Windows, you may encounter issues with the hidapi
library.
The library is not included in the system, so you have to install it manually.
Go to hidapi GitHub and download the latest version of the library in zip format.
Extract the zip file and copy the x64/x86 folder with hidapi.dll
to the static location where will be found by the system.
To make it work, you have to add the folder to the system PATH
variable.
Go to Windows settings and search for enviroment
.
Click on the Environment variables
.
Append the path to the folder with hidapi.dll
to the Path
variable.
After this setup, you have to restart (maybe log out) your computer to apply the changes. Let's start using this library in your Python code.