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 and modified to be multiplatform.

Supported 3Dconnexion devices

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

Installation

pip install pyspacemouse

Quick Start

import pyspacemouse

# Context manager (recommended) - automatically closes device
with pyspacemouse.open() as device:
    while True:
        state = device.read()
        print(state.x, state.y, state.z)

API Reference

From version 2.0.0 the API has been modularized and changed. Please look at the API Reference and Examples for more information.

Device Discovery

import pyspacemouse

# List connected SpaceMouse devices
pyspacemouse.get_connected_devices()
# Returns: ["SpaceNavigator", "SpaceMouse Pro", ...]

# List all supported device types
pyspacemouse.get_supported_devices()
# Returns: [(name, vendor_id, product_id), ...]

# List ALL HID devices (for debugging)
pyspacemouse.get_all_hid_devices()
# Returns: [(product, manufacturer, vid, pid), ...]

Opening Devices

# Auto-detect and open first device
with pyspacemouse.open() as device:
    state = device.read()

# Open specific device by name
with pyspacemouse.open(device="SpaceNavigator") as device:
    state = device.read()

# Open second device when multiple identical devices are connected
with pyspacemouse.open(device_index=1) as device:
    state = device.read()

# Open by filesystem path (Linux: /dev/hidraw0)
with pyspacemouse.open_by_path("/dev/hidraw0") as device:
    state = device.read()

Reading State

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

    # 6-DOF axes (range: -1.0 to 1.0)
    print(state.x, state.y, state.z)       # Translation
    print(state.roll, state.pitch, state.yaw)  # Rotation

    # Buttons (list of 0/1)
    print(state.buttons)

    # Timestamp
    print(state.t)

Callbacks

# Button callback
def on_button(state, buttons, pressed):
    print(f"Button {pressed} pressed!")

button_callbacks = [
    pyspacemouse.ButtonCallback(0, on_button),  # Button 0
    pyspacemouse.ButtonCallback([0, 1], on_button),  # Both 0 and 1
]

# DOF callback with filtering
dof_callbacks = [
    pyspacemouse.DofCallback(
        axis="x",
        callback=lambda s, v: print(f"X: {v}"),
        callback_minus=lambda s, v: print(f"X negative: {v}"),
        filter=0.1,  # Deadzone
        sleep=0.05,  # Rate limit
    ),
]

with pyspacemouse.open(
    button_callbacks=button_callbacks,
    dof_callbacks=dof_callbacks,
) as device:
    while True:
        device.read()  # Triggers callbacks

Custom Axis Mapping

Customize axis directions for specific coordinate conventions (ROS, OpenGL, etc.):

import pyspacemouse

# Get existing device spec and modify axes
specs = pyspacemouse.get_device_specs()
base = specs["SpaceNavigator"]

# Invert axes for your application
custom = pyspacemouse.modify_device_info(
    base,
    invert_axes=["y", "z", "roll", "yaw"],  # Invert these
)

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

See Custom Device Configuration for full API.

CLI

pyspacemouse --list-connected    # Show connected devices
pyspacemouse --list-supported    # Show all supported types
pyspacemouse --list-hid          # Show all HID devices
pyspacemouse --test              # Test connection
pyspacemouse --version           # Show version

Examples

See the examples/ directory:

Example	Description
01_basic.py	Simple reading with context manager
02_callbacks.py	Button and DOF callbacks
03_multi_device.py	Using two devices simultaneously
04_open_by_path.py	Open specific device by path
05_discovery.py	List and inspect devices
06_axis_callbacks.py	Per-axis callbacks with filtering
07_led.py	LED control
08_buttons.py	Button names and handling
09_custom_config.py	Custom axis mappings

Dependencies

hidapi (C library)

• Linux: sudo apt-get install libhidapi-dev
• macOS: brew install hidapi
• Windows: Download from hidapi releases

Linux 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

macOS PATH

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

Troubleshooting

See troubleshooting.md for help with common issues.

Used In

• 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