diff --git a/garden/index.yaml b/garden/index.yaml index b64dccee3..c45c97aad 100644 --- a/garden/index.yaml +++ b/garden/index.yaml @@ -45,7 +45,7 @@ pages: title: Migration from Ignition file: migration_from_ignition.md description: Migration from the Ignition name - + - name: comparison title: Feature Comparison file: comparison.md @@ -87,5 +87,4 @@ pages: file: sensors.md - name: actors title: Actors - file: actors.md - + file: actors.md diff --git a/garden/install.md b/garden/install.md index d12f04675..dfc2b83ef 100644 --- a/garden/install.md +++ b/garden/install.md @@ -62,7 +62,7 @@ for the full status. ## Migration Guide -Gazebo Garden is the first major release that [uses the Gazebo brand instead of Gazebo](https://community.gazebosim.org/t/a-new-era-for-gazebo/1356). +Gazebo Garden is the first major release that [uses the Gazebo brand instead of Ignition](https://community.gazebosim.org/t/a-new-era-for-gazebo/1356). So if you are upgrading from a prior release (e.g. Fortress), you will need to do some steps to migrate your packages. - [Guide for Migrating From Ignition](migration_from_ignition) diff --git a/harmonic/GUI_tutorial.md b/harmonic/GUI_tutorial.md new file mode 100644 index 000000000..6dc8a2d14 --- /dev/null +++ b/harmonic/GUI_tutorial.md @@ -0,0 +1,140 @@ +# Understanding the GUI + +This guide is an introduction to the Gazebo Graphical User Interface (GUI). + +## Prerequisites + +Before beginning, you should have [Harmonic installed](/docs/harmonic/install). +If you installed [from source](/docs/harmonic/install) +you will need to [source](/docs/harmonic/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 Harmonic (8.x.x), Garden (7.x.x), and Fortress (6.x.x) installed, `--versions` might return: + +```bash +8.0.0 +7.0.0 +6.0.0 +``` + +To ensure you're working with Harmonic, include the `--force-version` directive when starting up: + +```bash +gz sim --force-version 8.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/harmonic/Manipulating_models.md b/harmonic/Manipulating_models.md new file mode 100644 index 000000000..379166842 --- /dev/null +++ b/harmonic/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/harmonic/Model_insertion_fuel.md b/harmonic/Model_insertion_fuel.md new file mode 100644 index 000000000..7cfc5fc25 --- /dev/null +++ b/harmonic/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/harmonic/actors.md b/harmonic/actors.md new file mode 100644 index 000000000..3dd667ae8 --- /dev/null +++ b/harmonic/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/harmonic/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/harmonic/building_robot.md b/harmonic/building_robot.md new file mode 100644 index 000000000..178d0cf44 --- /dev/null +++ b/harmonic/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/harmonic/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/harmonic/comparison.md b/harmonic/comparison.md new file mode 100644 index 000000000..9d6d62c95 --- /dev/null +++ b/harmonic/comparison.md @@ -0,0 +1,329 @@ +# 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 Garden](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 1 Noetic (from source) +* ROS 2 Humble (from source) / Rolling (from source) + +Note: binaries for ROS2 might be available sometime after the Garden 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 +Garden release this means that it will be adopted when ROS 2 Iron 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: [command line](https://github.com/gazebosim/gz-sim/issues/25), [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/harmonic/hotkeys.md b/harmonic/hotkeys.md new file mode 100644 index 000000000..fa19f4c89 --- /dev/null +++ b/harmonic/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/harmonic/img/align.gif b/harmonic/img/align.gif new file mode 100644 index 000000000..04b15b6cf Binary files /dev/null and b/harmonic/img/align.gif differ diff --git a/harmonic/img/align_reverse.gif b/harmonic/img/align_reverse.gif new file mode 100644 index 000000000..3854876a2 Binary files /dev/null and b/harmonic/img/align_reverse.gif differ diff --git a/harmonic/img/bridge_image_exchange_ign-gazebo.png b/harmonic/img/bridge_image_exchange_ign-gazebo.png new file mode 100644 index 000000000..a2c020fbd Binary files /dev/null and b/harmonic/img/bridge_image_exchange_ign-gazebo.png differ diff --git a/harmonic/img/custom_snap.png b/harmonic/img/custom_snap.png new file mode 100644 index 000000000..fe22a3e61 Binary files /dev/null and b/harmonic/img/custom_snap.png differ diff --git a/harmonic/img/grid.gif b/harmonic/img/grid.gif new file mode 100644 index 000000000..562b55e11 Binary files /dev/null and b/harmonic/img/grid.gif differ diff --git a/harmonic/img/grid2.gif b/harmonic/img/grid2.gif new file mode 100644 index 000000000..4eed529a6 Binary files /dev/null and b/harmonic/img/grid2.gif differ diff --git a/harmonic/img/plugins.png b/harmonic/img/plugins.png new file mode 100644 index 000000000..1ef8c6858 Binary files /dev/null and b/harmonic/img/plugins.png differ diff --git a/harmonic/img/pose2.gif b/harmonic/img/pose2.gif new file mode 100644 index 000000000..630377ebd Binary files /dev/null and b/harmonic/img/pose2.gif differ diff --git a/harmonic/img/pose_value.gif b/harmonic/img/pose_value.gif new file mode 100644 index 000000000..df1263b28 Binary files /dev/null and b/harmonic/img/pose_value.gif differ diff --git a/harmonic/img/rotate.gif b/harmonic/img/rotate.gif new file mode 100644 index 000000000..649b7227a Binary files /dev/null and b/harmonic/img/rotate.gif differ diff --git a/harmonic/img/rotate_icon.png b/harmonic/img/rotate_icon.png new file mode 100644 index 000000000..a594047df Binary files /dev/null and b/harmonic/img/rotate_icon.png differ diff --git a/harmonic/img/rotate_worldframe.gif b/harmonic/img/rotate_worldframe.gif new file mode 100644 index 000000000..d57f531cb Binary files /dev/null and b/harmonic/img/rotate_worldframe.gif differ diff --git a/harmonic/img/select_mult.png b/harmonic/img/select_mult.png new file mode 100644 index 000000000..067bed1b0 Binary files /dev/null and b/harmonic/img/select_mult.png differ diff --git a/harmonic/img/snap.gif b/harmonic/img/snap.gif new file mode 100644 index 000000000..d113f863d Binary files /dev/null and b/harmonic/img/snap.gif differ diff --git a/harmonic/img/snap_icon.png b/harmonic/img/snap_icon.png new file mode 100644 index 000000000..490112b54 Binary files /dev/null and b/harmonic/img/snap_icon.png differ diff --git a/harmonic/img/translate.gif b/harmonic/img/translate.gif new file mode 100644 index 000000000..0956282b0 Binary files /dev/null and b/harmonic/img/translate.gif differ diff --git a/harmonic/img/translate_icon.png b/harmonic/img/translate_icon.png new file mode 100644 index 000000000..6c32b6ebc Binary files /dev/null and b/harmonic/img/translate_icon.png differ diff --git a/harmonic/img/translate_worldframe.gif b/harmonic/img/translate_worldframe.gif new file mode 100644 index 000000000..ba11d4b3d Binary files /dev/null and b/harmonic/img/translate_worldframe.gif differ diff --git a/harmonic/img/view.gif b/harmonic/img/view.gif new file mode 100644 index 000000000..badc9da1a Binary files /dev/null and b/harmonic/img/view.gif differ diff --git a/harmonic/index.yaml b/harmonic/index.yaml index 01343c768..edbfb990b 100644 --- a/harmonic/index.yaml +++ b/harmonic/index.yaml @@ -20,6 +20,15 @@ pages: file: install.md description: Harmonic 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 @@ -32,3 +41,50 @@ pages: - 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: ros2_integration + title: ROS 2 Integration + file: ros2_integration.md + - name: spawn_urdf + title: Spawn URDF + file: spawn_urdf.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: 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 diff --git a/harmonic/install.md b/harmonic/install.md index 6dfef34b3..3f769c930 100644 --- a/harmonic/install.md +++ b/harmonic/install.md @@ -7,7 +7,11 @@ long-term release. ## Binary installation instructions -There are no Harmonic binaries at the moment +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 @@ -50,8 +54,8 @@ This list may change up to the release date. These are the **officially** supported platforms: -* Ubuntu Focal on amd64 * Ubuntu Jammy on amd64 +* Ubuntu 24.04 on amd64 Platforms supported at **best-effort** include arm architectures, Windows and macOS. See diff --git a/harmonic/install_osx.md b/harmonic/install_osx.md new file mode 100644 index 000000000..8cfb02ff5 --- /dev/null +++ b/harmonic/install_osx.md @@ -0,0 +1,35 @@ +# Binary Installation on MacOS + +All the Harmonic 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 Harmonic can be installed running: + +```bash +brew tap osrf/simulation +brew install gz-harmonic +``` + +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-harmonic +``` + +## Troubleshooting + +See [Troubleshooting](/docs/harmonic/troubleshooting#macos) diff --git a/harmonic/install_osx_src.md b/harmonic/install_osx_src.md index 8be9b379a..dc0c3f78b 100644 --- a/harmonic/install_osx_src.md +++ b/harmonic/install_osx_src.md @@ -1,7 +1,6 @@ # Source Installation on macOS -This tutorial will work for macOS Catalina 10.15, macOS BigSur 10.16, -and macOS Monterey 12.0. +This tutorial will work for macOS BigSur 10.16 and macOS Monterey 12.0. ## Install tools @@ -92,7 +91,7 @@ brew install assimp boost bullet cmake cppzmq dartsim@6.10.0 doxygen eigen fcl f ``` `dartsim@6.10.0` and `qt@5` are not sym-linked. To use those dependencies when building -`gz-physics6` and `gz-gui8`, run the following after installation: +`gz-physics7` and `gz-gui8`, run the following after installation: For Macs with Intel processors, add them to `/usr/local`: @@ -105,7 +104,7 @@ export PKG_CONFIG_PATH=${PKG_CONFIG_PATH}:/usr/local/opt/dartsim@6.10.0/lib/pkgc 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: +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 @@ -127,60 +126,6 @@ You will need to sign in to your Apple account and download the Mojave version o 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 in MacOS Catalina (10.15) - -If you want to compile Gazebo Libraries in MacOS Catalina (10.15) you will need to apply some patches in your filesystem: - - - `/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/System/Library/Frameworks/Ruby.framework/Headers/ruby/ruby/intern.h` - -Create a file called `intern.patch` with the following content: - -```patch ---- intern.h 2019-12-16 18:17:08.000000000 +0100 -+++ /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/System/Library/Frameworks/Ruby.framework/Headers/ruby/ruby/intern.h -@@ -14,6 +14,10 @@ - #ifndef RUBY_INTERN_H - #define RUBY_INTERN_H 1 - -+#if __cplusplus > 199711L -+#define register // Deprecated in C++11. -+#endif // #if __cplusplus > 199711L -+ - #if defined(__cplusplus) - extern "C" { - #if 0 -``` - -Now we can apply the patch: - -```{.sh} -sudo patch -p0 < intern.patch -``` - - - `/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/System/Library/Frameworks/Ruby.framework/Headers/ruby/ruby/config.h` - -Create a file called `config.patch` with the following content: - -```patch ---- config.h 2019-12-16 18:19:13.000000000 +0100 -+++ /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/System/Library/Frameworks/Ruby.framework/Headers/ruby/ruby/config.h -@@ -410,6 +410,6 @@ - #define RUBY_PLATFORM_CPU "x86_64" - #endif /* defined __x86_64__ &&! defined RUBY_PLATFORM_CPU */ - #define RUBY_PLATFORM_OS "darwin19" --#define RUBY_ARCH"universal-"RUBY_PLATFORM_OS --#define RUBY_PLATFORM"universal."RUBY_PLATFORM_CPU"-"RUBY_PLATFORM_OS -+#define RUBY_ARCH "universal-" RUBY_PLATFORM_OS -+#define RUBY_PLATFORM "universal." RUBY_PLATFORM_CPU "-" RUBY_PLATFORM_OS - #endif /* INCLUDE_RUBY_CONFIG_H */ -``` - -Now we can appply the patch: - -```{.sh} -sudo patch -p0 < config.patch -``` - ## Building the Gazebo Libraries Once the compiler and all the sources are in place it is time to compile them. diff --git a/harmonic/install_ubuntu.md b/harmonic/install_ubuntu.md new file mode 100644 index 000000000..34df63d9a --- /dev/null +++ b/harmonic/install_ubuntu.md @@ -0,0 +1,44 @@ +# Binary Installation on Ubuntu + +Harmonic pre-release binaries are provided for Ubuntu Jammy (22.04) and Ubuntu 24.04. The +Harmonic binaries are hosted in the packages.osrfoundation.org repository. +To install all of them, the metapackage `gz-harmonic` can be installed. + +**WARNING:** `gz-harmonic` cannot be installed alongside gazebo-classic (eg. `gazebo11`) since both use the `gz` command line tool. Trying to install `gz-harmonic` 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 Harmonic: + + +```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 +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-prerelease $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-prerelease.list > /dev/null +sudo apt-get update +sudo apt-get install gz-harmonic +``` + +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-harmonic && sudo apt autoremove +``` + +## Troubleshooting + +See [Troubleshooting](/docs/harmonic/troubleshooting#ubuntu) diff --git a/harmonic/install_ubuntu_src.md b/harmonic/install_ubuntu_src.md index 3c16829f7..53b20e020 100644 --- a/harmonic/install_ubuntu_src.md +++ b/harmonic/install_ubuntu_src.md @@ -1,6 +1,6 @@ # Source Installation on Ubuntu -These instructions apply to Ubuntu Focal (20.04) and Jammy (22.04). +These instructions apply to Ubuntu Jammy (22.04) and Ubuntu 24.04. ## Install tools diff --git a/harmonic/install_windows.md b/harmonic/install_windows.md new file mode 100644 index 000000000..f0aacc753 --- /dev/null +++ b/harmonic/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/harmonic/troubleshooting#windows) diff --git a/harmonic/install_windows_src.md b/harmonic/install_windows_src.md index 1e8915691..435494f7a 100644 --- a/harmonic/install_windows_src.md +++ b/harmonic/install_windows_src.md @@ -1,3 +1,7 @@ +
+WARNING: Current Windows support is experimental. +
+ # Source Installation on Windows 10 Command line tools, DART physics engine, and GUI capabilities are diff --git a/harmonic/migration_from_ignition.md b/harmonic/migration_from_ignition.md new file mode 100644 index 000000000..30e5da93a --- /dev/null +++ b/harmonic/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 Harmonic, 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-Harmonic 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/harmonic/moving_robot.md b/harmonic/moving_robot.md new file mode 100644 index 000000000..f1d8e841d --- /dev/null +++ b/harmonic/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/harmonic/tutorials/building_robot/building_robot.sdf). +You can also find the finished world of this tutorial [here](https://github.com/gazebosim/docs/blob/master/harmonic/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/harmonic/ros2_integration.md b/harmonic/ros2_integration.md new file mode 100644 index 000000000..5909291f5 --- /dev/null +++ b/harmonic/ros2_integration.md @@ -0,0 +1,83 @@ +# 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 or commands +from ROS and apply it to Gazebo and vice versa. + +## ros_gz_bridge + +`ros_gz_bridge` 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). + + diff --git a/harmonic/sdf_worlds.md b/harmonic/sdf_worlds.md new file mode 100644 index 000000000..6a3a3fc70 --- /dev/null +++ b/harmonic/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/harmonic/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/harmonic/sensors.md b/harmonic/sensors.md new file mode 100644 index 000000000..b03d36257 --- /dev/null +++ b/harmonic/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/harmonic/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/harmonic/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/harmonic/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/harmonic/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/harmonic/spawn_urdf.md b/harmonic/spawn_urdf.md new file mode 100644 index 000000000..8d4e02669 --- /dev/null +++ b/harmonic/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`](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/foxy/Tutorials/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/harmonic/troubleshooting.md b/harmonic/troubleshooting.md index 94536837a..2294564ba 100644 --- a/harmonic/troubleshooting.md +++ b/harmonic/troubleshooting.md @@ -51,10 +51,10 @@ This command will ignore the system installation of `urdfdom` and use the intern When running the `gz sim -s` command, an error like the one below may show up: ```bash -Error while loading the library [/Users/harmonic/harmonic_ws/install/lib//libgz-physics6-dartsim-plugin.6.dylib]: dlopen(/Users/harmonic/harmonic_ws/install/lib//libgz-physics6-dartsim-plugin.6.dylib, 5): Library not loaded: @rpath/libIrrXML.dylib +Error while loading the library [/Users/garden/garden_ws/install/lib//libgz-physics6-dartsim-plugin.6.dylib]: dlopen(/Users/garden/garden_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/harmonic/harmonic_ws/install/lib//libgz-physics6-dartsim-plugin.6.dylib library. +[Err] [Physics.cc:275] Unable to load the /Users/garden/garden_ws/install/lib//libgz-physics6-dartsim-plugin.6.dylib library. Escalating to SIGKILL on [Gazebo Sim Server] ``` @@ -149,6 +149,10 @@ 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: @@ -158,9 +162,9 @@ 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: - ign gazebo -v 3 lights.sdf + gz sim -v 3 lights.sdf -If that loads, you can continue to use Ignition with Ogre 1, just use the +If that loads, you can continue to use Gazebo with Ogre 1, just use the `--render-engine ogre` option. ## Windows diff --git a/harmonic/tutorials.md b/harmonic/tutorials.md new file mode 100644 index 000000000..36e68c812 --- /dev/null +++ b/harmonic/tutorials.md @@ -0,0 +1,46 @@ +# 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 + +* [ROS 2 Integration](ros2_integration) + +## 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/7/tutorials.html) + +Other libraries: +- [Cmake](/api/cmake/3/tutorials.html) +- [Common](/api/common/5/tutorials.html) +- [Fuel_tools](/api/fuel_tools/8/tutorials.html) +- [Gui](/api/gui/7/tutorials.html) +- [Launch](/api/launch/6/tutorials.html) +- [Math](/api/math/7/tutorials.html) +- [Msgs](/api/msgs/9/tutorials.html) +- [Physics](/api/physics/6/tutorials.html) +- [Plugin](/api/plugin/2/tutorials.html) +- [Rendering](/api/rendering/7/tutorials.html) +- [Sensors](/api/sensors/7/tutorials.html) +- [Tools](/api/tools/2/tutorials.html) +- [Transport](/api/transport/12/tutorials.html) +- [Utils](/api/utils/2/tutorials.html) +- [Sdformat](/api/sdformat/13/) diff --git a/harmonic/tutorials/actors/actor_demo.gif b/harmonic/tutorials/actors/actor_demo.gif new file mode 100644 index 000000000..d1692f8f1 Binary files /dev/null and b/harmonic/tutorials/actors/actor_demo.gif differ diff --git a/harmonic/tutorials/actors/actor_demo.sdf b/harmonic/tutorials/actors/actor_demo.sdf new file mode 100644 index 000000000..5ee6a14cc --- /dev/null +++ b/harmonic/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/harmonic/tutorials/actors/actor_skin.gif b/harmonic/tutorials/actors/actor_skin.gif new file mode 100644 index 000000000..7292afe30 Binary files /dev/null and b/harmonic/tutorials/actors/actor_skin.gif differ diff --git a/harmonic/tutorials/actors/combined_movement.gif b/harmonic/tutorials/actors/combined_movement.gif new file mode 100644 index 000000000..50afbb6f0 Binary files /dev/null and b/harmonic/tutorials/actors/combined_movement.gif differ diff --git a/harmonic/tutorials/actors/skeleton_movement.gif b/harmonic/tutorials/actors/skeleton_movement.gif new file mode 100644 index 000000000..d13e07a4c Binary files /dev/null and b/harmonic/tutorials/actors/skeleton_movement.gif differ diff --git a/harmonic/tutorials/actors/trajectory_movement.gif b/harmonic/tutorials/actors/trajectory_movement.gif new file mode 100644 index 000000000..046e84120 Binary files /dev/null and b/harmonic/tutorials/actors/trajectory_movement.gif differ diff --git a/harmonic/tutorials/building_robot/building_robot.sdf b/harmonic/tutorials/building_robot/building_robot.sdf new file mode 100644 index 000000000..05a1bdbef --- /dev/null +++ b/harmonic/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/harmonic/tutorials/building_robot/car_left_wheel.png b/harmonic/tutorials/building_robot/car_left_wheel.png new file mode 100644 index 000000000..f35f5a4c6 Binary files /dev/null and b/harmonic/tutorials/building_robot/car_left_wheel.png differ diff --git a/harmonic/tutorials/building_robot/chassis.png b/harmonic/tutorials/building_robot/chassis.png new file mode 100644 index 000000000..d1e79c4e4 Binary files /dev/null and b/harmonic/tutorials/building_robot/chassis.png differ diff --git a/harmonic/tutorials/building_robot/model_axis.png b/harmonic/tutorials/building_robot/model_axis.png new file mode 100644 index 000000000..41d94fea5 Binary files /dev/null and b/harmonic/tutorials/building_robot/model_axis.png differ diff --git a/harmonic/tutorials/building_robot/two_wheeled_robot.png b/harmonic/tutorials/building_robot/two_wheeled_robot.png new file mode 100644 index 000000000..448463da7 Binary files /dev/null and b/harmonic/tutorials/building_robot/two_wheeled_robot.png differ diff --git a/harmonic/tutorials/fuel_insert/fuel.png b/harmonic/tutorials/fuel_insert/fuel.png new file mode 100644 index 000000000..e7cb49183 Binary files /dev/null and b/harmonic/tutorials/fuel_insert/fuel.png differ diff --git a/harmonic/tutorials/fuel_insert/husky.gif b/harmonic/tutorials/fuel_insert/husky.gif new file mode 100644 index 000000000..fb09b9e84 Binary files /dev/null and b/harmonic/tutorials/fuel_insert/husky.gif differ diff --git a/harmonic/tutorials/fuel_insert/mine_cart_engine_detail.png b/harmonic/tutorials/fuel_insert/mine_cart_engine_detail.png new file mode 100644 index 000000000..61c2c9104 Binary files /dev/null and b/harmonic/tutorials/fuel_insert/mine_cart_engine_detail.png differ diff --git a/harmonic/tutorials/fuel_insert/resource_spawner_cloud.png b/harmonic/tutorials/fuel_insert/resource_spawner_cloud.png new file mode 100644 index 000000000..2fe7d259a Binary files /dev/null and b/harmonic/tutorials/fuel_insert/resource_spawner_cloud.png differ diff --git a/harmonic/tutorials/fuel_insert/resource_spawner_local.png b/harmonic/tutorials/fuel_insert/resource_spawner_local.png new file mode 100644 index 000000000..f42147cd3 Binary files /dev/null and b/harmonic/tutorials/fuel_insert/resource_spawner_local.png differ diff --git a/harmonic/tutorials/gui/entity_select.png b/harmonic/tutorials/gui/entity_select.png new file mode 100644 index 000000000..aa95fd538 Binary files /dev/null and b/harmonic/tutorials/gui/entity_select.png differ diff --git a/harmonic/tutorials/gui/grid_config.png b/harmonic/tutorials/gui/grid_config.png new file mode 100644 index 000000000..f09f797f7 Binary files /dev/null and b/harmonic/tutorials/gui/grid_config.png differ diff --git a/harmonic/tutorials/gui/hover_steps.png b/harmonic/tutorials/gui/hover_steps.png new file mode 100644 index 000000000..e77f1c3fe Binary files /dev/null and b/harmonic/tutorials/gui/hover_steps.png differ diff --git a/harmonic/tutorials/gui/menu_btn.png b/harmonic/tutorials/gui/menu_btn.png new file mode 100644 index 000000000..6cb185d35 Binary files /dev/null and b/harmonic/tutorials/gui/menu_btn.png differ diff --git a/harmonic/tutorials/gui/playback.png b/harmonic/tutorials/gui/playback.png new file mode 100644 index 000000000..bd521bce1 Binary files /dev/null and b/harmonic/tutorials/gui/playback.png differ diff --git a/harmonic/tutorials/gui/plugins_btn.png b/harmonic/tutorials/gui/plugins_btn.png new file mode 100644 index 000000000..ddbdaa289 Binary files /dev/null and b/harmonic/tutorials/gui/plugins_btn.png differ diff --git a/harmonic/tutorials/gui/rtf_expanded.png b/harmonic/tutorials/gui/rtf_expanded.png new file mode 100644 index 000000000..85f275dfa Binary files /dev/null and b/harmonic/tutorials/gui/rtf_expanded.png differ diff --git a/harmonic/tutorials/gui/shape_insertion.png b/harmonic/tutorials/gui/shape_insertion.png new file mode 100644 index 000000000..e34222150 Binary files /dev/null and b/harmonic/tutorials/gui/shape_insertion.png differ diff --git a/harmonic/tutorials/gui/shapes.png b/harmonic/tutorials/gui/shapes.png new file mode 100644 index 000000000..8763a263d Binary files /dev/null and b/harmonic/tutorials/gui/shapes.png differ diff --git a/harmonic/tutorials/gui/toolbars.png b/harmonic/tutorials/gui/toolbars.png new file mode 100644 index 000000000..821ea3733 Binary files /dev/null and b/harmonic/tutorials/gui/toolbars.png differ diff --git a/harmonic/tutorials/moving_robot/keypublisher_data.png b/harmonic/tutorials/moving_robot/keypublisher_data.png new file mode 100644 index 000000000..0b357dbbd Binary files /dev/null and b/harmonic/tutorials/moving_robot/keypublisher_data.png differ diff --git a/harmonic/tutorials/moving_robot/moving_robot.sdf b/harmonic/tutorials/moving_robot/moving_robot.sdf new file mode 100644 index 000000000..3630c1ae5 --- /dev/null +++ b/harmonic/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/harmonic/tutorials/ros2_integration/empty_world.png b/harmonic/tutorials/ros2_integration/empty_world.png new file mode 100644 index 000000000..0b48a4ef0 Binary files /dev/null and b/harmonic/tutorials/ros2_integration/empty_world.png differ diff --git a/harmonic/tutorials/sdf_worlds/coke_world.png b/harmonic/tutorials/sdf_worlds/coke_world.png new file mode 100644 index 000000000..7ac8b9892 Binary files /dev/null and b/harmonic/tutorials/sdf_worlds/coke_world.png differ diff --git a/harmonic/tutorials/sdf_worlds/entity_tree.png b/harmonic/tutorials/sdf_worlds/entity_tree.png new file mode 100644 index 000000000..23a815192 Binary files /dev/null and b/harmonic/tutorials/sdf_worlds/entity_tree.png differ diff --git a/harmonic/tutorials/sdf_worlds/two_cokes.png b/harmonic/tutorials/sdf_worlds/two_cokes.png new file mode 100644 index 000000000..527cc0b74 Binary files /dev/null and b/harmonic/tutorials/sdf_worlds/two_cokes.png differ diff --git a/harmonic/tutorials/sdf_worlds/world_demo.sdf b/harmonic/tutorials/sdf_worlds/world_demo.sdf new file mode 100644 index 000000000..f9c3baacf --- /dev/null +++ b/harmonic/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/harmonic/tutorials/sdf_worlds/world_stats.png b/harmonic/tutorials/sdf_worlds/world_stats.png new file mode 100644 index 000000000..7dadcab36 Binary files /dev/null and b/harmonic/tutorials/sdf_worlds/world_stats.png differ diff --git a/harmonic/tutorials/sensors/CMakeLists.txt b/harmonic/tutorials/sensors/CMakeLists.txt new file mode 100644 index 000000000..09d0a8862 --- /dev/null +++ b/harmonic/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/harmonic/tutorials/sensors/imu_msgs.png b/harmonic/tutorials/sensors/imu_msgs.png new file mode 100644 index 000000000..56663f83b Binary files /dev/null and b/harmonic/tutorials/sensors/imu_msgs.png differ diff --git a/harmonic/tutorials/sensors/lidar_node.cc b/harmonic/tutorials/sensors/lidar_node.cc new file mode 100644 index 000000000..7b6e74458 --- /dev/null +++ b/harmonic/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/harmonic/tutorials/sensors/sensor_launch.gzlaunch b/harmonic/tutorials/sensors/sensor_launch.gzlaunch new file mode 100644 index 000000000..f52c47c29 --- /dev/null +++ b/harmonic/tutorials/sensors/sensor_launch.gzlaunch @@ -0,0 +1,11 @@ + + + + gz sim sensor_tutorial.sdf + + + + ./build/lidar_node + + + diff --git a/harmonic/tutorials/sensors/sensor_tutorial.sdf b/harmonic/tutorials/sensors/sensor_tutorial.sdf new file mode 100644 index 000000000..73c9639f6 --- /dev/null +++ b/harmonic/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/harmonic/tutorials/sensors/sensor_wall.png b/harmonic/tutorials/sensors/sensor_wall.png new file mode 100644 index 000000000..95b07c4b5 Binary files /dev/null and b/harmonic/tutorials/sensors/sensor_wall.png differ diff --git a/harmonic/tutorials/spawn_urdf/empty_world.png b/harmonic/tutorials/spawn_urdf/empty_world.png new file mode 100644 index 000000000..9671ce270 Binary files /dev/null and b/harmonic/tutorials/spawn_urdf/empty_world.png differ diff --git a/harmonic/tutorials/spawn_urdf/rrbot.gif b/harmonic/tutorials/spawn_urdf/rrbot.gif new file mode 100644 index 000000000..1dfad37ce Binary files /dev/null and b/harmonic/tutorials/spawn_urdf/rrbot.gif differ diff --git a/harmonic/tutorials/spawn_urdf/rrbot.urdf b/harmonic/tutorials/spawn_urdf/rrbot.urdf new file mode 100644 index 000000000..ff57a914c --- /dev/null +++ b/harmonic/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/harmonic/tutorials/spawn_urdf/urdf_spawned.png b/harmonic/tutorials/spawn_urdf/urdf_spawned.png new file mode 100644 index 000000000..aa032c0a6 Binary files /dev/null and b/harmonic/tutorials/spawn_urdf/urdf_spawned.png differ