{"id":15009705,"url":"https://github.com/jakubandrysek/pyspacemouse","last_synced_at":"2026-01-18T09:43:38.168Z","repository":{"id":57456433,"uuid":"351230856","full_name":"JakubAndrysek/PySpaceMouse","owner":"JakubAndrysek","description":"🎮 Multiplatform Python library for 3Dconnexion SpaceMouse devices using raw HID.","archived":false,"fork":false,"pushed_at":"2024-05-01T19:03:50.000Z","size":6503,"stargazers_count":46,"open_issues_count":0,"forks_count":14,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-05-02T04:06:30.163Z","etag":null,"topics":["3d","dof","hid","linux","multiplatform","py","python","space-mouse","spacemouse","windows"],"latest_commit_sha":null,"homepage":"https://spacemouse.kubaandrysek.cz/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JakubAndrysek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["JakubAndrysek"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2021-03-24T21:43:08.000Z","updated_at":"2024-05-03T09:53:40.263Z","dependencies_parsed_at":"2023-02-14T02:35:19.982Z","dependency_job_id":"dde732c3-81f3-41e1-80e6-a20b3aac2e28","html_url":"https://github.com/JakubAndrysek/PySpaceMouse","commit_stats":{"total_commits":20,"total_committers":6,"mean_commits":"3.3333333333333335","dds":0.25,"last_synced_commit":"d57a3681239a89a74ae7ed2ba670329a66f051c0"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakubAndrysek%2FPySpaceMouse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakubAndrysek%2FPySpaceMouse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakubAndrysek%2FPySpaceMouse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakubAndrysek%2FPySpaceMouse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JakubAndrysek","download_url":"https://codeload.github.com/JakubAndrysek/PySpaceMouse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137886,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","dof","hid","linux","multiplatform","py","python","space-mouse","spacemouse","windows"],"created_at":"2024-09-24T19:27:44.982Z","updated_at":"2026-01-18T09:43:38.146Z","avatar_url":"https://github.com/JakubAndrysek.png","language":"Python","funding_links":["https://github.com/sponsors/JakubAndrysek"],"categories":[],"sub_categories":[],"readme":"# PySpaceMouse\n\n🎮 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\u003cp align=\"center\"\u003e\n\u003ca href=\"https://hit.kubaandrysek.cz/?url=https%3A%2F%2Fgithub.com%2FJakubAndrysek%2Fpyspacemouse\u0026chart=true\"\u003e\u003cimg src=\"https://hit.kubaandrysek.cz/?url=https%3A%2F%2Fgithub.com%2FJakubAndrysek%2Fpyspacemouse\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://img.shields.io/github/license/JakubAndrysek/pyspacemouse?style=flat-square\"\u003e\n\u003cimg src=\"https://img.shields.io/github/stars/JakubAndrysek/pyspacemouse?style=flat-square\"\u003e\n\u003cimg src=\"https://img.shields.io/github/forks/JakubAndrysek/pyspacemouse?style=flat-square\"\u003e\n\u003cimg src=\"https://img.shields.io/github/issues/JakubAndrysek/pyspacemouse?style=flat-square\"\u003e\n\u003ca href=\"https://www.pepy.tech/projects/pyspacemouse\" target=\"_blank\"\u003e\u003cimg src=\"https://static.pepy.tech/badge/pyspacemouse\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n[PySpaceMouse](https://github.com/JakubAndrysek/pyspacemouse) is forked from: [johnhw/pyspacenavigator](https://github.com/johnhw/pyspacenavigator) and modified to be multiplatform.\n\n![](https://github.com/JakubAndrysek/pyspacemouse/raw/master/media/spacemouse-robot.jpg)\n\n## Supported 3Dconnexion devices\n\n* SpaceNavigator\n* SpaceMouse Pro / Pro Wireless\n* SpaceMouse Wireless\n* SpaceMouse Compact\n* SpaceMouse Enterprise\n* SpacePilot / SpacePilot Pro\n* 3Dconnexion Universal Receiver\n* ...\n* [Add more devices](https://spacemouse.kubaandrysek.cz/CONTRIBUTING/)\n\n## Installation\n\n```bash\npip install pyspacemouse\n```\n\n## Quick Start\n\n```python\nimport pyspacemouse\n\n# Context manager (recommended) - automatically closes device\nwith pyspacemouse.open() as device:\n    while True:\n        state = device.read()\n        print(state.x, state.y, state.z)\n```\n\n## API Reference\n\nFrom version 2.0.0 the API has been modularized and changed.\nPlease look at the [API Reference](./docs/mouseApi/index.md) and [Examples](https://github.com/JakubAndrysek/PySpaceMouse/tree/master/examples) for more information.\n\n### Device Discovery\n\n```python\nimport pyspacemouse\n\n# List connected SpaceMouse devices\npyspacemouse.get_connected_devices()\n# Returns: [\"SpaceNavigator\", \"SpaceMouse Pro\", ...]\n\n# List all supported device types\npyspacemouse.get_supported_devices()\n# Returns: [(name, vendor_id, product_id), ...]\n\n# List ALL HID devices (for debugging)\npyspacemouse.get_all_hid_devices()\n# Returns: [(product, manufacturer, vid, pid), ...]\n```\n\n### Opening Devices\n\n```python\n# Auto-detect and open first device\nwith pyspacemouse.open() as device:\n    state = device.read()\n\n# Open specific device by name\nwith pyspacemouse.open(device=\"SpaceNavigator\") as device:\n    state = device.read()\n\n# Open second device when multiple identical devices are connected\nwith pyspacemouse.open(device_index=1) as device:\n    state = device.read()\n\n# Open by filesystem path (Linux: /dev/hidraw0)\nwith pyspacemouse.open_by_path(\"/dev/hidraw0\") as device:\n    state = device.read()\n```\n\n### Reading State\n\n```python\nwith pyspacemouse.open() as device:\n    state = device.read()\n\n    # 6-DOF axes (range: -1.0 to 1.0)\n    print(state.x, state.y, state.z)       # Translation\n    print(state.roll, state.pitch, state.yaw)  # Rotation\n\n    # Buttons (list of 0/1)\n    print(state.buttons)\n\n    # Timestamp\n    print(state.t)\n```\n\n### Callbacks\n\n```python\n# Button callback\ndef on_button(state, buttons, pressed):\n    print(f\"Button {pressed} pressed!\")\n\nbutton_callbacks = [\n    pyspacemouse.ButtonCallback(0, on_button),  # Button 0\n    pyspacemouse.ButtonCallback([0, 1], on_button),  # Both 0 and 1\n]\n\n# DOF callback with filtering\ndof_callbacks = [\n    pyspacemouse.DofCallback(\n        axis=\"x\",\n        callback=lambda s, v: print(f\"X: {v}\"),\n        callback_minus=lambda s, v: print(f\"X negative: {v}\"),\n        filter=0.1,  # Deadzone\n        sleep=0.05,  # Rate limit\n    ),\n]\n\nwith pyspacemouse.open(\n    button_callbacks=button_callbacks,\n    dof_callbacks=dof_callbacks,\n) as device:\n    while True:\n        device.read()  # Triggers callbacks\n```\n\n### Custom Axis Mapping\n\nCustomize axis directions for specific coordinate conventions (ROS, OpenGL, etc.):\n\n```python\nimport pyspacemouse\n\n# Get existing device spec and modify axes\nspecs = pyspacemouse.get_device_specs()\nbase = specs[\"SpaceNavigator\"]\n\n# Invert axes for your application\ncustom = pyspacemouse.modify_device_info(\n    base,\n    invert_axes=[\"y\", \"z\", \"roll\", \"yaw\"],  # Invert these\n)\n\nwith pyspacemouse.open(device_spec=custom) as device:\n    state = device.read()\n```\n\nSee [Custom Device Configuration](./docs/mouseApi/index.md#custom-device-configuration) for full API.\n\n## CLI\n\n```bash\npyspacemouse --list-connected    # Show connected devices\npyspacemouse --list-supported    # Show all supported types\npyspacemouse --list-hid          # Show all HID devices\npyspacemouse --test              # Test connection\npyspacemouse --version           # Show version\n```\n\n## Examples\n\nSee the [examples/](https://github.com/JakubAndrysek/PySpaceMouse/tree/master/examples) directory:\n\n| Example | Description |\n|---------|-------------|\n| `01_basic.py` | Simple reading with context manager |\n| `02_callbacks.py` | Button and DOF callbacks |\n| `03_multi_device.py` | Using two devices simultaneously |\n| `04_open_by_path.py` | Open specific device by path |\n| `05_discovery.py` | List and inspect devices |\n| `06_axis_callbacks.py` | Per-axis callbacks with filtering |\n| `07_led.py` | LED control |\n| `08_buttons.py` | Button names and handling |\n| `09_custom_config.py` | Custom axis mappings |\n\n## Dependencies\n\n### hidapi (C library)\n\n- **Linux**: `sudo apt-get install libhidapi-dev`\n- **macOS**: `brew install hidapi`\n- **Windows**: Download from [hidapi releases](https://github.com/libusb/hidapi/releases)\n\n### Linux permissions\n\n```bash\nsudo echo 'KERNEL==\"hidraw*\", SUBSYSTEM==\"hidraw\", MODE=\"0664\", GROUP=\"plugdev\"' \u003e /etc/udev/rules.d/99-hidraw-permissions.rules\nsudo usermod -aG plugdev $USER\nnewgrp plugdev\n```\n\n### macOS PATH\n\n```bash\nexport DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/hidapi/\u003cVERSION\u003e/lib:$DYLD_LIBRARY_PATH\n```\n\n## Troubleshooting\n\nSee [troubleshooting.md](./troubleshooting.md) for help with common issues.\n\n## Used In\n\n\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    - ![](https://github.com/rail-berkeley/serl/raw/e59dc0d2721399af2e629d7bcad678fa2ffce9ae/docs/images/tasks-banner.gif)\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    - ![image](https://github.com/wuphilipp/gello_software/assets/33494544/229d90b5-c758-4c14-ab37-d4b2ed7ad50b)\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakubandrysek%2Fpyspacemouse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjakubandrysek%2Fpyspacemouse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakubandrysek%2Fpyspacemouse/lists"}