diff --git a/README.md b/README.md index 3bdb9a4..a8d231f 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,44 @@ - - - - [![Contributors][contributors-shield]][contributors-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] -[![Unlicense License][license-shield]][license-url] +[![License][license-shield]][license-url] [![LinkedIn][linkedin-shield]][linkedin-url] +

+ Robotnik logo +

- -![Logo Robotnik](./docs/assets/img/LOGO%20BLANCO-ROJO.png) - -
-
-======= - -

robot_simulation

- -

- Simulation of Robotnik Automation robots in ROS2! -
- Explore the docs » -
-
- View Demo - · - Report Bug - · - Request Feature -

-
+

Robotnik - ROS 2 Simulation

+

+ ROS 2 simulation of Robotnik Automation robots. +
+ Browse the docs » +

+ View demo + · + Report bug + · + Request feature +

+---
Table of Contents
  1. - About The Project -
    2. -
  2. - Getting Started - -
    3. -
  3. - Usage - + About The Project
  4. - Custom Simulation + Quick start
    5. +
  5. Docker
  6. Roadmap
  7. Contributing
  8. License
    9. @@ -77,216 +46,64 @@
+--- +## Overview +Simulation-based environments and launch assets for Robotnik platforms on ROS 2. - -## About The Project - -[![Simulation View][product-screenshot]](https://github.com/RobotnikAutomation/robot_simulation) - -This package will combine the different Robotnik packages in ROS2 to simulate the robots in the different available platforms, as Gazebo Sim 8.9.0, etc. - -This README will guide you to the simulation usage and the custom simulations that you can build for your own projects. - - - -

(back to top)

- - -## Getting Started - -This package works with the different packages that Robotnik developed for the robots. You will need to install some of these packages first. - -### Prerequisites - -#### - Gazebo Sim 8.9.0 -#### - ROS2 Jazzy - -First, be sure that you have all the [Gazebo packages](https://gazebosim.org/docs/harmonic/install_ubuntu/) installed for ROS2. - - -```sh -sudo apt install ros-jazzy-ros-gz -``` - -### Installation - -Then, let's procede with the installation of the Robotnik packages. -First, create the workspace to work with: - -``` -mkdir -p ~/ros2_ws/src -cd ~/ros2_ws/src/ -``` -Then continue with the installation of packages. - -1. [robotnik_description](https://github.com/RobotnikAutomation/robotnik_description/tree/jazzy-devel) -2. [robotnik_sensors](https://github.com/RobotnikAutomation/robotnik_sensors/tree/jazzy-devel) -3. [robotnik_common](https://github.com/RobotnikAutomation/robotnik_common) -4. [robotnik_interfaces](https://github.com/RobotnikAutomation/robotnik_interfaces) -5. [ur_description](https://github.com/RobotnikAutomation/Universal_Robots_ROS2_Description/tree/fix/gazebo-control-jazzy#) -6. [robotnik_simulation](https://github.com/RobotnikAutomation/robotnik_simulation.git#) - - ```sh - git clone https://github.com/RobotnikAutomation/robotnik_description.git -b jazzy-devel - - git clone https://github.com/RobotnikAutomation/robotnik_sensors.git -b jazzy-devel - - git clone https://github.com/RobotnikAutomation/robotnik_common.git -b ros2-devel - - git clone https://github.com/RobotnikAutomation/robotnik_interfaces.git -b jazzy-devel - - git clone https://github.com/RobotnikAutomation/Universal_Robots_ROS2_Description.git -b fix/gazebo-control-jazzy - - git clone https://github.com/RobotnikAutomation/robotnik_simulation.git -b jazzy-devel - ``` +## Supported simulators -Install precompiled debs for simulation. Please, change directory to the root of the repository and run the following command: +- **Gazebo (Ignition/Gazebo Sim):** see [`robotnik_gazebo_ignition/README.md`](robotnik_gazebo_ignition/README.md) -```sh -sudo apt-get install -y ./debs/ros-${ROS_DISTRO}-*.deb -``` -Install missing dependencies with rosdep: -```sh -cd ~/ros2_ws -rosdep update -rosdep install --from-paths src --ignore-src -r -y -``` - -Finally, compile workspace: -``` -source /opt/ros/jazzy/setup.bash -cd ~/ros2_ws && colcon build -source install/setup.bash -``` - - -

