These instructions are meant to help set up an Ubuntu Xenial 16.04.3 LTS development environment for the FRC 2017 FIRST STEAMWORKS competition or the FRC 2018 FIRST POWER UP competition. This guide applies to Java, not C++.
Through these steps, you should be able to run a simulated environment with which you can test your robot code for FRC 2017 or FRC 2018.
The simulated environment can be very helpful in debugging issues, and testing your software without needing access to a real/physical robot.
Simulation is a helpful tool, but it is not a substitute for testing the real deal. Use the simulation to test your code, but make sure to periodically test on the real robot as well!
- Install and configure prerequisites
- Install Eclipse
- Install Eclipse FRC Plugins
- Install Gazebo
- Install FRCSim
- Install 2016 model and world files
- Create a sample application
- Next steps
You should have a reliable Internet connection to run these steps, as you will be downloading a lot of software.
You must run these steps in the specified order.
You must wait for a step to finish before moving to the next step.
You must not skip ahead while another step is running. Many of these steps do things you might not expect, and it is very important you wait and run these steps in the proper order.
For example, the FRC Eclipse plugin creates a folder structure at
$HOME/wpilib after restarting Eclipse. That folder structure is a requisite for following steps.
I highly recommend a fresh Ubuntu install if possible.
You need a fast machine to run the simulator. I originally used a VirtualBox VM with 4096 MB RAM, 2 CPU, 128 MB GPU, and 3D acceleration enabled. The steps below worked fine, but the simulator was so slow that it was unusable.
I deleted the VM to try out an (old) LGA 775 Celeron with 2 GB RAM on real/physical hardware. This machine was slower than the VM, and the simulator would not run at all. Adding a dedicated NVIDIA GPU allowed the simulator to run, though at a very slow speed.
On my 5th gen Core i5 with 16 GB RAM the simulator ran reasonably well, but was still a bit choppy. Using a dedicated GPU may have improved performance, but I did not test that out.
The simulator ran best for me when using a Core i7.
Install and configure prerequisites
wpilib repository to your machine. This repository will be used to install FRC software.
sudo apt-add-repository ppa:wpilib/toolchain
webupd8team repository to your machine. This repository will be used to download Oracle Java installers, which make for a simpler Java install process than manually downloading and installing Java.
sudo add-apt-repository ppa:webupd8team/java
Refresh your machine's repository package list now that we have added the new repositories above.
sudo apt-get update
Install various required libraries and tools. Most notably, we will install the following three packages.
frc-toolchain, which includes compilers and tools required to support the ARM platform on the roboRIO ,
oracle-java8-installer (Oracle's version of Java), and
git for code management .
This code block can be copied and pasted into your terminal as is.
sudo apt-get install \ git \ libc6-i386 \ curl \ jstest-gtk gradle oracle-java8-installer \ frc-toolchain meshlab cmake libprotobuf-dev \ libprotoc-dev protobuf-compiler
$HOME/Downloads directory should already exist on your Ubuntu machine, but this will create it if it is not present.
mkdir -p $HOME/Downloads
Edit the file
sudo nano /etc/environment
Append a new line with this content. This defines a system-wide variable named
JAVA_HOME that references the install location of Java on your machine.
Immediately load the
/etc/environment configuration file you just created.
List the contents of your Java installation directory using your new
You should see contents like this, which means that your system is properly referencing the Java installation directory we set above.
bin LICENSE COPYRIGHT man db README.html include release javafx-src.zip src.zip jre THIRDPARTYLICENSEREADME-JAVAFX.txt lib THIRDPARTYLICENSEREADME.txt
Eclipse, and the WPILib plugins for Eclipse, allow us to write software for the robot.
Download eclipse Neon 64 bit.
It is possible to install Eclipse using
apt, but it's usually bundled with the openjdk (open source verson of Java) and, unfortunately, I feel it is less stable than Oracle's version of Java. That is why I suggest downloading Eclipse directly from eclipse.org
Right click on the
eclipse-inst-linux64.tar.gz file after it is finished downloading.
Extract Here to extract the contents of that
eclipse-installer directory and double-click the
eclipse-inst installer to being the installation process.
When prompted, select
Eclipse IDE for Java Developers as the flavor of Eclipse that we want.
Note that Eclipse will be installed to
$HOME/eclipse/java-neon by default. The install location should not matter. You can change it, but I recommend leaving it alone unless you know what you are doing.
Follow the prompts to install Eclipse, and then
Launch Eclipse after the installation is finished.
When prompted to choose a
workspace, use the default value and click
Ok unless you know what you are doing. The workspace is the directory where Eclipse will save your programming projects, and defaults to
Check on a couple of configuration options in Eclipse.
- Window -> Preferences -> Java -> Installed JREs.
- Make sure the Oracle JDK8 is listed.
- Window -> Preferences -> General -> Workspace
Save automatically before build.
Note that, if you used all the default settings, Eclipse should now be installed at
Install Eclipse FRC Plugins
Install the Eclipse FRC plugins. This will add extra functionality to Eclipse that is specific to FRC. The Eclipse plugins for FRC assist you in building, deploying, and testing Robot projects.
Be sure that you do not interrupt this process. It may seem to hang or freeze at times (especially on a slow machine), but let it take the time it needs.
Help -> Install new software -> Add…
Use the following settings.
Name: FRC Plugins Location: http://first.wpi.edu/FRC/roborio/release/eclipse/
WPILib Robot Development repo.
Check the box for the
Robot Java Development plugin.
Next, and follow the wizard and confirm and agree to the prompts presented to you.
You may see a message that says
Warning: You are installing software that contains unsigned content. Although this is not ideal, it is safe to click
Eclipse will prompt you to restart itself. Let it.
Eclipse will install critical files after it restarts.
Gazebo is the simulator software that models a 3D world through which we can test our robot.
The install process is wonderfully simple, but this is actually a very complex and resource intensive piece of software.
Gazebo will simulate the real world so that you can test your robot code in a (modeled) 3D space.
curl -ssL http://get.gazebosim.org | sh
With FRCSim, you should be able to finish 90% Of your programming without ever touching a RoboRIO.
We want you to be able to test your code BEFORE you put in on your robot, and before the robot is even built.
FRCSim allows robot code written in C++ or Java that normally runs on your RoboRIO to be run on your laptop or desktop. It connects to custom robot models in the Gazebo robot simulator. 
curl to download FRCSim files to your machine.
curl -o \ $HOME/Downloads/simulation-2017.2.1.zip \ http://first.wpi.edu/FRC/roborio/maven/release/edu/wpi/first/wpilib/simulation/simulation/2017.2.1/simulation-2017.2.1.zip
Create a directory for various simulation files. Note that Eclipse automatically created
$HOME/wpilib when we installed the FRC Plugin. We are now manually creating
Unzip our simulation files to the directory we just created.
unzip \ $HOME/Downloads/simulation-2017.2.1.zip \ -d $HOME/wpilib/simulation
Create a system-wide symlink to the
frcsim (FRC simulator) program.
sudo ln -s $HOME/wpilib/simulation/frcsim /usr/bin/frcsim
Create a system-wide symlink to the
sim_ds (simulated driver station) program.
sudo ln -s $HOME/wpilib/simulation/sim_ds /usr/bin/sim_ds
We must manually compile the wpilib simulation plugins for FRCsim in order for the simulator to work properly on Linux.
Navigate to the
$HOME/Downloads directory in your terminal.
git to download some
wpilib code that we must compile on our machine.
git clone https://github.com/wpilibsuite/allwpilib
Navigate to the
allwpilib code that we just downloaded.
Check out a specific version of the code we just downloaded.
I have to admit that I do not know how the versions of
allwpilib match up to versions of Ubuntu, our various toolchains, and FRCSim, but I found that the
v2017.3.1 tag of
allwpilib worked fine for me on Ubuntu 16.04.3. This seems to be the most recent stable release from what I could gather.
git checkout v2017.3.1
gradelw script. That script will use gradle, a software build tool, to compile the software we just downloaded. This script takes a while to run. Though, occasionally, I see this script freeze and hang. If that happens, it is safe to kill this and re-run it.
./gradlew build -PmakeSim
Copy the plugins we just compiled into our simulation plugins directory.
cp ./build/install/simulation/plugins/* \ $HOME/wpilib/simulation/plugins/
Install 2016 model and world files
2017 simulation files have not been released, but the 2016 simulation worlds and models give us something to work off.
Download some 3D models for our simulation.
curl -o \ $HOME/Downloads/models.zip \ https://usfirst.collab.net/sf/frs/do/downloadFile/projects.wpilib/frs.simulation.frcsim_gazebo_models/frs1160?dl=1
Unzip the model files into our
unzip $HOME/Downloads/models.zip -d $HOME/Downloads/
Copy the downloaded gazebo simulation models into our simulation directory.
cp -r $HOME/Downloads/frcsim-gazebo-models-4/models \ $HOME/wpilib/simulation/
Copy the downloaded gazebo simulation worlds into our simulation directory.
cp -r $HOME/Downloads/frcsim-gazebo-models-4/worlds \ $HOME/wpilib/simulation/
Download the official 2016 game arena world file to our simulation directory.
curl -o $HOME/wpilib/simulation/worlds/frc2016.world \ "http://first.wpi.edu/FRC/roborio/release/simulation/downloads/frc2016.world"
Create a sample application
If you already have Java code for your robot in Eclipse, you can skip this step. This is to get you set up with some sample code to get started.
Eclipse -> New -> Other -> Example Robot Java Project -> GearsBot -> Finish.
frcsim (Gazebo) using the terminal.
That will load an empty three dimensional world in which we can test our robot.
Alternatively, you can specify a world file to be loaded like so. Here we are using the world from 2016. As I mentioned above, the 2017 world has not been released.
Wait until Gazebo has finished loading. Once Gazebo loads, insert the sample
GearsBot robot provided by FRC.
Gazebo -> Insert -> Models -> GearsBot
Click somewhere in the world to place your model.
2. Simulated driver station
Run the drive station simulator.
Select your input controller from the list provided. Select
3. Run the code
Right click the name of your project in Eclipes and
Run As a
WPILib Java Simulation.
You should now be able to use your controller to drive your robot.
Your next steps should be that you alter the code (or create a whole new project as needed) tailored to the needs of your robot.
You should also research (see docs below) how you can export a CAD model of your robot, or create one from scratch, for use in Gazebo. That is critical, because then you can test your robot in the Gazebo simulator world rather than the sample robot. The sample robot may have motors and other physical components that do not align with the robot your team is building. Only by testing a model of your robot can you ensure your code will work as expected.
Robot is not moving
Make sure you completed all the above steps in the specified order.
- Terminate your Eclipse simulation (the red square "Stop" button) if it is running.
- Close Gazebo.
- Try re-running the Run steps above in the specified order.
Make sure the "Pause" button is not selected in Gazebo (it is located at the bottom of the Gazebo window).
This command helps test raw controller input in linux.
sim_ds will not stop
sim_ds does not fully exit after closing its window, you can type
ctrl + c in its terminal window to kill it.
sim_ds will not connect
$ sim_ds WARNING|Gazebo Transport: Cannot connect, retrying in five seconds. WARNING|Gazebo Transport: Cannot connect, retrying in five seconds. WARNING|Gazebo Transport: Cannot connect, retrying in five seconds. WARNING|Gazebo Transport: Cannot connect, retrying in five seconds.
This most likely means Gazebo is not running. Make sure to start Gazebo before starting
If it is still not working after you run Gazebo, close everything and try again. Remember, you must run the appropriate steps in the specified order.
Error when running a script or installing software
E: Could not get lock /var/lib/dpkg/lock - open (11: Resource temporarily unavailable) E: Unable to lock the administration directory (/var/lib/dpkg/), is another process using it?
This means that your machine is currently in the process of installing software. Do not reboot! Do not try to stop it!
There are two likely causes for that error.
- Your machine is auto-updating in the background.
- You are already in the middle of installing software.
In both cases, you should be patient and wait.
You can check the status of currently running software installs with this command.
ps ax | grep -i dpkg
If using an NVIDIA GPU, you can install proprietary drivers, which should perform better than the stock drivers.
System Menu -> Settings -> Additional Drivers.
Let the process scan and list the proprietary drivers you require (choose the newest tested proprietary drivers for your card).
Apply Changes. Let the install finish. Then reboot.
The official docs for FRCSim can be a tad confusing. The manual process is a bit out of date, and covers the 2016 models/worlds, but does not seem to have been updated for 2017. The official docs recommend a version of Ubuntu that is fairly old at this point.
That said, the official docs were my source material for this guide. I picked out the bits and pieces of the FRCSim install process that I needed, and tracked down the 2017 files where I could (and where they weren't referenced in the official docs).
- FRC 2017 Overview
- Programmer's Overview
- WPILib JAVA API
- Bootstrapping an FRC Java dev environment
- Installing FRC Toolchains
- Deploying code
- Creating a robot project in Eclipse
- Using the robot builder to generate stub code for motors, servos, etc.
- Exporing robot models from CAD using solidworks
- Importing robot models into gazebo
- Simulating gearsbot demo
- Overview of robot builder
- Creating robot models without SolidWords & CAD
- Troubleshooting gazebo 7, wpilib, and Ubuntu 16
- Java RobotDrive examples: Tank Drive, Arcade Drive, Mecanum drive