# 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`.
<p align="center">
<a href="https://hits.seeyoufarm.com"><img src="https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FJakubAndrysek%2Fpyspacemouse&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=true"/></a>
<img src="https://img.shields.io/github/license/JakubAndrysek/pyspacemouse?style=flat-square">
<img src="https://img.shields.io/github/stars/JakubAndrysek/pyspacemouse?style=flat-square">
<img src="https://img.shields.io/github/forks/JakubAndrysek/pyspacemouse?style=flat-square">
<img src="https://img.shields.io/github/issues/JakubAndrysek/pyspacemouse?style=flat-square">
<a href="https://www.pepy.tech/projects/pyspacemouse" target="_blank"><img src="https://static.pepy.tech/badge/pyspacemouse"></a>
</p>
[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
```
<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>
- ### 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)
Raw data
{
"_id": null,
"home_page": "https://github.com/JakubAndrysek/pyspacemouse",
"name": "pyspacemouse",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "pyspacemouse, 3d, 6 DoF, HID, python, open-source, spacemouse, spacenavigator, 3dconnection, 3d-mouse",
"author": "Jakub Andr\u00fdsek",
"author_email": "email@kubaandrysek.cz",
"download_url": "https://files.pythonhosted.org/packages/84/ed/7ee8e7dcff16f0fa82723ca8c22171a409b231d0e1fefc5ede142c205b57/pyspacemouse-1.1.4.tar.gz",
"platform": null,
"description": "# PySpaceMouse\n\n\ud83c\udfae Multiplatform Python library for 3Dconnexion SpaceMouse devices using raw HID.\n\n3Dconnexion Space Mouse in Python using raw HID.\nNote: you **don't** need to install or use any of the drivers or 3Dconnexion software to use this package.\nIt interfaces with the controller directly with `hidapi` and python wrapper library `easyhid`.\n\n<p align=\"center\">\n<a href=\"https://hits.seeyoufarm.com\"><img src=\"https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FJakubAndrysek%2Fpyspacemouse&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=true\"/></a>\n<img src=\"https://img.shields.io/github/license/JakubAndrysek/pyspacemouse?style=flat-square\">\n<img src=\"https://img.shields.io/github/stars/JakubAndrysek/pyspacemouse?style=flat-square\">\n<img src=\"https://img.shields.io/github/forks/JakubAndrysek/pyspacemouse?style=flat-square\">\n<img src=\"https://img.shields.io/github/issues/JakubAndrysek/pyspacemouse?style=flat-square\">\n<a href=\"https://www.pepy.tech/projects/pyspacemouse\" target=\"_blank\"><img src=\"https://static.pepy.tech/badge/pyspacemouse\"></a>\n</p>\n\n[PySpaceMouse](https://github.com/JakubAndrysek/pyspacemouse) is forked from: [johnhw/pyspacenavigator](https://github.com/johnhw/pyspacenavigator)\n\nImplements a simple interface for 6 DoF 3Dconnexion [Space Mouse](https://3dconnexion.com/uk/spacemouse/) device as\nwell as similar devices.\n\n\nControl [Robo Arm](https://roboruka.robotickytabor.cz/) with a Space Mouse.\n\n## Supported 3Dconnexion devices\n\n* SpaceNavigator\n* SpaceMouse Pro\n* SpaceMouse Pro Wireless\n* SpaceMouse Wireless\n* 3Dconnexion Universal Receiver\n* SpaceMouse Compact\n* SpacePilot\n* SpacePilot Pro\n* SpaceMouse Enterprise\n* [Add more devices](https://github.com/johnhw/pyspacenavigator/issues/1)\n\n## Installation\n\nUse 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`.\n\n```bash\n# Install package\npip install pyspacemouse\n\n# Only needed for ARM MacOs\npip install git+https://github.com/bglopez/python-easyhid.git\n```\n\n## Dependencies (required)\n\nThe library uses `hidapi` as low-level interface to the device and `easyhid` as a Python abstraction for easier use.\n\n- ### [hidapi](https://github.com/libusb/hidapi) is `C` library for direct communication with HID devices\n - #### Linux\n - [libhidapi-dev]() to access HID data\n - `sudo apt-get install libhidapi-dev` (Debian/Ubuntu)\n - Compile and install [hidapi](https://github.com/libusb/hidapi/#build-from-source). (other Linux\n distributions)\n\n - add rules for permissions\n ```bash\n sudo echo 'KERNEL==\"hidraw*\", SUBSYSTEM==\"hidraw\", MODE=\"0664\", GROUP=\"plugdev\"' > /etc/udev/rules.d/99-hidraw-permissions.rules\n sudo usermod -aG plugdev $USER\n newgrp plugdev\n ```\n <details>\n <summary>Aleternative option - with tee (RPi)</summary>\n <pre>\n echo 'KERNEL==\"hidraw*\", SUBSYSTEM==\"hidraw\", MODE=\"0664\", GROUP=\"plugdev\"' | sudo tee /etc/udev/rules.d/99-hidraw-permissions.rules\n sudo usermod -aG plugdev $USER\n newgrp plugdev\n </pre>\n </details>\n\n - ### Windows\n - Install the latest release of hidapi.dll and hidapi.lib from\n the [hidapi releases](https://github.com/libusb/hidapi/releases) page.\n - Set system environment: add absolute path for `x64` or `x86` folder in Path.\n - More info on [Troubleshooting - WIndows](./troubleshooting.md#windows) page.\n\n - ### Mac OS X (M1)\n - Install from [Homebrew](https://formulae.brew.sh/formula/hidapi)\n - `brew install hidapi`\n - Add hidapi to your `DYLD_LIBRARY_PATH` directory.\n ```bash\n export DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/hidapi/0.14.0/lib:$DYLD_LIBRARY_PATH\n ```\n - On MacOS M1 you will need patched version of easyhid. If easyhid is already installed, please uninstall it first.\n ```bash\n pip install git+https://github.com/bglopez/python-easyhid.git\n ```\n - In case of problem with M1 chip, try to run you code with Rosseta 2\n - 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)\n - Tested and developed by [consi](https://github.com/JakubAndrysek/PySpaceMouse/issues/10#issuecomment-1768362007) - thanks!\n - More info on [Troubleshooting - Mac OS (M1)](./troubleshooting.md#mac-os-m1) page.\n\n- ### [easyhid](https://github.com/bglopez/python-easyhid) is `hidapi` interface for Python - required on all platforms\n - `pip install git+https://github.com/bglopez/python-easyhid.git`\n - this fork fix problems with `hidapi` on MacOS.\n - on other platforms it possible works with original package `pip install easyhid`\n\n## Basic Usage:\n\nIf the 3Dconnexion driver is installed, please ensure to stop `3DconnexionHelper` before running your python scripts.\n\n\n\n## Basic example\n\n````py\nimport pyspacemouse\nimport time\n\nsuccess = pyspacemouse.open(dof_callback=pyspacemouse.print_state, button_callback=pyspacemouse.print_buttons)\nif success:\n while 1:\n state = pyspacemouse.read()\n time.sleep(0.01)\n````\nMore 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/).\n\n## Available CLI test commands\n```bash\nusage: pyspacemouse [-h] [--version] [--list-spacemouse]\n [--list-supported-devices] [--list-all-hid-devices]\n [--test-connect]\n\nPySpaceMouse CLI\n\noptions:\n -h, --help show this help message and exit\n --version Version of pyspacemouse\n --list-spacemouse List connected SpaceMouse devices\n --list-supported-devices\n List supported SpaceMouse devices\n --list-all-hid-devices\n List all connected HID devices\n --test-connect Test connect to the first available device\n\nFor more information, visit https://spacemouse.kubaandrysek.cz\n```\n\n\n## Troubleshooting\n\nLook at the [Troubleshooting](./troubleshooting.md) page for help with common issues.\n\n## References\n\nPySpaceMouse is used in the following projects:\n\n- [PySpaceApp](https://github.com/JakubAndrysek/pyspaceapp) - Control your PC with SpaceMouse (basic hotkeys, mouse control, and more)\n- [TeleMoMa](https://github.com/UT-Austin-RobIn/telemoma) - A Modular and Versatile Teleoperation System for Mobile Manipulation\n- [SERL](https://github.com/rail-berkeley/serl) - SERL: A Software Suite for Sample-Efficient Robotic Reinforcement Learning\n - \n- [Pancake Robot](https://github.com/pauldw/pancake-robot)- An integration of the Ufactory Lite 6 robot arm with kitchenware to make pancakes.\n- [GELLO](https://github.com/wuphilipp/gello_software) - GELLO: A General, Low-Cost, and Intuitive Teleoperation Framework for Robot Manipulators\n - \n- [spacepad](https://github.com/brianpeiris/spacepad) - A simple python script that turns a spacemouse device into a standard gamepad\n- [arm_xarm](https://github.com/johnrso/arm_xarm)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Multiplatform Python interface to the 3DConnexion Space Mouse - forked from pyspacenavigator",
"version": "1.1.4",
"project_urls": {
"Homepage": "https://github.com/JakubAndrysek/pyspacemouse"
},
"split_keywords": [
"pyspacemouse",
" 3d",
" 6 dof",
" hid",
" python",
" open-source",
" spacemouse",
" spacenavigator",
" 3dconnection",
" 3d-mouse"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "51ab3584d754e0e76ac39c96f7569163cc5dede143d983b4556026cfc1b8b05b",
"md5": "653536cf6f9b28a0176d988b31022406",
"sha256": "67a974b28a1331e913a198d83ec968ac2298b8c5bc5387189a0fb53f256ed3b9"
},
"downloads": -1,
"filename": "pyspacemouse-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "653536cf6f9b28a0176d988b31022406",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14742,
"upload_time": "2024-08-26T20:52:26",
"upload_time_iso_8601": "2024-08-26T20:52:26.522841Z",
"url": "https://files.pythonhosted.org/packages/51/ab/3584d754e0e76ac39c96f7569163cc5dede143d983b4556026cfc1b8b05b/pyspacemouse-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "84ed7ee8e7dcff16f0fa82723ca8c22171a409b231d0e1fefc5ede142c205b57",
"md5": "0c223c402f8dc3f6530b02a41f7ec03c",
"sha256": "cb8733d6d0abf7c2c2673ae8b36bb67f8523ae3a04f749fd2caca8f429b07a6b"
},
"downloads": -1,
"filename": "pyspacemouse-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "0c223c402f8dc3f6530b02a41f7ec03c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19106,
"upload_time": "2024-08-26T20:52:28",
"upload_time_iso_8601": "2024-08-26T20:52:28.061204Z",
"url": "https://files.pythonhosted.org/packages/84/ed/7ee8e7dcff16f0fa82723ca8c22171a409b231d0e1fefc5ede142c205b57/pyspacemouse-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-26 20:52:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JakubAndrysek",
"github_project": "pyspacemouse",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pyspacemouse"
}
JSON
