jakubandrysek / pyspacemouse

🎮 Multiplatform Python library for 3Dconnexion SpaceMouse devices using raw HID.

PySpaceMouse

🎮 Multiplatform Python library for 3Dconnexion SpaceMouse devices using raw HID.

3Dconnexion Space Mouse in Python using raw HID. Note: you don't need to install or use any of the drivers or 3Dconnexion software to use this package. It interfaces with the controller directly with hidapi and python wrapper library easyhid.

PySpaceMouse is forked from: johnhw/pyspacenavigator

Implements a simple interface for 6 DoF 3Dconnexion Space Mouse device as well as similar devices.

Control Robo Arm with a Space Mouse.

Supported 3Dconnexion devices

• SpaceNavigator
• SpaceMouse Pro
• SpaceMouse Pro Wireless
• SpaceMouse Wireless
• 3Dconnexion Universal Receiver
• SpaceMouse Compact
• SpacePilot
• SpacePilot Pro
• SpaceMouse Enterprise
• Add more devices

Installation

Use the package manager pip to install pyspacemouse. If you are using a Mac with an ARM processor, you'll need a patched version of easyhid.

# Install package
pip install pyspacemouse

# Only needed for ARM MacOs
pip install git+https://github.com/bglopez/python-easyhid.git

Dependencies (required)

The library uses hidapi as low-level interface to the device and easyhid as a Python abstraction for easier use.

• hidapi is C library for direct communication with HID devices

  • Linux

    • libhidapi-dev to access HID data

    • sudo apt-get install libhidapi-dev (Debian/Ubuntu)

    • Compile and install hidapi. (other Linux distributions)

    • add rules for permissions

      sudo echo 'KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="plugdev"' > /etc/udev/rules.d/99-hidraw-permissions.rules
      sudo usermod -aG plugdev $USER
      newgrp plugdev

      Aleternative option - with tee (RPi)

        echo 'KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/99-hidraw-permissions.rules
        sudo usermod -aG plugdev $USER
        newgrp plugdev
        

  • Windows

    • Install the latest release of hidapi.dll and hidapi.lib from the hidapi releases page.
    • Set system environment: add absolute path for x64 or x86 folder in Path.
    • More info on Troubleshooting - WIndows page.

  • Mac OS X (M1)

    • Install from Homebrew
    • brew install hidapi
    • Add hidapi to your DYLD_LIBRARY_PATH directory.

      export DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/hidapi/0.14.0/lib:$DYLD_LIBRARY_PATH

    • On MacOS M1 you will need patched version of easyhid. If easyhid is already installed, please uninstall it first.

      pip install git+https://github.com/bglopez/python-easyhid.git

    • In case of problem with M1 chip, try to run you code with Rosseta 2
      • How to use Rosseta 2 - Setup Rosetta
    • Tested and developed by consi - thanks!
    • More info on Troubleshooting - Mac OS (M1) page.

• easyhid is hidapi interface for Python - required on all platforms

  • pip install git+https://github.com/bglopez/python-easyhid.git
  • this fork fix problems with hidapi on MacOS.
  • on other platforms it possible works with original package pip install easyhid

Basic Usage:

If the 3Dconnexion driver is installed, please ensure to stop 3DconnexionHelper before running your python scripts.

Basic example

import pyspacemouse
import time

success = pyspacemouse.open(dof_callback=pyspacemouse.print_state, button_callback=pyspacemouse.print_buttons)
if success:
    while 1:
        state = pyspacemouse.read()
        time.sleep(0.01)

More examples can be found in the /examples directory or in page with Examples.

Available CLI test commands

usage: pyspacemouse [-h] [--version] [--list-spacemouse]
                    [--list-supported-devices] [--list-all-hid-devices]
                    [--test-connect]

PySpaceMouse CLI

options:
  -h, --help            show this help message and exit
  --version             Version of pyspacemouse
  --list-spacemouse     List connected SpaceMouse devices
  --list-supported-devices
                        List supported SpaceMouse devices
  --list-all-hid-devices
                        List all connected HID devices
  --test-connect        Test connect to the first available device

For more information, visit https://spacemouse.kubaandrysek.cz

Troubleshooting

Look at the Troubleshooting page for help with common issues.

References

PySpaceMouse is used in the following projects:

• PySpaceApp - Control your PC with SpaceMouse (basic hotkeys, mouse control, and more)
• TeleMoMa - A Modular and Versatile Teleoperation System for Mobile Manipulation
• SERL - SERL: A Software Suite for Sample-Efficient Robotic Reinforcement Learning
  • 
