Debugging Simulation

This article will cover some common problems, debugging techniques, and solutions. Check out the video series for more information!

FRCSim video series

Debugging your robot code

Please, use a real time debugger like GDB or the Eclipse Java debugger!

I cannot emphasize how awesome this is. Since your robot code is running on your computer and not a RoboRIO, you have full access to it at run time and can use the Eclipse Debugger, or GDB, or whatever else you'd like. Furthermore, we left all the debug symbols in WPILib so you can go as deep as you want into our code and find out what's going on!

Print statements are ok for some things, but they are slow to write and test, and require re-building your program just to test things that a debugger can give you for free.


There's a video on how to use the eclipse debugger to solve a real problem in the video series. Check it out!

The Eclipse Java Debugger

The eclipse java debugger is one of the most powerful java debuggers available. Learning to use it effectively will mean you spend less time debugging, and more time writing awesome robot code!

There are four main features of the debugger. These include stepping, breakpoints, watchpoints, and tracing.

There is a very detailed video tutorial on using this debugger available on youtube here


To run in debug mode, press the green bug icon, or right click and choose "Debug As" > "WPILib Java Simulation"

The Eclipse Java Debugger

C++ Code Fails to Compile

If you see an error message about including sdf or gazebo like below, there is an easy fix!


Simply right click on your project, and go the C++ settings.

Right click on your project, and go to C++ Include Settings

Right click on your project, and go to C++ Include Settings

Change the include path

Using the following to command to find what versions of gazebo and sdf you have

find /usr/include/ -name gazebo*
find /usr/include/ -name sdf*

The output should be something like:


From here you can copy those paths to replace the existing ones in eclipse.

Change the include path

Help! My robot isn't moving!

The most common symptom you'll see is, unfortunately, nothing happening. There are a number of reasons this might be happening, and we'll go through a few of them here.


1. Your robot code isn't built/running properly.

If you're using C++, make sure you select "linux_simulate" from the hammer drop-down when you're compiling. When you run, make sure you hit "simulation".


2. Gazebo is paused

If you hit the little "pause" button in gazebo, everything will freeze. Which means your robot code may also freeze in time as well.


3. Motor messages are not being published

This one is a little trickier to solve. For instance, if you expect a motor on port 1 to be moving, then messages should be published to a gazebo transport topic like


You can check if something is being published to this by running the following command in the terminal

gz topic --hz /gazebo/frc/simulator/pwm/1

This will print out the frequency with which messages are being publish. For instance, any time gazebo is running we can print out the frequency of a default gazebo message

gz topic --hz /gazebo/default/world_stats

If this is happening, it means your set function on your motors is not being called, or is being called with a value of 0. Use a debugger and figure out why!


4. The clock plugin is missing or not working

Every robot model in simulation needs clock plugin. Check the GearsBot model for an example:

<plugin name="clock" filename="">

This plugin is responsible for publishing time messages, and nothing will work without it functioning. You can verify it is working by running the following

gz topic --hz /gazebo/frc/time

If this doesn't print anything, you probably forgot to put the clock plug-in in your robot model. To diagnose, instead of running frcsim from the search bar, run it from the command line. This will print out lots of useful information as gazebo loads and as you try adding models.

How can I make robot models?

Field and game piece models will be available January 12th


Making robot models by hand is very tricky, so I suggest using the Solidworks plugin. However, if you absolutely can't use the solidworks plugin, it is still possible to do by hand. You will need to install meshlab before continuing, and you should have already made any CAD models for the parts of your robot, and exported them as STLs.

1. Install meshlab

sudo apt-get install meshlab

Using the model editor

Gazebo's built-in Model is a nice way to make simple robots to test your code, or to edit custom robots that have small errors.

Follow the guide below to use the model editor:

Using the Gazebo Documentation

The Gazebo community has a lot of experience making models, so you can always look at tutorials ( If you're looking for some information, or ask questions on the gazebo forum ( if you have a question.

Gazebo is an open source project, and thrives on people asking questions and contributing back to gazebo! You can even add your own custom robots to the online gazebo model repository!

Working by Example

1. Copy an example

The easiest way to make a new robot model is by basing it off a similar one. For FRC Robots, that usually means GearsBot is a good example. Copy the files in ~/wpilib/simulation/models/GearsBot to another folder, like ~/wpilib/simulation/models/MyRobot. This will give us a good starting point.

2. Understand the links and joints

Look through the copied GearsBot file. You'll see there are several links and joints. At this time we want to start replacing those links and joints with our own. It's common to have four wheels and a chassis in your robot, so you can start by simply replacing the models in those links with the models for your robot.

You might see this:

        <mesh filename="package://GearsBot/meshes/chassis.STL" />

And you can replace it with this:

        <mesh filename="package://MyRobots/meshes/chassis.STL" />


3. Update poses

Another difference between your robot and GearsBot are the pose and inertia of the links. For pose, start by setting all the numbers to zero, and adjust them until the links line up correctly. You can "insert" the model into gazebo, see in which direction they are off, make the adjustment, and re-insert.


4. Update intertia

The inertia for different links needs to be change for a new model. This is where meshlab comes in handy. Follow the instructions here ( to use meshlab to find out the values for the inertia tag.

The easiest way to calculate inertia for most simple links is to use the following table of inertial tensors:

Video Tutorials

Don't be afraid to comment on the videos if you have questions or comments!

FRCSim video series

0 Report Errors

Use this form to report any errors with the documentation. For help with WPILib, please use the FIRST Forums at For reporting WPILib bugs, please submit an issue on GitHub at