Skip to main content

Multiplatform Python interface to the 3DConnexion Space Mouse - forked from pyspacenavigator

Project description

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyspacemouse-1.1.4.tar.gz (19.1 kB view details)

Uploaded Source

Built Distribution

pyspacemouse-1.1.4-py3-none-any.whl (14.7 kB view details)

Uploaded Python 3

File details

Details for the file pyspacemouse-1.1.4.tar.gz.

File metadata

  • Download URL: pyspacemouse-1.1.4.tar.gz
  • Upload date:
  • Size: 19.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.4

File hashes

Hashes for pyspacemouse-1.1.4.tar.gz
Algorithm Hash digest
SHA256 cb8733d6d0abf7c2c2673ae8b36bb67f8523ae3a04f749fd2caca8f429b07a6b
MD5 0c223c402f8dc3f6530b02a41f7ec03c
BLAKE2b-256 84ed7ee8e7dcff16f0fa82723ca8c22171a409b231d0e1fefc5ede142c205b57

See more details on using hashes here.

File details

Details for the file pyspacemouse-1.1.4-py3-none-any.whl.

File metadata

  • Download URL: pyspacemouse-1.1.4-py3-none-any.whl
  • Upload date:
  • Size: 14.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.4

File hashes

Hashes for pyspacemouse-1.1.4-py3-none-any.whl
Algorithm Hash digest
SHA256 67a974b28a1331e913a198d83ec968ac2298b8c5bc5387189a0fb53f256ed3b9
MD5 653536cf6f9b28a0176d988b31022406
BLAKE2b-256 51ab3584d754e0e76ac39c96f7569163cc5dede143d983b4556026cfc1b8b05b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page