diff --git a/garden/install_osx_src.md b/garden/install_osx_src.md index 23b62e14e..af52e3a29 100644 --- a/garden/install_osx_src.md +++ b/garden/install_osx_src.md @@ -83,7 +83,7 @@ Install all dependencies: Dependency for Ogre: ```bash -brew cask install xquartz +brew install xquartz --cask ``` General dependencies: diff --git a/harmonic/install_osx_src.md b/harmonic/install_osx_src.md index dc0c3f78b..1313e70bf 100644 --- a/harmonic/install_osx_src.md +++ b/harmonic/install_osx_src.md @@ -81,7 +81,7 @@ Install all dependencies: Dependency for Ogre: ```bash -brew cask install xquartz +brew install xquartz --cask ``` General dependencies: diff --git a/ionic/GUI_tutorial.md b/ionic/GUI_tutorial.md new file mode 100644 index 000000000..b0ab28460 --- /dev/null +++ b/ionic/GUI_tutorial.md @@ -0,0 +1,141 @@ +# Understanding the GUI + +This guide is an introduction to the Gazebo Graphical User Interface (GUI). + +## Prerequisites + +Before beginning, you should have [Ionic installed](/docs/ionic/install). +If you installed [from source](/docs/ionic/install) +you will need to [source](/docs/ionic/install_ubuntu_src#using-the-workspace) the workspace; +otherwise, you're good to go! + +Start by getting Gazebo up and running with a sample world: + +```bash +gz sim shapes.sdf +``` + +`gz sim` will run the latest version of Gazebo you have installed. +You can check if you have more than one version of Gazebo installed by running `gz sim --versions`. +For example, if you have Ionic (9.x.x), Harmonic (8.x.x), Garden (7.x.x), and Fortress (6.x.x) installed, `--versions` might return: + +```bash +9.0.0 +8.0.0 +7.0.0 +6.0.0 +``` + +To ensure you're working with Ionic, include the `--force-version` directive when starting up: + +```bash +gz sim --force-version 9.0.0 shapes.sdf +``` + +## GUI + +After running `shapes.sdf`, you should see the following screen: + +![shapes.sdf](tutorials/gui/shapes.png) + +The interface consists of several sections: + +### The Toolbars + +The toolbar along the top of the GUI contains two buttons, a file menu button (![menu button](tutorials/gui/menu_btn.png)) on the left, and a plugins button (![plugins button](tutorials/gui/plugins_btn.png)) on the right. +The file menu button allows you to save the world to a file, save and load interface configurations and customize interface style settings. +An interface configuration consists of the plugins you have loaded and the style settings in place. + +![toolbars](tutorials/gui/toolbars.png) + +The top left toolbar hanging below the file menu button contains shape buttons (sphere, box, cylinder, capsule and ellipsoid) as well as lighting controls (point, directional and spot). +The shape buttons allow you to directly insert a box, sphere, cylinder capsule, or ellipsoid model into the world. +Simply click on the shape you would like to insert, and place it into the world. +The shape will automatically snap onto the ground plane, and its properties will show up on the Entity Tree plugin window. + +The following image shows the scene and the Entity Tree after adding three shapes (`box_0`, `sphere_0` and `capsule_0`): + +![shape insertion](tutorials/gui/shape_insertion.png) + +The first five buttons on the second row are for `Transform Control`. +To learn more about this plugin, go to the `Transform Control` section of [Manipulating Models](manipulating_models) tutorial. + +The plugins button lists all the available plugins. +You can scroll down this list to see all the plugins that are available for your version of Gazebo. +When you select one, its interface will appear in the right panel. + +### The Right Panel + +The GUI contains two plugins that you see in the right panel upon starting. +At the top is the Component Inspector, followed by the Entity Tree. + +Everything in a simulation is considered an "entity." +In `shapes.sdf`, the entities listed are the ground plane, each of the shape models, and the sun. + +Entities in the Entity Tree can be expanded to reveal their links, as well as corresponding visuals and collisions, and joints, if they exist. + +You can select entities in the simulation by clicking on their names in the Entity Tree (or by clicking directly on the entity in the scene). +You can also hold `Ctrl` and click to select multiple. + +![Selecting multiple entities from the entity tree](tutorials/gui/entity_select.png) + +You can right-click on any plugin to open basic `Settings` or to `Close`. +You can (re)open plugins through the plugin menu. + +### The Scene + +Within the scene is where you'll interact with your simulated world and objects. + +Currently, you can navigate the scene with a mouse in several ways: + +* **Left-click**: select entity +* **Right-click**: opens menu with options: + * *Move to*: center the scene on an entity + * *Follow*: choose an entity for the view to stay centered on, whether it moves or you pan around + * *Remove*: erase the entity from the simulation + * *Copy*: copy the entity to the virtual clipboard + * *Paste*: paste the entity from the virtual clipboard creating a duplicate + * *View*: open a submenu with different options to visualize the simulation aspects of the entity like the collisions, the centre of mass, etc. +* **Left-click and drag**: pan around the scene +* **Right-click and drag**: zoom in and out +* **Scroll wheel forward/backward**: zoom in and out +* **Scroll wheel click and drag**: rotate the scene + * Or use **Shift key + left-click and drag** + +More complex methods for interacting with the entities within a scene will be explained in-depth in the coming tutorials. + +#### Grid Config + +The grid visibility in the scene can be adjusted by a plugin. +You can adjust features of the world's grid, including cell size, grid position, cell count, and even color. + +Open the Grid Config plugin by selecting it from the plugins button from the toolbar and selecting it from the dropdown list. +The plugin will now show up in the right panel (below the Entity Tree, scroll down if your screen did not display it). + +![Select Grid Config](tutorials/gui/grid_config.png) + +#### World Control + +Along the bottom edge of the scene, you'll notice several buttons: + +![Playback buttons](tutorials/gui/playback.png) + +From left to right, the options are `Play`, `Steps` and `RTF` (real time factor). + +Pressing `Play` will start the simulation. +You can use the same button to pause the simulation as well. + +The `Steps` button allows you to step through the simulation at the rate of a step size, or simulation iteration. +You can customize step size by hovering over the button. + +![hover steps](tutorials/gui/hover_steps.png) + +At the furthest right end of the scene, you can expand `RTF` to see not only the percentage value that compares real time with sim time, but also those individual values themselves, as well as iteration count. + +![RTF expanded](tutorials/gui/rtf_expanded.png) + +The function of the World Control options will become clearer once you begin manipulating entities. + +## Next Up + +Now that you're comfortable with Gazebo GUI navigation and terminology, let's start learning about more meaningful model interactions with the [Manipulating Models](manipulating_models) tutorial. diff --git a/ionic/Manipulating_models.md b/ionic/Manipulating_models.md new file mode 100644 index 000000000..379166842 --- /dev/null +++ b/ionic/Manipulating_models.md @@ -0,0 +1,156 @@ +# Manipulating Models + +This tutorial will walk you through using various plugins to assist model and scene manipulation in the Gazebo GUI. + +The Transform Control plugin is a combination of keybindings and transform control options: selection, translation, rotation and snapping. +This chart of [Gazebo's keyboard shortcuts](hotkeys) may be helpful for this tutorial. + +The View Angle plugin allows you to quickly and easily adjust the direction from which your scene faces an entity in the simulation. + +The Component Inspector plugin displays a variety of object attributes. + +The Align Tool aligns entities along or about a specific entity's bounding box. + +## Prerequisites + +Start by getting Gazebo up and running with a sample world: + +```bash +gz sim shapes.sdf +``` + +The previous tutorial, [Understanding the GUI](gui), explains the basics of navigating the Gazebo GUI. + +## Transform Control + +The top left toolbar contains controls for transforming. +Alternatively, the Transform Control plugin can be selected from the plugin drop-down menu. +The plugin will then appear at the bottom of the right panel. + +![Choosing Transform Control from the plugin list](img/plugins.png) + +### Select Mode + +Selection is the default mode. +You can click to select entities in the scene. +A selected entity will be highlighted in the Entity Tree to indicate its selection. +You can select multiple entities by holding `Ctrl` and clicking. + +![Selecting multiple entities](img/select_mult.png) + +Entities can't be manipulated in select mode. + +You can always return to selection mode from any other mode by pressing `Esc`. + +### Translate Mode + +Enter into translate mode by clicking the second icon from the left in the top left toolbar, the Transform Control plugin, or by hitting the keyboard shortcut: `T`. + +![Translate mode icon](img/translate_icon.png) + +Translate mode allows you to translate entities along the x, y and z axes. + +Click on any entity while in translate mode to see the arrows representing the axes you can move along. +The red arrow represents the x-axis, green the y-axis, and blue the z-axis. +Click and hold on any of the arrows while moving your mouse to move the entity in that direction. + +![Translate mode](img/translate.gif) + +Additionally, holding down any one of the `X`, `Y` or `Z` keys, or a combination of them, while clicking and dragging will constrain the model's movement along those axes, regardless of the direction you move your mouse or the axis arrow you select. + +### Rotate Mode + +Enter into rotate mode by clicking the third icon from the left in the top left toolbar, the Transform Control plugin, or by hitting the keyboard shortcut: `R`. + +![Rotate mode icon](img/rotate_icon.png) + +Rotate mode allows you to rotate entities around the roll, pitch and yaw axes of rotation. + +Click on any entity while in rotate mode to see the circles representing the axes you can rotate along. +The red circle represents roll, green is pitch, and blue is yaw. +Click and hold on any of the circles while moving your mouse to rotate the entity around that axis. + +![Rotate mode](img/rotate.gif) + +#### Align to World frame + +An entity's local axes can become unaligned from the world frame after rotation. +If you would like to translate along the world frame axis, simply hold `Shift`. + +This isn't a permanent realignment; you can move the entity while holding `Shift`, but once you let go it will return to it's local translational frame. + +![World frame alignment - translation](img/translate_worldframe.gif) + +The same can be done for an entity's local rotational frame. + +![World frame alignment - rotation](img/rotate_worldframe.gif) + +### Enter Custom Snap Values + +When translating or rotating, you can "snap" an entity's movement to preset increments by holding `Ctrl` and then clicking and dragging. +By default, the snap value is 1 meter for translation and 45° for rotation. + +Translational snaps will snap relative to the world frame, whereas rotational snaps will snap relative to the object's current orientation. + +![Snap rotation](img/snap.gif) + +You can customize snap values by clicking on the snap icon ![Snap icon](img/snap_icon.png) in the top left toolbar or the Transform Control plugin. + +![Custom snap values](img/custom_snap.png) + +Try holding `Shift` and `Ctrl` simultaneously to snap a model along the world frame is if isn't already aligned. + +## Component Inspector + +With this plugin, you can select an entity to display some of its attributes, including its pose, whether or not wind is acting on it, whether or not it's static, and more. +The plugin also displays the gravitational and magnetic fields of your world. + +Expanding the `Pose` attribute will show the coordinate values for a selected object. +The values will update as the object is moved around (translated or rotated) while the simulation is running. + +![Updating pose values](img/pose_value.gif) + +You can also pause the plugin so an object's pose values don't update in the inspector while the simulation is playing. + +Additionally, the Component Inspector can be locked on one object so you can open another Component Inspector to simultaneously observe another object. + +![Two Component Inspectors](img/pose2.gif) + +## View Angle + +Select the View Angle from the plugins drop-down menu. + +You can choose which angle you want to view the scene from, relative to a selected entity or the world frame if no entity is selected. +The home button will return you to the original view pose from when the scene was loaded. + +You can also select multiple entities to face simultaneously from each view angle. + +![View angle for multiple entities](img/view.gif) + +## Align Tool + +Select the Align Tool from the plugins drop-down menu. + +The Align Tool aligns a model along or about the bounding box of another model, or any other entity that has a bounding box, like a link for example. +It can't, however, align a child link or anything other than the top-level model. + +With `Relative to First` selected, select two models using `Ctrl` + click (be sure you are in select mode) and then hover over any of the Align Tool +buttons to see a preview of the second model aligning to the first along its x, y or z axis. +Hovering over the buttons for each axis will show a preview of where the model would end up if aligned along that axis while clicking will confirm that +specific alignment. + +![Align](img/align.gif) + +The Reverse button will enable alignment about the outer boundary of a model's bounding box. This feature is helpful for placing objects exactly next to each +other. Notice the difference in alignment when the Reverse button is pressed in the gif below. + +![Align Reverse](img/align_reverse.gif) + +You can align more than two models as well, simply select more models with `Ctrl` + click. You can select `First` or `Last` in the `Relative to:` drop down menu to +choose which entity to align to. + +## Next Up + +So far you've interacted with basic shape models to learn about Gazebo's GUI. +It's also possible to insert more detailed models from [Gazebo Fuel](https://app.gazebosim.org) into the GUI. +Check out the [Model Insertion from Fuel](fuel_insert) tutorial to learn how. diff --git a/ionic/Model_insertion_fuel.md b/ionic/Model_insertion_fuel.md new file mode 100644 index 000000000..7cfc5fc25 --- /dev/null +++ b/ionic/Model_insertion_fuel.md @@ -0,0 +1,84 @@ +# Model Insertion from Fuel + +Gazebo Fuel hosts hundreds of models that can easily be added to a world running in the Gazebo GUI. + + +## Prerequisites + +Start by getting Gazebo up and running with an empty world: + +```bash +gz sim empty.sdf +``` + +The previous tutorial, [Manipulating Models](Manipulating_models.md), shows you how to interact with models, which might be helpful once you add some Fuel models to your world. + +## Choose a Model + +Fuel's model collection is at [app.gazebosim.org/fuel/models](https://app.gazebosim.org/fuel/models). +Head over and browse the available content. + +![Fuel models preview](tutorials/fuel_insert/fuel.png) + +Click on any one of the thumbnails, or use the search bar. +For example, let's find the [Mine Cart Engine](https://app.gazebosim.org/OpenRobotics/fuel/models/Mine%20Cart%20Engine). + +![Vent](tutorials/fuel_insert/mine_cart_engine_detail.png) + +Note that some of the model files are quite large and may take some time to download into your world. +Check that the file size on the right is reasonable for your application before moving on. + +## Spawn a Model + +There are a few different ways to spawn a model into the simulation. + +1. **Spawn from 'Fuel Resource' using the Resource Spawner plugin.** + + Select the Resource Spawner plugin from the plugin menu (top right corner). + The plugin will appear in the right panel, you might need to scroll down to be able to see the plugin. + Wait until the resource are loaded under the 'Fuel Resource' panel. + Select a resource owner (e.g. openrobotics), you can now search for the model name in the right panel. + Click on the cloud icon to download the model. + When the model has been downloaded, you can click on the model and insert it into your simulation scene. + + ![Resource Spawner - Fuel Resource](tutorials/fuel_insert/resource_spawner_cloud.png) + + +2. **Download model files from Fuel and spawn from local sources using the Resource Spawner plugin.** + + - Download the model files from [app.gazebosim.org/fuel/models](https://app.gazebosim.org/fuel/models). + - Extract the files and places them under your local model directory (e.g. `~/my-local-models/model-name`). + The folder should contain `materials`, `meshes` as well as the `model.config` and the `model.sdf` files. + - Add your model directory as a resource with `export GZ_SIM_RESOURCE_PATH=~/my-local/models/` + - Open the Gazebo Simulator and add the Resource Spawner Plugin, the model should now show up under your local resources. + + ![Resource Spawner - Fuel Resource](tutorials/fuel_insert/resource_spawner_local.png) + +3. **Copying the SDF snippet and adding it to your custom world SDF file.** + + With the `<>` button you can directly copy a SDF snippet to paste into your world SDF file. + The SDF snippet will look something like this: + + ``` + + + https://fuel.gazebosim.org/1.0/OpenRobotics/models/Mine Cart Engine + + + ``` + + You can then add that snippet to a world SDF file as shown in the animation below. + More information on how to build your own world SDF files can be found in the tutorial on [SDF Worlds](sdf_worlds). + + ![spawn](tutorials/fuel_insert/husky.gif) + +4. **Downloading the code to permanently add a Fuel model to your custum SDF file.** + + If you prefer to add a Fuel model permanently to an `sdf` file, you can just as easily download the code by clicking the download-arrow icon to the right of the model's image. + Kook at the tutorial on [SDF Worlds](sdf_worlds) for more information on how to construct a custom world SDF file. + +Now you can add more models, or even load in any one of the plugins you learned about to interact with the model the same way you could with the shapes in the previous tutorial. + +## Next Up + +Now that you know how to add models hosted on Gazebo Fuel, it is time to learn how to [Build Your Own Robot](building_robot). diff --git a/ionic/actors.md b/ionic/actors.md new file mode 100644 index 000000000..e0774b76b --- /dev/null +++ b/ionic/actors.md @@ -0,0 +1,159 @@ +# Actors + +In this tutorial we will learn how to add `actors` to our world and how to create a scripted animation. +You can find the final world of this tutorial [here](https://github.com/gazebosim/docs/blob/master/ionic/tutorials/actors/actor_demo.sdf). + +Animations are very useful if we want to have entities following a predefined path in simulation without being affected by the physics. This means that they won't fall due to gravity or collide with other objects. They will however, have a 3D visualization which can be seen by RGB cameras, and 3D meshes which can be detected by GPU based sensors. The tutorial explains how to create open-loop trajectories which don't interact with the rest of the simulation. + +## Actors + +In Gazebo Sim, an animated model is called an `actor`. + +There are two types of animations which can be used separately or combined together: + +* Skeleton animation, which is relative motion between links in one model: + +![skeleton_movement](tutorials/actors/skeleton_movement.gif) + +* Trajectory animation, which carries all of the actor's links around the world as one group along a trajectory: + +![trajectory_movement](tutorials/actors/trajectory_movement.gif) + +* Combined, to achieve a skeleton animation which moves in the world: + +![combined_movement](tutorials/actors/combined_movement.gif) + +Actors have the following properties: + +* No forces are applied on them, be it from gravity or contact or anything else +* Actors support skeleton animation imported from COLLADA (.dae) and BVH (.bvh) files. +* Actors can have trajectories scripted directly in SDF. + +You can check out the full specification for the `` SDF element +[here](http://sdformat.org/spec?ver=1.8&elem=actor). + +## Skeleton + +Gazebo Sim supports two different skeleton animation file formats: COLLADA (.dae) and Biovision Hierarchy (.bvh). + +Open any world, [empty.sdf](https://raw.githubusercontent.com/gazebosim/gz-sim/main/examples/worlds/empty.sdf) world +for example, and add an actor called `actor_walking` as follows: + +```xml + + + https://fuel.gazebosim.org/1.0/Mingfei/models/actor/tip/files/meshes/walk.dae + 1.0 + + + https://fuel.gazebosim.org/1.0/Mingfei/models/actor/tip/files/meshes/walk.dae + true + + +``` + +### Skin + +In the `` tag we just loaded a COLLADA file `walk.dae` which specifies how our actor will look. When a COLLADA file is used within the `` tags its animation is loaded. The `` scales the skin's size. + +### Animation + +In the `` tag we specify how our actor will move using the `` tag. `` is used to interpolate the animation within waypoints while following trajectory. Setting it as true allows for a more realistic and smooth animation. We can combine different skins with different animations as long as they have compatible skeletons. Now run the world and we should see our model moving. + +![actor loaded with skin tag](tutorials/actors/actor_skin.gif) + +**Note**: You can find many actors and models on [Gazebo Fuel](https://app.gazebosim.org/fuel). + +## Scripted trajectory + +This is the high level animation of actors, which consists of specifying a series of poses to be reached at specific times. Gazebo Sim takes care of interpolating the motion between them so the movement is fluid. + +Animations that have displacement on the X axis, like `walk.dae`, will have the skeleton animated while following a trajectory. But for animations that don't, such as `talk_b.dae`, their skeletons won't move if there's a trajectory. + +We can make our actor follow the specified trajectory forever and start playing as soon as the world is loaded as follows: + +```xml + +``` + +Within the `` tag we define a series of waypoints which our actor will follow. The `` has three attributes: `id`, `type`, and `tension`. The `type` should have the same name as the value specified in `name` attribute of the `` tag. Therefore, in this case it is specified as `walk`. The `tension` parameter is used to control how closely the trajectory will stick to the given waypoints. The default `tension` value is zero, which equates to a Catmull-Rom spline, which may cause the animation to overshoot waypoints. A `tension` value of one will cause the animation to stick to the waypoints. The `tension` value should be in the range 0 to 1. + +Under the `trajectory` tag we define the following: + +* `waypoint`: There can be any number of waypoints in a trajectory. Each waypoint consists of a time and a pose: + * `time`: The time in seconds, counted from the beginning of the script, when the pose should be reached. + * `pose`: The pose which should be reached with respect to the initial actor pose. + +Run the world and we should see our actor moving in a square following the waypoints. + +![actor_moving around](tutorials/actors/actor_demo.gif) + +**Notes**: + +* The order in which waypoints are defined is not important, they will follow the given times. +* The trajectory is smoothed as a whole. This means that you'll get a fluid motion, but the exact poses contained in the waypoints might not be reached. + +Now it's your turn! Try out different trajectory descriptions. + +## Video walk-through + +A video walk-through of this tutorial is available from our YouTube channel: [Gazebo tutorials: Animated human actors](https://youtu.be/1VZexw67a2o) + + diff --git a/ionic/building_robot.md b/ionic/building_robot.md new file mode 100644 index 000000000..2b79bd66e --- /dev/null +++ b/ionic/building_robot.md @@ -0,0 +1,447 @@ +# Building your own robot + +In this tutorial we will learn how to build our own robot in SDFormat. We will build a simple two wheeled robot. + + You can find the finished SDF file for the tutorial [here](https://github.com/gazebosim/docs/blob/master/ionic/tutorials/building_robot/building_robot.sdf). + +## What is SDF + +[SDFormat](http://sdformat.org/) (Simulation Description Format), sometimes abbreviated as SDF, is an XML format that describes objects and environments for robot simulators, visualization, and control. + +## Building a world + +We will start by building a simple world and then build our robot in it. Open a new file called `building_robot.sdf` and copy the following code to it. + +```xml + + + + + 0.001 + 1.0 + + + + + + + + + + true + 0 0 10 0 0 0 + 0.8 0.8 0.8 1 + 0.2 0.2 0.2 1 + + 1000 + 0.9 + 0.01 + 0.001 + + -0.5 0.1 -0.9 + + + + true + + + + + 0 0 1 + + + + + + + 0 0 1 + 100 100 + + + + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + + + + + + +``` + +Save the file, navigate to the directory where you saved the file and launch the simulator: + +`gz sim building_robot.sdf` + +**Note**: You can name your file any name and save it anywhere on your computer. + +You should see an empty world with just a ground plane and a sun light. Check [World demo](sdf_worlds) to learn how to build your own world. + +## Building a model + +Under the `` tag we will add our robot model as follows: + +### Defining the model + +```xml + + 0 0 0 0 0 0 +``` + +Here we define the name of our model `vehicle_blue`, which should be a unique name among its siblings (other tags or models on the same level). +Each model may have one link designated as the `canonical_link`, the implicit frame of the model is attached to this link. If not defined, the first `` will be chosen as the canonical link. +The `` tag is used to define the position and orientation of our model and the `relative_to` attribute is used to define the pose of the model relative to any other frame. +If `relative_to` is not defined, the model's `` will be relative to the world. + +Let's make our pose relative to the `world`. The values inside the pose tag are as follows: `X Y Z R P Y`, where the `X Y Z` represent the position of the frame and `R P Y` represent the orientation in roll pitch yaw. +We set them to zeros which makes the two frames (the model and the world) identical. + +## Links forming our robot + +Every model is a group of `links` (can be just one link) connected together with `joints`. + +### Chassis + +```xml + + 0.5 0 0.4 0 0 0 +``` + +We define the first link, the `chassis` of our car and it's pose relative to the `model`. + +#### Inertial properties + +```xml + + 1.14395 + + 0.095329 + 0 + 0 + 0.381317 + 0 + 0.476646 + + +``` + +Here we define the inertial properties of the chassis like the `` and the `` matrix. The values of the inertia matrix for primitive shapes can be calculated using this [tool](https://amesweb.info/inertia/mass-moment-of-inertia-calculator.aspx). + +#### Visual and collision + +```xml + + + + 2.0 1.0 0.5 + + + + + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + + +``` + +As the name suggests, the `` tag is responsible for how our link will look. +We define the shape of our link inside the `` tag as a `` (cuboid) and then specify the three dimensions (in meters) of this box inside the `` tag. +Then, inside the `` tag we define the material of our link. +Here we defined the ``, `` and `` colors in a set of four numbers red/green/blue/alpha each in range [0, 1]. + +```xml + + + + 2.0 1.0 0.5 + + + + + +``` + +The `` tag defines the collision properties of the link, how our link will react with other objects and the effect of the physics engine on it. + +**Note**: `` can be different from the visual properties, for example, simpler collision models are often used to reduce computation time. + +After copying all the parts above into the world file in order, run the world again: + +`gz sim building_robot.sdf` + +Our model should look like this: + +![car chassis](tutorials/building_robot/chassis.png) + +In the top left toolbar, click the Translate icon, then select your model. +You should see three axes like this: + +![model_axis](tutorials/building_robot/model_axis.png) + +These are the axes of our model where red is the x-axis, green is the y-axis and blue is the z-axis. + +### Left wheel + +Let's add wheels to our robot. The following code goes after the `` tag and before the `` tag. All the links and joints belonging to the same model should be defined before the ``. + +```xml + + -0.5 0.6 0 -1.5707 0 0 + + 1 + + 0.043333 + 0 + 0 + 0.043333 + 0 + 0.08 + + +``` + +We defined the name of our link `left_wheel` and then defined its `` `relative_to` the `chassis` link. +The wheel needed to be placed on the left to the back of the `chassis` so that's why we chose the values for `pose` as `-0.5 0.6 0`. +Also, our wheel is a cylinder, but on its side. +That's why we defined the orientation value as `-1.5707 0 0` which is a `-90` degree rotation around the x-axis (the angles are in radians). +Then we defined the `inertial` properties of the wheel, the `mass` and the `inertia` matrix. + +#### Visualization and Collision + +```xml + + + + 0.4 + 0.2 + + + + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + + + + + + 0.4 + 0.2 + + + + +``` + +The `` and the `` properties are similar to the previous link, except the shape of our link has the shape of `` that requires two attributes: the `` and the `` of the cylinder. +Save the file and run the world again, our model should look like this: + +![this](tutorials/building_robot/car_left_wheel.png) + +### Right wheel + +```xml + + + -0.5 -0.6 0 -1.5707 0 0 + + 1 + + 0.043333 + 0 + 0 + 0.043333 + 0 + 0.08 + + + + + + 0.4 + 0.2 + + + + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + + + + + + 0.4 + 0.2 + + + + +``` + +The right wheel is similar to the left wheel except for its position. + +### Defining an arbitrary frame + +As of SDF 1.7 (Fortress uses SDF 1.8), we can define arbitrary frames. It takes two attributes: + +* `name`: the name of the frame +* `attached_to`: the name of the frame or the link to which this frame is attached. + +Let's add a frame for our caster wheel as follows: + +```xml + + 0.8 0 -0.2 0 0 0 + +``` + +We gave our frame name `caster_frame` and attached it to the `chassis` link, then the `` tag to define the position and orientation of the frame. +We didn't use the `relative_to` attribute so the pose is with respect to the frame named in the `attached_to` attribute, `chassis` in our case. + +### Caster wheel + +```xml + + + + + 1 + + 0.016 + 0 + 0 + 0.016 + 0 + 0.016 + + + + + + 0.2 + + + + 0.0 1 0.0 1 + 0.0 1 0.0 1 + 0.0 1 0.0 1 + + + + + + 0.2 + + + + +``` + +Our last link is the `caster` and its pose is with respect to the frame `caster_frame` we defined above. +As you could notice we closed the `pose` tag without defining the position or the orientation; in this case the pose of the link is the same as (identity) the frame in `relative_to`. + +In the `` and `` tags we defined a different shape `` which requires the `` of the sphere. + +### Connecting links together (joints) + +We need to connect these links together; here comes the job of the `` tag. +The joint tag connects two links together and defines how they will move with respect to each other. +Inside the `` tag we need to define the two links to connect and their relations (way of movement). + +#### Left wheel joint + +```xml + + +``` + +Our first joint is the `left_wheel_joint`. +It takes two attributes: the name `name='left_wheel_joint'` and the type `type='revolute'`. +the `revolute` type gives 1 rotational degree of freedom with joint limits. +The pose of the joint is the same as the child link frame, which is the `left_wheel` frame. + +```xml + chassis + left_wheel +``` + +Every joint connects two links (bodies) together. +Here we connect the `chassis` with the `left_wheel`. +`chassis` is the parent link and `left_wheel` is the child link. + +```xml + + 0 1 0 + + -1.79769e+308 + 1.79769e+308 + + + +``` + +Here we define the axis of rotation. +The axis of rotation can be any frame, not just the `parent` or the `child` link. +We chose the y-axis with respect to the `model` frame so we put `1` in the y element and zeros in the others. +For the revolute joint we need to define the `` of our rotation angle in the `` and `` tags. + +**Note**: The angles are in radians. + +#### Right wheel joint + +The `right_wheel_joint` is very similar except for the pose of the joint. +This joint connects the `right_wheel` with the `chassis`. + +```xml + + + chassis + right_wheel + + 0 1 0 + + -1.79769e+308 + 1.79769e+308 + + + +``` + +#### Caster wheel joint + +For the caster we need a different type of joint (connection). +We used `type='ball'` which gives 3 rotational degrees of freedom. + +```xml + + chassis + caster + +``` + +## Conclusion + +Run the world: + +`gz sim building_robot.sdf` + +It should look like this: + +![two_wheeled_robot](tutorials/building_robot/two_wheeled_robot.png) + +Hurray! We build our first robot. You can learn more details about SDFormat tags [here](http://sdformat.org/spec). In the next [tutorial](moving_robot) we will learn how to move our robot around. + +## Video walk-through + +A video walk-through of this tutorial is available from our YouTube channel: [Gazebo tutorials: Building a robot](https://youtu.be/Z-gjU0KAjiw). + + diff --git a/ionic/comparison.md b/ionic/comparison.md new file mode 100644 index 000000000..2333e623f --- /dev/null +++ b/ionic/comparison.md @@ -0,0 +1,328 @@ +# Feature comparison + +A list of features present in [Gazebo-classic](https://github.com/osrf/gazebo/) +version 11 and the status of their migration to +[Gazebo Ionic](https://gazebosim.org/). + +All the issues below are labeled with +[close the gap](https://github.com/search?q=org%3Agazebosim+label%3A%22close+the+gap%22&type=Issues) +on GitHub. + +## Sensors + +Sensor | Gazebo-classic | Gazebo Sim +-- | -- | -- +Air pressure | ✕ | ✓ +Altimeter | ✓ | ✓ +Bounding Box camera | ✕ | ✓ +Camera | ✓ | ✓ +Contact sensor | ✓ | ✓ +Depth camera | ✓ | ✓ +Doppler Velocity Log (DVL) | ✕ | ✓ +Force-torque | ✓ | ✓ +GPS / NavSat | ✓ | ✓ +GPU Ray | ✓ | ✓ Renamed to GPU Lidar +IMU | ✓ | ✓ +Logical audio sensor | ✕ | ✓ +Logical camera | ✓ | ✓ +Magnetometer | ✓ | ✓ +Multi-camera | ✓ | ✕ Use individual cameras with same update rate +Optical tactile sensor | ✕ | ✓ +Ray | ✓ | [Issue](https://github.com/gazebosim/gz-sensors/issues/26) +RFID sensor and tag | ✓ | [Issue](https://github.com/gazebosim/gz-sensors/issues/27) +RGBD camera | ✕ | ✓ +Segmentation camera | ✕ | ✓ +Sonar | ✓ | [Issue](https://github.com/gazebosim/gz-sensors/issues/19) +Thermal camera | ✕ | ✓ +Triggered camera | ✕ | ✓ +Wide-angle camera | ✓ | ✓ +Wireless | ✓ | [Issue](https://github.com/gazebosim/gz-sensors/issues/28) + +Sensor features | Gazebo-classic | Gazebo Sim +-- | -- | -- +Custom update rate | ✓ | ✓ +Gaussian noise | ✓ | ✓ +Custom sensors | ✓ | ✓ +Laser retroreflection | ✓ | ✓ +Camera distortion | ✓ | ✓ +Performance metrics | ✓ | ✓ + +## SDF Features + +Feature | Gazebo-classic | Gazebo Sim +-- | -- | -- +SDF frame semantics |✓| ✓ +SDF parametrization | ✕ | [✓](http://sdformat.org/tutorials?tut=param_passing_proposal) +Load models from local files | ✓ | [✓](https://gazebosim.org/api/gazebo/6.6/resources.html) +Closed kinematic chains | ✓ | [Issue](https://github.com/gazebosim/gz-physics/issues/25) +Nested models | ✓ | ✓ +Populations | ✓ | [Issue](https://github.com/gazebosim/gz-sim/issues/240) +Actors | ✓ | ✓ +Markers | ✓ | ✓ +Heightmaps | ✓ | ✓ +DEM (Digital Elevation Models) | ✓ | ✓ +Polylines | ✓ | ✓ +World plugins | ✓ | ✓ Now called System plugin +Model plugins | ✓ | ✓ Now called System plugin +Sensor plugins | ✓ | ✓ Now called System plugin +Visual plugins | ✓ | ✓ +GUI plugins | ✓ | ✓ Gazebo GUI plugins and Gazebo GUI systems +System plugins | ✓ | ✓ Through Gazebo Launch +SDF python bindings | x | ✓ | In sdformat13 +SDF <-> Mujoco MJCF | x | ✓ | In sdformat13, [documentation](https://github.com/gazebosim/gz-mujoco/blob/main/sdformat_mjcf/README.md) + +## Plugins + +### Model plugins + +Plugin | Gazebo-classic | Gazebo Sim +-- | -- | -- +AckermannSteering | ✕ | ✓ +ActorPlugin | ✓ | ✕ See [FollowActor](https://github.com/gazebosim/gz-sim/blob/main/src/systems/follow_actor/FollowActor.hh) for a demo of Actor APIs +ActuatorPlugin | ✓ | +ArduCopterPlugin | ✓ | +AttachLightPlugin | ✓ | ✕ Does not apply, use SDF +Breadcrumbs | ✕ | ✓ +BuoyancyPlugin | ✓ | [✓](https://github.com/gazebosim/gz-sim/blob/ign-gazebo6/examples/worlds/buoyancy.sdf) +CartDemoPlugin | ✓ | ✕ +CessnaPlugin | ✓ | ✕ +DetachableJoint | ✕ | ✓ +DiffDrivePlugin | ✓ | ✓ +ElevatorPlugin | ✓ | ✓ +FlashLightPlugin | ✓ | +FollowerPlugin | ✓ | +GimbalSmall2dPlugin | ✓ | +GravityCompensationPlugin | ✓ | +HarnessPlugin | ✓ | +HydraDemoPlugin | ✓ | +InitialVelocityPlugin | ✓ | ✓ (use VelocityControl or JointController) +JointControlPlugin | ✓ (force / pos / vel, from SDF) | ✓ (vel, from msg) +JointStatePublisher | ✕ | ✓ +JointTrajectoryPlugin | ✓ | ✓ +KeysToCmdVelPlugin | ✓ | Use `gz::gui::KeyPublisher` with `gz::gazebo::systems::TriggeredPublisher` +KeysToJointsPlugin | ✓ | Use `gz::gui::KeyPublisher` with `gz::gazebo::systems::TriggeredPublisher` +LedPlugin | ✓ | +LiftDragPlugin | ✓ | ✓ +LinearBatteryConsumerPlugin | ✓ | ✓ +LinearBatteryPlugin | ✓ | ✓ +LinkPlot3DPlugin | ✓ | ✓ (renamed to Plot3D) +MecanumDrive | ✕ | ✓ +MudPlugin | ✓ | +MulticopterMotorModel | ✕ | ✓ +OdometryPublisherPlugin | ✕ | ✓ +PlaneDemoPlugin | ✓ | +PosePublisher | ✕ | ✓ +RandomVelocityPlugin | ✓ | +RegionEventBoxPlugin | ✓ | +SimpleTrackedVehiclePlugin | ✓ | ✓ +SkidSteerDrivePlugin | ✓ | ✓ +SphereAtlasDemoPlugin | ✓ | ✕ +TouchPlugin | ✓ | ✓ +TrackedVehiclePlugin | ✓ | ✓ +VariableGearboxPlugin | ✓ | +VehiclePlugin | ✓ | +WheelSlipPlugin | ✓ | ✓ +WheelTrackedVehiclePlugin | ✓ | ✓ +KineticEnergyMonitor | ✕ | ✓ +Buoyancy engine | ✕ | ✓ + +### World plugins + +Plugin | Gazebo-classic | Gazebo Sim +-- | -- | -- +ArrangePlugin | ✓ | +ContainPlugin | ✓ | Partial port, [Issue](https://github.com/gazebosim/gz-sim/issues/162) +HydraPlugin | ✓ | +JoyPlugin | ✓ | ✓ Migrated as an Gazebo Launch plugin +MisalignmentPlugin | ✓ | +RubblePlugin | ✓ | +StaticMapPlugin | ✓ | +TransporterPlugin | ✓ | +WindPlugin | ✓ | ✓ + +### Sensor plugins + +Plugin | Gazebo-classic | Gazebo Sim +-- | -- | -- +BreakableJointPlugin | ✓ | +CameraPlugin | ✓ | [Issue](https://github.com/gazebosim/gz-sim/issues/49) +ContactPlugin | ✓ | ✓ +DepthCameraPlugin | ✓ | [Issue](https://github.com/gazebosim/gz-sim/issues/49) +FiducialCameraPlugin | ✓ | +ForceTorquePlugin | ✓ | ✓ +GpuRayPlugin | ✓ | [Issue](https://github.com/gazebosim/gz-sim/issues/49) +ImuSensorPlugin | ✓ | ✓ +LensFlareSensorPlugin | ✓ | +MagnetometerPlugin | ✕ | ✓ +OpticalTactilePlugin | ✕ | ✓ +PressurePlugin | ✓ | +RayPlugin | ✓ | [Issue](https://github.com/gazebosim/gz-sim/issues/49) +RaySensorNoisePlugin | ✓ | ✕ Use SDF +SonarPlugin | ✓ | [Issue](https://github.com/gazebosim/gz-sim/issues/49) + +### Visual plugins + +Plugin | Gazebo-classic | Gazebo Sim +-- | -- | -- +AmbientOcclusionVisualPlugin | ✓ | +BlinkVisualPlugin | ✓ | +HeightmapLODPlugin | ✓ | +ShaderParamVisualPlugin | ✓ | ✓ + +### GUI plugins + +Plugin | Gazebo-classic | Gazebo Sim +-- | -- | -- +CessnaGUIPlugin | ✓ | +KeyboardGUIPlugin | ✓ | `gz::gui::KeyPublisher` +LookAtDemoPlugin | ✓ | +TimerGUIPlugin | ✓ | + +### System plugins + +Plugin | Gazebo-classic | Gazebo Sim +-- | -- | -- +ColladaWorldExporter | ✕ | ✓ +ModelPropShop | ✓ | [✓](https://gazebosim.org/api/gazebo/5.4/model_photo_shoot.html) +RestUiPlugin | ✓ | +RestWebPlugin | ✓ | +StopWorldPlugin | ✓ | + +## GUI + +Feature | Gazebo-classic | Gazebo Sim +-- | -- | -- +Play / pause / step | ✓ | ✓ +Reset world / models | ✓ | [Issue](https://github.com/gazebosim/gz-sim/issues/203) +World stats | ✓ | ✓ +Topic echo | ✓ | ✓ +Image viewer | ✓ | ✓ +Translate / rotate | ✓ | ✓ +Scale models | ✓ | [Issue](https://github.com/gazebosim/gz-sim/issues/195) +Insert models from Fuel | Partial support | ✓ +Insert models from disk | ✓ | ✓ +Insert simple shapes | ✓ | ✓ +Insert simple lights | ✓ | ✓ +Delete models | ✓ | ✓ +World tree | ✓ | ✓ +Scene properties | ✓ | [Issue](https://github.com/gazebosim/gz-sim/issues/246) +Log recording / playback | ✓ | ✓ +Plotting | ✓ | ✓ +Video recording | ✓ | ✓ +Screenshot | ✓ | [✓](https://gazebosim.org/api/gui/3.5/screenshot.html) +View angles | ✓ | ✓ +Apply force / torque | ✓ | +Visualize as transparent | ✓ | ✓ +Visualize as wireframe | ✓ | ✓ +Visualize joints | ✓ | ✓ +Visualize collisions | ✓ | ✓ +Visualize inertia | ✓ | ✓ +Visualize CoM | ✓ | ✓ +Visualize contacts | ✓ | ✓ +Visualize lights | ✓ | ✓ +Follow / move to | ✓ | ✓ +Copy / paste | ✓ | ✓ +Building editor | ✓ | +Model editor | ✓ | [Issues](https://github.com/gazebosim/gz-sim/issues?q=is%3Aissue+is%3Aopen+label%3Aeditor) +FPS view control | ✓ | +Orthographic projection | ✓ | ✓ +Undo / redo | ✓ | [Issue](https://github.com/gazebosim/gz-sim/issues/104) +Save world | ✓ | ✓ +Save GUI configuration | ✓ | ✓ +Color scheme and themes | ✕ | ✓ +Position, resize and configure widgets | ✕ | ✓ +Load GUI plugins from menu | ✕ | ✓ +Edit model pose | ✓ | ✓ +Edit light properties | ✓ | ✓ +Edit physics properties | ✓ | ✓ + +## Physics + +In Gazebo Physics, physics engines are integrated as plugins, so any engine +can be integrated without changing the core source code, as it was the case +in Gazebo. + +Feature | Gazebo-classic | Gazebo Sim +-- | -- | -- +ODE engine | ✓ | [Issue](https://github.com/gazebosim/gz-physics/issues/63) +Bullet engine | ✓ | ✓ +DART engine | ✓ | ✓ Plugin shipped with gz-physics +Simbody engine | ✓ | [Issue](https://github.com/gazebosim/gz-physics/issues/63) +TPE engine | ✕ | ✓ +Custom engine plugins | ✕ | ✓ +Collide bitmasks | ✓ | ✓ +Restitution coefficient | ✓ | ✓ +Collision detector | ✓ | ✓ +Solver | ✓ | ✓ + +## Rendering + +In Gazebo Rendering, render engines are integrated as plugins, so any engine +can be integrated without changing the core source code. + +Feature | Gazebo-classic | Gazebo Sim +-- | -- | -- +Ogre 1.x engine | ✓ | ✓ +Ogre 2.x engine | ✕ | ✓ +Optix engine | ✕ | ✓ Partial support +Custom engine plugins | ✕ | [✓](https://gazebosim.org/api/rendering/5.0/renderingplugin.html) +Sky | ✓ | ✓ +Fog | ✓ | +Material scripts | ✓ (Ogre 1.x scripts) | Does not apply +Physically Based Rendering (PBR) | ✕ | ✓ (with engines that support it, like Ogre 2) +Normal maps | ✓ | ✓ +Environment maps | ✕ | ✓ +Lightmaps | ✕ | ✓ +Particle effects | ✕ | ✓ +Render order | ✕ | ✓ +Projector | ✕ | ([ogre 1.x only](https://github.com/gazebosim/gz-sim/pull/1979)) + +## ROS integration + +ROS integration through the +[ros_gz](https://github.com/gazebosim/ros_gz) packages. + +Supported versions: + +* ROS 2 Iron (from source) / Rolling (from source) + +Note: binaries for ROS2 might be available sometime after the Ionic release. + +For **ROS 2 Rolling**, the Rolling distribution moves with the next future release +of ROS 2 defined in [REP-2000](https://www.ros.org/reps/rep-2000.html). For the Gz +Ionic release this means that it will be adopted when ROS 2 Jazzy goes into the +[REP-2000](https://www.ros.org/reps/rep-2000.html). + +## Platforms + +Platform | Gazebo-classic | Gazebo Sim +-- | -- | -- +Ubuntu | ✓ | ✓ +OSX | ✓ | Most of the stack works, outstanding issues: [render window](https://github.com/gazebosim/gz-sim/issues/44) +Windows | ✓ | All libraries compile, low-level libraries function well: [Issue](https://github.com/gazebosim/gz-sim/issues/168) + +## Others + +Feature | Gazebo-classic | Gazebo Sim +-- | -- | -- +Nested models | ✓ | ✓ +Log / playback | ✓ | ✓ +Web client (GzWeb) | ✓ | +COLLADA meshes | ✓ | ✓ +OBJ meshes | ✓ | ✓ +STL meshes | ✓ | ✓ +USD meshes | ✕ | [✓](https://github.com/gazebosim/sdformat/tree/sdf12/examples/usdConverter) +Code introspection | ✓ | All simulation state is accessible from system plugins or through the `SceneBroadcaster`'s state topic +Distribute simulation across processes | ✕ | (coming up) +Incrementally load levels | ✕ | ✓ +Online model database | [gazebo_models repository](https://github.com/osrf/gazebo_models/) | [Gazebo Fuel](https://app.gazebosim.org/fuel/models) +Saved simulation states | ✓ | [Issue](https://github.com/gazebosim/gz-sim/issues/137) +Sphere, cylinder and box primitives | ✓ | ✓ +Ellipsoid and capsule primitives | ✕ | ✓ +Hydrodynamics | ✕ | ✓ +Ocean currents | ✕ | ✓ +Test fixture | ✓ | [✓](https://gazebosim.org/api/gazebo/6.6/test_fixture.html) +Spherical coordinates | ✓ | ✓ +Generic comms system | ✕ | [✓](https://github.com/gazebosim/gz-sim/blob/ign-gazebo6/examples/worlds/perfect_comms.sdf) +Acoustic communication | ✕ | ✓ +Static linked plugins | ✕ | ✓ diff --git a/ionic/hotkeys.md b/ionic/hotkeys.md new file mode 100644 index 000000000..fa19f4c89 --- /dev/null +++ b/ionic/hotkeys.md @@ -0,0 +1,53 @@ +# Gazebo Keyboard Shortcuts + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ActionOperationInstruction
MODE
Enter Selection mode (default mode)Escpress "Esc" for Select (model) mode
Enter Rotate moderpress "r" for Rotate (model) mode
Enter Translate modetpress "t" for Translate (model) mode
Pause / unpauseSpacepress the space bar to pause / unpause
MANIPULATING MODELS
Rotate modelrpress "r" for Rotate mode; click a model & rotate it using markers
Translate modeltpress "t" for Translate mode; click a model & translate it using markers
Constrain along axisx/y/zhold key while manipulating a model to constrain movement along that axis
Snap when rotatingCtrl + draghold Ctrl while rotating a model to rotate in customizable increments (default is 45° but can be changed from Tranform Control GUI)
Snap when translatingCtrl + draghold Ctrl while translating a model to move in customizable increments (default is 1m but can be changed from Tranform Control GUI)
Align to world frameShifthold Shift while manipulating a model to temporarily align axis its to the world frame
MAIN WINDOW
Save ConfigCtrl + shold Ctrl and press "s" to save the current window configuration
Save Config AsCtrl + Shift + shold Ctrl and Shift, and press "s" to save the current window configuration to a designated location
Load ConfigCtrl + ohold Ctrl and press "o" to load a window configuration
CloseCtrl + qhold Ctrl and press "q" to shut down Gazebo
Search Menu/press "/" to open the search menu for plugins
+ + + +
diff --git a/ionic/images/GzGuiQmlDebugging01.png b/ionic/images/GzGuiQmlDebugging01.png new file mode 100644 index 000000000..9f2646e00 Binary files /dev/null and b/ionic/images/GzGuiQmlDebugging01.png differ diff --git a/ionic/images/GzGuiQmlDebugging02.png b/ionic/images/GzGuiQmlDebugging02.png new file mode 100644 index 000000000..6228bc135 Binary files /dev/null and b/ionic/images/GzGuiQmlDebugging02.png differ diff --git a/ionic/img/align.gif b/ionic/img/align.gif new file mode 100644 index 000000000..04b15b6cf Binary files /dev/null and b/ionic/img/align.gif differ diff --git a/ionic/img/align_reverse.gif b/ionic/img/align_reverse.gif new file mode 100644 index 000000000..3854876a2 Binary files /dev/null and b/ionic/img/align_reverse.gif differ diff --git a/ionic/img/bridge_image_exchange_ign-gazebo.png b/ionic/img/bridge_image_exchange_ign-gazebo.png new file mode 100644 index 000000000..a2c020fbd Binary files /dev/null and b/ionic/img/bridge_image_exchange_ign-gazebo.png differ diff --git a/ionic/img/custom_snap.png b/ionic/img/custom_snap.png new file mode 100644 index 000000000..fe22a3e61 Binary files /dev/null and b/ionic/img/custom_snap.png differ diff --git a/ionic/img/grid.gif b/ionic/img/grid.gif new file mode 100644 index 000000000..562b55e11 Binary files /dev/null and b/ionic/img/grid.gif differ diff --git a/ionic/img/grid2.gif b/ionic/img/grid2.gif new file mode 100644 index 000000000..4eed529a6 Binary files /dev/null and b/ionic/img/grid2.gif differ diff --git a/ionic/img/plugins.png b/ionic/img/plugins.png new file mode 100644 index 000000000..1ef8c6858 Binary files /dev/null and b/ionic/img/plugins.png differ diff --git a/ionic/img/pose2.gif b/ionic/img/pose2.gif new file mode 100644 index 000000000..630377ebd Binary files /dev/null and b/ionic/img/pose2.gif differ diff --git a/ionic/img/pose_value.gif b/ionic/img/pose_value.gif new file mode 100644 index 000000000..df1263b28 Binary files /dev/null and b/ionic/img/pose_value.gif differ diff --git a/ionic/img/rotate.gif b/ionic/img/rotate.gif new file mode 100644 index 000000000..649b7227a Binary files /dev/null and b/ionic/img/rotate.gif differ diff --git a/ionic/img/rotate_icon.png b/ionic/img/rotate_icon.png new file mode 100644 index 000000000..a594047df Binary files /dev/null and b/ionic/img/rotate_icon.png differ diff --git a/ionic/img/rotate_worldframe.gif b/ionic/img/rotate_worldframe.gif new file mode 100644 index 000000000..d57f531cb Binary files /dev/null and b/ionic/img/rotate_worldframe.gif differ diff --git a/ionic/img/select_mult.png b/ionic/img/select_mult.png new file mode 100644 index 000000000..067bed1b0 Binary files /dev/null and b/ionic/img/select_mult.png differ diff --git a/ionic/img/snap.gif b/ionic/img/snap.gif new file mode 100644 index 000000000..d113f863d Binary files /dev/null and b/ionic/img/snap.gif differ diff --git a/ionic/img/snap_icon.png b/ionic/img/snap_icon.png new file mode 100644 index 000000000..490112b54 Binary files /dev/null and b/ionic/img/snap_icon.png differ diff --git a/ionic/img/translate.gif b/ionic/img/translate.gif new file mode 100644 index 000000000..0956282b0 Binary files /dev/null and b/ionic/img/translate.gif differ diff --git a/ionic/img/translate_icon.png b/ionic/img/translate_icon.png new file mode 100644 index 000000000..6c32b6ebc Binary files /dev/null and b/ionic/img/translate_icon.png differ diff --git a/ionic/img/translate_worldframe.gif b/ionic/img/translate_worldframe.gif new file mode 100644 index 000000000..ba11d4b3d Binary files /dev/null and b/ionic/img/translate_worldframe.gif differ diff --git a/ionic/img/view.gif b/ionic/img/view.gif new file mode 100644 index 000000000..badc9da1a Binary files /dev/null and b/ionic/img/view.gif differ diff --git a/ionic/index.yaml b/ionic/index.yaml new file mode 100644 index 000000000..de293f3fc --- /dev/null +++ b/ionic/index.yaml @@ -0,0 +1,96 @@ +# This file is an index of the pages to display on the documentation website +# (https://gazebosim.org/docs). The order of the pages in this file +# is reflected on the website's left sidebar. +# +# Components of the index: +# +# 1. "pages:" The master list of pages +# +# 2. Each page has a +# a. "name:" This should be a short url-friendly and unique name. It will +# be used in the website url. +# +# b. "title:" This is a human-friendly title for the page. This title will +# be displayed on the website's left side bar. +# +# c. "file:" The markdown file that contains the page's content. +pages: + - name: install + title: Install + file: install.md + description: Ionic installation instructions + children: + - name: install_ubuntu + title: Binary Ubuntu Install + file: install_ubuntu.md + - name: install_osx + title: Binary macOS Install + file: install_osx.md + - name: install_windows + title: Binary Windows Install + file: install_windows.md + - name: install_ubuntu_src + title: Ubuntu Source Install + file: install_ubuntu_src.md + - name: install_osx_src + title: macOS Source Install + file: install_osx_src.md + - name: install_windows_src + title: Windows Source Install + file: install_windows_src.md + - name: troubleshooting + title: Troubleshooting + file: troubleshooting.md + - name: migration_from_ignition + title: Migration from Ignition + file: migration_from_ignition.md + description: Migration from the Ignition name + + - name: comparison + title: Feature Comparison + file: comparison.md + description: A list of features present in Gazebo-classic and the status of their migration to Gazebo. + - name: tutorials + title: Tutorials + file: tutorials.md + children: + - name: building_robot + title: Building your own robot + file: building_robot.md + - name: moving_robot + title: Moving the robot + file: moving_robot.md + - name: sdf_worlds + title: SDF worlds + file: sdf_worlds.md + - name: sensors + title: Sensors + file: sensors.md + - name: actors + title: Actors + file: actors.md + - name: gui + title: Understanding the GUI + file: GUI_tutorial.md + - name: manipulating_models + title: Manipulating Models + file: Manipulating_models.md + - name: fuel_insert + title: Model Insertion from Fuel + file: Model_insertion_fuel.md + - name: hotkeys + title: Keyboard Shortcuts + file: hotkeys.md + description: Gazebo keyboard shortcuts + - name: spawn_urdf + title: Spawn URDF + file: spawn_urdf.md + - name: ros2_integration + title: ROS 2 integration via bridge + file: ros2_integration.md + - name: ros2_interop + title: ROS 2 interoperability + file: ros2_interop.md + - name: ros_gz_project_template_guide + title: ROS 2 integration template + file: ros_gz_project_template_guide.md diff --git a/ionic/install.md b/ionic/install.md new file mode 100644 index 000000000..9c0952a29 --- /dev/null +++ b/ionic/install.md @@ -0,0 +1,63 @@ +# Gazebo Ionic + +Up to Ionic's release date, the collection should be considered unstable. + +Gazebo Ionic will be the 8th major release of Gazebo. It will be a +long-term release. + +## Binary installation instructions + +Binary installation is the recommended method of installing Gazebo. + + * [Binary Installation on Ubuntu](install_ubuntu) + * [Binary Installation on macOS](install_osx) + * [Binary Installation on Windows](install_windows) + +## Source Installation instructions + +Source installation is recommended for users planning on altering Gazebo's source code (advanced). + + * [Source Installation on Ubuntu](install_ubuntu_src) + * [Source Installation on macOS](install_osx_src) + * [Source Installation on Windows](install_windows_src) + +## Ionic Libraries + +The Ionic collection is composed of many different Gazebo libraries. The +collection assures that all libraries are compatible and can be used together. + +This list of library versions may change up to the release date. + +| Library name | Version | +| ------------------ |:-------------:| +| gz-cmake | 4.x | +| gz-common | 6.x | +| gz-fuel-tools | 10.x | +| gz-sim | 9.x | +| gz-gui | 9.x | +| gz-launch | 8.x | +| gz-math | 8.x | +| gz-msgs | 11.x | +| gz-physics | 8.x | +| gz-plugin | 3.x | +| gz-rendering | 9.x | +| gz-sensors | 9.x | +| gz-tools | 2.x | +| gz-transport | 14.x | +| gz-utils | 3.x | +| sdformat | 15.x | + +## Supported platforms + +Ionic is planned to be [supported](/docs/all/releases) on the platforms below. +This list may change up to the release date. + +These are the **officially** supported platforms: + +* Ubuntu Jammy on amd64 +* Ubuntu 24.04 on amd64 + +Platforms supported at **best-effort** include arm architectures, Windows and +macOS. See +[this ticket](https://github.com/gazebo-tooling/release-tools/issues/597) +for the full status. diff --git a/ionic/install_osx.md b/ionic/install_osx.md new file mode 100644 index 000000000..870c42b98 --- /dev/null +++ b/ionic/install_osx.md @@ -0,0 +1,35 @@ +# Binary Installation on MacOS + +All the Ionic binaries are available in Big Sur and Monterey using the +[homebrew package manager](https://brew.sh/). + +The homebrew tool can be installed using: + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" +``` + +After installing the homebrew package manager, Gazebo Ionic can be installed running: + +```bash +brew tap osrf/simulation +brew install gz-ionic +``` + +All libraries should be ready to use and the `gz sim -s` server app ready to be executed. + +Head back to the [Getting started](/docs/all/getstarted) +page to start using Gazebo! + +## Uninstalling binary install + +If you need to uninstall Gazebo or switch to a source-based install once you +have already installed the library from binaries, run the following command: + +```bash +brew uninstall gz-ionic +``` + +## Troubleshooting + +See [Troubleshooting](/docs/ionic/troubleshooting#macos) diff --git a/ionic/install_osx_src.md b/ionic/install_osx_src.md new file mode 100644 index 000000000..4e7a424a0 --- /dev/null +++ b/ionic/install_osx_src.md @@ -0,0 +1,215 @@ +# Source Installation on macOS + +This tutorial will work for macOS BigSur 10.16 and macOS Monterey 12.0. + +## Install tools + +The use of some additional tools is recommended to help with the source compilation, +although other ways of correctly getting and building the sources are also possible. + +The easiest way to get the sources of all libraries is to use +[vcstool](https://github.com/dirk-thomas/vcstool). + +To compile all the different libraries and gz-sim in the right order +[colcon](https://colcon.readthedocs.io/en/released/) is recommended. +The colcon tool is available on all platforms using pip (or pip3, if pip fails). + +## Python3 from homebrew + +Tools and dependencies for Ionic can be installed using the [homebrew package manager](https://brew.sh/). +The homebrew tool can be installed by entering the following in a terminal: + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" +``` + +Ionic is compatible with Python3; it can be installed by running the following in a terminal: + +```bash +brew install python3 +``` + +## vcstool and colcon from pip + +PIP is available on all platforms: + +```bash +python3 -m pip install vcstool +``` + +```bash +python3 -m pip install -U colcon-common-extensions +``` + +## Getting the sources + +The first step is to create a developer workspace in which `vcstool` and +`colcon` can work: + +```bash +mkdir -p ~/workspace/src +cd ~/workspace/src +``` + +All the sources of gazebo-ionic are declared in a yaml file. Download +it to the workspace: + +```bash +wget https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-ionic.yaml +``` + +Use `vcstool` to automatically retrieve all the Gazebo libraries sources from +their repositories: + +```bash +vcs import < collection-ionic.yaml +``` + +The src subdirectory should contain all the sources ready to be built. + +## Install dependencies + +Add `osrf/simulation` to Homebrew formulae + +```bash +brew update +brew tap osrf/simulation +``` + +Install all dependencies: + +Dependency for Ogre: + +```bash +brew cask install xquartz +``` + +General dependencies: + +```bash +brew install assimp boost bullet cmake cppzmq dartsim@6.10.0 doxygen eigen fcl ffmpeg flann freeimage freetype gdal gflags google-benchmark gts ipopt jsoncpp libccd libyaml libzzip libzip nlopt ode open-scene-graph ossp-uuid ogre1.9 ogre2.3 pkg-config protobuf qt@5 qwt-qt5 rapidjson ruby tbb tinyxml tinyxml2 urdfdom zeromq +``` + +`dartsim@6.10.0` and `qt@5` are not sym-linked. To use those dependencies when building +`gz-physics8` and `gz-gui9`, run the following after installation: + +For Macs with Intel processors, add them to `/usr/local`: + +```bash +# dartsim@6.10.0 +export CMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}:/usr/local/opt/dartsim@6.10.0 +export DYLD_FALLBACK_LIBRARY_PATH=${DYLD_FALLBACK_LIBRARY_PATH}:/usr/local/opt/dartsim@6.10.0/lib:/usr/local/opt/octomap/local +export PKG_CONFIG_PATH=${PKG_CONFIG_PATH}:/usr/local/opt/dartsim@6.10.0/lib/pkgconfig +# qt@5 +export CMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}:/usr/local/opt/qt@5 +``` + +Note if you are on an ARM based Apple Silicon Mac machine, you will need to add them to `/opt/homebrew` instead: + +```bash +# dartsim@6.10.0 +export CMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}:/opt/homebrew/opt/dartsim@6.10.0 +export DYLD_FALLBACK_LIBRARY_PATH=${DYLD_FALLBACK_LIBRARY_PATH}:/opt/homoebrew/opt/dartsim@6.10.0/lib:/opt/homebrew/opt/octomap/local +export PKG_CONFIG_PATH=${PKG_CONFIG_PATH}:/opt/homebrew/opt/dartsim@6.10.0/lib/pkgconfig +# qt@5 +export CMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}:/opt/homebrew/opt/qt@5 +``` + +### Install compiler requirements + +The Gazebo Libraries require the Xcode 10 compiler on MacOS Mojave. + +On Mac machines, gcc is acquired by installing Xcode command line tools. +The required version of Xcode for Ionic is Xcode 10.3, which can be downloaded from +[Apple Developer Site](https://developer.apple.com/download/more/). +You will need to sign in to your Apple account and download the Mojave version of +Xcode command line tools. Command line tools can also be obtained by downloading +Xcode from the Apple App Store (installing the full app may take over an hour). + +## Building the Gazebo Libraries + +Once the compiler and all the sources are in place it is time to compile them. +Start the procedure by changing into the workspace and listing the packages +recognized by `colcon`: + +```bash +cd ~/workspace/ +colcon graph +``` + +`colcon graph` should list the Gazebo libraries with an +[interdependency diagram](https://colcon.readthedocs.io/en/released/reference/verb/graph.html#example-output). +If that is the case, then you are ready +to build the whole set of libraries: + +```bash +colcon build --merge-install +``` + +Note if you are on an ARM based Apple Silicon Mac machine, you may need to set a couple more cmake args: + +```bash +colcon build --cmake-args -DCMAKE_MACOSX_RPATH=FALSE -DCMAKE_INSTALL_NAME_DIR=$(pwd)/install/lib --merge-install +``` + +To speed up the build process, you could also disable tests by using + +```bash +colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install +``` + +To use debuggers activate debug symbols. Gazebo will run slower, but you'll be able to use `lldb`: + +```bash +colcon build --cmake-args ' -DBUILD_TESTING=OFF' ' -DCMAKE_BUILD_TYPE=Debug' --merge-install +``` + +To build a specific package with all its dependent packages: + +```bash +colcon build --merge-install --packages-up-to PACKAGE_NAME +``` + +To build a single package: + +```bash +colcon build --merge-install --packages-select PACKAGE_NAME +``` + +Visit [colcon documentation](https://colcon.readthedocs.io/en/released/#) to view more `colcon` build and test options. + +If there are no errors, all the binaries should be ready to use. + +## Using the workspace + +The workspace needs to be sourced every time a new terminal is used. + +Run the following command to source the workspace in bash: + +```bash +. ~/workspace/install/setup.bash +``` + +Or in zsh: + +```zsh +. ~/workspace/install/setup.zsh +``` + +You should now be able to launch gazebo: + +```sh +# launch server in one terminal +gz sim -v 4 shapes.sdf -s + +# launch gui in a separate terminal +# remember to source the workspace setup script +gz sim -v 4 -g +``` + +This is the end of the source install instructions; head back to the [Getting started](/docs/all/getstarted) +page to start using Gazebo! + +## Troubleshooting + +See [Troubleshooting](/docs/ionic/troubleshooting#macos) diff --git a/ionic/install_ubuntu.md b/ionic/install_ubuntu.md new file mode 100644 index 000000000..8b9039260 --- /dev/null +++ b/ionic/install_ubuntu.md @@ -0,0 +1,43 @@ +# Binary Installation on Ubuntu + +Ionic binaries are provided for Ubuntu Jammy (22.04) and Ubuntu 24.04 (when it's released). The +Ionic binaries are hosted in the packages.osrfoundation.org repository. +To install all of them, the metapackage `gz-ionic` can be installed. + +**WARNING:** `gz-ionic` cannot be installed alongside gazebo-classic (eg. `gazebo11`) since both use the `gz` command line tool. Trying to install `gz-ionic` on a system that already has gazebo-classic installed from binaries will cause gazebo-classic and its dependencies to be uninstalled. Currently, the workarounds for this are to install from source or to use Docker [`gazebo-classic`](https://hub.docker.com/_/gazebo) so they are not installed side-by-side on the same system. + +First install some necessary tools: + +```bash +sudo apt-get update +sudo apt-get install lsb-release wget gnupg +``` + +Then install Gazebo Ionic: + + +```bash +sudo wget https://packages.osrfoundation.org/gazebo.gpg -O /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 +sudo apt-get update +sudo apt-get install gz-ionic +``` + +All libraries should be ready to use and the `gz sim` app ready to be executed. + +Head back to the [Getting started](/docs/all/getstarted) +page to start using Gazebo! + + +## Uninstalling binary install + +If you need to uninstall Gazebo or switch to a source-based install once you +have already installed the library from binaries, run the following command: + +```bash +sudo apt remove gz-ionic && sudo apt autoremove +``` + +## Troubleshooting + +See [Troubleshooting](/docs/ionic/troubleshooting#ubuntu) diff --git a/ionic/install_ubuntu_src.md b/ionic/install_ubuntu_src.md new file mode 100644 index 000000000..4005b0ea4 --- /dev/null +++ b/ionic/install_ubuntu_src.md @@ -0,0 +1,280 @@ +# Source Installation on Ubuntu + +These instructions apply to Ubuntu Jammy (22.04) and Ubuntu 24.04. + +## Install tools + +The use of some additional tools is recommended to help with the source compilation, +although other ways of correctly getting and building the sources are also possible. + +The easiest way to get the sources of all libraries is to use +[vcstool](https://github.com/dirk-thomas/vcstool). + +To compile all the different libraries and gz-sim in the right order +[colcon](https://colcon.readthedocs.io/en/released/) is recommended. +The colcon tool is available on all platforms using pip (or pip3, if pip fails). + +Some tools require Python 3.5 (or higher) which is not the default option on some +platforms (like Ubuntu Focal). The Python +[virtualenv](https://virtualenv.pypa.io/en/latest/) could be a useful solution in +cases where the default option cannot be easily changed. + +## Generic tools + +Install tools needed by this tutorial: + +```bash +sudo apt install python3-pip wget lsb-release gnupg curl +``` + +## vcstool and colcon from pip + +PIP is available on all platforms: + +```bash +pip install vcstool || pip3 install vcstool +``` + +```bash +pip install -U colcon-common-extensions || pip3 install -U colcon-common-extensions +``` + +Check that no errors were printed while installing with PIP. If your system is not recognising the commands, and you're using a system that is compatible with Debian or Ubuntu packages, see the instructions below to install using `apt`. + +After installing `vcstool` and `colcon` with PIP, you may need to add their executables to your `$PATH`. +Check where the installation of these packages took place: + +```bash +pip show vcstool || pip3 show vcstool | grep Location + +pip show colcon-common-extensions || pip3 show colcon-common-extensions | grep Location +``` + +If your install path is prefixed with `$HOME/.local`, you'll probably need to add the executables within this directory to your `$PATH` in order to avoid "command not found" errors when using `vcstool` and `colcon` later on: + +```bash +export PATH=$PATH:$HOME/.local/bin/ +``` + +## vcstool and colcon from apt + +An alternative method is to use the `.deb` packages available on Debian or Ubuntu: + +```bash +sudo sh -c 'echo "deb http://packages.ros.org/ros2/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros2-latest.list' +curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add - +sudo apt-get update +sudo apt-get install python3-vcstool python3-colcon-common-extensions +``` + +## Git + +Gazebo libraries use `git` for version control, so it must be available +in the system for `vcstool` to work properly. + +```bash +sudo apt-get install git +``` + +## Getting the sources + +The instructions below use some UNIX commands to manage directories but the +equivalent alternatives on Windows should provide the same result. + +The first step is to create a developer workspace in which `vcstool` and +`colcon` can work: + +```bash +mkdir -p ~/workspace/src +cd ~/workspace/src +``` + +All the sources of gazebo-ionic are declared in a yaml file. Download +it to the workspace: + +```bash +wget https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-ionic.yaml +``` + +Use `vcstool` to automatically retrieve all the Gazebo libraries sources from +their repositories: + +```bash +vcs import < collection-ionic.yaml +``` + +The src subdirectory should contain all the sources ready to be built. + +## Install dependencies + +Before compiling it is necessary to install all the dependencies of the different +packages that compose the Ionic collection. Every platform has a different +method to install software dependencies. + +Add `packages.osrfoundation.org` to the apt sources list: + +```bash +sudo wget https://packages.osrfoundation.org/gazebo.gpg -O /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 +sudo apt-get update +``` + +The command below must be run from a workspace with the Gazebo source code and will install all dependencies in Ubuntu: + +```bash +cd ~/workspace/src +sudo apt -y install \ + $(sort -u $(find . -iname 'packages-'`lsb_release -cs`'.apt' -o -iname 'packages.apt' | grep -v '/\.git/') | sed '/gz\|sdf/d' | tr '\n' ' ') +``` + +## Building the Gazebo Libraries + +Once the compiler and all the sources are in place it is time to compile them. +Start the procedure by changing into the workspace and listing the packages +recognized by `colcon`: + +```bash +cd ~/workspace/ +colcon graph +``` + +`colcon graph` should list the Gazebo libraries with an +[interdependency diagram](https://colcon.readthedocs.io/en/released/reference/verb/graph.html#example-output). +If that is the case, then you are ready +to build the whole set of libraries: + +```bash +colcon build --merge-install +``` + +To speed up the build process, you could also disable tests by using + +```bash +colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install +``` + +To use debuggers activate debug symbols. Gazebo will run slower, but you'll be able to use GDB: + +```bash +colcon build --cmake-args ' -DBUILD_TESTING=OFF' ' -DCMAKE_BUILD_TYPE=Debug' --merge-install +``` + +To build a specific package with all its dependent packages: + +```bash +colcon build --merge-install --packages-up-to PACKAGE_NAME +``` + +To build a single package: + +```bash +colcon build --packages-select PACKAGE_NAME +``` + +Visit [colcon documentation](https://colcon.readthedocs.io/en/released/#) to view more `colcon` build and test options. + +If there are no errors, all the binaries should be ready to use. You can check the [Troubleshooting](/docs/ionic/troubleshooting#ubuntu) section for errors. + +## Using the workspace + +The workspace needs to be sourced every time a new terminal is used. + +Run the following command to source the workspace in bash: + +```bash +. ~/workspace/install/setup.bash +``` + +Or in zsh: + +```zsh +. ~/workspace/install/setup.zsh +``` + +This is the end of the source install instructions; head back to the [Getting started](/docs/all/getstarted) +page to start using Gazebo! + +## Uninstalling source-based install + +A source-based install can be "uninstalled" using several methods, depending on +the results you want: + + 1. If you installed your workspace with `colcon` as instructed above, "uninstalling" + could be just a matter of opening a new terminal and not sourcing the + workspace's `setup.sh`. This way, your environment will behave as though + Gazebo is not installed on your system. + + 2. If, in addition to not wanting to use the libraries, you're also trying to + free up space, you can delete the entire workspace directory with: + + ```bash + rm -rf ~/workspace + ``` + + 3. If you want to keep the source code, you can remove the + `install` / `build` / `log` directories as desired, leaving the `src` directory. + +## Troubleshooting + +See [Troubleshooting](/docs/ionic/troubleshooting#ubuntu) + +## QML Debugging + +To perform QML debugging you'll need: + + - Add `--cmake-args -DDQT_QML_DEBUG` flag to colcon + - QtCreator + +You will need to build Gazebo with: + +```bash +colcon build --cmake-args -DQT_QML_DEBUG --merge-install +``` + +> **Note:** Advanced users may note that only the `gz-sim` project needs this flag. + +After that's done, launching `gz sim -g` will result in the following message: + +``` +QML debugging is enabled. Only use this in a safe environment. +QML Debugger: Waiting for connection on port 40000... +``` + +After that you can just head to +`QtCreator -> Debug -> Start Debugging -> Attach to QML Port...` +and enter the QML port + +![](images/GzGuiQmlDebugging01.png) + +Once you click there, set the port number to 40000 and hit ok + +![](images/GzGuiQmlDebugging02.png) + +We're working to improve QtCreator integration so that it works out of the box. + +The ruby `gz` script doesn't yet pass the necessary command line arguments to the application. + +Note that because all instances will try to use port 40000, only one instance +can use it. If you shutdown the process and restart it immediately too quickly, +the OS may still claim the port is in use and hence the 2nd (re)launch will not +listen to QML debugger attach requests. + +### Avoid QML stall waiting for debugger on startup + +During development, you may find troublesome that `gz sim -g` won't actually start until +QtCreator hooks to the QML Debugging port. + +If that's a problem, you can edit the C++ file `gz-sim/src/gz.cc` and remove `block` +from it. E.g. + +```c++ +// The following: +const_cast( + "-qmljsdebugger=port:40000,block,services:DebugMessages,QmlDebugger," + "V8Debugger,QmlInspector,DebugTranslation") + +// Must become the following +const_cast( + "-qmljsdebugger=port:40000,services:DebugMessages,QmlDebugger," + "V8Debugger,QmlInspector,DebugTranslation") +``` diff --git a/ionic/install_windows.md b/ionic/install_windows.md new file mode 100644 index 000000000..5457a0aa8 --- /dev/null +++ b/ionic/install_windows.md @@ -0,0 +1,72 @@ +
+WARNING: Current Windows support is experimental. +
+ +# Binary Installation on Windows 10 + +Most Gazebo packages are available in Windows 10 using the [conda-forge package manager](https://conda-forge.org/), +and the Gazebo feedstock recipes can be found [here](https://github.com/search?q=org:conda-forge+libgz&type=code). + +Additionally, command line tools, the DART physics engine, and some tests are not currently supported in Windows. + +In order to use `conda-forge`, you will need to +1. Install a [Conda package management system](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html). + Miniconda suffices. You will likely want to check the box to add `conda` to your `PATH` + during the installation process so that you won't have to do this step manually. + +2. Open a Windows command prompt, being sure to have `conda` added to your + Windows `PATH` system environment variable (you may also need to open + a new command prompt to see any `PATH` changes reflected). + + If you did not add Conda to your `PATH` environment variable + during Conda installation, you may need to navigate to the + location of `condabin` in order to use the `conda` command. + To find `condabin`, search for "Anaconda Prompt" in the + Windows search field near the Windows button, open it, run + `where conda`, and look for a line containing the directory `condabin`. + +3. Create and activate a new Conda environment: + ```bash + conda create -n gz-env + conda activate gz-env + ``` +4. Install desired Gazebo packages you want to install based on your application. Packages with the prefix `libgz-` + contain only the C++ libraries while the Python bindings are available separately as `gz-<#>-python`. + To install both with a single command use `gz-<#>`. + Thus you can use `gz-sim<#>` to fully install the latest version of Gazebo. + ```bash + conda install libgz-<#> --channel conda-forge + ``` + Be sure to replace `` with your desired package name (ie, common, msgs, etc.) + and `<#>` with the release version. If left unspecified, `conda-forge` will install the + most recently stable release packages. Be sure to check the + [high level install instructions](install) for corresponding version numbers. + +**Note** + +You can view all available versions of a specific package with: +```bash +conda search libgz-* --channel conda-forge +``` +and view their dependencies with +```bash +conda search libgz-* --channel conda-forge --info +``` +and install a specific minor version with +```bash +conda install libgz-=.. --channel conda-forge +``` +where `` is the major release number, `` is the minor release number, and ` --channel conda-forge +``` + +## Troubleshooting + +See [Troubleshooting](/docs/ionic/troubleshooting#windows) diff --git a/ionic/install_windows_src.md b/ionic/install_windows_src.md new file mode 100644 index 000000000..3506a2ab5 --- /dev/null +++ b/ionic/install_windows_src.md @@ -0,0 +1,201 @@ +
+WARNING: Current Windows support is experimental. +
+ +# Source Installation on Windows 10 or 11 + +OGRE2 rendering capabilities are not currently supported in Windows, and Gazebo GUI +works in a limited fashion. These functionalities correspond to the currently +building packages `gz-rendering` and `gz-sim`, respectively. The packages will build, +but you can expect runtime failures when using their functionalities. + +> **NOTE** +> You should be able to use `ogre` as a rendering engine instead of the default `ogre2`. +> Just append `--render-engine ogre` to the command line. + +## Install dependencies + +1. Install a conda distribution. As Gazebo uses all dependencies from the conda-forge channel, + we suggest to install miniforge following [the official miniforge installation docs](https://github.com/conda-forge/miniforge#windows) + You will likely want to check the box to add `conda` to your `PATH` + during the installation process so that you won't have to do this step manually. + +2. Install [Visual Studio 2019 or 2022](https://visualstudio.microsoft.com/downloads/). + The Community version is free for students, open-source developers, and personal + development. Check "Desktop development with C++" in the Workloads tab, + check "MFC and ATL support", and uncheck "C++ Cmake Tools." We will install + cmake via Conda. All other checkboxes can be left unchecked. + +3. Open a Visual Studio Command Prompt (search for "x64 Native Tools Command Prompt + for VS" in the Windows search field near the Windows button). Optionally, + right-click and pin to the task bar for quick access in the future. + + If you did not add Conda to your `PATH` environment variable during Conda installation, + you may need to navigate to the location of `condabin` in order to use the `conda` command. + To find `condabin`, search for "Anaconda Prompt" in the Windows search field near the + Windows button, open it, run `where conda`, and look for a line containing the directory `condabin`. + +4. Navigate to your `condabin`, if necessary, and then create and activate a Conda environment: + ```bash + conda create -n gz-ws + conda activate gz-ws + ``` + Once you have activated an environment, a prefix like `(gz-ws)` will be prepended to + your prompt, and you can use the `conda` command outside of the `condabin` directory. + + You can use `conda info --envs` to see all of your environments. + + To speed up conda installations, also set the following to use libmamba solver. + Older conda installations may need to do [additional steps](https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community). + ```bash + conda config --set solver libmamba + ``` + To remove an environment, use `conda remove --all --name `. + + > **NOTE** + > This way of Conda environment creation puts it into a default folder. If you need + to install it elsewhere, use `--prefix ` instead of `--name `. + Environments in custom paths cannot be referenced by names, so even `conda activate` + needs to be passed a path (relative or absolute) instead of the name. If you refer + to a subdirectory of the current directory, you have to prepend `.\` so that Conda + knows it is a path and not a name. + +5. Install dependencies: + ```bash + conda install cmake git vcstool curl pkg-config ^ + colcon-common-extensions dartsim eigen freeimage gdal gts ^ + glib dlfcn-win32 ffmpeg ruby tinyxml2 tinyxml ^ + libprotobuf urdfdom zeromq cppzmq ogre=1.10 ogre-next jsoncpp ^ + libzip qt pybind11 --channel conda-forge + ``` + This can take tens of minutes (or less when using libmamba solver). + +6. Navigate to where you would like to build the library, create and enter your workspace directory, + create the `src` directory which will contain the Gazebo source code. + ```bash + mkdir gz-ws + cd gz-ws + mkdir src + ``` + +7. Then clone the repositories + ```bash + # CMD + curl -sk https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-ionic.yaml -o collection-ionic + vcs import src < collection-ionic + + # PowerShell + curl https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-ionic.yaml -o collection-ionic + vcs import --input collection-ionic src + ``` + +## Building the Gazebo Libraries + +Once the compiler and all the sources are in place it is time to compile them. +Start the procedure by navigating to your workspace and listing the packages +recognized by `colcon`: + +```bash +colcon graph +``` + +`colcon graph` should list the Gazebo libraries with an +[interdependency diagram](https://colcon.readthedocs.io/en/released/reference/verb/graph.html#example-output). +If that is the case, then you are ready to build the whole set of libraries: + +```bash +colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install --packages-up-to gz-sim9 gz-tools2 +``` +Tests are turned off as they are not currently supported on Windows. + +To build a specific package with all its dependent packages: + +```bash +colcon build --merge-install --packages-up-to PACKAGE_NAME +``` + +To build a single package: + +```bash +colcon build --packages-select PACKAGE_NAME +``` + +Visit [colcon documentation](https://colcon.readthedocs.io/en/released/#) to view more `colcon` build and test options. + +If there are no errors, all the binaries should be ready to use. + +## Using the workspace + +The workspace needs to be sourced every time a new terminal is used ( +and Conda environment activated before that). + +Run the following command to source the workspace: + +```bash +# CMD +call install\setup.bat + +# PowerShell +.\install\setup.ps1 +``` + +This is the end of the source install instructions; head back to the [Getting started](/docs/all/getstarted) +page to start using Gazebo! + +> **NOTE** +> As Gazebo GUI is not yet working, running `gz sim` will not work. You can run only the server with +> ```cmd +> gz sim -s -v +> ``` + +> **NOTE** +> If your username contains spaces (which is quite common on Windows), you will probably get errors +> saying `Invalid partition name [Computer:My User With Spaces]`. Fix this by changing `GZ_PARTITION` +> to something else: +> ```cmd +> set GZ_PARTITION=test +> ``` +> Remember to set the same partition in all other consoles. + +### Gazebo GUI workaround + +Although running `gz sim` without arguments is not supported on Windows, +and `gz sim -g` is also not supported, there is a workaround you can apply +to be able to launch `gz sim -g` on Windows. + +> Manually comment [these lines](https://github.com/gazebosim/gz-sim/blob/gz-sim7_7.5.0/src/cmd/cmdsim.rb.in#L497-L501) and [these lines](https://github.com/gazebosim/gz-sim/blob/gz-sim7_7.5.0/src/cmd/cmdsim.rb.in#L558-L562) in file `install\lib\ruby\gz\cmdsim9.rb`. + +This should allow you to run the GUI in a separate console, connecting to the server running in another console. + +## Uninstalling source-based install + +A source-based install can be "uninstalled" using several methods, depending on +the results you want: + + 1. If you installed your workspace with `colcon` as instructed above, "uninstalling" + could be just a matter of opening a new terminal and not sourcing the + workspace's `setup.bat`. This way, your environment will behave as though + Gazebo is not installed on your system. + + 2. If, in addition to not wanting to use the libraries, you're also trying to + free up space, you can delete the entire workspace directory from within + your `conda` environment with: + + ```bash + rm -rf + ``` + + 3. If you want to keep the source code, you can remove the + `install` / `build` / `log` directories as desired, leaving the `src` directory. + + 4. Last, if you do not need the conda environment anymore, you can remove it with + + ```bash + conda deactivate + conda remove --all --name + # or conda remove --all --prefix if you installed to custom path + ``` + +## Troubleshooting + +See [Troubleshooting](/docs/ionic/troubleshooting#windows) diff --git a/ionic/migration_from_ignition.md b/ionic/migration_from_ignition.md new file mode 100644 index 000000000..6798db1d8 --- /dev/null +++ b/ionic/migration_from_ignition.md @@ -0,0 +1,523 @@ +# Migration Guide + +Hello Gazebo community!! + +In April 2022, it was announced that [we’d be retiring the “Ignition” name in favor of “Gazebo”.](https://community.gazebosim.org/t/a-new-era-for-gazebo/1356) +This migration guide will serve you help you execute the necessary changes in your own packages, and luckily it won’t be as troublesome as the move from Gazebo Classic! + +## Overview + +### Changes + +So what’s happening in practice? In summary: + +- Whenever the name `Ignition` or `ign` is used, the Gazebo counterpart (`Gazebo` or `gz`) is used instead, preserving case +- `ign-gazebo` / `Ignition Gazebo` became `gz-sim` / `Gazebo Sim` +- The Ignition logo has been replaced by the Gazebo logo. + +These changes were made in: + +- Websites +- GitHub organizations and repositories +- Documentation +- UIs +- Namespaces, command line tools, shared libraries, directories, APIs, files + +This means that a bulk of the migration effort on a user's part will involve intelligent find-and-replaces of filenames, directories, and source code. +You may also look at the [tracking GitHub issue](https://github.com/gazebo-tooling/release-tools/issues/698) if you need to trace any changes made to support the migration in the core libraries. + +### Tick-tocks and Hard-tocks + +This section provides just an overview of the different changes made, for a more detailed listing of tick-tocks, see the migration file in each of the individual core libraries’ repositories: + +- [gz-cmake](https://github.com/gazebosim/gz-cmake/blob/main/Migration.md) +- [gz-common](https://github.com/gazebosim/gz-common/blob/main/Migration.md) +- [gz-fuel-tools](https://github.com/gazebosim/gz-fuel-tools/blob/main/Migration.md) +- [gz-gui](https://github.com/gazebosim/gz-gui/blob/main/Migration.md) +- [gz-launch](https://github.com/gazebosim/gz-launch/blob/main/Migration.md) +- [gz-math](https://github.com/gazebosim/gz-math/blob/main/Migration.md) +- [gz-msgs](https://github.com/gazebosim/gz-msgs/blob/main/Migration.md) +- [gz-physics](https://github.com/gazebosim/gz-physics/blob/main/Migration.md) +- [gz-plugin](https://github.com/gazebosim/gz-plugin/blob/main/Migration.md) +- [gz-rendering](https://github.com/gazebosim/gz-rendering/blob/main/Migration.md) +- [gz-sensors](https://github.com/gazebosim/gz-sensors/blob/main/Migration.md) +- [gz-sim](https://github.com/gazebosim/gz-sim/blob/main/Migration.md) +- [gz-tools](https://github.com/gazebosim/gz-tools/blob/main/Migration.md) +- [gz-transport](https://github.com/gazebosim/gz-transport/blob/main/Migration.md) +- [gz-utils](https://github.com/gazebosim/gz-utils/blob/main/Migration.md) +- [sdformat](https://github.com/gazebosim/sdformat/blob/main/Migration.md) + +Additionally the migration pointers in a later section of this migration guide should help you get your packages ready and working with Gazebo. + +Generally speaking, you should still be able to use either the Ignition counterpart or Gazebo counterpart for **most things** if you are using Ionic, due to explicit tick-tocking logic written in the stack. +Just note that using the Ignition counterpart will generally cause deprecation warnings to be emitted. + +#### Tick-tocks + +Tick-tocks for the following are implemented, though not all of them will emit deprecation warnings. +These tick-tocks are implemented either as aliases, or otherwise have some sort of redirection mechanism (e.g. symlinks, directory retargets, string replacements in source) to target the Gazebo counterpart instead. + +Also, in the source code, most of these tick-tocks will have an associated comment calling out that they are deprecated, or have a `GZ_DEPRECATED()` macro call. + + +**Namespaces** + +- Python namespaces + - e.g. `ignition.math.XXX` → `gz.math.XXX` +- C++ namespaces + - e.g. `ignition::gazebo::XXX` → `gz::sim::XXX` +- Message namespaces and packages + - e.g. `ignition.msgs.XXX` → `gz.msgs.XXX`, `ignition/msgs/header.proto` → `gz/msgs/header.proto` + +**Source** + +- Class names, members, functions, and variables in public headers + - e.g. `IgnitionFormatter` → `GzFormatter` +- Public headers + - e.g. `include/ignition` → `include/gz` +- Plugins + - e.g. `ignition::gazebo::systems::LiftDrag` → `gz::sim::systems::LiftDrag` +- Shared libraries + - e.g. `libignition-gazebo-buoyancy-engine-system.so` → `libgz-sim-buoyancy-engine-system.so` + - You may remove the `lib` and `.so` prefix and suffixes! + - e.g. `libignition-gazebo-buoyancy-engine-system.so` → `gz-sim-buoyancy-engine-system` +- C++ Macros in public headers + - e.g. `IGN_PARTITION` → `GZ_PARTITION` + +**CMake and Packaging** + +- CMake macros/functions + - e.g. `ign_find_package()` → `gz_find_package()` +- CMake macro/function arguments + - e.g. `NO_IGNITION_PREFIX` → `NO_PROJECT_PREFIX` +- CMake variables* + - e.g. `IgnOGRE2_FOUND` → `GzOGRE2_FOUND` + - Not every CMake variable is tick-tocked, but most of the ones that are used in downstream libraries are +- CMake packages found by `gz_find_package()` + - e.g. `gz_find_package(IgnCURL)` → `gz_find_package(GzCURL)` +- Debian packages + - e.g. `libignition-cmake3-dev` → `libgz-cmake3-dev` + +**Misc.** + +- Environment variables (names and values) + - e.g. `IGN_GAZEBO_RESOURCE_PATH` → `GZ_SIM_RESOURCE_PATH` +- Command line + - e.g. `ign` → `gz`, `ign gazebo` → `gz sim` +- GUI QML + - e.g. `IgnSpinBox` → `GzSpinBox` +- Topics* (typically in tests) + - e.g. `/ignition/XXX` → `/gz/XXX` + - **Note:** `/gazebo` is NOT migrated to `/sim` +- GitHub organizations and repositories + - e.g. `ignitionrobotics` → `gazebosim` , `ign-cmake` → `gz-cmake` +- GitHub actions and workflows + - e.g. `ignition-tooling` → `gazebo-tooling` +- Websites + - e.g. [ignitionrobotics.org](http://ignitionrobotics.org) → [gazebosim.org](http://gazebosim.org) +- SDF and launch tags + - e.g. `` → `` +- SDF namespaces + - e.g. `ignition:type` + + +#### Hard-tocks + +There are some exceptions that have been hard-tocked instead, meaning that you **MUST** use the Gazebo counterpart. +Using the Ignition counterpart will likely cause compilation or something else to break (unless it’s just a documentation change.) + +**Namespaces** + +- Ruby namespaces + - e.g. `ignition/math` → `gz/math` + +**Source** + +- Install space + - e.g. `install/share/ignition` → `install/share/gz` + +**CMake and Packaging** + +- Most includeable CMake files in `gz-cmake` + - e.g. `IgnUtils.cmake` → `GzUtils.cmake` +- Gazebo library CMake project names + - e.g. `ignition-utils2` → `gz-utils2` +- Internally used CMake variables + - e.g. `IGN_TRANSPORT_VER` → `GZ_TRANSPORT_VER` + +**Misc.** + +- Gazebo launchfiles and tags + - e.g. `sim.ign` → `sim.gzlaunch`, ` `gzerr` +- `ignwarn` -> `gzwarn` +- `ignmsg` -> `gzmsg` +- `igndbg` -> `gzdbg` +- `ignlog` -> `gzlog` +- `ignLogInit` -> `gzLogInit` +- `ignLogClose` -> `gzLogClose` +- `ignLogDirectory` -> `gzLogDirectory` + +#### Migrate SDF + +In `.sdf` files: + +```cpp +Find: /dev/null; then + $(which ign) "$@" + else + if which gz &> /dev/null; then + echo "[DEPRECATED] ign is deprecated! Please use gz instead!" + if [ "$1" = "gazebo" ]; then + echo "[DEPRECATED] The gazebo verb is deprecated! Please use sim instead!" + shift + $(which gz) sim "$@" + else + $(which gz) "$@" + fi + else + echo "[ERROR] It seems like you don't have Gazebo installed!" + return 1 + fi + fi +} +``` + +### Double-Check + +These might be useful to double-check if you have any lingering stuff, or erroneously migrated instances + +You should match these **case-insensitively**. + +**Errors** + +- `gz-gazebo` +- `gzition` +- `an gz` + +**Remaining Ign** + +- `\.ign(ition)?` +- `ign(ition)?[-_]` + +## Additional Packages + +This section details changes that have taken place in some other Gazebo related packages. + + + +### ros_gz + +`ros_ign` has been renamed to `ros_gz`. +All internal references to `ign` or `ignition` that pre-Ionic versions of Gazebo don't rely on have been migrated. + +If you want to run `ros_gz` demos with custom sim version or sim args, use the `gz_version` and `gz_args` launch parameters. +Using the `ign_version` launch parameter will also require you to explicitly set the `ign_args` launch parameters instead. diff --git a/ionic/moving_robot.md b/ionic/moving_robot.md new file mode 100644 index 000000000..51c7ef14a --- /dev/null +++ b/ionic/moving_robot.md @@ -0,0 +1,173 @@ +# Moving the robot + +In this tutorial we will learn how to move our robot. We will use the +robot we built in the [Build your own robot](building_robot) +tutorial. You can download the robot from [here](https://github.com/gazebosim/docs/blob/master/ionic/tutorials/building_robot/building_robot.sdf). +You can also find the finished world of this tutorial [here](https://github.com/gazebosim/docs/blob/master/ionic/tutorials/moving_robot/moving_robot.sdf). + +## What is a plugin + +To make our robot move we will use the `diff_drive` plugin. But before doing so let's answer the question "What is a plugin?" A plugin is a chunk of code that is compiled as a shared library and inserted into the simulation. Plugins make us control many aspects of the simulation like world, models, etc. + +### Diff_drive plugin + +`diff_drive` plugin helps us control our robot, specifically a robot that +can be differentially driven. Let's setup the plugin on our robot. Open +the `building_robot.sdf` and add the following code within the `vehicle_blue` +model tags. + +```xml + + left_wheel_joint + right_wheel_joint + 1.2 + 0.4 + 1 + cmd_vel + +``` + +The `` tag has two attributes, `filename` which takes the library file name and `name` which takes the name of the plugin. +In the `` and `` tags we define the joints which connect the left and the right wheel with the body of the robot, in our case `left_wheel_joint` and `right_wheel_joint`. `` takes the distance between the two wheels. +Our robot has its `left_wheel` at 0.6 m and the `right_wheel` at -0.6 m in y-axis with respect to the `chassis`, so the `wheel_separation` is 1.2 m. +`` takes the radius of the wheel which was defined in the `` tag under the wheel link. +`` sets the frequency at which the odometry is published at `/model/vehicle_blue/odometry`. +`cmd_vel` is the input `` to the `DiffDrive` plugin. + +## Topics and Messages + +Now our model is ready. We just need to send commands (messages) to it. +These messages will be published (sent) on the `cmd_vel` topic defined above. + +A topic is simply a name for grouping a specific set of messages or a particular service. +Our model will subscribe (listen) to the messages sent on the `cmd_vel` topic. + +Launch the robot world: + +`gz sim building_robot.sdf` + +In another terminal let's send a message to to our robot: + +`gz topic -t "/cmd_vel" -m gz.msgs.Twist -p "linear: {x: 0.5}, angular: {z: 0.05}"` + +Now you should have your robot moving in the simulation. + +**Note:** Don't forget to press the play button in the simulation. + +The command specifies the topic to publish to after the `-t` option. +After the `-m` we specify the message type. +Our robot expects messages of type `Twist` which consists of two components, `linear` and `angular`. +After the `-p` option we specify the content (value) of the message: linear speed `x: 0.5` and angular speed `z: 0.05`. + +**Hint:** You can know what every topic option does using this command: `gz topic -h` + +For more information about `Topics` and `Messages` in Gazebo check the [Transport library tutorials](https://gazebosim.org/api/transport/9.0/tutorials.html) + +## Moving the robot using the keyboard + +Instead of sending messages from the terminal we will send messages using the keyboard keys. To do so we will add two new plugins: `KeyPublisher` and `TriggeredPublisher`. + +### KeyPublisher + +`KeyPublisher` is an `gz-gui` plugin that reads the keyboard's keystrokes and sends them on a default topic `/keyboard/keypress`. +Let's try this plugin as follows: + +* In one terminal type + + `gz sim building_robot.sdf` + +* In the top right corner click on the plugins dropdown list (vertical ellipsis), click the Key Publisher. + +* In another terminal type + + `gz topic -e -t /keyboard/keypress` + +The last command will display all messages sent on `/keyboard/keypress` topic. + +In the Gazebo window press different keys and you should see data (numbers) on the terminal where you run the `gz topic -e -t /keyboard/keypress` command. + +![KeyPublisher](tutorials/moving_robot/keypublisher_data.png) + +We want to map these keystrokes into messages of type `Twist` and publish them to the `/cmd_vel` topic which our model listens to. +The `TriggeredPublisher` plugin will do this. + +### Triggered Publisher + +The `TriggeredPublisher` plugin publishes a user specified message on an output topic in response to an input message that matches user specified criteria. +Let's add the following code under the `` tag: + +```xml + + + + 16777235 + + + linear: {x: 0.5}, angular: {z: 0.0} + + +``` + +This code defines the `triggered-publisher` plugin. +It accepts messages of type `gz.msgs.Int32` on the `/keyboard/keypress` topic and if the value in the `data` field matches `16777235`(Up arrow key) it outputs a `Twist` message on the `cmd_vel` topic with values `x: 0.5`, `z: 0.0`. + +Now launch `building_robot.sdf` then add the Key Publisher plugin and our robot should move forward as we press the Up arrow key ↑ (make sure you start the simulation by pressing the play button to see the robot move forward after pressing the Up arrow key). + +There is a demo explaining how the [Triggered Publisher](https://github.com/gazebosim/gz-sim/blob/gz-sim7/tutorials/triggered_publisher.md) works. + +### Moving using arrow keys + +To see what values are sent on the `/keyboard/keypress` topic when pressing the arrows we can use the `--echo` or `-e` option + +* Run the model in one terminal: + + `gz sim building_robot.sdf` + +* In the top right corner click on the plugins dropdown list (vertical ellipsis), click the Key Publisher. + +* In another terminal run the following command: + + `gz topic -e -t /keyboard/keypress` + +Start pressing the arrows keys and see what values they give: + +* Left ← : 16777234 +* Up ↑ : 16777235 +* Right → : 16777236 +* Down ↓ : 16777237 + +We will add the `Triggered publisher` plugin for each arrow key. +For example, the Down arrow: + +```xml + + + + 16777237 + + + linear: {x: -0.5}, angular: {z: 0.0} + + +``` + +Map each arrow (key stroke) with the desired message (movement) as we did with the backward arrow: + +* Left ➞ 16777234 ➞ linear: {x: 0.0}, angular: {z: 0.5} +* Up ➞ 16777235 ➞ linear: {x: 0.5}, angular: {z: 0.0} +* Right ➞ 16777236 ➞ linear: {x: 0.0}, angular: {z: -0.5} +* Down ➞ 16777237 ➞ linear: {x: -0.5}, angular: {z: 0.0} + +Now it's your turn try to make the robot move using different keys. + +In the [next tutorial](sdf_worlds), you'll learn to create your own simulated world with SDF. + +## Video walk-through + +A video walk-through of this tutorial is available from our YouTube channel: [Gazebo tutorials: Moving robot](https://youtu.be/oHtQYPDGk3Y). + + diff --git a/ionic/ros2_integration.md b/ionic/ros2_integration.md new file mode 100644 index 000000000..74eb62970 --- /dev/null +++ b/ionic/ros2_integration.md @@ -0,0 +1,112 @@ +# ROS 2 Integration + +In this tutorial we will learn how to Integrate ROS 2 with Gazebo. We will establish +communication between them. This can help in many aspects; we can receive data (like joint states, TFs) or commands +from ROS and apply it to Gazebo and vice versa. This can also help to enable RViz to visualize a robot model +simulatenously simulated by a Gazebo world. + +## ros_gz_bridge + +[`ros_gz_bridge`](https://github.com/gazebosim/ros_gz) provides a network bridge which enables the exchange of messages between ROS 2 and [Gazebo Transport](https://github.com/gazebosim/gz-transport). Its support is limited to only certain message types. Please, check this [README](https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_bridge/README.md) to verify if your message type is supported by the bridge. + +## Requirements + +Please follow the [Install Gazebo and ROS document](/docs/latest/ros_installation) +before starting this tutorial. A working installation of ROS 2 and Gazebo is +required to go further. + +## Bidirectional communication + +We can initialize a bidirectional bridge so we can have ROS as the publisher and Gazebo as the subscriber or vice versa. + +For example: + +``` +ros2 run ros_gz_bridge parameter_bridge /TOPIC@ROS_MSG@GZ_MSG +``` + +The `ros2 run ros_gz_bridge parameter_bridge` command simply runs the `parameter_bridge` code from the `ros_gz_bridge` package. Then, we specify our topic `/TOPIC` over which the messages will be sent. The first `@` symbol delimits the topic name from the message types. Following the first `@` symbol is the ROS message type. + +The ROS message type is followed by an `@`, `[`, or `]` symbol where: + +* `@` is a bidirectional bridge. +* `[` is a bridge from Gazebo to ROS. +* `]` is a bridge from ROS to Gazebo. + +Have a look at these [examples]( https://github.com/gazebosim/ros_gz/blob/ros2/ros_gz_bridge/README.md#example-1a-gazebo-transport-talker-and-ros-2-listener) +explaining how to make communication connections from ROS to Gazebo and vice versa. + +## Publish key strokes to ROS + +Let's send messages to ROS using the `Key Publisher` an Gazebo plugin. + +**Note:** Make sure to have all workspaces you need (ROS, Gazebo and, `ros_gz`...) sourced. + + +First we will start a bridge between ROS and Gazebo specifying the topic +at which the `Key Publisher` plugin sends messages and also the type +of the messages as follows: + +``` +ros2 run ros_gz_bridge parameter_bridge /keyboard/keypress@std_msgs/msg/Int32@gz.msgs.Int32 +``` + +We started a bridge on `/keyboard/keypress` topic with message of type `Int32`. +For ROS it is `std_msgs/msg/Int32` and for Gazebo it is `gz.msgs.Int32` + +In another terminal launch an Gazebo Sim world, for example the `empty.sdf` world: + +``` +gz sim empty.sdf +``` + +Then add the `Key Publisher` plugin from the dropdown menu on the top right corner. + +![empty_world_with_KeyPublisher](tutorials/ros2_integration/empty_world.png) + +In another terminal start the ROS listener: + +``` +ros2 topic echo /keyboard/keypress +``` + +This command listens to the messages sent over the `/keyboard/keypress` topic. + +On the Gazebo window, press on the keyboard keys and you should +find data on the listener terminal. + +Now it's your turn! Try to send data from ROS to Gazebo. You can also try different data types and different directions of communication. + +## Video walk-through + +A video walk-through of this tutorial is available from our YouTube channel: [Gazebo tutorials: ROS 2 Foxy integration](https://youtu.be/IpZTNyTp9t8). + + + +## Visualize in RViz + +Take a step further and try out demos from [`ros_gz_sim_demos`](https://github.com/gazebosim/ros_gz/tree/ros2/ros_gz_sim_demos). + +For the `sdf_parser` demo, install [`ros_gz`](https://github.com/gazebosim/ros_gz/tree/ros2) and the parser plugin `sdformat_urdf` from source in a colcon workspace. +Read more about `sdformat_urdf` [here](https://github.com/ros/sdformat_urdf/blob/ros2/sdformat_urdf/README.md). + +Run the demo launch file with the rviz launch argument set: + +```bash +ros2 launch ros_gz_sim_demos sdf_parser.launch.py rviz:=True +``` + +Start the simulation in Gazebo and wait a few seconds for TFs to be published. + +In another terminal, send either ROS or Gazebo commands for the vehicle to move in circles: + +```bash +gz topic -t "/model/vehicle/cmd_vel" -m gz.msgs.Twist -p "linear: {x: 1.0}, angular: {z: -0.1}" +ros2 topic pub /model/vehicle/cmd_vel geometry_msgs/msg/Twist "{linear: {x: 5.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: -0.1}} +``` + +And verify the vehicle matching its trajectory in Gazebo and RViz. + +![gz_rviz](tutorials/ros2_integration/gz_rviz.gif) + +For more details on implementation of this demo see [ROS 2 Interoperability](ros2_interop). diff --git a/ionic/ros2_interop.md b/ionic/ros2_interop.md new file mode 100644 index 000000000..197b832c6 --- /dev/null +++ b/ionic/ros2_interop.md @@ -0,0 +1,115 @@ +# ROS 2 Interoperability + +`rrbot` is a simple two-link robotic arm with revolute joints, and this tutorial serves as an illustrative example using the same to demonstrate the interoperability of ROS 2 and Gazebo Sim. + +## Overview +We'll leverage ROS 2's communication and control mechanisms to interact with the robot. Gazebo is used as the simulation environment, providing realistic physics simulation and visualization of the `rrbot` robot arm. +The robot model is described using [SDFormat](http://sdformat.org/) (Simulation Description Format), which defines the robot's structure, joints, links, and their properties. +While Gazebo's physics engine simulates the dynamics of the robot, [RViz](https://github.com/ros2/rviz), a visualization tool in ROS 2, displays the robot model and its motion based on data published by the control nodes, all using the same robot description file. +Users can interact with `rrbot` through ROS 2 commands to move the robot's arms or retrieve joint state information. + +## Prerequisites + +1. A working installation of ROS 2 and Gazebo is required to go further. Please follow the [Install Gazebo and ROS document](/docs/latest/ros_installation). +2. Basic familiarity with ROS concepts and terminal commands. +3. Check out [ROS 2 Integration](ros2_integration) to get familiar with [`ros_gz_bridge`](https://github.com/gazebosim/ros_gz) before starting this tutorial. + +## Setup + +Start a fresh ROS 2 Python launch file or add the following nodes in your project's main launch file. We aim to achieve: +1. A robot model development and test setup +2. Configure RViz (and other ROS 2 tools) to control a robot model simulated by a Gazebo world + +Note: The full source code for this tutorial can be found in the [ros_gz_example_bringup package](https://github.com/gazebosim/ros_gz_project_template/tree/main/ros_gz_example_bringup/launch) launch files. + +## Implementation + +### Load robot description to the parameter server + +Load the robot description file to set the `robot_description` parameter on the parameter server. + +```python + sdf_file = os.path.join(pkg_project_description, 'models', 'rrbot', 'model.sdf') + with open(sdf_file, 'r') as infp: + robot_desc = infp.read() +``` + +### Launch state publisher nodes + +For publishing and controlling the robot pose, we need joint states of the robot. + +![jsp](tutorials/ros2_integration/jsp_diagram.jpg) + +1. The [`joint_state_publisher`](https://github.com/ros/joint_state_publisher) reads the `robot_description` parameter from the parameter server, finds all of the non-fixed joints and publishes a [JointState](https://docs.ros.org/en/api/sensor_msgs/html/msg/JointState.html) message with all those joints defined. + ```python + joint_state_publisher_gui = Node( + package='joint_state_publisher_gui', + executable='joint_state_publisher_gui', + name='joint_state_publisher_gui', + arguments=[sdf_file], + output=['screen'] + ) + ``` +2. Visualize in RViz and with the help of the `joint_state_publisher_gui`, configure your robot model by adjusting joint states and poses using the slider. + + ![jsp_gui](tutorials/ros2_integration/jsp_gui.png) + + See [documentation](http://docs.ros.org/en/rolling/p/joint_state_publisher_gui/) for node API. + This functionality is useful during initial development of the model. + At this point we have achieved the first aim defined in [Setup](#setup). + +3. Now if you'd want to extend this to visualize robot motion, we need positions and transforms. + The [`robot_state_publisher`](https://github.com/ros/robot_state_publisher) takes the description and joint angles of the robot as inputs and publishes the 3D poses of the robot links, using a kinematic tree model of the robot. + ```python + robot_state_publisher = Node( + package='robot_state_publisher', + executable='robot_state_publisher', + name='robot_state_publisher', + output='both', + parameters=[ + {'use_sim_time': True}, + {'robot_description': robot_desc}, + ] + ) + ``` + These 3D poses are published on the `/tf` topic which is useful to track/plan the robot's motion, communicate between different parts of the robot or evaluate the robot's performance. + +### Configure a communication bridge + +These joint states can either come from `joint_state_publisher` as seen earlier or from simulated [JointStatePub](https://gazebosim.org/api/sim/8/classgz_1_1sim_1_1systems_1_1JointStatePublisher.html) system's `joint_state` message. + +Configure a bridge between ROS topic `/joint_states` and Gazebo topic `/world/demo/model/diff_drive/joint_state` by adding remappings in the node setup or by creating a [bridge.yaml](https://github.com/gazebosim/ros_gz_project_template/blob/main/ros_gz_example_bringup/config/ros_gz_example_bridge.yaml): + +```bash +- ros_topic_name: "/joint_states" + gz_topic_name: "/world/demo/model/diff_drive/joint_state" + ros_type_name: "sensor_msgs/msg/JointState" + gz_type_name: "gz.msgs.Model" + direction: GZ_TO_ROS +``` + +Learn more about the bridge from [ROS 2 Integration](ros2_integration). + +### Maintaining a single robot description format + +The main pain point of using existing simulation assets with ROS 2 tools was updating URDF files into a Gazebo-readable format. This is no longer required. If you are maintaining a URDF and an SDF file in a project, you can now drop the URDF and just use the SDF for both ROS and Gazebo. + +This is made possible by `sdformat_urdf`, a parser plugin library that converts an SDF file to URDF C++ DOM structures, making it understandle by the ROS 2 ecosystem. +Although, there are some limitations of the plugin, like not all SDFormat tags are compatible. For example, if you have any sensors attached to a joint, it won't be parsed. More details [here](https://github.com/ros/sdformat_urdf/tree/ros2/sdformat_urdf). + +To embed this functionality, we simply need to print the SDFormat file to the `/robot_description` ROS topic, and internally ROS will find a suitable parser, `sdformat_urdf` in this case, to read the file. This is already done while configuring the `robot_state_publisher` earlier. + +### Run RViz and Gazebo + +The second aim defined in [Setup](#setup) is essentially maintaining only one robot description format which now can be controlled directly with Gazebo. +Using the SDFormat XML description of a robot, the simulator publishes model joint states. +And `robot_state_publisher` handles turning those joint states into `tf`s which is used by RViz and other ROS tools. +This enables visualizing a model in RViz simulated by Gazebo. + +![gz_rviz](tutorials/ros2_integration/gz_rviz.gif) + +## Conclusion + +Configure this functionality to enhance your existing ROS and Gazebo project. +`ros_gz_project_template` provides an organized structure for ROS 2 and Gazebo projects, including necessary directories, build files, and launch scripts. +See [Getting Started with `ros_gz_project_template` for ROS 2 and Gazebo Development](ros_gz_project_template_guide) for guidance on using the template. diff --git a/ionic/ros_gz_project_template_guide.md b/ionic/ros_gz_project_template_guide.md new file mode 100644 index 000000000..92a01493f --- /dev/null +++ b/ionic/ros_gz_project_template_guide.md @@ -0,0 +1,137 @@ +# Guide to `ros_gz_project_template` for ROS 2 and Gazebo Development + +In this guide, you will learn how to use the `ros_gz_project_template` to create a (recommended) structured workspace or improve your existing workspace for your ROS 2 and Gazebo projects. This template offers a consistent layout, automated build process, and integration with both ROS 2 and Gazebo, enabling you to focus on developing your robotics applications. + +## Installation Steps + +1. If you are starting a project, create a new workspace or go to your existing project's source directory: + + ```bash + mkdir -p ~/project_ws/src + cd ~/project_ws/src + ``` + +2. Directly use the [`ros_gz_project_template` template](https://github.com/gazebosim/ros_gz_project_template) and create your project repository on GitHub. + + ![use_template](tutorials/ros2_integration/use_template.png) + + Or start by cloning the template repository: + + ```bash + wget https://raw.githubusercontent.com/gazebosim/ros_gz_project_template/main/template_workspace.yaml + vcs import < template_workspace.yaml + ``` + +3. Rename the cloned repository folder to your desired project name: + + ```bash + mv ros_gz_project_template your_project_name + ``` + +## Package structure + +At this point you'll have the following packages in your project: + +* `ros_gz_example_application` - holds ROS 2 specific code and configurations. Namely where control, planning or any high level algoritms reside. + + 
 ├── CMakeLists.txt
