Awesome
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
<details> <summary>Aleternative option - with tee (RPi)</summary> <pre> 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 </pre> </details>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
-
-
Windows
- Install the latest release of hidapi.dll and hidapi.lib from the hidapi releases page.
- Set system environment: add absolute path for
x64
orx86
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 platformspip 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