Intro

Welcome to the Beginner Module! This module will guide you through the mostbasic features of Gazebo. We will build a simple vehicle to demonstrate thesefeatures.

Each tutorial builds upon the last, so we recommend following the tutorials in order.

These tutorials are intended for those new to Gazebo and/or folks with no programming or Linux experience.

What is Gazebo?

Gazebo is a 3D dynamic simulator with the ability to accurately andefficiently simulate populations of robots in complex indoor and outdoorenvironments. While similar to game engines, Gazebo offers physicssimulation at a much higher degree of fidelity, a suite of sensors, andinterfaces for both users and programs.

Typical uses of Gazebo include:

• testing robotics algorithms,

• designing robots,

• performing regression testing with realistic scenarios

A few key features of Gazebo include:

• multiple physics engines,

• a rich library of robot models and environments,

• a wide variety of sensors,

• convenient programmatic and graphical interfaces

System requirements

Gazebo is currently best used on Ubuntu, a flavor of Linux. You will need a computer that has:

• A dedicated GPU,
  • Nvidia cards tend to work well in Ubuntu
• A CPU that is at least an Intel I5, or equivalent,
• At least 500MB of free disk space,
• Ubuntu Trusty or later installed.

Installation Instructions for Ubuntu

If you run into problems during the install, please see the complete install instructions.

1. Download the installer. If a window opens, you can close it again.

2. Copy the following text by pressing Ctrl-C:

   chmod +x ~/Downloads/gazebo7_install.sh
   

3. Press Alt-F2

   • A window with a prompt should appear in the upper left

4. Press Ctrl-V to paste the text, and press Enter

   • The window will disappear

5. Copy the following by pressing Ctrl-C:

   gnome-terminal --working-directory="~" -e "./Downloads/gazebo7_install.sh"
   

6. Press Alt-F2

   • A window with a prompt should appear in the upper left

7. Press Ctrl-V to paste the text, and press Enter

   • A new window will appear with a password prompt.

8. Enter your password, and press Enter

9. If prompted, press Y to continue

10. Wait until the window disappears

Run Gazebo

1. Press Alt-F2
2. Type "gazebo", and press Enter.

Install Gazebo using Ubuntu packages

Default installation: one-liner

1. Install

   curl -ssL http://get.gazebosim.org | sh
   

2. Run

   gazebo
   

Alternative installation: step-by-step

1. Setup your computer to accept software from packages.osrfoundation.org.

   Note: there is a list of available mirrors for this repository which could improve the download speed.

   sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list'
   

   You can check to see if the file was written correctly. For example, in Ubuntu Trusty, you can type:

   $ cat /etc/apt/sources.list.d/gazebo-stable.list
   deb http://packages.osrfoundation.org/gazebo/ubuntu-stable trusty main
   

2. Setup keys

   wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add -
   

3. Install Gazebo.

   First update the debian database:

   sudo apt-get update
   

   Hint: make sure the apt-get update process ends without any errors, the console output ends in Done similar to below:

   $ sudo apt-get update
   ...
   Hit http://ppa.launchpad.net trusty/main Translation-en
   Ign http://us.archive.ubuntu.com trusty/main Translation-en_US
   Ign http://us.archive.ubuntu.com trusty/multiverse Translation-en_US
   Ign http://us.archive.ubuntu.com trusty/restricted Translation-en_US
   Ign http://us.archive.ubuntu.com trusty/universe Translation-en_US
   Reading package lists... Done
   

   Next install gazebo-7 by:

   sudo apt-get install gazebo7
   # For developers that work on top of Gazebo, one extra package
   sudo apt-get install libgazebo7-dev
   

   If you see the error below:

   $ sudo apt-get install gazebo7
   Reading package lists... Done
   Building dependency tree
   Reading state information... Done
   E: Unable to locate package gazebo7
   

   It's possible the version of Gazebo you are looking for is not supported on the version of OS you are using.For example, installing gazebo7 on Ubuntu Precise (12.04) will produce the error above.Hint: Take a look at "Project Status" section at http://gazebosim.org/#status, next to each version is the supported ubuntu versions and ROS versions.

4. Check your installation

   Note The first time gazebo is executed requires the download of some models and it could take some time, please be patient.

   gazebo
   

