# 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.
- ### 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 in [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/).
## 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/aa/7c/8885eef3826a8c65e681adc25054639c7fc93793aca0f1ac242909992b2b/pyspacemouse-1.1.2.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\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 in [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\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.2",
"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": "4e01809140b01402e6e0d24bd14219aef5fca3fa00b9eafbf8fc20b6ae263646",
"md5": "6baf80045bcafa69bd8566f2f1a45d3b",
"sha256": "d5550e032181857ccc7c893383d04538343f34029a9e11b2001d0769181f58af"
},
"downloads": -1,
"filename": "pyspacemouse-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6baf80045bcafa69bd8566f2f1a45d3b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12913,
"upload_time": "2024-04-20T20:22:34",
"upload_time_iso_8601": "2024-04-20T20:22:34.756926Z",
"url": "https://files.pythonhosted.org/packages/4e/01/809140b01402e6e0d24bd14219aef5fca3fa00b9eafbf8fc20b6ae263646/pyspacemouse-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aa7c8885eef3826a8c65e681adc25054639c7fc93793aca0f1ac242909992b2b",
"md5": "e6057d4019753bbd3a7b92643414befb",
"sha256": "07ba9a56bd3b50475a41f4f58ef84355b885886a155dd6f0219684809c0d26eb"
},
"downloads": -1,
"filename": "pyspacemouse-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "e6057d4019753bbd3a7b92643414befb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17640,
"upload_time": "2024-04-20T20:22:35",
"upload_time_iso_8601": "2024-04-20T20:22:35.908068Z",
"url": "https://files.pythonhosted.org/packages/aa/7c/8885eef3826a8c65e681adc25054639c7fc93793aca0f1ac242909992b2b/pyspacemouse-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-20 20:22:35",
"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
