Skip to content

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
      • 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
    • image
  • spacepad - A simple python script that turns a spacemouse device into a standard gamepad
  • arm_xarm