Gazebo in different deb packages

Gazebo ships different Ubuntu debian packages following the official packagingguidelines. This changesbrings an option about how to install gazebo:

• Use Gazebo as an application: for the users that just run Gazebo simulatorwith the provided plugins and models and do not plan on developing on top ofgazebo its own custom software. To use Gazebo 7.0, please install the packagecalled gazebo7.

• Use Gazebo to develop software using Gazebo libraries: for users thatdevelop plugins or any other kind of software that needs Gazebo headers andlibraries. In this case, together with gazebo7 package, please installlibgazebo7-dev.

User Interface

This is an introduction to the Gazebo Graphical User Interface, or GUI. We will learn interface basics like what the buttons do and how to navigate in the scene.

By now, you should have Gazebo installed.

Start by opening Gazebo. Press Alt-F2, type Gazebo, and then press Enter.

GUI

This is what you should see:

Note that the Gazebo interface consists of multiple sections, explained below.

The Scene

The Scene is the main part of the simulator. This is where the simulatedobjects are animated and you interact with the environment.

The Panels

Both side panels—right and left—can be displayed, hidden or resized by draggingthe bar that separates them from the Scene.

Left Panel

The left panel appears by default when you launch Gazebo. There are three tabsin the panel:

• WORLD: The World tab displays the models that are currently in thescene, and allows you to view and modify model parameters, like theirpose. You can also change the camera view angle by expanding the"GUI" option and tweaking the camera pose.

• INSERT: The Insert tab is where you add new objects (models) to thesimulation. To see the model list, you may need to click the arrow to expand thefolder. Click (and release) on the model you want to insert, and clickagain in the Scene to add it.

• LAYERS: The Layers tab organizes and displays the differentvisualization groups that are available in the simulation, if any. A layermay contain one or more models. Toggling a layer on or off will displayor hide the models in that layer.

  This is an optional feature, so this tab will be empty inmost cases. To learn more about Layers, check out theVisibility Layerstutorial.

Right Panel (hidden by default)

The right panel is hidden by default. Click and drag the bar to open it. The right panel canbe used to interact with the mobile parts of a selected model (the joints). If there are nomodels selected in the Scene, the panel does not display any information.

The Toolbars

The Gazebo interface has two Toolbars. One is located just above the Scene, andthe other is just below.

Upper Toolbar

The main Toolbar includes some of the most-used options for interacting withthe simulator, such as buttons to: select, move, rotate, and scale objects;create simple shapes (e.g. cube, sphere, cylinder); and copy/paste. Go ahead and playaround with each button to see how it behaves.

Select mode: Navigate in the scene

Translate mode: Select models you want to move

Rotate mode: Select models you want to rotate

Scale mode: Select models you want to scale

Undo/Redo: Undo/redo actions in the scene

Simple shapes: Insert simple shapes into the scene

Lights: Add lights to the scene

Copy/paste: Copy/paste models in the scene

Align: Align models to one another

Snap: Snap one model to another

Change view: View the scene from various angles

Bottom Toolbar

The Bottom Toolbar displays data about the simulation, like the simulation timeand its relationship to real-life time. "Simulation time" refers to how quicklytime is passing in the simulator when a simulation is running. Simulation canbe slower or faster than real time, depending on how much computation isrequired to run the simulation.

"Real time" refers to the actual time that is passing in real life as thesimulator runs. The relationship between the simulation time and real time isknown as the "real time factor" (RTF). It's the ratio of simulation time to realtime. The RTF is a measure of how fast or slow your simulation is runningcompared to real time.

The state of the world in Gazebo is calculated once per iteration. You cansee the number of iterations on the right side of the bottom toolbar. Eachiteration advances simulation by a fixed number of seconds, called the stepsize. By default, the step size is 1 ms. You can pressthe pause button to pause the simulation and step through a few steps ata time using the step button.

The Menu

Like most applications, Gazebo has an application menu up top. Some of the menuoptions are duplicated in the Toolbars or as right-click context menu optionsin the Scene. Check out the various menus to familiarize yourself.

NOTE: Some Linux desktops hide application menus. If you don't see themenus, move your cursor to the top of the application window, and the menusshould appear.

