These instructions are meant to help set up an Ubuntu Xenial 16.04.1 LTS development environment for the FRC 2017 FIRST STEAMWORKS 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.

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!

Warnings!

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.

For my setup, I used Xubuntu 16.04.1. I imagine the steps will work on any modern Ubuntu variant, but Xubuntu is the only environment on which I have tested.

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 dumped the VM to try out an 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

sudo apt-add-repository ppa:wpilib/toolchain
sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install \
  git libc6-i386 curl \
  jstest-gtk gradle oracle-java8-installer \
  frc-toolchain meshlab cmake libprotobuf-dev \
  libprotoc-dev protobuf-compiler
mkdir -p ~/Downloads

Append the following to /etc/environment.

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

Verify $JAVA_HOME is properly configured.

source /etc/environment
echo $JAVA_HOME

Install Eclipse and WPILib plugins

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 from apt, but it's usually bundled with the openjdk and ends up being a nightmare. That is why I suggest downloading directly from eclipse.org

Extract the eclipse-installer directory to your Downloads directory. Run the eclipse-inst installer.

When prompted, Eclipse IDE for Java Developers is the flavor we want.

Note that Eclipse will be installed to $HOME/eclipse/java-neon by default. The install location should not matter.

Run Eclipse and check on a couple of configuration options.

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

Install the Eclipse FRC plugins.

  1. Help -> Install new software -> Add
    1. Name: FRC Plugins
    2. Location: http://first.wpi.edu/FRC/roborio/release/eclipse/
    3. Click OK
    4. Expand the WPILib Robot Development repo and choose to install the Robot Java Development plugin.
    5. Follow/confirm the wizard/prompts

Eclipse will prompt you to restart itself. Do so, Eclipse will install critical files after it restarts. Be sure that you do not interrupt this process.

Install Gazebo

Gazebo is the simulator software that models a 3D world through which we can test our robot.

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.

curl -o ~/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
mkdir ~/wpilib/simulation
unzip ~/Downloads/simulation-2017.2.1.zip -d ~/wpilib/simulation
sudo ln -s ~/wpilib/simulation/frcsim /usr/bin/frcsim
sudo ln -s ~/wpilib/simulation/sim_ds /usr/bin/sim_ds

Manually build wpilib simulation plugins.

cd $HOME
git clone https://github.com/wpilibsuite/allwpilib
cd allwpilib
./gradlew build -PmakeSim
cp ./build/install/simulation/plugins/* ~/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.

curl -o ~/Downloads/models.zip https://usfirst.collab.net/sf/frs/do/downloadFile/projects.wpilib/frs.simulation.frcsim_gazebo_models/frs1160?dl=1
unzip ~/Downloads/models.zip -d ~/Downloads/
cp -r ~/Downloads/frcsim-gazebo-models-4/models ~/wpilib/simulation/
cp -r ~/Downloads/frcsim-gazebo-models-4/worlds ~/wpilib/simulation/
curl -o ~/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 ~/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

Run your Java app in Eclipse 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).