Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jakubandrysek/pyspacemouse
🎮 Multiplatform Python library for 3Dconnexion SpaceMouse devices using raw HID.
https://github.com/jakubandrysek/pyspacemouse
3d dof hid linux multiplatform py python space-mouse spacemouse windows
Last synced: 3 days ago
JSON representation
🎮 Multiplatform Python library for 3Dconnexion SpaceMouse devices using raw HID.
- Host: GitHub
- URL: https://github.com/jakubandrysek/pyspacemouse
- Owner: JakubAndrysek
- License: mit
- Created: 2021-03-24T21:43:08.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-05-01T19:03:50.000Z (5 months ago)
- Last Synced: 2024-05-02T04:06:30.163Z (5 months ago)
- Topics: 3d, dof, hid, linux, multiplatform, py, python, space-mouse, spacemouse, windows
- Language: Python
- Homepage: https://spacemouse.kubaandrysek.cz/
- Size: 6.2 MB
- Stars: 46
- Watchers: 2
- Forks: 14
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/JakubAndrysek/pyspacemouse) is forked from: [johnhw/pyspacenavigator](https://github.com/johnhw/pyspacenavigator)
Implements a simple interface for 6 DoF 3Dconnexion [Space Mouse](https://3dconnexion.com/uk/spacemouse/) device as
well as similar devices.
Control [Robo Arm](https://roboruka.robotickytabor.cz/) 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](https://github.com/johnhw/pyspacenavigator/issues/1)
## Installation
Use the package manager [pip](https://pip.pypa.io/en/stable/) to install [pyspacemouse](https://pypi.org/project/pyspacemouse/). If you are using a Mac with an ARM processor, you'll need a patched version of `easyhid`.
```bash
# 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](https://github.com/libusb/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](https://github.com/libusb/hidapi/#build-from-source). (other Linux
distributions)
- add rules for permissions
```bash
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](https://github.com/libusb/hidapi/releases) page.
- Set system environment: add absolute path for `x64` or `x86` folder in Path.
- More info on [Troubleshooting - WIndows](./troubleshooting.md#windows) page.
- ### Mac OS X (M1)
- Install from [Homebrew](https://formulae.brew.sh/formula/hidapi)
- `brew install hidapi`
- Add hidapi to your `DYLD_LIBRARY_PATH` directory.
```bash
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.
```bash
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](https://apple.stackexchange.com/questions/428768/on-apple-m1-with-rosetta-how-to-open-entire-terminal-iterm-in-x86-64-architec)
- Tested and developed by [consi](https://github.com/JakubAndrysek/PySpaceMouse/issues/10#issuecomment-1768362007) - thanks!
- More info on [Troubleshooting - Mac OS (M1)](./troubleshooting.md#mac-os-m1) page.
- ### [easyhid](https://github.com/bglopez/python-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
````py
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](https://github.com/JakubAndrysek/PySpaceMouse/tree/master/examples) directory or in page with [Examples](https://spacemouse.kubaandrysek.cz/mouseApi/examples/).
## Available CLI test commands
```bash
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](./troubleshooting.md) page for help with common issues.
## References
PySpaceMouse is used in the following projects:
- [PySpaceApp](https://github.com/JakubAndrysek/pyspaceapp) - Control your PC with SpaceMouse (basic hotkeys, mouse control, and more)
- [TeleMoMa](https://github.com/UT-Austin-RobIn/telemoma) - A Modular and Versatile Teleoperation System for Mobile Manipulation
- [SERL](https://github.com/rail-berkeley/serl) - SERL: A Software Suite for Sample-Efficient Robotic Reinforcement Learning
- 
- [Pancake Robot](https://github.com/pauldw/pancake-robot)- An integration of the Ufactory Lite 6 robot arm with kitchenware to make pancakes.
- [GELLO](https://github.com/wuphilipp/gello_software) - GELLO: A General, Low-Cost, and Intuitive Teleoperation Framework for Robot Manipulators
- 
- [spacepad](https://github.com/brianpeiris/spacepad) - A simple python script that turns a spacemouse device into a standard gamepad
- [arm_xarm](https://github.com/johnrso/arm_xarm)