Mouse Controls

The mouse is very useful when navigating in the Scene. We highly recommendusing a mouse with a scroll wheel. Below are the basic mouse operations fornavigating in the Scene and changing the view angle.

Right-clicking on models will open a context menu with various options.Right-click on a model now to see what's available.

Model Editor

Now we'll construct our simple robot. We'll make a wheeled vehicle and add a sensor that allows us to make the robot follow a blob (person).

The Model Editor lets us construct simple models right in the Graphical User Interface (GUI). For more complex models, you'll need to learn how to write SDF files, and check out the tutorials on building a robot.But for now, we can do everything right in the Gazebo GUI!

Model Editor User Interface

To enter the Model Editor, click on Edit in the menu bar and select Model Editor. Or, use the hotkeys, Ctrl+M. Physics and the simulation will be paused as soon as you are in the Model Editor.

The Model Editor interface looks similar to the main Gazebo UI but with some subtle differences. The left panel and top Toolbar now contain only widgets for editing and creating parts of the model. The bottom Toolbar that displays simulation data is hidden since the simulation is now paused.

Left Panel

The left panel, also known as the Palette, has two tabs.

• INSERT tab: The Insert tab is where you add new parts (links and models)to the Model Editor. There are three sections.

  • Simple Shapes: These are primitive geometries that can beinserted to form a link of the model.
  • Custom Shapes: The Add button allows you to import custom meshes(currently supports COLLADA, STL, and SVG files) into the editor to forma link of the model.
  • Model Database: Located in the bottom half of the Palette is alist of models. These are models on your local computer or modelsavailable for download from the online model database.They can be inserted into the Model Editor in the same way as simple shapesand custom meshes. Once inserted, they become a part of the model you arebuilding. We refer to them as Nested Models.

• MODEL tab: The Model tab allows you to set the name and basic parameters of the model youare building. It also displays a list of the links, joints, nested models, and plugins that are currentlypart of the model. You can view and modify a part's parameters, like its pose, in two ways: 1) by double-clicking on the part in the list, or 2) byright-clicking on the part and selecting Open Inspector from the context menu in the Scene.

Toolbar

Like in Simulation mode, the main Toolbar in the Model Editor includes tools for interacting with the objects in the Scene (see the User Interface tutorial).

A new Joint Creation tool is available; it is used to create joints between links in the model.

Limitations

The Model Editor supports most of the basic model building tasks that can be done by writing SDF. However, there are a few features that are notyet available:

• adding and editing model plugins.

• editing nested models and links within nested models.

• adding and editing certain geometry types including Plane and Polyline.

• support for heightmaps.

• CAD functionalities.

Vehicle construction

Creating a vehicle

This section provides step-by-step instructions on creating a simple vehicle model in the Model Editor.

Chassis

1. First, we'll create the vehicle chassis. In the Insert tab in the left panel, click once on the Box icon, move the cursor to anywhere in the Scene, and click again to release the box.

   

2. Next, resize the box so that it looks more like the shape of a car chassis. We can do this by selecting the Scale tool located on the top Toolbar.Select the box in the Scene, and a RGB-colored marker should appear over the box. The red marker represents the X axis, green is Y, and blue is Z. Move the mouse over the red marker to highlight it, then click and drag to make the chassis longer along the X axis. Scale the chassisso it is roughly 2 meters long. You can estimate this by looking at the 1x1 meter grids on the ground.

   

3. Now flatten the chassis with the Scale tool. Click and drag the blue marker down so that the chassis is approximately half of its original size.

   

4. We want to lower the chassis closer to the ground. To give exact measurements, we will use the Link Inspector. Double-click on the box to bring up theInspector. Scroll down to the bottom of the Link tab to find the Pose parameters and change Z to be 0.4m. Click OK to save the changes and closethe Inspector.

   

Front Wheels

1. Let's move on to the front wheels. Start by inserting a cylinder from the Insert tab on the left panel.

2. The cylinder in its default orientation will not roll very well. Let's rotate it along the X axis using the Link Inspector. Double-click on the cylinder, scroll to the Pose section at the bottom, and change Roll to 1.5707 radians (90 degrees) and hit the Enter key on the keyboard. Do not close the Inspector just yet.

   