+   ├── package.xml
+   ├── src
+       └── ...
+
+ +* `ros_gz_example_bringup` - holds launch files and high level utilities, communication bridge between ROS and Gazebo. Any robot or hardware specific configurations go here. + + 
 ├── config
+   │   ├── ros_gz_example_bridge.yaml
+   │   └── diff_drive.rviz
+   ├── launch
+       └── diff_drive.launch.py
+
+ +* `ros_gz_example_description` - holds the SDF description of the simulated system and any other [simulation assets](#accessing-simulation-assets). + + 
 ├── hooks
+   │   └── ros_gz_example_description.dsv.in
+   ├── models
+       ├── diff_drive
+           ├── model.config
+           └── model.sdf
+
+ +* `ros_gz_example_gazebo` - holds Gazebo specific code and configurations. Namely this is where user-defined worlds and custom system plugins end up. + + 
 ├── include
+   │   └── ros_gz_example_gazebo
+   │       ├── BasicSystem.hh
+   │       └── FullSystem.hh
+   ├── src
+   │   ├── BasicSystem.cc
+   │   └── FullSystem.cc
+   ├── worlds
+           └── diff_drive.sdf
+
+ +## Accessing Simulation Assets + +Simulation assets include your models or robot descriptions in URDF or SDF, meshes and materials files to help visualize different parts of the robot and finally compiling all these elements in a simulated world SDF. Gazebo offers a few different mechanisms for locating those, initializing it's search on `GZ_SIM_RESOURCE_PATH` environment variable, see gz-sim API on [finding resources](https://gazebosim.org/api/sim/8/resources.html) for more details. + +There is a difference in how ROS and Gazebo resolves URIs, that the ROS side can handle `package://` URIs, but by default SDFormat only supports `model://`. Now `libsdformat` can convert `package://` to `model://` URIs. So existing simulation assets can be loaded by "installing" the models directory and exporting the model paths to your environment. + +This can be automated using colcon environment hooks (shell scripts provided by a ROS package) in a [DSV file](https://colcon.readthedocs.io/en/released/developer/environment.html?highlight=dsv#dsv-files). Whenever you source the setup file in a workspace these environment hooks are also being sourced. See an [example](https://github.com/gazebosim/ros_gz_project_template/blob/main/ros_gz_example_gazebo/hooks/ros_gz_example_gazebo.dsv.in) of prepending the model share path to `GZ_SIM_RESOURCE_PATH` which enables Gazebo to load models from a ROS package using the `model://` URI. + +## Development + +1. Choose a ROS and Gazebo [combination](ros_installation) + + Note: If you're using a specific and unsupported Gazebo version with ROS 2, you might need to set the `GZ_VERSION` environment variable, for example: + + ```bash + export GZ_VERSION=ionic + ``` + +2. Install dependencies + + ```bash + cd ~/project_ws + source /opt/ros//setup.bash + sudo rosdep init + rosdep update + rosdep install --from-paths src --ignore-src -r -i -y --rosdistro + ``` + +3. Modify + + Explore the `src/your_project_name` directory to add/modify the packages associated with your project. + There are two primary mechanisms to integrate ROS 2 and Gazebo depending on your application: + 1. Use [ros_gz_bridge](https://github.com/gazebosim/ros_gz) to dynamically connect topics between ROS 2 and Gazebo (which is demonstrated as an example in this template) + 2. Embed ROS 2 directly in a Gazebo system plugin + + The main consideration is in choosing the depth of integration is required between ROS and Gazebo. Using the bridge keeps dependencies separate and Gazebo systems don't have to know about ROS. By embedding ROS 2 nodes directly allows accessing the [EntityComponentManager](https://gazebosim.org/api/sim/8/classgz_1_1sim_1_1EntityComponentManager.html) within a Gazebo plugin. + +4. Build + + ```bash + cd ~/project_ws + colcon build --cmake-args -DBUILD_TESTING=ON + ``` + +## Usage + +1. Source the workspace + + ```bash + . ~/project_ws/install/setup.sh + ``` + +2. Launch the simulation and visualize in RViz: + + To visualize your robot model and the data generated by your ROS 2 nodes, open a new terminal and launch: + + ```bash + ros2 launch ros_gz_example_bringup diff_drive.launch.py + ``` + +## ROSCon 2022 + +Check out a ROSCon 2022 talk titled [ROS 2 and Gazebo Integration Best Practices](https://vimeo.com/showcase/9954564/video/767127300), to learn more about best practices of integrating simulation with ROS 2, drawn from accumulated experience and successful deployments. The talk will additionally cover tips and techniques to ease migration to the latest versions. diff --git a/ionic/sdf_worlds.md b/ionic/sdf_worlds.md new file mode 100644 index 000000000..a52d06504 --- /dev/null +++ b/ionic/sdf_worlds.md @@ -0,0 +1,320 @@ +# SDF worlds + +In this tutorial we will learn how to build our world using SDF, and how to add models to it. Open your text editor and add code as you follow along with this tutorial. You can also download the finished world for this tutorial from [here](https://github.com/gazebosim/docs/blob/master/ionic/tutorials/sdf_worlds/world_demo.sdf). + +## Defining a world + +Every SDF world starts with these tags. + +```xml + + + + ... + ... + + +``` + +The first two tags define the version of the `XML` and the `SDF`. Then we have the ` ` tags between which everything goes. + +## Physics + +```xml + + 0.001 + 1.0 + +``` + +The physics tag specifies the type and properties of the dynamic engine. We chose the `name` `1ms` as the step size is 1 millisecond. The `type` is the type of the dynamic engine (physics library). There are options like, Ode, Bullet, Simbody and Dart. We set it to `ignored`, as choosing the type of the physics engine is not done through this tag yet. + +`` is the maximum time at which every system in simulation can interact with the states of the world. The smaller the value, the more accurate your calculations, but more computation power is needed. +`` is the ratio of simulation time to real time. + +## Plugins + +Plugins are a dynamically loaded chunk of code. For example: + +```xml + + +``` + +The `Physics` plugin is very important for simulating the dynamics of the world. + +```xml + + +``` + +The `UserCommands` plugin is responsible for creating models, moving models, deleting them and many other user commands. + +```xml + + +``` + +`SceneBroadcaster` shows our world scene. + +## GUI + +Now let's define the GUI. Under the `` tag we specify anything related to the `GUI` of Gazebo. + +```xml + + ... + ... + +``` + +[gazebo-gui](https://github.com/gazebosim/gz-gui/) has a bunch of plugins to choose from. We will add the ones that are necessary to get our world up and running with basic functionality. + +```xml + + + + 3D View + false + docked + + + ogre2 + scene + 0.4 0.4 0.4 + 0.8 0.8 0.8 + -6 0 6 0 0.5 0 + + 0.25 + 25000 + + + + + false + 5 + 5 + floating + false + + +``` + +`MinimalScene` and `GzSceneManager` are responsible for displaying the 3D scene of our world. +It has the following properties (most of the GUI plugins have them): + +* `showTitleBar` if true it will show the blue title bar over the plugin with the name mentioned in the `` tag. +* `state` is the state of the plugin it can be docked in its place using `docked` or it can be `floating`. + +For the rendering engine we can choose `ogre` or `ogre2`. The `<ambient_light>` and the `<background_color>` specify the ambient and the background color of the scene. `<camera_pose>` specifies the `X Y Z` position of the camera followed by its rotation in `Roll Pitch Yaw`. + +### World control plugin + +```xml +<!-- World control --> +<plugin filename="WorldControl" name="World control"> + <gz-gui> + <title>World control + false + false + 72 + 121 + 1 + + floating + + + + + + + true + true + true + /world/world_demo/control + /world/world_demo/stats + +``` + +The `World control` plugin is responsible for controlling the world. Some of its properties are the following: + +* `` if `true` we will have the play-pause button on the bottom left corner. +* `` tag specifies the topic at which the world stats like simulation time and real time are published on. +* `` if `true` the simulation will be paused at the start of +Gazebo. + +### World stats plugin + +```xml + + + + World stats + false + false + 110 + 290 + 1 + + floating + + + + + + + true + true + true + true + /world/world_demo/stats + + +``` + +The `World stats` plugin is responsible for displaying the world statistics, +``, ``, `` and ``. + +With these tags we can choose what values to display (expand the bottom right corner to see these values). We can choose which `` these values will be published on. Let's try to run the world and listen to that topic. + +Run the world: + +`gz sim world_demo.sdf` + +Press the play button and in another terminal listen to the messages: + +`gz topic -e -t /world/world_demo/stats` + +The message should look like this: + +![world_shapes_stats](tutorials/sdf_worlds/world_stats.png) + +### Entity tree + +```xml + + + +``` + +In this plugin we can see all the entities of our world (everything in simulation is considered an "entity"). We can see the different models, sun and also their links, visuals and collisions. + +![Entity tree plugin](tutorials/sdf_worlds/entity_tree.png) + +It is blank because we didn't add anything to our world yet. + +There are a bunch of useful gz-gui plugins like the `Transform control` plugin that allows us to manipulate different components of our world, and translate and rotate the entities. Check out this [tutorial](manipulating_models) explaining how to manipulate models. + +The plugins can also be added from the GUI using the plugin drop-down menu in the top right corner of Gazebo. Now that we are done with the GUI, let's add different elements to our world. **Don't** forget to add the closing tag ``. + +## Light + +```xml + + true + 0 0 10 0 0 0 + 0.8 0.8 0.8 1 + 0.2 0.2 0.2 1 + + 1000 + 0.9 + 0.01 + 0.001 + + -0.5 0.1 -0.9 + +``` + +* `` specifies the light source in the world. The `` of the light can be `point`, `directional` or `spot`. +* `` is the position (x,y,z) and orientation (roll, pitch, yaw) of the light element with respect to the frame mentioned in the `relative_to attribute`; in our case (`relative_to` attribute is ignored) it is relative to the world. +* `` when true the light will cast shadows. `` and `` are the diffuse and specular light color. +* `` specifies the light attenuation properties, which are: + + * `` is range of light. + * `` is the constant attenuation factor, `1` never attenuate and `0` complete attenuation. + * `` is the linear attenuation factor, `1` means attenuate evenly over the distance. + * `` is the quadratic attenuation factor. It adds curvature to the attenuation. + * `` is direction of the light, only applicable to spot and directional light. + +## Adding models + +Instead of building our own models we can use already built ones. [Gazebo Fuel](https://app.gazebosim.org/fuel) hosts hundreds of models that can easily be added to an Gazebo world. Models can be added as follows. + +### Spawning a model + +For adding various models from fuel to your world chekout this [tutorial](fuel_insert). + +### Include the model URI + +Another way of adding the model to your world is to use the model link. Visit the [Gazebo Fuel website](https://app.gazebosim.org/fuel). Choose the model you like and click on the `<>` icon on the model description page. This will copy an SDF snippet to your clipboard, then paste it in your world right above the closing `` tag, like this: + +```xml + + + https://fuel.gazebosim.org/1.0/OpenRobotics/models/Coke + + +``` + +### Download the model + +The previous methods download your model on run time. For saving the model permanently you can download the model from fuel, and then refer to it like this: + +```xml + + + model://Coke + + +``` + +We need to set `GZ_SIM_RESOURCE_PATH` environment variable to the parent folder of our model. For example, if our directory looks like this: + +``` +world_tutorial
+├── Coke
+└── world_demo.sdf +``` + +Then we have to set it to the `world_tutorial` directory, like this: + +`export GZ_SIM_RESOURCE_PATH="$HOME/world_tutorial"` + +Run your world: + +`gz sim world_demo.sdf` + +You should see the model in the origin of the world. + +![world with can](tutorials/sdf_worlds/coke_world.png) + +You can also set its coordinates using the `` tag. +If you want to spawn multiple instances of the same model you must give them different names with the `` tag. + +``` + + Coke0 + 0 0 0 0 0 0 + https://fuel.gazebosim.org/1.0/OpenRobotics/models/Coke + + + Coke1 + 0 0.1 0 0 0 0 + https://fuel.gazebosim.org/1.0/OpenRobotics/models/Coke + +``` +![two cans](tutorials/sdf_worlds/two_cokes.png) + +Now that you have a custom world, the [next tutorial](sensors) will teach you how to add sensors to a robot to allow it to interact with the world around it. + +## Video walk-through + +A video walk-through of this tutorial is available from our YouTube channel: [Gazebo tutorials: Creating worlds](https://youtu.be/48TX-XJ14Gs). + + diff --git a/ionic/sensors.md b/ionic/sensors.md new file mode 100644 index 000000000..c1a26d14a --- /dev/null +++ b/ionic/sensors.md @@ -0,0 +1,427 @@ +# Sensors + +**Note:** This tutorial is a continuation from the +[Moving the robot tutorial](moving_robot). + +In this tutorial we will learn how to add sensors to our robot and +to other models in our world. We will use three different sensors: +an IMU sensor, a Contact sensor and a Lidar sensor. We will also +learn how to launch multiple tasks with just one file using `gz launch`. + +You can find the final world of this tutorial [here](https://github.com/gazebosim/docs/blob/master/ionic/tutorials/sensors/sensor_tutorial.sdf) + +## IMU sensor + +The inertial measurement unit (IMU) outputs the `orientation` of our +robot in quaternions, the `angular_velocity` in the three axes (X, Y, Z), +and the `linear_acceleration` in the three axes. Let's use our +[moving_robot.sdf](https://github.com/gazebosim/docs/blob/master/ionic/tutorials/moving_robot/moving_robot.sdf) world and modify it. Create a new file +`sensor_tutorial.sdf` and add the code from `moving_robot.sdf` to it. +To define the `IMU` sensor add this code under the `` tag: + +```xml + + +``` + +This code defines the `IMU` sensor plugin to be used in our world. +Now we can add the `IMU` sensor to our robot as follows: + +```xml + + 1 + 1 + true + imu + +``` + +The sensor is usually added to one of the links of our model; we added + it under the `chassis` link. + +Let's describe the tags: + + * `` if true the sensor will always be updated + according to the update rate. + * `` the frequency at which the sensor data is generated. + * `` if true the sensor is visualized in the GUI. + * `` name of the topic on which data is published. + +**Note:** Not all the tags are supported for all sensors yet. + +### Read data from IMU + +To read the data from the `IMU`, run the world in one terminal and press the play button: + +`gz sim sensor_tutorial.sdf` + +In another terminal, run: + +`gz topic -e -t /imu` + +The last command listens to the messages sent over the `/imu` topic. The IMU data are `orientation`, `angular_velocity` and `linear_acceleration` as described above. It should look like this: + +![Imu_message](tutorials/sensors/imu_msgs.png) + +Move your robot forward using the keyboard up key. You should see the sensor values changing. + +## Contact sensor + +Let's introduce a different type of sensor, the `contact` sensor. +You can guess from the name that this sensor gives indication when +it touches (contacts) something else. We will build an obstacle (wall) +and add the contact sensor to it. If the robot hits the obstacle it will +stop, preventing the robot from damaging itself. Let's first build the +obstacle as follows: + +```xml + + true + 5 0 0 0 0 0 + + + + + 0.5 10.0 2.0 + + + + + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + + + + + + 0.5 10.0 2.0 + + + + + +``` + +It is just a simple model with one link of box shape. You can check the [Build your own robot tutorial](building_robot) to learn how to build models. + +Now run the world and make sure that the wall appears in the simulation like this: + +![wall_in_world](tutorials/sensors/sensor_wall.png) + +Let's add the contact sensor to the wall. As with the `IMU` sensor, we should first define the `Contact` sensor by adding the following code: + +```xml + + +``` + +Now we can add the `contact` sensor to the `box` link of the `wall` model: + +```xml + + + collision + + +``` + +The definition of the `` is straight forward, we just define the `name` and the `type` of the sensor. And inside the `collision` we define the box link collision name which is `collision`. + +We need also to add the `TouchPlugin` under the `wall` model as follows: + +```xml + + vehicle_blue + wall + + true + +``` + +The `TouchPlugin` will publish (send) a message when the `wall` +has been touched. The tags of the plugin are as follows: + +* `` which will be in contact with our wall, in our case `vehicle_blue`. +* `` takes the namespace of our topic, so when our robot hits the wall it will send a message to `/wall/touched` topic. + + Run the world in one terminal: + +`gz sim sensor_tutorial.sdf` + +In another terminal, listen to the `/wall/touched` topic: + +`gz topic -e -t /wall/touched` + +Drive your robot forward to the wall using the keyboard arrow keys. Make sure to start the simulation by hitting the play button, and enable the Key Publisher plugin as well by clicking on the plugins dropdown list (vertical ellipsis), then selecting "Key Publisher". + +When you hit the bump you should see a message `data: true` on the terminal where you ran the `gz topic -e -t /wall/touched`. + +Now we can use the `TriggeredPublisher` plugin to make our robot stop when hits the wall as follows: + +```xml + + + data: true + + + linear: {x: 0.0}, angular: {z: 0.0} + + +``` + +As explained in the [Moving robot tutorial](moving_robot), +we can publish an output depending on a received input. So when we receive +`data: true` on the `/wall/touched` topic we publish +`linear: {x: 0.0}, angular: {z: 0.0}` to make our robot stop. + +## Lidar sensor + +We don't want our robot to touch the wall at all because this may cause some damage, so instead of the contact sensor we can use the Lidar. Lidar is an acronym for "light detection and ranging". This sensor can help us detect obstacles around the robot. We will use it to measure the distance between our robot and the wall. + +First let's create a frame to fix our lidar to. This should be added inside of the `vehicle_blue` `` tag, since the lidar frame is attached to the robot's `chassis`: + +```xml + + 0.8 0 0.5 0 0 0 + +``` + +Then add this plugin under the `` tag, to be able to use the `lidar` sensor: + +```xml + + ogre2 + +``` + +Under the `chassis` link we can add the `lidar` sensor as follows: + +```xml +" + 0 0 0 0 0 0 + lidar + 10 + + + + 640 + 1 + -1.396263 + 1.396263 + + + 1 + 0.01 + 0 + 0 + + + + 0.08 + 10.0 + 0.01 + + + 1 + true + +``` + +* First we defined the `name` and `type` of our sensor, then we defined its +`` relative to the `lidar_frame`. +* In the `` we define the topic on which the lidar data will be published. +* `` is the frequency at which the `lidar` data is generated, in +our case `10 Hz` which is equal to `0.1 sec`. +* Under the `` and `` tags we define the properties of the +horizontal and vertical laser rays. +* `` is the number of simulated lidar rays to generate per complete +laser sweep cycle. +* ``: this number is multiplied by samples to determine the number +range data points. +* The `` and `` are the angle range of the generated rays. +* Under the `` we define range properties of each simulated ray + * `` and `` define the minimum and maximum distance for each lidar ray. + * The `` tag here defines the linear resolution of each lidar ray. + * ``: if true the sensor will always be updated according to the ``. + * ``: if true the sensor is visualized in the GUI. + +Now run the world and press the play button in the bottom-left corner: + +`gz sim sensor_tutorial.sdf` + +Look at the lidar messages on the `/lidar` topic, specifically the `ranges` data: + +`gz topic -e -t /lidar` + +The lidar message has the following attributes: + +``` +message LaserScan +{ + Header header = 1; + + string frame = 2; + Pose world_pose = 3; + double angle_min = 4; + double angle_max = 5; + double angle_step = 6; + double range_min = 7; + double range_max = 8; + uint32 count = 9; + double vertical_angle_min = 10; + double vertical_angle_max = 11; + double vertical_angle_step = 12; + uint32 vertical_count = 13; + + repeated double ranges = 14; + repeated double intensities = 15; +} +``` + +### Avoid the wall + +Now as we have the lidar on our robot, we can use the `ranges` data +and make our robot avoid hitting the wall. +To do that, we'll write a short C++ program that listens to +the sensor data and sends velocity commands to the robot. +This program is called a node. We will build a node that subscribes +to the `/lidar` topic and reads its data. +Have a look at this [tutorial](https://gazebosim.org/api/transport/9.0/messages.html) +to learn how to build a `publisher` and a `subscriber` node. +You can download the finished node for this demo from [here](https://github.com/gazebosim/docs/blob/master/ionic/tutorials/sensors/lidar_node.cc). + +#### The lidar_node + +```cpp +gz::transport::Node node; +std::string topic_pub = "/cmd_vel"; +gz::msgs::Twist data; +auto pub = node.Advertise(topic_pub); +``` + +We declare a `node` which will publish to `cmd_vel` topic and defined the message type `Twist`. Then advertise our node. + +```cpp +void cb(const gz::msgs::LaserScan &_msg) +{ + bool allMore = true; + for (int i = 0; i < _msg.ranges_size(); i++) + { + if (_msg.ranges(i) < 1.0) + { + allMore = false; + break; + } + } + if (allMore) //if all bigger than one + { + data.mutable_linear()->set_x(0.5); + data.mutable_angular()->set_z(0.0); + } + else + { + data.mutable_linear()->set_x(0.0); + data.mutable_angular()->set_z(0.5); + } + pub.Publish(data); +} +``` + +Inside the callback function we check if the range of all rays are bigger than `1.0`. +If so we publish a message to our car to move forward. Otherwise we make the robot rotate. + +```cpp +int main(int argc, char **argv) +{ + std::string topic = "/lidar"; + // Subscribe to a topic by registering a callback. + if (!node.Subscribe(topic, cb)) + { + std::cerr << "Error subscribing to topic [" << topic << "]" << std::endl; + return -1; + } + + // Zzzzzz. + gz::transport::waitForShutdown(); + + return 0; +} +``` + +Inside the main we subscribe to the `lidar` topic, and wait until the node is shut down. + +#### Build the node + +Download the [CMakeLists.txt](https://github.com/gazebosim/docs/blob/master/ionic/tutorials/sensors/CMakeLists.txt), and in the same folder of `lidar_node` create `build/` directory: + +```{.sh} +mkdir build +cd build +``` + +Run cmake and build the code: + +```{.sh} +cmake .. +make lidar_node +``` + +##### Run the node + +Run the node from terminal 1: + +```{.sh} +./build/lidar_node +``` + +Run the world from terminal 2: + +```{.sh} +gz sim sensor_tutorial.sdf +``` + +Now you can see the robot move forward and as it approaches the wall it starts to turn left until it's clear and moves forward again (be sure to press the play button in the bottom-left corner to make the robot start moving). + +## Gazebo launch + +Instead of running two different tasks from two different terminals we can make a launch file which will run the `sensor_world` and the `lidar_node` at the same time. Open your text editor and add the following code. + +```xml + + + + gz sim sensor_tutorial.sdf + + + + ./build/lidar_node + + + +``` + +The launch file is an XML file. We simply define what commands will run under the `` tag. +The first command is `gz sim sensor_tutorial.sdf` which launches the world. +And the second command is `./build/lidar_node` which runs the `lidar_node`. +Save the file as `sensor_launch.gzlaunch`, and then run it using the following command: + +```{.sh} +gz launch sensor_launch.gzlaunch +``` + +Press the play button to start the simulation. Hurray! Our robot is now moving and avoiding the wall. + +To add even more complexity to your simulation, learn how to add actors to a world in the [next tutorial](actors). + +## Video walk-through + +A video walk-through of this tutorial is available from our YouTube channel: [Gazebo tutorials: Sensors](https://youtu.be/WcFyGPEfhHc) + + diff --git a/ionic/spawn_urdf.md b/ionic/spawn_urdf.md new file mode 100644 index 000000000..abd95dedc --- /dev/null +++ b/ionic/spawn_urdf.md @@ -0,0 +1,56 @@ +# Spawn URDF + +This tutorial will cover how to spawn a URDF model in Gazebo Sim. +URDF files are often used in ROS to represent robot models. +While SDF can describe a world with multiple robot models, URDF can only describe one robot model. +More information about URDF can be found at [https://wiki.ros.org/urdf](https://wiki.ros.org/urdf). + +## Obtaining a URDF file + +This tutorial assumes that the reader already has a URDF file that they'd like to load into Gazebo Sim. +If you are looking for a URDF file to use, you can use the [`rrbot.urdf`](https://github.com/gazebosim/docs/blob/master/ionic/tutorials/spawn_urdf/rrbot.urdf) that was preprocessed for you. The `rrbot` robot model is from the [`gazebo_ros_demos`](https://github.com/ros-simulation/gazebo_ros_demos) package. You could also use one of the examples listed at [https://wiki.ros.org/urdf/Examples](https://wiki.ros.org/urdf/Examples). + +If you have a `xacro` representation of a robot model, you can turn the `xacro` file into a `URDF` file using the [`xacro`](https://index.ros.org/p/xacro/) package: see [this tutorial](https://docs.ros.org/en/humble/Tutorials/Intermediate/URDF/Using-Xacro-to-Clean-Up-a-URDF-File.html) for more information. + +## Spawning the URDF + +To spawn a URDF model in Gazebo Sim, we will start a world and make use of the world's `create` service, which uses the [EntityFactory](https://gazebosim.org/api/msgs/9/entity__factory_8pb_8h.html) message type. + +Start by launching an empty world in Gazebo Sim: +```bash +gz sim empty.sdf +``` + +You should see a window that looks like this: + +![empty_world](tutorials/spawn_urdf/empty_world.png) + +In another terminal, get the list of available services by running `gz service -l`. +Look for a `create` service. +You should see this service in the list: +``` +/world/empty/create +``` + +We can double-check that this is the service we want to use by running `gz service -is /world/empty/create`. +This will show us the service's request and response message types: +``` +gz.msgs.EntityFactory, gz.msgs.Boolean +``` + +Now that we have found the service that has an `EntityFactory` request type, we can call this service and pass the URDF file to the service's request so that the robot represented by this URDF file is spawned in the Gazebo Sim world. +We do this by setting the desired URDF file to the `sdf_file_name` field of the `EntityFactory` request message. +The [libsdformat](https://gazebosim.org/libs/sdformat) library will then internally convert the URDF file to an SDF representation, and load this into the running world. + +The following command spawns the URDF file `model.urdf` into the Gazebo Sim world as a model named `urdf_model`: +```bash +gz service -s /world/empty/create --reqtype gz.msgs.EntityFactory --reptype gz.msgs.Boolean --timeout 1000 --req 'sdf_filename: "/path/to/model.urdf", name: "urdf_model"' +``` + +If `model.urdf` is the URDF representation of [rrbot.xacro](https://github.com/ros-simulation/gazebo_ros_demos/blob/kinetic-devel/rrbot_description/urdf/rrbot.xacro) in the `gazebo_ros_demos` package, executing the service call above should result in a simulation that now looks like this: + +![urdf_spawned](tutorials/spawn_urdf/urdf_spawned.png) + +We can now play the simulation to make sure that the loaded URDF model behaves as expected: + +![urdf_arm_falling](tutorials/spawn_urdf/rrbot.gif) diff --git a/ionic/troubleshooting.md b/ionic/troubleshooting.md new file mode 100644 index 000000000..146bc40ab --- /dev/null +++ b/ionic/troubleshooting.md @@ -0,0 +1,210 @@ +# Troubleshooting + +## Gazebo libraries are not found +If you see this error message: + +```bash +I cannot find any available 'gz' command: + * Did you install any Gazebo library? + * Did you set the GZ_CONFIG_PATH environment variable? + E.g.: export GZ_CONFIG_PATH=$HOME/local/share/gz +``` + +You should set up the environment variable: + +``` +# replace to your Gazebo installation directory +GZ_CONFIG_PATH=/share/gz/ +``` + +## macOS + +### Unable to find `urdf_model.h` error +After installing all the dependencies and starting the build process, you may encounter an error that looks like this: + +```bash +/Users/user/ionic_ws/src/sdformat/src/parser_urdf.cc:30:10: fatal error: 'urdf_model/model.h' file not found +#include + ^~~~~~~~~~~~~~~~~~~~ +1 error generated. +make[2]: *** [src/CMakeFiles/sdformat9.dir/parser_urdf.cc.o] Error 1 +make[1]: *** [src/CMakeFiles/sdformat9.dir/all] Error 2 +make: *** [all] Error 2 +Failed <<< sdformat9 [ Exited with code 2 ] +``` + +First check if `urdfdom` and `urdfdom_headers` are installed by running: + +```bash +brew install urdfdom urdfdom_headers +``` + +Then if the error persists, compile with the internal version of `urdfdom` by running: + +```bash +colcon build --cmake-args -DUSE_INTERNAL_URDF=ON --merge-install +``` + +This command will ignore the system installation of `urdfdom` and use the internal version instead. + +### Unable to load .dylib file +When running the `gz sim -s` command, an error like the one below may show up: + +```bash +Error while loading the library [/Users/ionic/ionic_ws/install/lib//libgz-physics6-dartsim-plugin.6.dylib]: dlopen(/Users/ionic/ionic_ws/install/lib//libgz-physics6-dartsim-plugin.6.dylib, 5): Library not loaded: @rpath/libIrrXML.dylib + Referenced from: /usr/local/opt/assimp/lib/libassimp.5.dylib + Reason: image not found +[Err] [Physics.cc:275] Unable to load the /Users/ionic/ionic_ws/install/lib//libgz-physics6-dartsim-plugin.6.dylib library. +Escalating to SIGKILL on [Gazebo Sim Server] +``` + +The issue is related to OSX System Integrity Protection (SIP). The workaround is to run `gz` with a different ruby then make sure that ruby is loaded. + +```bash +brew install ruby + +# Add the following to ~/.bashrc +export PATH=/usr/local/Cellar/ruby/2.6.5/bin:$PATH + +# Source ~/.bashrc in terminal +. ~/.bashrc +``` + +### No rule to make target `'/usr/lib/libm.dylib', needed by 'lib/libgz-physics6-dartsim-plugin.6.1.0.dylib'. Stop.` +Try to run `brew outdated` followed by a `brew upgrade` may fix some of it. + +## Ubuntu + +### Out of memory issues + +There can be out of memory issue during the compilation of Gazebo, especially during +compilation of gz-physics. To prevent out of memory issues you can restrict the number of jobs: + +```bash +MAKEFLAGS="-j " colcon build --executor sequential +``` + +### Problems with dual Intel and Nvidia GPU systems + +If you are using a dual Intel/Nvidia system it could be the case that the +simulator is being run under Intel instead of using the Nvidia GPU. Bugs can +vary but there could problems with shadows, incorrect laser scans or other +rendering related issues. + +#### prime-select command line tool + +Hybrid Intel/Nvidia systems can be configured using the command line tool prime-select. +One option is to use always Nvidia: + + sudo prime-select nvidia + # logout user session and login again + +Other option is to configure the render offload for OpenGL applications to use +Nvidia. This means that your X screen and all normal applications are handled +by the Intel GPU, but all OpenGL applications that you start from the terminal +(including Gazebo) are rendered on the Nvidia GPU. + + # place the lines in your .bashrc if you want the change to be permanent + export __NV_PRIME_RENDER_OFFLOAD=1 + export __GLX_VENDOR_LIBRARY_NAME=nvidia + # logout user session and login again + +#### nvidia-settings GUI tool + +nvidia-settings is a GUI program that helps to configure the options for the Nvidia +graphic cards and includes some controls for hybrid Intel/Nvidia: + +The section "PRIME Profiles" can be used to select that the Nvidia card controls +all the GUI applications by selecting "NVIDIA (Performance Mode)". + +The "Application Profiles" can control the use of the Nvidia GPU per application. + +### Unable to create the rendering window + +If you're getting errors like "Unable to create the rendering window", it could +mean you're using an old OpenGL version. Gazebo Sim uses the Ogre 2 +rendering engine by default, which requires an OpenGL version higher than 3.3, +preferrably 4.3+. + +This can be confirmed by checking the Ogre 2 logs at `~/.gz/rendering/ogre2.log`, +which should have an error like: + + "OGRE EXCEPTION(3:RenderingAPIException): OpenGL 3.3 is not supported. Please update your graphics card drivers." + +You can also check your OpenGL version running: + + glxinfo | grep "OpenGL version" + +To enable Ogre 2 support, you'll need to update your computer's OpenGL version. +As suggested on the Ogre logs, this may require updating your graphics card +drivers. + +If you still run into OpenGL issues when running Gazebo with Ogre 2, it could +be that certain extensions are not supported by your driver or you are running +inside a virtual machine. In this case, you can try disabling DRI: + + export LIBGL_DRI3_DISABLE=1 + +or force software rendering + + export LIBGL_ALWAYS_SOFTWARE=1 + +If you are using MESA drivers, you can also try overriding the OpenGL version + + export MESA_GL_VERSION_OVERRIDE=3.3 + +The Ogre 2 debs from the osrfoundation repository are built from a fork of +Ogre's `v2-3` branch with changes needed for deb packaging and allowing it to +be co-installable with Ogre 1.x. The code can be found here: + +https://github.com/osrf/ogre-2.3-release + +You should be able to use Ogre 1 without any issues however. You can check if +that's working by running a world which uses Ogre 1 instead of Ogre 2, such as: + + gz sim -v 3 lights.sdf + +If that loads, you can continue to use Gazebo with Ogre 1, just use the +`--render-engine ogre` option. + +### Wayland issues + +For users on Wayland, you will need to make sure Gazebo is launched with +XWayland. + +If you see an error message like the one below: + +``` +Unable to create the rendering window: OGRE EXCEPTION(3:RenderingAPIException): currentGLContext was specified with no current GL context in GLXWindow::create at ./RenderSystems/GL3Plus/src/windowing/GLX/OgreGLXWindow.cpp (line 165) +``` + +try unsetting the `WAYLAND_DISPLAY` environment variable, e.g. + +```sh +env -u WAYLAND_DISPLAY gz sim -v 4 shapes.sdf +``` + +## Windows + +### VisualStudioVersion is not set, please run within a Visual Studio Command Prompt. +When you try to compile Gazebo you might see an error in your prompt like: + + VisualStudioVersion is not set, please run within a Visual Studio Command Prompt. + +In this case execute one of the following commands: + - CMD +```bash + "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64 +``` + + - PowerShell: +```bash +pushd "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools" +cmd /c "VsDevCmd.bat&set" | +foreach { + if ($_ -match "=") { + $v = $_.split("="); set-item -force -path "ENV:\$($v[0])" -value "$($v[1])" + } +} +popd +``` diff --git a/ionic/tutorials.md b/ionic/tutorials.md new file mode 100644 index 000000000..cd1103df2 --- /dev/null +++ b/ionic/tutorials.md @@ -0,0 +1,49 @@ +# Gazebo Tutorials + +These tutorials cover general concepts to help get you started with Gazebo. + +## Basics tutorials + +* [Building Your Own Robot](building_robot) +* [Moving the Robot](moving_robot) +* [SDF Worlds](sdf_worlds) +* [Sensors](sensors) +* [Actors](actors) + +## GUI tutorials + +* [Understanding the GUI](gui) +* [Manipulating Models](manipulating_models) +* [Model Insertion from Fuel](fuel_insert) +* [Keyboard Shortcuts](hotkeys) + +## ROS integration + +* [Spawn URDF](spawn_urdf) +* [ROS 2 Integration via Bridge](ros2_integration) +* [ROS 2 Interoperability](ros2_interop) +* [ROS 2 Integration Template](ros_gz_project_template_guide) + +## Per-library tutorials + +See the *API & Tutorials* sections on the [Libraries page](/libs) page for more specific content correlating to each Gazebo library. + +The entrypoint library is Sim. +- [Sim](/api/sim/8/tutorials.html) + +Other libraries: +- [Cmake](/api/cmake/3/tutorials.html) +- [Common](/api/common/5/tutorials.html) +- [Fuel_tools](/api/fuel_tools/9/tutorials.html) +- [Gui](/api/gui/8/tutorials.html) +- [Launch](/api/launch/7/tutorials.html) +- [Math](/api/math/7/tutorials.html) +- [Msgs](/api/msgs/10/tutorials.html) +- [Physics](/api/physics/7/tutorials.html) +- [Plugin](/api/plugin/2/tutorials.html) +- [Rendering](/api/rendering/8/tutorials.html) +- [Sensors](/api/sensors/8/tutorials.html) +- [Tools](/api/tools/2/tutorials.html) +- [Transport](/api/transport/13/tutorials.html) +- [Utils](/api/utils/2/tutorials.html) +- [Sdformat](/api/sdformat/13/) diff --git a/ionic/tutorials/actors/actor_demo.gif b/ionic/tutorials/actors/actor_demo.gif new file mode 100644 index 000000000..d1692f8f1 Binary files /dev/null and b/ionic/tutorials/actors/actor_demo.gif differ diff --git a/ionic/tutorials/actors/actor_demo.sdf b/ionic/tutorials/actors/actor_demo.sdf new file mode 100644 index 000000000..5ee6a14cc --- /dev/null +++ b/ionic/tutorials/actors/actor_demo.sdf @@ -0,0 +1,115 @@ + + + + + + ogre + + + + + + + + true + 0 0 10 0 0 0 + 0.8 0.8 0.8 1 + 0.2 0.2 0.2 1 + + 1000 + 0.9 + 0.01 + 0.001 + + -0.5 0.1 -0.9 + + + + true + + + + + 0.0 0.0 1 + + + + + + + 0.0 0.0 1 + 100 100 + + + + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + + + + + + + + https://fuel.gazebosim.org/1.0/Mingfei/models/actor/tip/files/meshes/walk.dae + 1.0 + + + https://fuel.gazebosim.org/1.0/Mingfei/models/actor/tip/files/meshes/walk.dae + + + + + + diff --git a/ionic/tutorials/actors/actor_skin.gif b/ionic/tutorials/actors/actor_skin.gif new file mode 100644 index 000000000..7292afe30 Binary files /dev/null and b/ionic/tutorials/actors/actor_skin.gif differ diff --git a/ionic/tutorials/actors/combined_movement.gif b/ionic/tutorials/actors/combined_movement.gif new file mode 100644 index 000000000..50afbb6f0 Binary files /dev/null and b/ionic/tutorials/actors/combined_movement.gif differ diff --git a/ionic/tutorials/actors/skeleton_movement.gif b/ionic/tutorials/actors/skeleton_movement.gif new file mode 100644 index 000000000..d13e07a4c Binary files /dev/null and b/ionic/tutorials/actors/skeleton_movement.gif differ diff --git a/ionic/tutorials/actors/trajectory_movement.gif b/ionic/tutorials/actors/trajectory_movement.gif new file mode 100644 index 000000000..046e84120 Binary files /dev/null and b/ionic/tutorials/actors/trajectory_movement.gif differ diff --git a/ionic/tutorials/building_robot/building_robot.sdf b/ionic/tutorials/building_robot/building_robot.sdf new file mode 100644 index 000000000..05a1bdbef --- /dev/null +++ b/ionic/tutorials/building_robot/building_robot.sdf @@ -0,0 +1,249 @@ + + + + + 0.001 + 1.0 + + + + + + + + + + true + 0 0 10 0 0 0 + 0.8 0.8 0.8 1 + 0.2 0.2 0.2 1 + + 1000 + 0.9 + 0.01 + 0.001 + + -0.5 0.1 -0.9 + + + + true + + + + + 0 0 1 + + + + + + + 0 0 1 + 100 100 + + + + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + + + + + + + 0 0 0 0 0 0 + + + + 0.5 0 0.4 0 0 0 + + 1.14395 + + 0.095329 + 0 + 0 + 0.381317 + 0 + 0.476646 + + + + + + 2.0 1.0 0.5 + + + + + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + + + + + + 2.0 1.0 0.5 + + + + + + + + -0.5 0.6 0 -1.5707 0 0 + + 1 + + 0.043333 + 0 + 0 + 0.043333 + 0 + 0.08 + + + + + + 0.4 + 0.2 + + + + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + + + + + + 0.4 + 0.2 + + + + + + + + -0.5 -0.6 0 -1.5707 0 0 + + 1 + + 0.043333 + 0 + 0 + 0.043333 + 0 + 0.08 + + + + + + 0.4 + 0.2 + + + + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + + + + + + 0.4 + 0.2 + + + + + + + + 0.8 0 -0.2 0 0 0 + + + + + + + 1 + + 0.016 + 0 + 0 + 0.016 + 0 + 0.016 + + + + + + 0.2 + + + + 0.0 1 0.0 1 + 0.0 1 0.0 1 + 0.0 1 0.0 1 + + + + + + 0.2 + + + + + + + + + chassis + left_wheel + + 0 1 0 + + -1.79769e+308 + 1.79769e+308 + + + + + + + + chassis + right_wheel + + 0 1 0 + + -1.79769e+308 + 1.79769e+308 + + + + + + + chassis + caster + + + + diff --git a/ionic/tutorials/building_robot/car_left_wheel.png b/ionic/tutorials/building_robot/car_left_wheel.png new file mode 100644 index 000000000..f35f5a4c6 Binary files /dev/null and b/ionic/tutorials/building_robot/car_left_wheel.png differ diff --git a/ionic/tutorials/building_robot/chassis.png b/ionic/tutorials/building_robot/chassis.png new file mode 100644 index 000000000..d1e79c4e4 Binary files /dev/null and b/ionic/tutorials/building_robot/chassis.png differ diff --git a/ionic/tutorials/building_robot/model_axis.png b/ionic/tutorials/building_robot/model_axis.png new file mode 100644 index 000000000..41d94fea5 Binary files /dev/null and b/ionic/tutorials/building_robot/model_axis.png differ diff --git a/ionic/tutorials/building_robot/two_wheeled_robot.png b/ionic/tutorials/building_robot/two_wheeled_robot.png new file mode 100644 index 000000000..448463da7 Binary files /dev/null and b/ionic/tutorials/building_robot/two_wheeled_robot.png differ diff --git a/ionic/tutorials/fuel_insert/fuel.png b/ionic/tutorials/fuel_insert/fuel.png new file mode 100644 index 000000000..e7cb49183 Binary files /dev/null and b/ionic/tutorials/fuel_insert/fuel.png differ diff --git a/ionic/tutorials/fuel_insert/husky.gif b/ionic/tutorials/fuel_insert/husky.gif new file mode 100644 index 000000000..fb09b9e84 Binary files /dev/null and b/ionic/tutorials/fuel_insert/husky.gif differ diff --git a/ionic/tutorials/fuel_insert/mine_cart_engine_detail.png b/ionic/tutorials/fuel_insert/mine_cart_engine_detail.png new file mode 100644 index 000000000..61c2c9104 Binary files /dev/null and b/ionic/tutorials/fuel_insert/mine_cart_engine_detail.png differ diff --git a/ionic/tutorials/fuel_insert/resource_spawner_cloud.png b/ionic/tutorials/fuel_insert/resource_spawner_cloud.png new file mode 100644 index 000000000..2fe7d259a Binary files /dev/null and b/ionic/tutorials/fuel_insert/resource_spawner_cloud.png differ diff --git a/ionic/tutorials/fuel_insert/resource_spawner_local.png b/ionic/tutorials/fuel_insert/resource_spawner_local.png new file mode 100644 index 000000000..f42147cd3 Binary files /dev/null and b/ionic/tutorials/fuel_insert/resource_spawner_local.png differ diff --git a/ionic/tutorials/gui/entity_select.png b/ionic/tutorials/gui/entity_select.png new file mode 100644 index 000000000..30fcea17f Binary files /dev/null and b/ionic/tutorials/gui/entity_select.png differ diff --git a/ionic/tutorials/gui/grid_config.png b/ionic/tutorials/gui/grid_config.png new file mode 100644 index 000000000..2243a63f3 Binary files /dev/null and b/ionic/tutorials/gui/grid_config.png differ diff --git a/ionic/tutorials/gui/hover_steps.png b/ionic/tutorials/gui/hover_steps.png new file mode 100644 index 000000000..2e240e3ac Binary files /dev/null and b/ionic/tutorials/gui/hover_steps.png differ diff --git a/ionic/tutorials/gui/menu_btn.png b/ionic/tutorials/gui/menu_btn.png new file mode 100644 index 000000000..6cb185d35 Binary files /dev/null and b/ionic/tutorials/gui/menu_btn.png differ diff --git a/ionic/tutorials/gui/playback.png b/ionic/tutorials/gui/playback.png new file mode 100644 index 000000000..1dbe16945 Binary files /dev/null and b/ionic/tutorials/gui/playback.png differ diff --git a/ionic/tutorials/gui/plugins_btn.png b/ionic/tutorials/gui/plugins_btn.png new file mode 100644 index 000000000..ddbdaa289 Binary files /dev/null and b/ionic/tutorials/gui/plugins_btn.png differ diff --git a/ionic/tutorials/gui/rtf_expanded.png b/ionic/tutorials/gui/rtf_expanded.png new file mode 100644 index 000000000..85f275dfa Binary files /dev/null and b/ionic/tutorials/gui/rtf_expanded.png differ diff --git a/ionic/tutorials/gui/shape_insertion.png b/ionic/tutorials/gui/shape_insertion.png new file mode 100644 index 000000000..2263701b5 Binary files /dev/null and b/ionic/tutorials/gui/shape_insertion.png differ diff --git a/ionic/tutorials/gui/shapes.png b/ionic/tutorials/gui/shapes.png new file mode 100644 index 000000000..61567ec57 Binary files /dev/null and b/ionic/tutorials/gui/shapes.png differ diff --git a/ionic/tutorials/gui/toolbars.png b/ionic/tutorials/gui/toolbars.png new file mode 100644 index 000000000..616693080 Binary files /dev/null and b/ionic/tutorials/gui/toolbars.png differ diff --git a/ionic/tutorials/moving_robot/keypublisher_data.png b/ionic/tutorials/moving_robot/keypublisher_data.png new file mode 100644 index 000000000..0b357dbbd Binary files /dev/null and b/ionic/tutorials/moving_robot/keypublisher_data.png differ diff --git a/ionic/tutorials/moving_robot/moving_robot.sdf b/ionic/tutorials/moving_robot/moving_robot.sdf new file mode 100644 index 000000000..3630c1ae5 --- /dev/null +++ b/ionic/tutorials/moving_robot/moving_robot.sdf @@ -0,0 +1,300 @@ + + + + + 0.001 + 1.0 + + + + + + + + + + true + 0 0 10 0 0 0 + 0.8 0.8 0.8 1 + 0.2 0.2 0.2 1 + + 1000 + 0.9 + 0.01 + 0.001 + + -0.5 0.1 -0.9 + + + + true + + + + + 0 0 1 + + + + + + + 0 0 1 + 100 100 + + + + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + + + + + + + 0 0 0 0 0 0 + + + 0.5 0 0.4 0 0 0 + + 1.14395 + + 0.126164 + 0 + 0 + 0.416519 + 0 + 0.481014 + + + + + + 2.0 1.0 0.5 + + + + + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + + + + + + 2.0 1.0 0.5 + + + + + + + + -0.5 0.6 0 -1.5707 0 0 + + 2 + + 0.145833 + 0 + 0 + 0.145833 + 0 + 0.125 + + + + + + 0.4 + 0.2 + + + + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + + + + + + 0.4 + 0.2 + + + + + + + + -0.5 -0.6 0 -1.5707 0 0 + + 1 + + 0.145833 + 0 + 0 + 0.145833 + 0 + 0.125 + + + + + + 0.4 + 0.2 + + + + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + + + + + + 0.4 + 0.2 + + + + + + + 0.8 0 -0.2 0 0 0 + + + + + + + 1 + + 0.1 + 0 + 0 + 0.1 + 0 + 0.1 + + + + + + 0.2 + + + + 0.0 1 0.0 1 + 0.0 1 0.0 1 + 0.0 1 0.0 1 + + + + + + 0.2 + + + + + + + + + + chassis + left_wheel + + 0 1 0 + + -1.79769e+308 + 1.79769e+308 + + + + + + + chassis + right_wheel + + 0 1 0 + + -1.79769e+308 + 1.79769e+308 + + + + + + + chassis + caster + + + + + left_wheel_joint + right_wheel_joint + 1.2 + 0.4 + 1 + cmd_vel + + + + + + + 16777234 + + + linear: {x: 0.0}, angular: {z: 0.5} + + + + + + 16777235 + + + linear: {x: 0.5}, angular: {z: 0.0} + + + + + + 16777236 + + + linear: {x: 0.0}, angular: {z: -0.5} + + + + + + 16777237 + + + linear: {x: -0.5}, angular: {z: 0.0} + + + + diff --git a/ionic/tutorials/ros2_integration/empty_world.png b/ionic/tutorials/ros2_integration/empty_world.png new file mode 100644 index 000000000..0b48a4ef0 Binary files /dev/null and b/ionic/tutorials/ros2_integration/empty_world.png differ diff --git a/ionic/tutorials/ros2_integration/gz_rviz.gif b/ionic/tutorials/ros2_integration/gz_rviz.gif new file mode 100644 index 000000000..d81e10576 Binary files /dev/null and b/ionic/tutorials/ros2_integration/gz_rviz.gif differ diff --git a/ionic/tutorials/ros2_integration/jsp_diagram.jpg b/ionic/tutorials/ros2_integration/jsp_diagram.jpg new file mode 100644 index 000000000..2c5e62305 Binary files /dev/null and b/ionic/tutorials/ros2_integration/jsp_diagram.jpg differ diff --git a/ionic/tutorials/ros2_integration/jsp_gui.png b/ionic/tutorials/ros2_integration/jsp_gui.png new file mode 100644 index 000000000..5326e690b Binary files /dev/null and b/ionic/tutorials/ros2_integration/jsp_gui.png differ diff --git a/ionic/tutorials/ros2_integration/use_template.png b/ionic/tutorials/ros2_integration/use_template.png new file mode 100644 index 000000000..b5413c09d Binary files /dev/null and b/ionic/tutorials/ros2_integration/use_template.png differ diff --git a/ionic/tutorials/sdf_worlds/coke_world.png b/ionic/tutorials/sdf_worlds/coke_world.png new file mode 100644 index 000000000..7ac8b9892 Binary files /dev/null and b/ionic/tutorials/sdf_worlds/coke_world.png differ diff --git a/ionic/tutorials/sdf_worlds/entity_tree.png b/ionic/tutorials/sdf_worlds/entity_tree.png new file mode 100644 index 000000000..23a815192 Binary files /dev/null and b/ionic/tutorials/sdf_worlds/entity_tree.png differ diff --git a/ionic/tutorials/sdf_worlds/two_cokes.png b/ionic/tutorials/sdf_worlds/two_cokes.png new file mode 100644 index 000000000..527cc0b74 Binary files /dev/null and b/ionic/tutorials/sdf_worlds/two_cokes.png differ diff --git a/ionic/tutorials/sdf_worlds/world_demo.sdf b/ionic/tutorials/sdf_worlds/world_demo.sdf new file mode 100644 index 000000000..f9c3baacf --- /dev/null +++ b/ionic/tutorials/sdf_worlds/world_demo.sdf @@ -0,0 +1,46 @@ + + + + + 0.001 + 1.0 + + + + + + + + + + + true + 0 0 10 0 0 0 + 0.8 0.8 0.8 1 + 0.2 0.2 0.2 1 + + 1000 + 0.9 + 0.01 + 0.001 + + -0.5 0.1 -0.9 + + + Coke0 + 0 0 0 0 0 0 + https://fuel.gazebosim.org/1.0/OpenRobotics/models/Coke + + + Coke1 + 0 0.1 0 0 0 0 + https://fuel.gazebosim.org/1.0/OpenRobotics/models/Coke + + + diff --git a/ionic/tutorials/sdf_worlds/world_stats.png b/ionic/tutorials/sdf_worlds/world_stats.png new file mode 100644 index 000000000..7dadcab36 Binary files /dev/null and b/ionic/tutorials/sdf_worlds/world_stats.png differ diff --git a/ionic/tutorials/sensors/CMakeLists.txt b/ionic/tutorials/sensors/CMakeLists.txt new file mode 100644 index 000000000..09d0a8862 --- /dev/null +++ b/ionic/tutorials/sensors/CMakeLists.txt @@ -0,0 +1,14 @@ +cmake_minimum_required(VERSION 3.10.2 FATAL_ERROR) + +project(avoid_wall) + +# Find the Gazebo_Transport library +find_package(gz-transport12 QUIET REQUIRED OPTIONAL_COMPONENTS log) +set(GZ_TRANSPORT_VER ${gz-transport12_VERSION_MAJOR}) + +include_directories(${CMAKE_BINARY_DIR}) + +if (EXISTS "${CMAKE_SOURCE_DIR}/lidar_node.cc") + add_executable(lidar_node lidar_node.cc) + target_link_libraries(lidar_node gz-transport${GZ_TRANSPORT_VER}::core) +endif() diff --git a/ionic/tutorials/sensors/imu_msgs.png b/ionic/tutorials/sensors/imu_msgs.png new file mode 100644 index 000000000..56663f83b Binary files /dev/null and b/ionic/tutorials/sensors/imu_msgs.png differ diff --git a/ionic/tutorials/sensors/lidar_node.cc b/ionic/tutorials/sensors/lidar_node.cc new file mode 100644 index 000000000..7b6e74458 --- /dev/null +++ b/ionic/tutorials/sensors/lidar_node.cc @@ -0,0 +1,70 @@ +/* + * Copyright (C) 2020 Open Source Robotics Foundation + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * +*/ + +#include +#include +#include + + +std::string topic_pub = "/cmd_vel"; //publish to this topic +gz::transport::Node node; +auto pub = node.Advertise(topic_pub); + +////////////////////////////////////////////////// +/// \brief Function called each time a topic update is received. +void cb(const gz::msgs::LaserScan &_msg) +{ + gz::msgs::Twist data; + + bool allMore = true; + for (int i = 0; i < _msg.ranges_size(); i++) + { + if (_msg.ranges(i) < 1.0) + { + allMore = false; + break; + } + } + if (allMore) //if all bigger than one + { + data.mutable_linear()->set_x(0.5); + data.mutable_angular()->set_z(0.0); + } + else + { + data.mutable_linear()->set_x(0.0); + data.mutable_angular()->set_z(0.5); + } + pub.Publish(data); +} + +////////////////////////////////////////////////// +int main(int argc, char **argv) +{ + std::string topic_sub = "/lidar"; // subscribe to this topic + // Subscribe to a topic by registering a callback. + if (!node.Subscribe(topic_sub, cb)) + { + std::cerr << "Error subscribing to topic [" << topic_sub << "]" << std::endl; + return -1; + } + + // Zzzzzz. + gz::transport::waitForShutdown(); + + return 0; +} diff --git a/ionic/tutorials/sensors/sensor_launch.gzlaunch b/ionic/tutorials/sensors/sensor_launch.gzlaunch new file mode 100644 index 000000000..f52c47c29 --- /dev/null +++ b/ionic/tutorials/sensors/sensor_launch.gzlaunch @@ -0,0 +1,11 @@ + + + + gz sim sensor_tutorial.sdf + + + + ./build/lidar_node + + + diff --git a/ionic/tutorials/sensors/sensor_tutorial.sdf b/ionic/tutorials/sensors/sensor_tutorial.sdf new file mode 100644 index 000000000..73c9639f6 --- /dev/null +++ b/ionic/tutorials/sensors/sensor_tutorial.sdf @@ -0,0 +1,664 @@ + + + + + 0.001 + 1.0 + + + + + + + + + + + ogre2 + + + + + + + + + 3D View + false + docked + + + ogre2 + scene + 0.4 0.4 0.4 + 0.8 0.8 0.8 + -6 0 6 0 0.5 0 + + 0.25 + 25000 + + + + + + + floating + 5 + 5 + false + + + + + false + 5 + 5 + floating + false + + + + + false + 5 + 5 + floating + false + + + + + false + 5 + 5 + floating + false + + + + + false + 5 + 5 + floating + false + + + + + + + + + false + 5 + 5 + floating + false + + + + + false + 5 + 5 + floating + false + + + + + + + + + + false + 5 + 5 + floating + false + + + + + + + World control + false + false + 72 + 121 + 1 + + floating + + + + + + + true + true + true + true + + + + + + + World stats + false + false + 110 + 290 + 1 + + floating + + + + + + + true + true + true + true + + + + + + false + 0 + 0 + 250 + 50 + floating + false + #666666 + + + + + + + false + 250 + 0 + 150 + 50 + floating + false + #666666 + + + + + + + false + 0 + 50 + 250 + 50 + floating + false + #777777 + + + + + + + false + 250 + 50 + 50 + 50 + floating + false + #777777 + + + + + + + false + 300 + 50 + 50 + 50 + floating + false + #777777 + + + + true + false + 4000000 + + + + + + + docked_collapsed + + + + + + + docked_collapsed + + + + + + + docked_collapsed + + + + + + + + + + true + 0 0 10 0 0 0 + 0.8 0.8 0.8 1 + 0.2 0.2 0.2 1 + + 1000 + 0.9 + 0.01 + 0.001 + + -0.5 0.1 -0.9 + + + + true + + + + + 0 0 1 + + + + + + + 0 0 1 + 100 100 + + + + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + + + + + + + 0 0 1 0 0 0 + + + 0.8 0 0.5 0 0 0 + + + + 0.5 0 0.4 0 0 0 + + 1.14395 + + 0.126164 + 0 + 0 + 0.416519 + 0 + 0.481014 + + + + + + 2.0 1.0 0.5 + + + + + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + + + + + + 2.0 1.0 0.5 + + + + + 1 + 1 + true + imu + + " + 0 0 0 0 0 0 + lidar + 10 + + + + 640 + 1 + -1.396263 + 1.396263 + + + 1 + 0.01 + 0 + 0 + + + + 0.08 + 10.0 + 0.01 + + + 1 + true + + + + + + -0.5 0.6 0 -1.5707 0 0 + + 2 + + 0.145833 + 0 + 0 + 0.145833 + 0 + 0.125 + + + + + + 0.4 + 0.2 + + + + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + + + + + + 0.4 + 0.2 + + + + + + + + -0.5 -0.6 0 -1.5707 0 0 + + 1 + + 0.145833 + 0 + 0 + 0.145833 + 0 + 0.125 + + + + + + 0.4 + 0.2 + + + + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + 1.0 0.0 0.0 1 + + + + + + 0.4 + 0.2 + + + + + + + 0.8 0 -0.2 0 0 0 + + + + + + + 1 + + 0.1 + 0 + 0 + 0.1 + 0 + 0.1 + + + + + + 0.2 + + + + 0.0 1 0.0 1 + 0.0 1 0.0 1 + 0.0 1 0.0 1 + + + + + + 0.2 + + + + + + + + + chassis + left_wheel + + 0 1 0 + + -1.79769e+308 + 1.79769e+308 + + + + + + + chassis + right_wheel + + 0 1 0 + + -1.79769e+308 + 1.79769e+308 + + + + + + + chassis + caster + + + + + left_wheel_joint + right_wheel_joint + 1.2 + 0.4 + 1 + cmd_vel + + + + + + true + 5 0 0 0 0 0 + + + + 1.14395 + + 9.532917 + 0 + 0 + 0.023832 + 0 + 9.556749 + + + + + + 0.5 10.0 2.0 + + + + + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + 0.0 0.0 1.0 1 + + + + + + 0.5 10.0 2.0 + + + + + + collision + + + + + vehicle_blue + wall + + true + + + + + + + 16777234 + + + linear: {x: 0.0}, angular: {z: 0.5} + + + + + + 16777235 + + + linear: {x: 0.5}, angular: {z: 0.0} + + + + + + 16777236 + + + linear: {x: 0.0}, angular: {z: -0.5} + + + + + + 16777237 + + + linear: {x: -0.5}, angular: {z: 0.0} + + + + + + + data: true + + + linear: {x: 0.0}, angular: {z: 0.0} + + + + diff --git a/ionic/tutorials/sensors/sensor_wall.png b/ionic/tutorials/sensors/sensor_wall.png new file mode 100644 index 000000000..95b07c4b5 Binary files /dev/null and b/ionic/tutorials/sensors/sensor_wall.png differ diff --git a/ionic/tutorials/spawn_urdf/empty_world.png b/ionic/tutorials/spawn_urdf/empty_world.png new file mode 100644 index 000000000..9671ce270 Binary files /dev/null and b/ionic/tutorials/spawn_urdf/empty_world.png differ diff --git a/ionic/tutorials/spawn_urdf/rrbot.gif b/ionic/tutorials/spawn_urdf/rrbot.gif new file mode 100644 index 000000000..1dfad37ce Binary files /dev/null and b/ionic/tutorials/spawn_urdf/rrbot.gif differ diff --git a/ionic/tutorials/spawn_urdf/rrbot.urdf b/ionic/tutorials/spawn_urdf/rrbot.urdf new file mode 100644 index 000000000..ff57a914c --- /dev/null +++ b/ionic/tutorials/spawn_urdf/rrbot.urdf @@ -0,0 +1,312 @@ + + + + + + + + + + + + /rrbot + gazebo_ros_control/DefaultRobotHWSim + + + + + Gazebo/Orange + + + + 0.2 + 0.2 + Gazebo/Black + + + + 0.2 + 0.2 + Gazebo/Orange + + + + 0.2 + 0.2 + Gazebo/Red + + + + + 0 0 0 0 0 0 + false + 40 + + + + 720 + 1 + -1.570796 + 1.570796 + + + + 0.10 + 30.0 + 0.01 + + + gaussian + + 0.0 + 0.01 + + + + /rrbot/laser/scan + hokuyo_link + + + + + + + 30.0 + + 1.3962634 + + 800 + 800 + R8G8B8 + + + 0.02 + 300 + + + gaussian + + 0.0 + 0.007 + + + + true + 0.0 + rrbot/camera1 + image_raw + camera_info + camera_link_optical + + 0.0 + 0.0 + 0.0 + 0.0 + 0.0 + 0.0 + 0 + 0.0 + 0.0 + 0.0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + transmission_interface/SimpleTransmission + + hardware_interface/EffortJointInterface + + + hardware_interface/EffortJointInterface + 1 + + + + transmission_interface/SimpleTransmission + + hardware_interface/EffortJointInterface + + + hardware_interface/EffortJointInterface + 1 + + + diff --git a/ionic/tutorials/spawn_urdf/urdf_spawned.png b/ionic/tutorials/spawn_urdf/urdf_spawned.png new file mode 100644 index 000000000..aa032c0a6 Binary files /dev/null and b/ionic/tutorials/spawn_urdf/urdf_spawned.png differ diff --git a/release_features.md b/release_features.md index afa76eec0..9852f661d 100644 --- a/release_features.md +++ b/release_features.md @@ -2,9 +2,32 @@ Here you will find the set of features that are available in each release. -Take a look at the [Roadmap](/docs/roadmap) for information about upcoming +Take a look at the [Roadmap](/docs/all/roadmap) for information about upcoming features, some of which may land in released versions of Gazebo. +## Harmonic + +For a complete list of features included in the initial release of Harmonic, please see the [highlights](https://github.com/gazebosim/gz-harmonic/blob/main/highlights.md) and [release notes](https://github.com/gazebosim/gz-harmonic/blob/main/release_notes.md) documentation in the Gazebo Harmonic repository. + +| Library name | Version | Changelog | +| ------------------ |:-------------:|:-------------:| +| gz-cmake | 3.x | [Changelog](https://github.com/gazebosim/gz-cmake/blob/gz-cmake3/Changelog.md) | +| gz-common | 5.x | [Changelog](https://github.com/gazebosim/gz-common/blob/gz-common5/Changelog.md) | +| gz-fuel-tools | 9.x | [Changelog](https://github.com/gazebosim/gz-fuel-tools/blob/gz-fuel-tools9/Changelog.md) | +| gz-gui | 8.x | [Changelog](https://github.com/gazebosim/gz-gui/blob/gz-gui8/Changelog.md) | +| gz-launch | 7.x | [Changelog](https://github.com/gazebosim/gz-launch/blob/gz-launch7/Changelog.md) +| gz-math | 7.x | [Changelog](https://github.com/gazebosim/gz-math/blob/gz-math7/Changelog.md) +| gz-msgs | 10.x | [Changelog](https://github.com/gazebosim/gz-msgs/blob/gz-msgs10/Changelog.md) +| gz-physics | 7.x | [Changelog](https://github.com/gazebosim/gz-physics/blob/gz-physics7/Changelog.md) +| gz-plugin | 2.x | [Changelog](https://github.com/gazebosim/gz-plugin/blob/gz-plugin2/Changelog.md) | +| gz-rendering | 8.x | [Changelog](https://github.com/gazebosim/gz-rendering/blob/gz-rendering8/Changelog.md) | +| gz-sensors | 8.x | [Changelog](https://github.com/gazebosim/gz-sensors/blob/gz-sensors8/Changelog.md) | +| gz-sim | 8.x | [Changelog](https://github.com/gazebosim/gz-sim/blob/gz-sim8/Changelog.md) | +| gz-tools | 2.x | [Changelog](https://github.com/gazebosim/gz-tools/blob/gz-tools2/Changelog.md) | +| gz-transport | 13.x | [Changelog](https://github.com/gazebosim/gz-transport/blob/gz-transport13/Changelog.md) | +| gz-utils | 2.x | [Changelog](https://github.com/gazebosim/gz-utils/blob/gz-utils2/Changelog.md) | +| sdformat | 14.x | [Changelog](https://github.com/osrf/sdformat/blob/sdf14/Changelog.md) | + ## Garden 1. [Point cloud visualization.](https://github.com/gazebosim/gz-sim/issues/1156) @@ -33,8 +56,9 @@ features, some of which may land in released versions of Gazebo. 1. [Lens flare support for Ogre and Ogre2.](https://github.com/gazebosim/gz-rendering/issues/730) 1. [Allow specifying initial simulation time with a CLI argument](https://github.com/gazebosim/gz-sim/pull/1801) 1. [Joints defined at the world level](https://github.com/gazebosim/sdformat/issues/1115) +1. [Dynamic wrench application through the GUI (Mouse interaction with simulated models)](https://github.com/gazebosim/gz-sim/issues/306) -[^1]: All the functionality for creating custom rendering sensors is in Garden, but the PR listed, which serves as an +[^1]: All the functionality for creating custom rendering sensors is in Garden, but the PR listed, which serves as an example, is only available in Harmonic. | Library name | Version | Changelog | @@ -245,6 +269,7 @@ features, some of which may land in released versions of Gazebo. * [Link](https://gazebosim.org/api/gazebo/3.5/migrationlinkapi.html) 1. [Expose camera calibration parameters.](https://github.com/gazebosim/sdformat/pull/1088) 1. [Speed up Resource Spawner.](https://github.com/gazebosim/gz-sim/issues/1936) +1. [Bash completion](https://github.com/gazebosim/gz-tools/issues/1) | Library name | Version | Changelog | | ------------------ |:-------------:|:-------------:| diff --git a/roadmap.md b/roadmap.md index 411038e60..3111792e5 100644 --- a/roadmap.md +++ b/roadmap.md @@ -8,37 +8,18 @@ info@openrobotics.org. ## Quarterly Roadmap -## 2023 Q1 (Jan - Mar) / Q2 (Apr - Jun) - ongoing - -* **Out-of-box experience**: Improve end-user experience - * [All open tickets](https://github.com/search?q=org%3Agazebosim+label%3A%22OOBE+%F0%9F%93%A6%E2%9C%A8%22&state=open&type=Issues) - * [Status](https://github.com/orgs/gazebosim/projects/1?card_filter_query=label%3A%22oobe+%F0%9F%93%A6%E2%9C%A8%22) - -* **APIs that ease migration from Gazebo-classic** - * Tickets: [gz-sim#325](https://github.com/gazebosim/gz-sim/issues/325), [gz-sim#85](https://github.com/gazebosim/gz-sim/issues/85) - -* **Provide infrastructure to generate bindings for gz-msg protos instead of packaging generated code** - * Tickets: Part of [gz-sim#494](https://github.com/gazebosim/gz-sim/issues/494), Related to: [gz-sim#36](https://github.com/gazebosim/gz-msgs/issues/36) and [gz-sim#113](https://github.com/gazebosim/gz-msgs/issues/113) - -* **Complete Python scripting capability with documentation and examples** - * Goals: - * Ability to control simulation from python - * Ability to write system "plugins" in python - * Using Gazebo in a jupyter notebook - * Tickets: Part of [gz-sim#790](https://github.com/gazebosim/gz-sim/issues/790) - -## 2023 Q3 (Jul - Sept) - -* **Complete Python scripting capability with documentation and examples** - * Tickets: Part of [gz-sim#790](https://github.com/gazebosim/gz-sim/issues/790) - -* **Improve interoperability with ROS** - * Goals: - - Make Joint state publisher work with SDF - - Eliminate the need for having both URDF and SDF files in robot model packages - - Create more documentation around ROS 2 launch and resources (eg. meshes) - - Create a better workflow for creating custom message bridges other than forking the `ros_gz` repo. - - Events emitted by Gazebo to indicate completion of world/model loading. +## 2024 Q4 (Oct - Dec) + +* **Improve documentation website (gazebosim.org/docs)** + * Use a static site generator for the documentation website so that anyone can preview changes made in a PR. (https://github.com/gazebosim/docs/issues/85) + * Make doxygen tutorials from each library accessible on the main tutorials page on gazebosim.org/docs (https://github.com/gazebosim/docs/issues/55) + * Add new tutorials + * Copy/adapt tutorials from https://classic.gazebosim.org/tutorials + * Improve existing content + * Establish QA checklist for PRs in https://github.com/gazebosim/docs +* **Migrate from Qt5 to Qt6** (https://github.com/gazebosim/gz-gui/issues/586) +* **Define platform dependencies and prepare for the new Ubuntu LTS 24.04 and the interaction with ROS 2 Jazzy.** +* **Support nested models in Bullet-featherstone gz-physics engine plugin** ## Feature Roadmap @@ -56,8 +37,6 @@ compatible non-EOL release and propagate the feature forward. ### Citadel -1. [Bash completion](https://github.com/gazebosim/gz-tools/issues/1) - ### Fortress 1. [Run server and client in the same process.](https://github.com/gazebosim/gz-sim/pull/793) @@ -70,14 +49,14 @@ compatible non-EOL release and propagate the feature forward. ### Garden 1. [Satisfying ASAN for Gazebo Math.](https://github.com/gazebosim/gz-math/issues/370) -1. [Mimic joint type.](https://github.com/gazebosim/sdf_tutorials/pull/62) 1. [SDF APIs to prevent console logging.](https://github.com/gazebosim/sdformat/issues/820) 1. [Download Fuel models on the background](https://github.com/gazebosim/gz-sim/issues/1260) 1. [Bazel build files.](https://github.com/gazebosim/gz-bazel) -1. [Dynamic wrench application through the GUI (Mouse interaction with simulated models)](https://github.com/gazebosim/gz-sim/issues/306) ### Harmonic +### Ionic + See the [Quarterly Roadmap](/docs/all/roadmap#quarterly-roadmap) above. ## Planned releases diff --git a/ros_installation.md b/ros_installation.md index 2afe5f19c..6900c7ccc 100644 --- a/ros_installation.md +++ b/ros_installation.md @@ -48,7 +48,7 @@ continued use. * ✅ - Recommended combination * ❌ - Incompatible / not possible. -* ⚡ - Possible, *but not recommended*. These combinations of ROS and Gazebo can +* ⚡ - Possible, *but use with caution*. These combinations of ROS and Gazebo can be made to work together, but some effort is required. @@ -188,7 +188,7 @@ every ROS package that uses a Gazebo library): Both approaches may also require that you modify your ROS or Gazebo source code to support this compilation. -### Gazebo Harmonic (Not Recommended) +### Gazebo Harmonic with ROS 2 Iron or Rolling (Use with caution) Gazebo Harmonic can be used with ROS 2 Iron and non ROS official binary packages hosted in `packages.osrfoundation.org`. These packages conflict with `ros-iron-ros-gz*` @@ -214,7 +214,7 @@ from source. * [ROS 2 Rolling](https://github.com/gazebosim/ros_gz/tree/ros2#from-source) * Be sure of using `export GZ_VERSION=harmonic` -### Gazebo Garden (Not Recommended) +### Gazebo Garden with ROS 2 Humble, Iron or Rolling (Use with caution) Gazebo Garden can be used with ROS 2 Humble and non ROS official binary packages hosted in `packages.osrfoundation.org`. These packages conflict with `ros-humble-ros-gz*` @@ -252,7 +252,7 @@ from source. * [ROS 2 Rolling](https://github.com/gazebosim/ros_gz/tree/ros2#from-source) * Be sure of using `export GZ_VERSION=garden` -### Gazebo Fortress (Not Recommended) +### Gazebo Fortress with ROS 2 Galactic or ROS 1 Noetic (Not Recommended) Gazebo Fortress can be used with ROS 2 Galactic and ROS 1 Noetic by compiling [`ros_gz`](https://github.com/gazebosim/ros_gz) from source @@ -304,11 +304,18 @@ If you don't need ROS support, the recommended version is the latest released version that can be [installed using the `osrfoundation.org` repo](https://gazebosim.org/docs) depending on your platform. -#### I want to use Gazebo Garden with ROS. Where are the packages? +#### I want to use Gazebo Harmonic or Gazebo Garden with ROS 2. Where are the packages? -Unfortunately there are no Gazebo Garden packages for any ROS distribution. Please -read how to compile it from source in this document under the section -"[Using an specific Gazebo version with ROS2](https://staging.gazebosim.org/docs/garden/ros_installation#using-a-specific-and-unsupported-gazebo-version-with-ros-2)" >> "Gazebo Garden" +We provide binary packages for `ros_gz` for the following Gazebo and ROS 2 pairings in the packages.osrfoundation.org repository +but these packages are not official ROS packages, which means if there is a breaking change in the corresponding ROS 2 distribution, +there will be a short delay before these packages are rebuilt with the changes. Installing these packages may also cause conflicts with +other ROS packages that depend on Gazebo-classic. + + +| | **Gazebo Garden** | **Gazebo Harmonic (LTS)** | +|------------------------ |----------------------------- | -------------------------- | +| **ROS 2 Iron** | `ros-iron-ros-gzgarden` | `ros-iron-ros-gzharmonic` | +| **ROS 2 Humble (LTS)** | `ros-humble-ros-gzgarden` | `ros-humble-ros-gzharmonic` | #### Where I can find the different features implemented on each Gazebo version?