|
| 1 | +# The Arm Commander Package |
| 2 | + [](https://opensource.org/licenses/BSD-3-Clause) |
| 3 | + |
| 4 | +<!-- |
| 5 | +Replace REPO_USER, & REPO_NAME in the lines below to get more auto-generated badges |
| 6 | + |
| 7 | +[](./BSD.txt) |
| 8 | +--> |
| 9 | + |
| 10 | +The **Arm Commander** is a library providing an enhanced interface for robot arm manipulation. It is designed to wrap around a robot arm movement planner (i.e. robotic manipulation platforms) such as [Moveit](https://ros-planning.github.io/moveit_tutorials/) or [Armer](https://github.com/qcr/armer) and to offer features that achieve more with less programming: |
| 11 | + |
| 12 | +- Multiple forms of movement target specification |
| 13 | + - Pose |
| 14 | + - PoseStamped |
| 15 | + - A list of 6 numbers (xyzrpy) |
| 16 | + - A list of 7 numbers (xyzqqqq) |
| 17 | + - The position components with defaults (x, y, and z) |
| 18 | + - The missing parameters are defaulted to the current values |
| 19 | + - The rotation components with defaults (roll, pitch, and yaw) |
| 20 | + - The missing parameters are defaulted to the current values |
| 21 | + - Displacement components (dx, dy, dz) |
| 22 | +- Simple switch between cartesian path and planned path. |
| 23 | + - In a move command along a cartesian path, fractional execution is supported. |
| 24 | +- Addition and removal of collision objects for path planning and pose transform |
| 25 | + - Primitive shapes (box and sphere) and custom shapes are supported. |
| 26 | + - Pose transform between collision objects and robot links is supported through the tranform tree. |
| 27 | + - Attach and detach of objects for grab and drop simulation. |
| 28 | +- Asynchronous and synchronous command support |
| 29 | + - State transition model for command management. |
| 30 | + - Convenient functions for waiting, polling, and aborting of commands. |
| 31 | +- Addition and removal of contraints |
| 32 | + - Helper function for the creation of rotation, position, and joint-space constraints |
| 33 | +- Agnostic to the robotic manipulation platform design-wise (though this implementation supports only Moveit) |
| 34 | +- Agnostic to the robot arm model (through the underlying robotic manipulation platform) |
| 35 | + |
| 36 | +## Installation |
| 37 | + |
| 38 | +The arm_commander stems from an architecture that is robot model agnostic and arm manipulation platform agnostic. It hides away the |
| 39 | +details and offers a consistent application programming interface. |
| 40 | + |
| 41 | +This implementation of arm_commander is specific to Moveit Version 1 (and therefore ROS Noetic). An environment installed with Moveit + ROS Noetic is needed. For your convenience, please refer to the docker image from the [docker deployment](https://github.com/REF-RAS/docker_deployment) repository of the REF-RAS group. |
| 42 | + |
| 43 | +### Install Moveit (Non-Docker Method) |
| 44 | + |
| 45 | +The non-docker method assumes the starting point of having ROS Noetic installed. |
| 46 | + |
| 47 | +``` |
| 48 | +sudo apt-get update |
| 49 | +sudo apt-get install ros-noetic-moveit -y |
| 50 | +``` |
| 51 | + |
| 52 | +### Install Arm Commander |
| 53 | + |
| 54 | +Create a catkin workspace. |
| 55 | +``` |
| 56 | +mkdir -p ~/arm_commander_ws/src |
| 57 | +cd ~/arm_commander_ws/src |
| 58 | +``` |
| 59 | + |
| 60 | +Clone this repository to the `src` directory. |
| 61 | +``` |
| 62 | +git clone git@github.com:REF-RAS/arm_commander.git |
| 63 | +``` |
| 64 | + |
| 65 | +### Install a Robot Arm Model |
| 66 | + |
| 67 | +The demo program and the tutorial programs are designed to work with the dimension of a Panda. |
| 68 | + |
| 69 | +``` |
| 70 | +cd ~/arm_commander_ws/src |
| 71 | +git clone https://github.com/ros-planning/panda_moveit_config.git -b noetic-devel |
| 72 | +``` |
| 73 | + |
| 74 | +### Build the Packages |
| 75 | + |
| 76 | +``` |
| 77 | +rosdep install --from-paths src --ignore-src -r -y --rosdistro noetic |
| 78 | +source /opt/ros/noetic/setup.bash |
| 79 | +catkin_make -DPYTHON_EXECUTABLE=/usr/bin/python3 |
| 80 | +``` |
| 81 | + |
| 82 | +## Demonstration |
| 83 | + |
| 84 | +The demo program is located at `examples/commander_demo.py`. To look at the demo, fire up the Panda model on RViz. |
| 85 | +``` |
| 86 | +roslaunch panda_moveit_config demo.launch |
| 87 | +``` |
| 88 | +Then execute the demo program. |
| 89 | +``` |
| 90 | +cd ~/arm_commander_ws |
| 91 | +source devel/setup.bash |
| 92 | +/usr/bin/python3 ./src/arm_commander/arm_commander/commander_demo.py |
| 93 | +``` |
| 94 | + |
| 95 | +Video of the demo program |
| 96 | +[](https://www.youtube.com/watch?v=YleDRs649VA) |
| 97 | + |
| 98 | +## Tutorials |
| 99 | + |
| 100 | +A set of tutorials and example programs are provided in this package. |
| 101 | + |
| 102 | +- [Tutorial: Programming with the Arm Commander Package (Part 1)](docs/TUTORIAL_PART1.md) |
| 103 | +- [Tutorial: Programming with the Arm Commander Package (Part 2)](docs/TUTORIAL_PART2.md) |
| 104 | + |
| 105 | + |
| 106 | +## API Documentation |
| 107 | + |
| 108 | +API Documentation can be found in `/docs/build/html`. It will be available through Github Pages soon. |
| 109 | + |
| 110 | +<!-- [API Documentation](https://REF-RAS.github.io/robotarchi/) is available for reference. --> |
| 111 | + |
| 112 | +## Authors |
| 113 | + |
| 114 | +Dr Andrew Lui, Senior Research Engineer <br /> |
| 115 | +Dr Dasun Gunasinghe, Senior Research Engineer <br /> |
| 116 | +Robotics and Autonomous Systems, Research Engineering Facility <br /> |
| 117 | +Research Infrastructure <br /> |
| 118 | +Queensland University of Technology <br /> |
| 119 | + |
| 120 | +Latest update: Feb 2024 |
0 commit comments