3. Next, resize the wheel by giving it exact dimensions. Go to the Visual tab to see the list of visuals in this link. There should only be one. Expand the visual item by clicking on the small arrow next to the visual text label. Scroll down to the Geometry section and change the Radiusto 0.3m and Length to 0.25m.

   

4. You should now see a smaller cylinder inside a bigger cylinder. This is expected as we have only changed the visual geometry but not the collision. A 'visual' is the graphical representation of the link and does not affect the physics simulation. On the other hand, a 'collision'is used by the physics engine for collision checking. To also update the wheel's collision, go to the Collision tab, expand the only collision item, and enter the same Geometry dimensions. Radius: 0.3m and Length: 0.25m. Click on OK to save the changes and close the Inspector.

5. Now that we have created our first wheel, we'll use it as a template and make another one. Select the wheel and click on the Copy icon in the top Toolbar.

   

6. Click on the Paste icon and move the mouse back to the Scene to insert the copy.

   

   Let's now make sure that the vehicle will drive correctly by aligning the chassis along the positive X axis (the red marker in the scene). When you add the wheels in the next step,make sure they are at the end of the vehicle that is extending along the positive X axis.

7. The chassis and the wheels are currently free-moving bodies. To constrain their motion, we'll add joints between each wheel and the chassis. Click on the Joint icon in the top Toolbar to bring up the Joint Creation dialog.

   

8. The Joint Creation dialog contains joint properties that are commonly specified for a joint. Before configuring any of the properties, you are prompted to select the parent and child links of the joint. Move the mouse over the chassis in the Scene to see it highlighted, and click on it to set it as theparent of the joint.

9. Move the mouse to the left front wheel; a line should now extend from the origin of the chassis to the end of the mouse. Click on the wheel to set it as the child of the joint. A new joint is created. By default it is a revolute joint (as indicated in the Joint Types section in the dialog) which justhappens to be the joint type we want.

   Note: You may find it useful to change the view angle at this point. This can be done in the Upper Toolbar; click the cube icon with an orange side.

   

10. Next, we need to configure the axis of rotation of the wheel. In the Joint Creation dialog, find the Joint axis section and change the axis to be Z (0, 0, 1). Pay attention to the RGB joint visual on the wheel. You should see that a yellow ring now appears over the blue arrow of the joint visual toindicate that it is the axis of rotation.

    

11. To align the wheel next to the chassis, we will use the different alignment options in the Align links section in the Joint Creation dialog. First we will align in the X axis, so click on the X Align Max option to see the result of the alignment. The cylinder should be highlighted to indicate that itspose has changed.

    

12. In our example, we want to position the wheel flush against the chassis. To bring the wheel closer, click the Y Align Max option. However, it is not quite what we want yet. Click the Reverse option next the Y alignment options to align the wheel's minimum (reverse of maximum) to the chassis's maximum.Note that the Reverse option is applied to the child link since the default alignment configuration shown in the drop down list below is Child to Parent. If Parent to Child configuration is set, the Reverse option will be applied to the parent link. Press Create.

    

13. To position the wheel above the ground, open the Link Inspector by double-clicking on the wheel. We can use the Pose section at the bottom of the dialog to move the wheel. Given that the wheel has a radius of 0.3m, go ahead and change the Z position to 0.3m to place on the ground, and press Ok.

14. Repeat the joint creation process and axis configuration for the other front wheel, make sure that a) the chassis is the parent of the joint and the wheel is the child, b) the axis of rotation is set to Z, and c) use the Y Align Min option to align the right wheel as it is on the other side of the chassis.

    

Caster Wheel

1. To make a caster wheel for the vehicle, click on the Sphere button on the Left Panel and insert it into the scene.

   

2. Resize the sphere by giving it exact dimensions in the same way you did for the front wheels. Go to the Visual tab to see the list of visuals in this link, expand the only visual item, scroll down to the Geometry section and change the Radius to 0.2m. Make sure to also do the same to the collision in theCollision tab.

   

3. To create a joint between the caster wheel and the chassis, bring up the Joint Creation dialog by clicking on the Joint icon in the top Toolbar. Move the mouse to the Scene and select the chassis as the parent link and the sphere as the child link.

   

