Skip to content

Commit 7ec46b1

Browse files
xela-95xela-95
authored
Merge pull request #216 from robotology/docs/move-erogcub-wiki-to-docs
Move erogcub wiki to docs
2 parents f8dda51 + a13f785 commit 7ec46b1

File tree

2 files changed

+191
-2
lines changed

2 files changed

+191
-2
lines changed

‎README.md

+6-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# gz-sim-yarp-plugins
22

3-
> [!WARNING]
3+
> [!WARNING]
44
> This repository contains a preliminary work in progress of integration of Modern Gazebo (gz) and YARP devices, a port of some functionalities of <https://github.com/robotology/gazebo-yarp-plugins> to Modern Gazebo. \
55
> The repo is working in progress, and public interfaces can change without warning.
66
@@ -50,7 +50,7 @@ There are two ways to specify the Yarp configuration of a plugin:
5050
Concerning `yarpConfigurationFile`, the preferred way to specify the path to the configuration file is by using [Gazebo URIs](https://gazebosim.org/api/common/6/classgz_1_1common_1_1URI.html). A URI has the following general scheme:
5151

5252
```
53-
scheme:[//authority]path[?query][#fragment]
53+
scheme:[//authority]path[?query][#fragment]
5454
```
5555

5656
For example, the configuration file for an IMU plugin can be specified as:
@@ -76,6 +76,10 @@ models
7676
> [!WARNING]
7777
> It is possible, but strongly discouraged, to specify the location of a `yarpConfigurationFile` using absolute paths or paths relative to the current working directory: the former approach is not portable, while the latter only works if the library is loaded from the directory it was intended to be loaded from.
7878
79+
### Applications
80+
81+
One project that is already using these plugins is [ergocub-software](https://github.com/icub-tech-iit/ergocub-software). Check out our [guide](docs/how-to-use-plugins-with-ergoCub.md) to learn how to perform simulations with it.
82+
7983
## Tools
8084

8185
This repository also contain some helper executable tools:

‎docs/how-to-use-plugins-with-ergoCub.md

+185
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# How to use `gz‐sim‐yarp‐plugins` with ergoCub
2+
3+
This document explains how to install and use ergoCub in the Modern Gazebo (gz-sim) simulator through `gz-sim-yarp-plugins`.
4+
5+
> [!NOTE]
6+
> For the time being this guide will provide operative instructions only for **Linux** distributions; instructions will also be provided for Windows and macOS in the future.
7+
8+
Note that some features of the ergocub model (mainly the depth sensors and the hands) are not supported, see <https://github.com/robotology/gz-sim-yarp-plugins/issues/137> for more details.
9+
10+
## Table of Contents
11+
12+
- [Installation](#installation)
13+
- [World creation](#world-creation)
14+
- [Run the simulation](#run-the-simulation)
15+
16+
## Installation
17+
18+
The easiest ways to setup an environment with everything we need is to follow only one of the following two options:
19+
20+
- [Creating a conda environment](#conda-environment)
21+
- [Using the robotology-superbuild](#installation-via-robotology-superbuild)
22+
23+
24+
### Conda environment
25+
26+
#### Install a conda distribution
27+
28+
If you do not have one, please install a conda distribution. We suggest to use the minimal [miniforge](https://github.com/conda-forge/miniforge) distribution, which uses conda-forge packages by default.
29+
30+
To install miniforge, please follow the instructions in [install-miniforge](https://github.com/robotology/robotology-superbuild/blob/master/doc/install-miniforge.md) documentation.
31+
32+
#### Create an environment
33+
34+
Then create the following environment with all the packages needed:
35+
36+
~~~bash
37+
conda create -n ergocub-gz libgz-sim-yarp-plugins ergocub-software
38+
~~~
39+
40+
Once you did this, you can activate it with:
41+
42+
~~~bash
43+
conda activate ergocub-gz
44+
~~~
45+
46+
### Installation via robotology-superbuild
47+
48+
[robotology-superbuild](https://github.com/robotology/robotology-superbuild) is a meta repository that is able to download and compile a plethora of software from the [robotology](https://github.com/robotology) organization.
49+
50+
First of all, we have to configure the superbuild such that it will download and install the software we need. It is possible to do this by enabling the appropriate options: in particular, we need to enable the `ROBOTOLOGY_ENABLE_CORE` profile with `ROBOTOLOGY_USES_GZ` option and disable the `ROBOTOLOGY_USES_GAZEBO` one.
51+
52+
Follow the [source installation guide](https://github.com/robotology/robotology-superbuild/tree/master?tab=readme-ov-file#source-installation) to install the required software.
53+
54+
## World creation
55+
56+
In Modern Gazebo the preferred way to initialize the simulator is by providing a **World**: an SDF file that contains everything we need to simulate our scenario.
57+
58+
In a directory of your choice, create a file called `ergocub-world.sdf` and fill it by copy-pasting the following content:
59+
60+
```xml
61+
<?xml version="1.0"?>
62+
63+
<sdf version="1.11">
64+
<world name="tutorial_controlboard">
65+
<physics name="1ms" type="ignored">
66+
<max_step_size>0.001</max_step_size>
67+
<real_time_factor>1.0</real_time_factor>
68+
</physics>
69+
<plugin
70+
filename="gz-sim-physics-system"
71+
name="gz::sim::systems::Physics">
72+
</plugin>
73+
<plugin
74+
filename="gz-sim-user-commands-system"
75+
name="gz::sim::systems::UserCommands">
76+
</plugin>
77+
<plugin
78+
filename="gz-sim-sensors-system"
79+
name="gz::sim::systems::Sensors">
80+
</plugin>
81+
<plugin
82+
filename="gz-sim-scene-broadcaster-system"
83+
name="gz::sim::systems::SceneBroadcaster">
84+
</plugin>
85+
<plugin
86+
filename="gz-sim-contact-system"
87+
name="gz::sim::systems::Contact">
88+
</plugin>
89+
90+
<!-- YARP CLOCK -->
91+
<plugin
92+
filename="gz-sim-yarp-clock-system"
93+
name="gzyarp::Clock">
94+
</plugin>
95+
96+
<light type="directional" name="sun">
97+
<cast_shadows>true</cast_shadows>
98+
<pose>0 0 10 0 0 0</pose>
99+
<diffuse>0.8 0.8 0.8 1</diffuse>
100+
<specular>0.2 0.2 0.2 1</specular>
101+
<attenuation>
102+
<range>1000</range>
103+
<constant>0.9</constant>
104+
<linear>0.01</linear>
105+
<quadratic>0.001</quadratic>
106+
</attenuation>
107+
<direction>-0.5 0.1 -0.9</direction>
108+
</light>
109+
110+
<model name="ground_plane">
111+
<static>true</static>
112+
<link name="link">
113+
<collision name="collision">
114+
<geometry>
115+
<plane>
116+
<normal>0 0 1</normal>
117+
<size>100 100</size>
118+
</plane>
119+
</geometry>
120+
</collision>
121+
<visual name="visual">
122+
<geometry>
123+
<plane>
124+
<normal>0 0 1</normal>
125+
<size>100 100</size>
126+
</plane>
127+
</geometry>
128+
<material>
129+
<ambient>0.8 0.8 0.8 1</ambient>
130+
<diffuse>0.8 0.8 0.8 1</diffuse>
131+
<specular>0.8 0.8 0.8 1</specular>
132+
</material>
133+
</visual>
134+
</link>
135+
</model>
136+
137+
<include>
138+
<uri>model://ergoCub/robots/ergoCubGazeboV1_1</uri>
139+
</include>
140+
141+
</world>
142+
</sdf>
143+
```
144+
145+
## Run the simulation
146+
147+
To run the simulation, open a terminal, navigate to the folder containing the world file (otherwise prefix the world filename with the path to it) and execute the following command:
148+
149+
```bash
150+
gz sim ergocub-world.sdf
151+
```
152+
153+
The simulator should open in a paused state with ergoCub in place. To start the simulation just click on the play button on the bottom left.
154+
155+
![image](https://github.com/robotology/gz-sim-yarp-plugins/assets/57228872/50b24661-5885-4314-be6e-2827d45e6908)
156+
157+
### Gazebo + YARP = ❤️
158+
159+
Things get interesting when `gz-sim-yarp-plugins` are used to connect the Gazebo simulation via to YARP devices able to interact with it.
160+
161+
For example, one could use [yarpmotorgui](https://yarp.it/latest//group__yarpmotorgui.html) to control the robot joints.
162+
163+
To do this, we need three terminals:
164+
165+
1. In the first one, start a `yarp server` by executing:
166+
167+
```bash
168+
yarp server
169+
```
170+
171+
2. In the second terminal, launch the simulator by executing:
172+
173+
```bash
174+
gz sim ergocub-world.sdf
175+
```
176+
177+
and start the simulation;
178+
3. In the third one launch the `yarpmotorgui` by executing:
179+
180+
```bash
181+
yarpmotorgui --robot ergocubSim
182+
```
183+
184+
Then click Ok on the panel asking which robot parts to control and finally you should be able to control each joint of the ergoCub robot:
185+
![image](https://github.com/robotology/gz-sim-yarp-plugins/assets/57228872/9247b83f-9333-4e44-bc5b-f65cbe592d89)

0 commit comments

Comments
 (0)