Skip to content

Troubleshooting

If you encounter any issues, you can find help in the following section.

Axis Conventions

The library applies some axis inversions to make values more intuitive:

  • Z axis: Inverted so positive = up (HID spec defines down as positive)
  • Y axis: Inverted for common conventions
  • Rotations: pitch/roll inverted from HID spec

If your application needs different conventions (e.g., ROS, OpenGL), use the modify_device_info() function:

import pyspacemouse

specs = pyspacemouse.get_device_specs()
base = specs["SpaceNavigator"]

# Customize axes for your application
custom = pyspacemouse.modify_device_info(
    base,
    invert_axes=["y", "z", "roll", "yaw"],  # Axes to flip
)

with pyspacemouse.open(device_spec=custom) as device:
    state = device.read()

See Custom Device Configuration for full details.

Common issues

ModuleNotFoundError: No module named 'easyhid'

  • Install easyhid by pip install easyhid-ng.

AttributeError: function/symbol 'hid_enumerate' not found in library '': python3: undefined symbol: hid_enumerate

  • HID C library is not installed or not found in PATH.
  • Follow the instructions in requirements.

Mac OS (M1)

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/<VERSION>/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 <VERSION> with the version you have installed on your system (brew info hidapi). 

export DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/hidapi/<VERSION>/lib:$DYLD_LIBRARY_PATH

After this setup everything works correctly. Tested on:

  • MacBook Pro 14 (M1 Pro, 2021)
  • ... add your device and feedback

Testing Hidapi

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

My output 
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

My output 
./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

My output 
./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

Linux

Failed to open device / Permission denied

If you encounter an error like Failed to open device or Permission denied when trying to use your SpaceMouse on Linux, this is typically a permissions issue. Normal users don't have permission to access HID devices by default.

Error example: 

Traceback (most recent call last):
  File "/home/user/.local/lib/python3.8/site-packages/pyspacemouse/pyspacemouse.py", line 183, in open
    self.device.open()
  File "/home/user/.local/lib/python3.8/site-packages/easyhid/easyhid.py", line 134, in open
    raise HIDException("Failed to open device")
easyhid.easyhid.HIDException: Failed to open device

Solution:

  1. Find your device's Vendor ID and Product ID: 

    lsusb
    Look for your SpaceMouse device. Example output: 
    Bus 001 Device 013: ID 256f:c652 3Dconnexion Universal Receiver
    Here, 256f is the Vendor ID and c652 is the Product ID.

  2. Create udev rules to grant permissions: 

    cd /etc/udev/rules.d
sudo touch 99-spacemouse.rules
sudo nano 99-spacemouse.rules

  3. Add the following rules (replace 046d and c62b with your Vendor ID and Product ID): 

    SUBSYSTEM=="input", GROUP="input", MODE="0660"
KERNEL=="hidraw*", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="c62b", MODE="0666"

Common SpaceMouse IDs: - SpaceMouse Compact: 256f:c635 - SpaceMouse Wireless: 256f:c62e - 3Dconnexion Universal Receiver: 256f:c652 - SpaceNavigator: 046d:c626

  1. Reload udev rules: 

    sudo udevadm control --reload-rules
sudo udevadm trigger

  2. Add your user to the input group: 

    sudo usermod -a -G input $USER

  3. Disconnect and reconnect your SpaceMouse, then log out and log back in to Ubuntu (or restart your computer).

After these steps, your SpaceMouse should work correctly without permission errors.

Windows

Error message - OSError: cannot load library 'hidapi.dll'

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
Other error message - OSError: dlopen(None) cannot work on Windows for Python 3 
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. image

Click on the Environment variables. image

Append the path to the folder with hidapi.dll to the Path variable. image

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.