4. Unlike the front wheel joints, a caster wheel rolls in all directions and does not have a specific axis of rotation. In Gazebo, this is simulated using a ball joint. So under the Joint types section, select the Ball joint option. You should see the joint visual in the scene change color to indicate adifferent joint type has been set.

   

5. Next, align the caster wheel so that it is centered with the chassis and positioned at the rear end. In the Align links section, select the Y Align Center option to center the two links in the Y axis, and select the X Align Min option to move the caster wheel so it is placed right at the back of the vehicle. Press the Create button to finish the joint creation process.

   

6. Finally, position the caster wheel so that it sits just above the ground. Do this by opening the Link Inspector and setting the Z position to 0.2m.

Adding a sensor

The sensor we will add to the car is a depth camera sensor which is going to help us detect objects in front of the car. In this tutorial, we will insert an existing sensor model from the model database.

1. Go to the Palette (left panel) and select the Insert tab to see a list of models available in the Model Database section.

   

2. The models in the lists are organized by the path in which they are located. As you can see, the first list contains models available on your local machine as indicated by the path in the title. If you are a first-time user, you may not see many models in the lists. More will appear as you download them fromthe online model database. Find the list with the path http://gazebosim.org/models/ and expand it to see models available from the online model database.

   

3. The models are arranged in alphabetical order. Find Depth Camera in the list and click on it to start downloading the model. This may take a few seconds depending on the network connectivity.

4. Once the download is complete, you should see the depth camera model appear in the Scene. It looks like a small cube. Move the mouse over to the Scene and click on an empty space in front of the car to insert the depth camera.

   

5. Select the Translate tool in the top Toolbar and move the depth camera so that it sits on top of the chassis at the front of the vehicle and roughly centered in the Y axis.

   

6. Next, fix the depth camera to the chassis. Click on the Joint icon in the top Toolbar to open the Joint Creation dialog. Move the mouse to the Scene and select the chassis as the parent link and the depth camera as the child link.

   

7. In the Joint Creation dialog under the Joint Types section, select the Fixed joint option, and click on Create to finish creating the joint.

   

Adding a plugin

The vehicle we have built so far is complete with all of the physical and sensor components. However, it will not really do much but stay still and generate depth data in simulation. Plugins are a great way to enhance the model with some autonomy by allowing it to perform computations such as sensor dataprocessing, path planning, and control. For simplicity, this tutorial will use an existing plugin for our vehicle. Note that it is possible to create your own plugins but it requires writing code. See the Plugin tutorials.

1. Go to the left panel and select the Model tab to see the parts that make up the car model you built.

   

2. Under Model Plugins, you should see an Add button. Click on it to bring up a Model Plugin Inspector that lets you add a new plugin to the model.

   

3. First, give the plugin a name. Enter follower in the Plugin Name field. The plugin name has to be unique within this model.

4. The plugin we are going to use is called libFollowerPlugin.so so enter this in the Filename field. The filename corresponds to the actual filename of the plugin library stored on your local machine. It exists in the form of a dynamically linked shared object library, hence the naming convention and theextension .so (on Linux). Do not worry if you are using Gazebo on other operating systems as the extension will be automatically replaced with the correct one.

   

5. The follower plugin does not require any additional parameters so you can leave the Innerxml field empty. Note: This is a simple plugin for demonstration purposes. Plugins typically have various parameters associated, e.g. a differential drive plugin requires specifying the name of joints controlling theleft and right wheels so it can move the vehicle in the correct direction. In the case of the follower plugin, it makes many assumptions on the type of model it is attached to and tries to find the joints and sensor automatically.

6. Click OK to add the plugin. The plugin should now appear under Model Plugins in the left panel.

   

Save your model

1. Save the model by going to the File menu and selecting Save As. Enter a name for the model and click Save.

   

2. Exit the Model Editor by going to File and selecting Exit Model Editor. Gazebo should now switch back to normal simulation mode. Hit the Play button to run the simulation.

   

3. To test that the plugin is working, insert a box in front of the car and see the car move slowly towards it.

   

If you want to edit the model again later, just right-click on it and select Edit Model in the context menu.