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.

# Install package
pip install pyspacemouse

Note for ARM Mac users: If you encounter issues with easyhid, see the Troubleshooting - Mac OS (M1) section.

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

      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

      Alternative 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
        

    • Note: If you encounter "Failed to open device" errors, see the Troubleshooting - Linux section for device-specific permission setup.

  • 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

  • Automatically installed with pip install pyspacemouse
  • This fork fixes problems with hidapi on MacOS

Development Setup

To contribute to pyspacemouse or run it in development mode:

# Clone the repository
git clone https://github.com/JakubAndrysek/pyspacemouse.git
cd pyspacemouse

# Install in editable mode with development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks (optional, but recommended)
pre-commit install

# Run tests
pytest

# Run linting
ruff check .

# Format code
ruff format .

Using Hatch (Recommended for Maintainers)

# Install Hatch
pip install hatch

# Run tests
hatch run test:pytest

# Run linting
hatch run ruff check .

# Format code
hatch run ruff format .

# Build package
hatch build

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