[](https://github.com/Auromix)
[](https://ubuntu.com/)
[](https://github.com/Auromix/auro_joystick/blob/main/LICENSE)
[](https://github.com/Auromix/auro_joystick/stargazers)
[](https://twitter.com/Hermanye233)
# 🎮 Auro Joystick
Auro Joystick is a Python library designed for interfacing with joystick devices in robotics applications, offering robust support for ROS to facilitate easy integration.
## 🚀 Features
- **Joystick Detection:** Automatically identifies supported joystick devices.
- **Event Handling:** Efficiently processes input events for joystick buttons and axes.
- **ROS Compatibility:** Seamlessly integrates with both ROS1 and ROS2 for robotic systems.
- **Configurable Logging:** Delivers comprehensive logging for straightforward debugging.
- **Custom Event Handlers:** Supports the registration of custom event handlers for specific joystick actions.
## 🧪 Testing Conditions
Auro Joystick has been tested on the `Beitong` gamepad.
It is also compatible with other controllers that follow the `Xbox` layout.
## ⚙️ Installation
To install Auro Joystick, you can use one of the following methods:
```bash
# Install from PyPI
pip install auro_joystick
```
```bash
# Install from the current directory (local development)
pip install .
```
## 🔥 Quickstart
You can find detailed examples for the project in the `examples` directory of the repository.
### Print Input
This example will display the current inputs and corresponding values from your gamepad:
```bash
python examples/print_input.py
```
### ROS Example
Use the `left joystick` to control the movement of a turtle in Turtlesim, while the `right joystick` will manage its rotation.
Press the `B` key to reset the turtle.
```bash
# [Terminal 1]
# Run roscore
roscore
```
```bash
# [Terminal 2]
# Run Turtlesim
rosrun turtlesim turtlesim_node
```
```bash
# [Terminal 3]
# Run the example
python examples/control_ros_turtlesim.py
```
### Minimal Code Example
This example will call a function when the `A` button is pressed.
```python
import time
from auro_joystick import AuroJoystick
# Your callback function
def on_button_a_pressed():
print("Button A pressed!")
# Init the joystick
joystick = AuroJoystick()
# Register the function for button A
joystick.register_event_handler(on_button_a_pressed, "button_a_pressed")
# Start the joystick
joystick.start()
# Your loop
while True:
time.sleep(0.05)
```
```bash
python examples/minimal.py
```
## 🧑💻 Documentation
For comprehensive documentation, please refer to the comments within the source code and examples.
## 🙋 Troubleshooting
### Joystick Device Not Found
```python
ValueError: Joystick device not found
```
<details> <summary> Click here to see the solution </summary>
It means that the system couldn't find your joystick.
- Step 1: How AuroJoystick Finds Devices
AuroJoystick automatically searches for devices matching certain keywords, like `["pad", "X-Box", "360"]`.
- Step 2: Manual Device Path Setup
If the joystick isn’t found automatically, you can manually specify the device path.
```bash
# Install input-utils
sudo apt-get install input-utils
# List input devices
sudo lsinput
```
- Step 3: Find the Joystick Device
Look for a device that looks like this:
```bash
/dev/input/event17
bustype : BUS_USB
vendor : 0x45e
product : 0x28e
version : 256
name : "Microsoft X-Box 360 pad"
phys : "usb-0000:00:14.0-6.4/input0"
```
- Step 4: Use the Device Path
In your code, specify the path:
```python
joystick = AuroJoystick(device_path="/dev/input/event17")
```
</details>
### Permission Denied for Input Device
```bash
PermissionError: [Errno 13] Permission denied: '/dev/input/event18'
```
<details> <summary> Click here to see the solution </summary>
This error means the program does not have the necessary permissions to access the device.
- Step 1: Grant Temporary Permissions
To give your program temporary access, you can change the permissions of the device using the `chmod` command:
```bash
sudo chmod 777 /dev/input/event18
```
This grants read, write, and execute permissions for all users. Note that this is temporary and will be reset after a reboot.
This ensures your joystick device is accessible every time it's plugged in.
</details>
If you encounter any issues or have questions regarding this package, please contact the maintainers:
- Herman Ye @ Auromix (Email: <hermanye233@icloud.com>)
## 📜 License
```text
Copyright 2023-2024 Herman Ye@Auromix
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at:
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either express or implied. See the License for the specific
language governing permissions and limitations under the License.
```
## 🏆 Contributing
Contributions are welcome! Please follow the guidelines provided in the repository for contributing.
Raw data
{
"_id": null,
"home_page": "https://github.com/Auromix/auro_joystick",
"name": "auro-joystick",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "auro_joystick",
"author": "Herman Ye",
"author_email": "hermanye233@icloud.com",
"download_url": "https://files.pythonhosted.org/packages/b8/f9/f2e74141daa7959f7b94ae740384698a54c74f07f56f2da5630a94bbe910/auro_joystick-1.0.2.tar.gz",
"platform": null,
"description": "[](https://github.com/Auromix) \n[](https://ubuntu.com/) \n[](https://github.com/Auromix/auro_joystick/blob/main/LICENSE) \n[](https://github.com/Auromix/auro_joystick/stargazers) \n[](https://twitter.com/Hermanye233) \n\n# \ud83c\udfae Auro Joystick\n\nAuro Joystick is a Python library designed for interfacing with joystick devices in robotics applications, offering robust support for ROS to facilitate easy integration.\n\n\n\n## \ud83d\ude80 Features\n\n- **Joystick Detection:** Automatically identifies supported joystick devices.\n- **Event Handling:** Efficiently processes input events for joystick buttons and axes.\n- **ROS Compatibility:** Seamlessly integrates with both ROS1 and ROS2 for robotic systems.\n- **Configurable Logging:** Delivers comprehensive logging for straightforward debugging.\n- **Custom Event Handlers:** Supports the registration of custom event handlers for specific joystick actions.\n\n## \ud83e\uddea Testing Conditions\n\nAuro Joystick has been tested on the `Beitong` gamepad.\n\nIt is also compatible with other controllers that follow the `Xbox` layout.\n\n## \u2699\ufe0f Installation\n\nTo install Auro Joystick, you can use one of the following methods:\n\n```bash\n# Install from PyPI\npip install auro_joystick\n```\n\n```bash\n# Install from the current directory (local development)\npip install .\n```\n\n## \ud83d\udd25 Quickstart\n\nYou can find detailed examples for the project in the `examples` directory of the repository.\n\n### Print Input\n\nThis example will display the current inputs and corresponding values from your gamepad:\n\n```bash\npython examples/print_input.py\n```\n\n### ROS Example\n\nUse the `left joystick` to control the movement of a turtle in Turtlesim, while the `right joystick` will manage its rotation.\n\nPress the `B` key to reset the turtle.\n\n```bash\n# [Terminal 1]\n# Run roscore\nroscore\n```\n\n```bash\n# [Terminal 2]\n# Run Turtlesim\nrosrun turtlesim turtlesim_node\n```\n\n```bash\n# [Terminal 3]\n# Run the example\npython examples/control_ros_turtlesim.py\n```\n\n### Minimal Code Example\n\nThis example will call a function when the `A` button is pressed.\n\n```python\nimport time\nfrom auro_joystick import AuroJoystick\n\n\n# Your callback function\ndef on_button_a_pressed():\n print(\"Button A pressed!\")\n\n\n# Init the joystick\njoystick = AuroJoystick()\n# Register the function for button A\njoystick.register_event_handler(on_button_a_pressed, \"button_a_pressed\")\n\n# Start the joystick\njoystick.start()\n\n# Your loop\nwhile True:\n time.sleep(0.05)\n```\n\n```bash\npython examples/minimal.py\n```\n\n## \ud83e\uddd1\u200d\ud83d\udcbb Documentation\n\nFor comprehensive documentation, please refer to the comments within the source code and examples.\n\n## \ud83d\ude4b Troubleshooting\n\n### Joystick Device Not Found\n\n```python\nValueError: Joystick device not found\n```\n\n<details> <summary> Click here to see the solution </summary>\nIt means that the system couldn't find your joystick.\n\n- Step 1: How AuroJoystick Finds Devices\n\n AuroJoystick automatically searches for devices matching certain keywords, like `[\"pad\", \"X-Box\", \"360\"]`.\n\n- Step 2: Manual Device Path Setup\n\n If the joystick isn\u2019t found automatically, you can manually specify the device path.\n\n ```bash\n # Install input-utils\n sudo apt-get install input-utils\n # List input devices\n sudo lsinput\n ```\n\n- Step 3: Find the Joystick Device\n\n Look for a device that looks like this:\n\n ```bash\n /dev/input/event17\n bustype : BUS_USB\n vendor : 0x45e\n product : 0x28e\n version : 256\n name : \"Microsoft X-Box 360 pad\"\n phys : \"usb-0000:00:14.0-6.4/input0\"\n ```\n\n- Step 4: Use the Device Path\n\n In your code, specify the path:\n\n ```python\n joystick = AuroJoystick(device_path=\"/dev/input/event17\")\n ```\n\n</details>\n\n### Permission Denied for Input Device\n\n```bash\nPermissionError: [Errno 13] Permission denied: '/dev/input/event18'\n```\n\n<details> <summary> Click here to see the solution </summary>\nThis error means the program does not have the necessary permissions to access the device.\n\n- Step 1: Grant Temporary Permissions\n\n To give your program temporary access, you can change the permissions of the device using the `chmod` command:\n\n ```bash\n sudo chmod 777 /dev/input/event18\n ```\n\n This grants read, write, and execute permissions for all users. Note that this is temporary and will be reset after a reboot.\n\n This ensures your joystick device is accessible every time it's plugged in.\n\n</details>\n\nIf you encounter any issues or have questions regarding this package, please contact the maintainers:\n\n- Herman Ye @ Auromix (Email: <hermanye233@icloud.com>)\n\n## \ud83d\udcdc License\n\n```text\nCopyright 2023-2024 Herman Ye@Auromix\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at:\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing,\nsoftware distributed under the License is distributed on an\n\"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,\neither express or implied. See the License for the specific\nlanguage governing permissions and limitations under the License.\n```\n\n## \ud83c\udfc6 Contributing\n\nContributions are welcome! Please follow the guidelines provided in the repository for contributing.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Auro Joystick is a Python library designed for interfacing with joystick devices in robotics applications, offering robust support for ROS to facilitate easy integration.",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/Auromix/auro_joystick"
},
"split_keywords": [
"auro_joystick"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b8f9f2e74141daa7959f7b94ae740384698a54c74f07f56f2da5630a94bbe910",
"md5": "79efc18fd767a60335c76a1497a439ae",
"sha256": "50291b2075289e98784c616a8959117013ab9768b7482ea6bf956d86ff6e245b"
},
"downloads": -1,
"filename": "auro_joystick-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "79efc18fd767a60335c76a1497a439ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10361,
"upload_time": "2024-10-22T09:22:47",
"upload_time_iso_8601": "2024-10-22T09:22:47.983702Z",
"url": "https://files.pythonhosted.org/packages/b8/f9/f2e74141daa7959f7b94ae740384698a54c74f07f56f2da5630a94bbe910/auro_joystick-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 09:22:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Auromix",
"github_project": "auro_joystick",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "auro-joystick"
}
JSON
