| Name | armctl JSON |
| Version |
0.3.2
JSON |
| download |
| home_page | https://github.com/MGross21/armctl |
| Summary | Agnostic Robotic Manipulator Controller (armctl) |
| upload_time | 2025-08-04 04:30:48 |
| maintainer | None |
| docs_url | None |
| author | Michael Gross |
| requires_python | <4.0,>=3.9 |
| license | MIT License
Copyright (c) 2025 Michael Gross
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
robotics
socket
control
automation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<h1><img src="https://raw.githubusercontent.com/MGross21/armctl/main/assets/logo/armctl_logo_orange.png" alt="armctl" width="300px"></h1>
</div>
<p align="center">
<!-- <img src="https://github.com/MGross21/armctl/actions/workflows/ci.yml/badge.svg" alt="Build Status"> -->
<img src="https://img.shields.io/badge/python-3-orange.svg" alt="Python Version">
<img src="https://img.shields.io/github/license/MGross21/armctl?color=orange" alt="License">
</p>
A unified Python interface for controlling a variety of industrial and hobbyist robots from different manufacturers.
## Supported Manufacturers & Robot Series
The `armctl` library currently supports the following manufacturers and robot models:
### [Universal Robots](https://www.universal-robots.com)
- **Supported Models:** UR3, UR5, UR5e, UR10, UR16 <br>
<img src=https://raw.githubusercontent.com/MGross21/armctl/main/assets/gifs/ur5.gif alt="UR5" width="400">
### [Vention](https://vention.io)
- **Supported Models:** 7th Axis Plate <br>
<img src="https://raw.githubusercontent.com/MGross21/armctl/main/assets/gifs/vention.gif" alt="Vention Plate" width="400">
### [Elephant Robotics](https://www.elephantrobotics.com/en/)
- **Supported Models:** myCobot Pro600 <br>
<img src="https://raw.githubusercontent.com/MGross21/armctl/main/assets/gifs/elephant_pro600.gif" alt="Elephant myCobot Pro600" width="400">
> **Want to see your robot supported?**
> [Open an issue](https://github.com/MGross21/armctl/issues) or contribute a pull request!
## Quick Start
### Installation
*From PyPI:*
```bash
pip install armctl
```
*From GitHub:*
```bash
pip install git+https://github.com/MGross21/armctl.git
```
### Importing the Library
```python
from armctl import *
```
> **Note:**
> For improved runtime performance and clarity, you may import specific manufacturers and robot series directly.
### Simple Example with Manufacturer Defaults
```python
with Manufacturer("ROBOT_IP_ADDRESS") as robot:
robot.move_joints([...])
robot.get_joint_positions()
robot.move_cartesian([...])
robot.get_cartesian_position(...)
robot.sleep(...)
robot.get_robot_state()
```
### Simple Example with Specific Robot Series
```python
with RobotSeries("ROBOT_IP_ADDRESS") as robot:
robot.home()
robot.move_joints([...])
robot.get_joint_positions()
robot.move_cartesian([...])
robot.get_cartesian_position()
robot.sleep(...)
robot.get_robot_state()
```
### Multi-Robot Control
<img src="https://raw.githubusercontent.com/MGross21/armctl/main/assets/gifs/ur5_vention.gif" alt="UR5 on Vention Plate" width="400">
```python
with (
Robot1("ROBOT1_IP_ADDRESS") as r1,
Robot2("ROBOT2_IP_ADDRESS") as r2,
):
r1.home()
r2.home()
r1.move_joints([...])
r2.move_joints([...])
```
> **Tip:**
> For more precise and synchronous control of two or more robots, it is recommended to manage each robot within its own thread or process.
#### Multithread Control
Replicating the prior example,
```python
import threading
def control_robot(robot, ip):
with robot(ip) as r:
r.home()
r.move_joints([0] * r.DOF)
threads = [
threading.Thread(target=control_robot, args=(Robot1, "ROBOT1_IP")),
threading.Thread(target=control_robot, args=(Robot2, "ROBOT2_IP"))
]
for t in threads:
t.start()
for t in threads:
t.join()
```
## API Reference
> **Note:**
> The API has been designed for maximum compatibility across supported robots. Additional commands, such as gripper controls and other advanced features, are planned for future releases to further expand functionality.
### Control Template
The following methods are available to users of the library to control various supported robots.
| Method Name | Description |
|------------------------------|-----------------------------------------------------------------------------|
| `move_joints(pos)` | Move the robot to specified joint positions. |
| `get_joint_positions()` | Retrieve the current joint positions of the robot. |
| `move_cartesian(pose)` | Move the robot to a specified Cartesian pose. |
| `get_cartesian_position()` | Retrieve the current Cartesian position of the robot. |
| `stop_motion()` | Stop all robot motion immediately. |
| `get_robot_state()` | Retrieve the current state of the robot. |
| `sleep(seconds)` | Pause execution for a specified number of seconds. |
| `home()` <br> <sub>*(Available only for specific robot series, not for generic manufacturer control)*</sub> | Move the robot to its home position. |
#### Standard Units
All inputs and outputs use these standard units:
| Type | Unit |
| ---------------------- | ------------------------ |
| **Joint Angle** | radians |
| **Cartesian Position** | meters (`[x, y, z]`) |
| **Cartesian Rotation** | radians (`[rx, ry, rz]`) |
### Connection Template
The following methods facilitate explicit connection management and low-level command execution. These are primarily intended for advanced scenarios, such as when not using Python's `with/as` context manager or when sending custom commands outside the standard API. *Use with caution*.
| Method Name | Description |
|------------------------------|------------------------------------------------------------------|
| `connect()` | Establish a connection to the robot controller. |
| `disconnect()` | Close the connection to the robot controller. |
| `send_command(cmd)` | Send a low-level command to the robot controller. |
### Graphical Overview
Below is a high-level diagram illustrating the architecture of the `armctl` library. This design emphasizes the careful templatization of connection and control APIs, ensuring a consistent and extensible interface across different manufacturers and robot series.
<p align="center">
<img src="https://raw.githubusercontent.com/MGross21/armctl/main/assets/images/template_overview_mermaid.png" alt="Template Overview" width="800">
</p>
### System Logging
By default, the library will show the outgoing commands and incoming data. An example can be seen below:
```console
2025-02-12 13:18:11,350 - INFO - Connected to ElephantRobotics(192.168.1.159:5001)(SEND/RECV)
2025-02-12 13:18:11,351 - SEND - Sending command: power_on()
2025-02-12 13:18:11,954 - RECV - Received response: [ok]
2025-02-12 13:18:11,954 - SEND - Sending command: state_on()
2025-02-12 13:18:12,647 - RECV - Received response: [ok]
2025-02-12 13:18:12,647 - SEND - Sending command: get_angles()
2025-02-12 13:18:12,663 - RECV - Received response: get_angles:[0.290562,-95.891321,-74.804509,-162.949219,1.845703,12.041016]
2025-02-12 13:18:12,663 - SEND - Sending command: task_stop()
2025-02-12 13:18:13,466 - RECV - Received response: [ok]
2025-02-12 13:18:13,466 - SEND - Sending command: state_off()
2025-02-12 13:18:14,176 - RECV - Received response: [ok]
2025-02-12 13:18:14,176 - SEND - Sending command: power_off()
2025-02-12 13:18:14,176 - RECV - Received response: [ok]
2025-02-12 13:18:14,176 - INFO - Disconnected from ElephantRobotics
```
#### Disabling
```python
from armctl import *
Logger.disable()
```
#### Re-Enabling
```python
Logger.enable()
```
## Under Development
- [JAKA](https://www.jaka.com/en)
- **Models:** Zu 5
- [Dobot](https://www.dobot-robots.com)
- **Models:** Magician Lite
## Future Development
- [FANUC](https://www.fanucamerica.com)
- **Models:** LR Mate 200iD Series
- **More manufacturers and robot series will be supported in future releases.**
## Contributing
Please feel free to submit a pull request or open an issue for any enhancements or bug fixes. See [CONTRIBUTING](https://github.com/MGross21/armctl/blob/main/CONTRIBUTING.md) for more details.
## License
This project is licensed under the MIT License. See the [LICENSE](https://github.com/MGross21/armctl/blob/main/LICENSE) file for more details.
### Notice
> This package automatically installs the [Universal Robots RTDE Python Client Library](https://github.com/UniversalRobots/RTDE_Python_Client_Library) when needed.
> The RTDE library is provided by Universal Robots and is subject to their licensing terms.
Raw data
{
"_id": null,
"home_page": "https://github.com/MGross21/armctl",
"name": "armctl",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "robotics, socket, control, automation",
"author": "Michael Gross",
"author_email": "MGross21@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/75/df/0ffb0d9ab08bb7d61aade0de5fb5a333f074192f888dde9fb8fad22fcd32/armctl-0.3.2.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <h1><img src=\"https://raw.githubusercontent.com/MGross21/armctl/main/assets/logo/armctl_logo_orange.png\" alt=\"armctl\" width=\"300px\"></h1>\n</div>\n\n<p align=\"center\">\n <!-- <img src=\"https://github.com/MGross21/armctl/actions/workflows/ci.yml/badge.svg\" alt=\"Build Status\"> -->\n <img src=\"https://img.shields.io/badge/python-3-orange.svg\" alt=\"Python Version\">\n <img src=\"https://img.shields.io/github/license/MGross21/armctl?color=orange\" alt=\"License\">\n</p>\n\nA unified Python interface for controlling a variety of industrial and hobbyist robots from different manufacturers.\n\n## Supported Manufacturers & Robot Series\n\nThe `armctl` library currently supports the following manufacturers and robot models:\n\n### [Universal Robots](https://www.universal-robots.com)\n\n- **Supported Models:** UR3, UR5, UR5e, UR10, UR16 <br>\n <img src=https://raw.githubusercontent.com/MGross21/armctl/main/assets/gifs/ur5.gif alt=\"UR5\" width=\"400\">\n\n### [Vention](https://vention.io)\n\n- **Supported Models:** 7th Axis Plate <br>\n <img src=\"https://raw.githubusercontent.com/MGross21/armctl/main/assets/gifs/vention.gif\" alt=\"Vention Plate\" width=\"400\">\n\n### [Elephant Robotics](https://www.elephantrobotics.com/en/)\n\n- **Supported Models:** myCobot Pro600 <br>\n <img src=\"https://raw.githubusercontent.com/MGross21/armctl/main/assets/gifs/elephant_pro600.gif\" alt=\"Elephant myCobot Pro600\" width=\"400\">\n\n> **Want to see your robot supported?** \n> [Open an issue](https://github.com/MGross21/armctl/issues) or contribute a pull request!\n\n## Quick Start\n\n### Installation\n\n*From PyPI:*\n\n```bash\npip install armctl\n```\n\n*From GitHub:*\n\n```bash\npip install git+https://github.com/MGross21/armctl.git\n```\n\n### Importing the Library\n\n```python\nfrom armctl import *\n```\n\n> **Note:** \n> For improved runtime performance and clarity, you may import specific manufacturers and robot series directly.\n\n### Simple Example with Manufacturer Defaults\n\n```python\nwith Manufacturer(\"ROBOT_IP_ADDRESS\") as robot:\n robot.move_joints([...])\n robot.get_joint_positions()\n robot.move_cartesian([...])\n robot.get_cartesian_position(...)\n robot.sleep(...)\n robot.get_robot_state()\n```\n\n### Simple Example with Specific Robot Series\n\n```python\nwith RobotSeries(\"ROBOT_IP_ADDRESS\") as robot:\n robot.home()\n robot.move_joints([...])\n robot.get_joint_positions()\n robot.move_cartesian([...])\n robot.get_cartesian_position()\n robot.sleep(...)\n robot.get_robot_state()\n```\n\n### Multi-Robot Control\n\n<img src=\"https://raw.githubusercontent.com/MGross21/armctl/main/assets/gifs/ur5_vention.gif\" alt=\"UR5 on Vention Plate\" width=\"400\">\n\n```python\nwith (\n Robot1(\"ROBOT1_IP_ADDRESS\") as r1,\n Robot2(\"ROBOT2_IP_ADDRESS\") as r2,\n):\n r1.home()\n r2.home()\n\n r1.move_joints([...])\n r2.move_joints([...])\n```\n\n> **Tip:** \n> For more precise and synchronous control of two or more robots, it is recommended to manage each robot within its own thread or process.\n\n#### Multithread Control\n\nReplicating the prior example,\n\n```python\nimport threading\n\ndef control_robot(robot, ip):\n with robot(ip) as r:\n r.home()\n r.move_joints([0] * r.DOF)\n\nthreads = [\n threading.Thread(target=control_robot, args=(Robot1, \"ROBOT1_IP\")),\n threading.Thread(target=control_robot, args=(Robot2, \"ROBOT2_IP\"))\n]\n\nfor t in threads:\n t.start()\nfor t in threads:\n t.join()\n```\n\n## API Reference\n\n> **Note:** \n> The API has been designed for maximum compatibility across supported robots. Additional commands, such as gripper controls and other advanced features, are planned for future releases to further expand functionality.\n\n### Control Template\n\nThe following methods are available to users of the library to control various supported robots.\n\n| Method Name | Description |\n|------------------------------|-----------------------------------------------------------------------------|\n| `move_joints(pos)` | Move the robot to specified joint positions. |\n| `get_joint_positions()` | Retrieve the current joint positions of the robot. |\n| `move_cartesian(pose)` | Move the robot to a specified Cartesian pose. |\n| `get_cartesian_position()` | Retrieve the current Cartesian position of the robot. |\n| `stop_motion()` | Stop all robot motion immediately. |\n| `get_robot_state()` | Retrieve the current state of the robot. |\n| `sleep(seconds)` | Pause execution for a specified number of seconds. |\n| `home()` <br> <sub>*(Available only for specific robot series, not for generic manufacturer control)*</sub> | Move the robot to its home position. |\n\n#### Standard Units\n\nAll inputs and outputs use these standard units:\n\n| Type | Unit |\n| ---------------------- | ------------------------ |\n| **Joint Angle** | radians |\n| **Cartesian Position** | meters (`[x, y, z]`) |\n| **Cartesian Rotation** | radians (`[rx, ry, rz]`) |\n\n### Connection Template\n\nThe following methods facilitate explicit connection management and low-level command execution. These are primarily intended for advanced scenarios, such as when not using Python's `with/as` context manager or when sending custom commands outside the standard API. *Use with caution*.\n\n| Method Name | Description |\n|------------------------------|------------------------------------------------------------------|\n| `connect()` | Establish a connection to the robot controller. |\n| `disconnect()` | Close the connection to the robot controller. |\n| `send_command(cmd)` | Send a low-level command to the robot controller. |\n\n### Graphical Overview\n\nBelow is a high-level diagram illustrating the architecture of the `armctl` library. This design emphasizes the careful templatization of connection and control APIs, ensuring a consistent and extensible interface across different manufacturers and robot series.\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/MGross21/armctl/main/assets/images/template_overview_mermaid.png\" alt=\"Template Overview\" width=\"800\">\n</p>\n\n### System Logging\n\nBy default, the library will show the outgoing commands and incoming data. An example can be seen below:\n\n```console\n2025-02-12 13:18:11,350 - INFO - Connected to ElephantRobotics(192.168.1.159:5001)(SEND/RECV)\n2025-02-12 13:18:11,351 - SEND - Sending command: power_on()\n2025-02-12 13:18:11,954 - RECV - Received response: [ok]\n2025-02-12 13:18:11,954 - SEND - Sending command: state_on()\n2025-02-12 13:18:12,647 - RECV - Received response: [ok]\n2025-02-12 13:18:12,647 - SEND - Sending command: get_angles()\n2025-02-12 13:18:12,663 - RECV - Received response: get_angles:[0.290562,-95.891321,-74.804509,-162.949219,1.845703,12.041016]\n2025-02-12 13:18:12,663 - SEND - Sending command: task_stop()\n2025-02-12 13:18:13,466 - RECV - Received response: [ok]\n2025-02-12 13:18:13,466 - SEND - Sending command: state_off()\n2025-02-12 13:18:14,176 - RECV - Received response: [ok]\n2025-02-12 13:18:14,176 - SEND - Sending command: power_off()\n2025-02-12 13:18:14,176 - RECV - Received response: [ok]\n2025-02-12 13:18:14,176 - INFO - Disconnected from ElephantRobotics\n```\n\n#### Disabling\n\n```python\nfrom armctl import *\nLogger.disable()\n```\n\n#### Re-Enabling\n\n```python\nLogger.enable()\n```\n\n## Under Development\n\n- [JAKA](https://www.jaka.com/en)\n - **Models:** Zu 5\n- [Dobot](https://www.dobot-robots.com)\n - **Models:** Magician Lite\n\n## Future Development\n\n- [FANUC](https://www.fanucamerica.com)\n - **Models:** LR Mate 200iD Series\n- **More manufacturers and robot series will be supported in future releases.**\n\n## Contributing\n\nPlease feel free to submit a pull request or open an issue for any enhancements or bug fixes. See [CONTRIBUTING](https://github.com/MGross21/armctl/blob/main/CONTRIBUTING.md) for more details.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](https://github.com/MGross21/armctl/blob/main/LICENSE) file for more details.\n\n### Notice\n\n> This package automatically installs the [Universal Robots RTDE Python Client Library](https://github.com/UniversalRobots/RTDE_Python_Client_Library) when needed. \n> The RTDE library is provided by Universal Robots and is subject to their licensing terms.\n",
"bugtrack_url": null,
"license": "MIT License\n\nCopyright (c) 2025 Michael Gross\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.",
"summary": "Agnostic Robotic Manipulator Controller (armctl)",
"version": "0.3.2",
"project_urls": {
"Homepage": "https://github.com/MGross21/armctl",
"Tracker": "https://github.com/MGross21/armctl/issues"
},
"split_keywords": [
"robotics",
" socket",
" control",
" automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "64bf36a25b2378acde28d2e9daa768067f747bb6eb9af2674d7b402e49af14bc",
"md5": "2abbbe1e503ee06ba5fcec9080ddf589",
"sha256": "ca8bf978ff3b11a5d41433a9fb001630c807b68906f4c6ca5f565b9c4a816aae"
},
"downloads": -1,
"filename": "armctl-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2abbbe1e503ee06ba5fcec9080ddf589",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 32226,
"upload_time": "2025-08-04T04:30:47",
"upload_time_iso_8601": "2025-08-04T04:30:47.281199Z",
"url": "https://files.pythonhosted.org/packages/64/bf/36a25b2378acde28d2e9daa768067f747bb6eb9af2674d7b402e49af14bc/armctl-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "75df0ffb0d9ab08bb7d61aade0de5fb5a333f074192f888dde9fb8fad22fcd32",
"md5": "f8d9e9a53cc5ef9a4090676fdcf4b9db",
"sha256": "9c0d8acc85516aa3f80ca281e65b484bfb60bc16fb5dfb0c376326c44dada1f5"
},
"downloads": -1,
"filename": "armctl-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "f8d9e9a53cc5ef9a4090676fdcf4b9db",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 24156,
"upload_time": "2025-08-04T04:30:48",
"upload_time_iso_8601": "2025-08-04T04:30:48.445672Z",
"url": "https://files.pythonhosted.org/packages/75/df/0ffb0d9ab08bb7d61aade0de5fb5a333f074192f888dde9fb8fad22fcd32/armctl-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 04:30:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MGross21",
"github_project": "armctl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "armctl"
}
