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!

Index

Warnings!

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.

Machine

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

Add the wpilib repository to your machine. This repository will be used to install FRC software.

sudo apt-add-repository ppa:wpilib/toolchain

Add the 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 [1], oracle-java8-installer (Oracle's version of Java), and git for code management [2].

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

The $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 /etc/environment.

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.

JAVA_HOME="/usr/lib/jvm/java-8-oracle"

Immediately load the /etc/environment configuration file you just created.

source /etc/environment

List the contents of your Java installation directory using your new $JAVA_HOME variable.

ls $JAVA_HOME

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

Install Eclipse

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.

Click Extract Here to extract the contents of that .tar.gz file.

Open the 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 $HOME/workspace.

Check on a couple of configuration options in Eclipse.

  1. Window -> Preferences -> Java -> Installed JREs.
    • Make sure the Oracle JDK8 is listed.
  2. Window -> Preferences -> General -> Workspace
    • Check Save automatically before build.

Note that, if you used all the default settings, Eclipse should now be installed at $HOME/eclipse/java-neon/eclipse.

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/

Click Ok

Expand the WPILib Robot Development repo.

Check the box for the Robot Java Development plugin.

Click 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 Ok.

Eclipse will prompt you to restart itself. Let it.

Eclipse will install critical files after it restarts.

Install Gazebo

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

Install FRCSim

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. [3]

Use 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 $HOME/wpilib/simulation.

mkdir $HOME/wpilib/simulation

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.

cd $HOME/Downloads

Use 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.

cd $HOME/Downloads/allwpilib

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

Run the 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 $HOME/Downloads directory.

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.

Run

1. FRCSim/Gazebo

Fire up frcsim (Gazebo) using the terminal.

frcsim

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.

frcsim $HOME/wpilib/simulation/worlds/frc2016.world

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.

sim_ds

Select your input controller from the list provided. Select Teleop. Click Enable.

3. Run the code

Right click the name of your project in Eclipes and Run As a WPILib Java Simulation.

4. Enjoy

Gazebo

You should now be able to use your controller to drive your robot.

Next steps

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.

Troubleshooting

Robot is not moving

Make sure you completed all the above steps in the specified order.

  1. Terminate your Eclipse simulation (the red square "Stop" button) if it is running.
  2. Close Gazebo.
  3. Close sim_ds.
  4. 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).

Joystick/Controller

This command helps test raw controller input in linux.

jstest-gtk

sim_ds will not stop

If 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 sim_ds.

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.

  1. Your machine is auto-updating in the background.
  2. 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

NVIDIA GPU

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).

nvidia

Click Apply Changes. Let the install finish. Then reboot.

Docs

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).