diff --git a/README.md b/README.md index 3cc72a5..a65a633 100644 --- a/README.md +++ b/README.md @@ -25,27 +25,26 @@ Among other things, you will find in this repository instructions on how to simu - **Controllable from any ROS 2.0 enabled computer**: [ORC](https://acutronicrobotics.com/products/orc/) is the ideal complement for MARA, but not mandatory. Choose yourself how you steer MARA. ## Table of Contents -* [MARA](#mara) - * [Features](#features) - * [Table of Contents](#table-of-contents) - * [Specifications](#specifications) - * [Packages](#packages) - * [Dependendent tools](#dependent-tools) - * [Create a ROS workspace](#create-a-ros-workspace) - * [Compile the ROS workspace](#compile-the-ros-workspace) - * [Set up MoveIt! in ROS 1 (optional)](#set-up-optional-moveit-in-ros-1) - * [MoveIt! with MARA in Gazebo](#usage-in-gazebo-simulator) - * [Terminal 1 (ROS 2.0):](#terminal-1-ros-2) - * [Terminal 2 (ROS):](#terminal-2-ros) - * [Terminal 3 (bridge):](#terminal-3-bridge) - * [Real robot](#usage-on-the-real-robot) - * [Terminal 1 (ROS 2):](#terminal-1-ros-2) - * [Terminal 2 (ROS):](#terminal-2-ros) - * [Terminal 3 (bridge):](#terminal-3-bridge) - * [Example code](#example-code) - * [Help](#help) - -### Specifications +* [Specifications](#specifications) +* [Packages](#packages) +* [Install](#install) + * [Dependendent tools](#dependent-tools) + * [Create a ROS 2.0 workspace](#create-a-ros-20-workspace) + * [Compile the ROS 2.0 workspace](#compile-the-ros-20-workspace) + * [MoveIt! in ROS1 (Optional)](#moveit-in-ros1-optional) +* [MoveIt!](#moveit) + * [MoveIt! with MARA - Simulation](#moveit-with-mara---simulation) + * [Terminal 1 (ROS 2.0):](#terminal-1-ros-20) + * [Terminal 2 (ROS):](#terminal-2-ros) + * [Terminal 3 (bridge):](#terminal-3-bridge) + * [MoveIt! with MARA - Real](#moveit-with-mara---real-robot) + * [Terminal 1 (ROS 2.0):](#terminal-1-ros-20) + * [Terminal 2 (ROS):](#terminal-2-ros) + * [Terminal 3 (bridge):](#terminal-3-bridge) +* [Examples](#examples) +* [Help](#help) + +## Specifications ![](https://acutronicrobotics.com/products/mara/images/xMARA_evolution_end.jpg.pagespeed.ic.dVNwzZ6-4i.webp) @@ -68,7 +67,7 @@ Among other things, you will find in this repository instructions on how to simu | Automatic updates | Over-the-Air (OTA) | | Datasheet | [Download datasheet](https://acutronicrobotics.com/products/mara/files/MARA_datasheet_v1.1.pdf) | -### Packages +## Packages @@ -81,15 +80,12 @@ Among other things, you will find in this repository instructions on how to simu - `mara_gazebo_plugins`: MARA Gazebo plugins for sensors and motors. - `mara_utils_scripts`: Some scripts to move the MARA or spawn the model. -### Gazebo, ROS 2.0, ROS and MoveIt! +## Install + +### ROS 2.0 and Gazebo - **Gazebo 9**: following the official instructions, [one-liner or step-by-step](http://gazebosim.org/tutorials?tut=install_ubuntu) - **ROS 2.0 Crystal**: following the official instructions, [source](https://index.ros.org/doc/ros2/Linux-Development-Setup/) or [debian packages](https://index.ros.org/doc/ros2/Linux-Install-Debians/). - ROS and MoveIt! are optional, required if you want to use `ìndividual_trajectories_bridge` to controll the MARA, which means using ROS Melodic with MoveIt through bridges. - -- **ROS melodic**: following the official instructions, [source](http://wiki.ros.org/melodic/Installation/Source) or [debian_packages](http://wiki.ros.org/melodic/Installation/Ubuntu). -- **MoveIt!**: `sudo apt install ros-melodic-moveit`. - ### Dependent tools ```sh @@ -123,11 +119,20 @@ Please make sure you are not sourcing ROS1 workspaces via `.bashrc` or any othe source /opt/ros/crystal/setup.bash cd ~/ros2_mara_ws && colcon build --merge-install --packages-skip individual_trajectories_bridge ``` +**Installation completed!** Now make sure you check the **[Examples](#examples)** section! Or follow the MoveIt! installation. + +### MoveIt! in ROS1 (Optional) +While MoveIt2! is not released (we are activelly developing), we provide the option to use ROS 1.0 MoveIt! through bridges. -### Set up MoveIt! in ROS 1 (optional) +Continue the following steps to complete the MoveIt! installation. +#### ROS and MoveIt! +ROS and MoveIt! are required if you want to use `ìndividual_trajectories_bridge` to control the MARA, which means using ROS Melodic with MoveIt through bridges. +- **ROS melodic**: following the official instructions, [source](http://wiki.ros.org/melodic/Installation/Source) or [debian_packages](http://wiki.ros.org/melodic/Installation/Ubuntu). +- **MoveIt!**: `sudo apt install ros-melodic-moveit`. -Optional `individual_trajectories_bridge`: +#### ROS - ROS 2.0 Bridge +Compile the trajectory bridge located in the workspace using ROS 1.0 as source. ```sh source /opt/ros/melodic/setup.bash @@ -135,7 +140,8 @@ cd ~/ros2_mara_ws && colcon build --merge-install --packages-select individual_t # Building ROS 1 creates conflicts with this ROS 2.0 workspace. Next line ensures the workspace is completely ROS 2.0. sed -i 's#/opt/ros/melodic#/opt/ros/crystal#g' ~/ros2_mara_ws/install/setup.bash ``` - +#### ROS Workspace +Compile the MARA_ROS1 packages. ```sh mkdir -p ~/ros_mara_ws/src cd ~/catkin_mara_ws/src @@ -143,10 +149,13 @@ git clone https://github.com/AcutronicRobotics/MARA_ROS1 cd ~/catkin_mara_ws/ catkin_make_isolated --install ``` +## MoveIt! +Motion planning, manipulation, 3D perception, kinematics, control and navigation through brigdes. -### Usage in Gazebo Simulator +### MoveIt! with MARA - Simulation +Plan trajectories in a virtual environment with Gazebo and MoveIt!. -#### Terminal 1 (ROS 2.0): +#### Terminal 1 (ROS 2.0) To spawn the simulated robot in Gazebo, you can choose one of the following ros2 launch files depending on the gripper that you want to use: @@ -155,7 +164,7 @@ source ~/ros2_mara_ws/install/setup.bash ros2 launch mara_gazebo mara.launch.py ``` -**Optionally**, you can launch one of these launch files, which correspond to different types of grippers. +**Optionally**, you can launch one of these launch files, which correspond to different grippers. ```sh ros2 launch mara_gazebo mara_gripper_140.launch.py @@ -163,7 +172,7 @@ ros2 launch mara_gazebo mara_gripper_85.launch.py ros2 launch mara_gazebo mara_gripper_hande.launch.py ``` -#### Terminal 2 (ROS): +#### Terminal 2 (ROS) ```sh source ~/catkin_mara_ws/devel/setup.bash @@ -173,7 +182,7 @@ roslaunch mara_bringup mara_bringup_moveit_actions.launch prefix:=140 & ``` -#### Terminal 3 (bridge): +#### Terminal 3 (bridge) ```sh source ~/catkin_mara_ws/devel/setup.bash source ~/ros2_mara_ws/install/setup.bash @@ -181,7 +190,8 @@ source ~/ros2_mara_ws/install/setup.bash ros2 run individual_trajectories_bridge individual_trajectories_bridge_actions -motors ~/ros2_mara_ws/src/mara/individual_trajectories_bridge/config/motors_actions.yaml ``` -### Usage on the real robot +### MoveIt! with MARA - Real Robot +Plan trajectories in a real environment with MoveIt!. #### Terminal 1 (ROS 2.0) ```sh @@ -213,11 +223,10 @@ export ROS_DOMAIN_ID=22 ros2 run individual_trajectories_bridge individual_trajectories_bridge_actions -motors ~/ros2_mara_ws/src/mara/individual_trajectories_bridge/config/motors_actions.yaml & ``` -### Examples - - - [mara_examples](https://github.com/AcutronicRobotics/mara_examples.git) +## Examples - [Documentation and tutorials](https://acutronicrobotics.com/docs/products/robots/mara) + - [mara_examples](https://github.com/AcutronicRobotics/mara_examples.git) -### Help +## Help If you need help with MARA's real robot or its simulation, feel free to raise an issue [here](https://github.com/AcutronicRobotics/MARA/issues).