(back to top)

- -## Docker -If you want to use Docker, you can use the docker-compose file that is in the root of the repository. This will create a container with all the dependencies installed and ready to use. - -To start the containers, run the following command: - -```sh -docker compose up -``` -This will build a robotnik_simulator image the first time you run it. After that, it will use the cached image. - -### Setup -You can configure the simulation based on docker images editing the environment in the env/robot.env file. You will need to uncomment the specific variables related to desired robot to simulate and comment or delete the others. - -Make sure that the environment variables (ROBOT, ROBOT_MODEL, HAS_ARM) are set correctly before running the containers. - -

(back to top)

- - -## Usage - -See each package for more details. - -- [robotnik_gazebo_ignition](robotnik_gazebo_ignition/README.md) - - -#### Enjoy! - -![rbvogui_gif](docs/assets/img/RBVogui_Docking.gif) - -

(back to top)

- - - -## Custom Simulation - -In case that the robot model that you want to simulate is not in robotnik_description package, or the world, or you want to use a different controller, you will have to create your own simulaiton files. - -This will guide you to create your custom simulation. - -### Custom Robot Model - -1. First, create your own package for the project. -2. In this package, create your URDF file. You can base in the [template file](robotnik_pkgs/robotnik_description/robots/robot_template.urdf.xacro) that are in robotnik_description package. -3. In the README of [robotnik_description](robotnik_pkgs/robotnik_description/README.md) there is a brief descripiton on how to create a robot. -4. On this file you can modify and add all the sensors, arms and any other component. -5. Then, launch the spawn_robot with the argument _robot_xacro_path_. - -### Custom Control - -In case that you want to modify the velocity, topics, frames and everything related to the control, you can find the files in [robotnik_gazebo_ignition/config folder](robotnik_gazebo_ignition/config/). -There is a file for each robot that you can modify. - -### Custom world - -To launch a custom file, you can use the _world_path_ argument that it's in the spawn_world launch. See Launch Gazebo. - - ## Roadmap -- [x] Add Gazebo Ignition -- [ ] Add more worlds -- [ ] Add multi robot support +* [x] Gazebo Sim support +* [ ] More worlds +* [ ] Multi-robot support -See the [open issues](https://github.com/RobotnikAutomation/robot_simulation/issues) for a full list of proposed features (and known issues). +See [open issues][issues-url] for planned work and known problems. -

(back to top)

- - - - ## Contributing -Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. +Contributions are welcome. -If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". -Don't forget to give the project a star! Thanks again! +1. Fork the repo +2. Create a feature branch: `git checkout -b feature/jazzy/AmazingFeature` +3. Commit: `git commit -m "Add AmazingFeature"` +4. Push: `git push origin feature/AmazingFeature` +5. Open a PR and describe your changes -1. Fork the Project -2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) -3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`) -4. Push to the Branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request -### Top contributors: +Special thanks to all contributors! - - contrib.rocks image + + Contributors graph -

(back to top)

- - - - ## License -Distributed under the Unlicense License. See `LICENSE.txt` for more information. - -

(back to top)

- - +Distributed under **BSD-3**. See [`LICENSE`][license-url]. - ## Contact -Project Link: [https://github.com/RobotnikAutomation](https://github.com/RobotnikAutomation) +Project link: [https://github.com/RobotnikAutomation/robotnik_simulation](https://github.com/RobotnikAutomation/robotnik_simulation) -

(back to top)