• Pancake Robot- An integration of the Ufactory Lite 6 robot arm with kitchenware to make pancakes.
• GELLO - GELLO: A General, Low-Cost, and Intuitive Teleoperation Framework for Robot Manipulators
  • 
• spacepad - A simple python script that turns a spacemouse device into a standard gamepad
• arm_xarm

pyspacemouse's Issues

Test HIDAPI `set_nonblocking`

Look at set_nonblocking and test it wit the library.

PySpaceMouse on MacOS ARM M1

I have tried to install PySpaceMouse on MacOS M1, but it doesn`t work.
Is there anybody who fixed this issue?

I have installed hidapi trough brew install hidapi.
My result from basicExample.py is there:

 ✘ kuba@KA-M1  ~/Documents/git/kuba/pyspacemouse   master ±  python3.11 ./examples/basicExample.py
Traceback (most recent call last):
  File "/Users/kuba/Documents/git/kuba/pyspacemouse/./examples/basicExample.py", line 4, in <module>
    success = pyspacemouse.open()
              ^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/pyspacemouse/pyspacemouse.py", line 703, in open
    all_devices = list_devices()
                  ^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/pyspacemouse/pyspacemouse.py", line 643, in list_devices
    hid = Enumeration()
          ^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/easyhid/easyhid.py", line 366, in __init__
    self.device_list = _hid_enumerate(vid, pid)
                       ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/easyhid/easyhid.py", line 428, in _hid_enumerate
    start = hidapi.hid_enumerate(vendor_id, product_id)
            ^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/cffi/api.py", line 912, in __getattr__
    make_accessor(name)
  File "/opt/homebrew/lib/python3.11/site-packages/cffi/api.py", line 908, in make_accessor
    accessors[name](name)
  File "/opt/homebrew/lib/python3.11/site-packages/cffi/api.py", line 838, in accessor_function
    value = backendlib.load_function(BType, name)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: function/symbol 'hid_enumerate' not found in library '<None>': dlsym(RTLD_DEFAULT, hid_enumerate): symbol not found

Related links:

• gl-sergei/u2f-token#18
• earlephilhower/arduino-pico#703

Error while running example.py

Hi, I am receiving the following error on a raspi installation, any idea where it come from ?

Traceback (most recent call last):
  File "/home/user/git/example.py", line 8, in <module>
    state=pyspacemouse.read()
  File "/home/user/.local/lib/python3.9/site-packages/pyspacemouse/pyspacemouse.py", line 586, in read
    return _active_device.read()
  File "/home/user/.local/lib/python3.9/site-packages/pyspacemouse/pyspacemouse.py", line 209, in read
    self.process(ret)
  File "/home/user/.local/lib/python3.9/site-packages/pyspacemouse/pyspacemouse.py", line 241, in process
    flip * to_int16(data[b1], data[b2]) / float(self.axis_scale)
IndexError: bytearray index out of range

button mapping modifiers for space pro bluetooth

I am emulating space pro bluetooth with esp32 and my button mapping same as yours. But modifier (like ctrl,shif etc) bits doesnt work.

I'm asking this question here because I couldn't see the Space Pro Bluetooth description in your code. Is there a specific reason for this?

roll/pitch/yaw Spacemouse Wireless

Dear Jakub,
Thank you for your great contribution!

I had some issues when I changed from USB to wireless Spacemouse, but I found the solution here (the byte-array issue that was solved here) I dont think it is implemented in the current version that is downloaded from PyPi however.

My next issue is the fact that rotation doesnt show any reaction ( roll, pitch, yaw). I'm testing on a beaglebone blue running some new debian release. I tried to change channels in the pyspacemouse.py similar to the wired versions, but no change there...

When I connect the device, i get 5 HID devices popping up..

Best regards
Viktor

Windows 10 error ; and raspi error

C:\Users\61240\Downloads\weimo_ws\src>python mouse.py
Traceback (most recent call last):
  File "C:\opt\ros\noetic\x64\lib\site-packages\easyhid\easyhid.py", line 53, in <module>
    hidapi = ffi.dlopen('hidapi.dll')
  File "C:\opt\ros\noetic\x64\lib\site-packages\cffi\api.py", line 150, in dlopen
    lib, function_cache = _make_ffi_library(self, name, flags)
  File "C:\opt\ros\noetic\x64\lib\site-packages\cffi\api.py", line 832, in _make_ffi_library
    backendlib = _load_backend_lib(backend, libname, flags)
  File "C:\opt\ros\noetic\x64\lib\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'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "mouse.py", line 1, in <module>
    import pyspacemouse
  File "C:\opt\ros\noetic\x64\lib\site-packages\pyspacemouse\__init__.py", line 1, in <module>
    from .pyspacemouse import *
  File "C:\opt\ros\noetic\x64\lib\site-packages\pyspacemouse\pyspacemouse.py", line 1, in <module>
    from easyhid import Enumeration
  File "C:\opt\ros\noetic\x64\lib\site-packages\easyhid\__init__.py", line 8, in <module>
    from easyhid.easyhid import *
  File "C:\opt\ros\noetic\x64\lib\site-packages\easyhid\easyhid.py", line 55, in <module>
    hidapi = ffi.dlopen(ctypes.util.find_library('hidapi.dll'))
  File "C:\opt\ros\noetic\x64\lib\site-packages\cffi\api.py", line 150, in dlopen
    lib, function_cache = _make_ffi_library(self, name, flags)
  File "C:\opt\ros\noetic\x64\lib\site-packages\cffi\api.py", line 832, in _make_ffi_library
    backendlib = _load_backend_lib(backend, libname, flags)
  File "C:\opt\ros\noetic\x64\lib\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)

[docs] Setting permission rules on Raspberry Pi fails [fixed]

Following the documentation for installing the dependencies, I ran into a Permission denied error with:

sudo echo 'KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="plugdev"' > /etc/udev/rules.d/99-hidraw-permissions.rules

The solution was to use sudo tee:

echo 'KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/99-hidraw-permissions.rules

Latency of Data Reading

In a Python application with a SpaceMouse Wireless and SpaceMouse Compact we have very high delays when reading data.
We get the first values after initiating a movement after 100ms, but after reaching the zero position again it takes about 1-2 seconds until the values return to zero.
Is this problem known or are certain filters applied?
We are using the pyspacemouse package, and the 3 methods open(), read(), close().
Here is my code:

Thank you very much for your support.

Spacemouse bluetooth wireless (not supported?)

Hey I have a space mouse which I am trying to use with your repo:

I can see the device with hidapitester:

256F/C63A: 3Dconnexion - SpaceMouse Wireless BT
  vendorId:      0x256F
  productId:     0xC63A

However, pyspacemouse is telling me that no devices are connected. I'm suspecting that maybe this space mouse model isn't supported?

Available SpaceMouse devices:
- SpaceMouse Enterprise [VID: 0x256f, PID: 0xc633]
- SpaceExplorer [VID: 0x46d, PID: 0xc627]
- SpaceNavigator [VID: 0x46d, PID: 0xc626]
- SpaceMouse USB [VID: 0x256f, PID: 0xc641]
- SpaceMouse Compact [VID: 0x256f, PID: 0xc635]
- SpaceMouse Pro Wireless [VID: 0x256f, PID: 0xc632]
- SpaceMouse Pro [VID: 0x46d, PID: 0xc62b]
- SpaceMouse Wireless [VID: 0x256f, PID: 0xc62e]
- 3Dconnexion Universal Receiver [VID: 0x256f, PID: 0xc652]
- SpacePilot [VID: 0x46d, PID: 0xc625]
- SpacePilot Pro [VID: 0x46d, PID: 0xc629]

Wondering if maybe I need to connect the device in a different way (usb vs bluetooth)?
Any help would be appreciated.

Replace 3DXWare with this script

Hi,
I use a Cadmouse Pro Wireless and I want to be able to control the mouse features (Smartscrolling in particular) and button remapping.

I tried to get this tool (https://github.com/mia-0/cadmousectl) to run, but with no success unfortunately.

Is it doable to make those configurations with your pyton module?

Explore HIDAPI callback function

Try to implement a callback read using a low-level function from the HIDAPI library - read_callback

• https://askubuntu.com/questions/1447628/how-to-implement-generic-hid-read-with-libusb-interrupt-callback

This function has to be additionally implemented to a python HID wrapper like easyhid

The parent project pyspacenavigator, which supports only the Windows platform uses a callback function to the smooth read

• dev.set_raw_data_handler(lambda x: new_device.process(x))

Update Windows install info

C:\Users\Student\Downloads\hidapi-win\x64

`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
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'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "C:\Users\Student\Downloads\basicExample.py", line 1, in
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
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
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
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
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)
`