+--- + - - -[contributors-shield]: https://img.shields.io/github/contributors/RobotnikAutomation/robot_simulation.svg?style=for-the-badge -[contributors-url]: https://github.com/RobotnikAutomation/robot_simulation/graphs/contributors -[forks-shield]: https://img.shields.io/github/forks/RobotnikAutomation/robot_simulation.svg?style=for-the-badge -[forks-url]: https://github.com/RobotnikAutomation/robot_simulation/network/members -[stars-shield]: https://img.shields.io/github/stars/RobotnikAutomation/robot_simulation.svg?style=for-the-badge -[stars-url]: https://github.com/RobotnikAutomation/robot_simulation/stargazers -[issues-shield]: https://img.shields.io/github/issues/RobotnikAutomation/robot_simulation.svg?style=for-the-badge -[issues-url]: https://github.com/RobotnikAutomation/robot_simulation/issues -[license-shield]: https://img.shields.io/github/license/RobotnikAutomation/robot_simulation.svg?style=for-the-badge -[license-url]: https://github.com/RobotnikAutomation/robot_simulation/blob/master/LICENSE.txt +[contributors-shield]: https://img.shields.io/github/contributors/RobotnikAutomation/robotnik_simulation.svg?style=for-the-badge +[contributors-url]: https://github.com/RobotnikAutomation/robotnik_simulation/graphs/contributors +[forks-shield]: https://img.shields.io/github/forks/RobotnikAutomation/robotnik_simulation.svg?style=for-the-badge +[forks-url]: https://github.com/RobotnikAutomation/robotnik_simulation/network/members +[stars-shield]: https://img.shields.io/github/stars/RobotnikAutomation/robotnik_simulation.svg?style=for-the-badge +[stars-url]: https://github.com/RobotnikAutomation/robotnik_simulation/stargazers +[issues-shield]: https://img.shields.io/github/issues/RobotnikAutomation/robotnik_simulation.svg?style=for-the-badge +[issues-url]: https://github.com/RobotnikAutomation/robotnik_simulation/issues +[license-shield]: https://img.shields.io/github/license/RobotnikAutomation/robotnik_simulation.svg?style=for-the-badge +[license-url]: https://github.com/RobotnikAutomation/robotnik_simulation/blob/master/LICENSE [linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555 [linkedin-url]: https://www.linkedin.com/company/robotnik-automation/ [product-screenshot]: docs/assets/img/ignition_simulation_view.png diff --git a/img/LOGO BLANCO-ROJO.png b/docs/assets/img/LOGO BLANCO-ROJO.png similarity index 100% rename from img/LOGO BLANCO-ROJO.png rename to docs/assets/img/LOGO BLANCO-ROJO.png diff --git a/img/RBVogui_Docking.gif b/docs/assets/img/RBVogui_Docking.gif similarity index 100% rename from img/RBVogui_Docking.gif rename to docs/assets/img/RBVogui_Docking.gif diff --git a/img/ignition_simulation_view.png b/docs/assets/img/ignition_simulation_view.png similarity index 100% rename from img/ignition_simulation_view.png rename to docs/assets/img/ignition_simulation_view.png diff --git a/img/robotnik_simulation_structure.png b/docs/assets/img/robotnik_simulation_structure.png similarity index 100% rename from img/robotnik_simulation_structure.png rename to docs/assets/img/robotnik_simulation_structure.png diff --git a/img/simulation_view.png b/docs/assets/img/simulation_view.png similarity index 100% rename from img/simulation_view.png rename to docs/assets/img/simulation_view.png diff --git a/robotnik_gazebo_ignition/README.md b/robotnik_gazebo_ignition/README.md index 34cb60f..b1b6885 100644 --- a/robotnik_gazebo_ignition/README.md +++ b/robotnik_gazebo_ignition/README.md @@ -2,7 +2,59 @@ This package provides Gazebo Ignition plugins and resources for Robotnik robots. -## Launch Gazebo +## Installation + +1. Setup sources and keys. +```sh +sudo apt update +sudo apt-get install curl lsb-release gnupg +sudo curl https://packages.osrfoundation.org/gazebo.gpg --output /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null +``` + +2. Install Gazebo Harmonic. +```sh +sudo apt-get update +sudo apt-get install gz-harmonic +``` + +3. Install ROS 2 Jazzy and ROS-GZ bridge. +```sh +sudo apt install ros-jazzy-ros-gz +``` + +4. Set up workspace and install dependencies: + +```sh +# Workspace +mkdir -p ~/ros2_ws/src +cd ~/ros2_ws + +# Robotnik and related packages (ROS 2 Jazzy) +vcs import --input https://raw.githubusercontent.com/RobotnikAutomation/robotnik_simulation/jazzy-devel/robotnik_simulation.jazzy.repos src/ + +# Install prebuilt simulation debs from this repo (run at repo root) +cd ~/ros2_ws/src/robotnik/robotnik_simulation +sudo apt-get install -y ./debs/ros-${ROS_DISTRO}-*.deb + +# Resolve dependencies +source /opt/ros/jazzy/setup.bash +cd ~/ros2_ws +rosdep update +rosdep install --from-paths src --ignore-src -r -y +``` + +5. Build the workspace: + +```sh +cd ~/ros2_ws +colcon build --symlink-install +source install/setup.bash +``` + +## Usage + +### Launch Gazebo Fist step to use this simulation is launch world where the robot will be spawned. For example, to launch the `empty` world, use the following command: @@ -10,20 +62,18 @@ Fist step to use this simulation is launch world where the robot will be spawned ros2 launch robotnik_gazebo_ignition spawn_world.launch.py world:=empty ``` -Available worlds are located in the `worlds` folder of this package. You can replace `empty` with the name of any other world file (without the `.world` extension) to launch a different world. +Available worlds are located in the `worlds` folder of this package. You can replace `empty` with the name of any other world file (without the `.world` extension) to launch a different world. Also, you can enable or disable the Gazebo GUI by setting the `gui:=true` or `gui:=false` parameter. By default, the GUI is enabled. -Also, you can enable or disable the Gazebo GUI by setting the `gui:=true` or `gui:=false` parameter. By default, the GUI is enabled. - -## Spawn Robot +### Spawn Robot Use the launch file to insert a robot into the Gazebo (Ignition) world. -### Basic +#### Basic ```bash ros2 launch robotnik_gazebo_ignition spawn_robot.launch.py robot:=rbwatcher ``` -### Advanced +#### Advanced ```bash # Specific ID and pose ros2 launch robotnik_gazebo_ignition spawn_robot.launch.py robot_id:=robot_a robot:=rbwatcher robot_model:=rbwatcher x:=0.0 y:=0.0 z:=0.0 run_rviz:=true @@ -34,7 +84,7 @@ ros2 launch robotnik_gazebo_ignition spawn_robot.launch.py robot_id:=robot_a rob ros2 launch robotnik_gazebo_ignition spawn_robot.launch.py robot_id:= robot:= robot_model:= x:= y:= z:= ``` -### Parameters +#### Parameters | Name | Required | Purpose | Example | |---|---|---|---| | `robot_id` | no | Instance name for the spawned robot | `robot_a` | @@ -43,12 +93,12 @@ ros2 launch robotnik_gazebo_ignition spawn_robot.launch.py robot_id:=/models/` folder for available models. [Example models for rbwatcher](https://github.com/RobotnikAutomation/robotnik_description/tree/jazzy-devel/robots/rbwatcher). -### Notes +#### Notes - Use a unique `robot_id` when spawning multiple robots. ## Control the Robot @@ -69,3 +119,47 @@ ros2 run teleop_twist_keyboard teleop_twist_keyboard --ros-args -r cmd_vel:=/rob Make sure to replace `/robot/robotnik_base_control/cmd_vel` with the appropriate topic name based on the `robot_id` you used when spawning the robot. Also, you can use RViz plugin on the bottom right to control the robot by clicking on the arrows. + +## Enjoy + +Example of RBVogui executing docking procedure in Gazebo Ignition: + +![rbvogui_gif](../docs/assets/img/RBVogui_Docking.gif) + +## Custom robot model + +1. Create a new package for your project. +2. Create a URDF/XACRO. Use the template in `robotnik_description` as a starting point: + `robotnik_description/robots/robot_template.urdf.xacro` +3. See `robotnik_description/README.md` for a brief guide to composing robots. +4. Add sensors, arms, and components as needed. +5. Spawn with `robot_xacro_path`: + +```sh +ros2 launch robotnik_gazebo_ignition spawn_robot.launch.py robot_xacro_path:= +``` + +## Custom control + +Edit the robot-specific config files in: +`robotnik_gazebo_ignition/config/` +You can adjust topics, frames, velocity limits, and controllers. + +### Custom world + +Pass a custom world file via `world_path`: + +```sh +ros2 launch robotnik_gazebo_ignition spawn_world.launch.py world_path:= +``` + +## Docker +🚧 Work in progress. 🚧 + +Use the compose file in the repo root to run a preconfigured simulator container. + +```sh +docker compose up +``` + +> **Note**: The first time will take a while as it builds the image. Subsequent runs will be faster.