Tutorial

Debugging: Java Remote debugging

So far you’ve probably been debugging Java code by adding print statements;  you add code that gives you a peek into the robot’s internal state.  Monitoring the robot with ShuffleBoard is similar;  you add output statements to your code.

Imagine a better system that doesn’t require added code, where you could stop time, crack the roboRIO open and see what was going on inside.   You could examine the variables and then watch the lines of code execute, one at at time.  This technique, called Remote Debugging, is available to you from most modern Java development environments.

Remote debugging lets us answer questions like “Did my code even get executed?” or  “Did the initialization code really get executed before the periodic code?” or “What were the variable values?”.   Since the the debugger can let you see the actual execution, you can also verify that conditionals and loops really execute the way you expect.  You can even use the debugger to alter variable values, so novel scenarios can be tested.

We call this technique “remote” debugging because it involves a network connection between your programming laptop and the roboRIO.  Your robot program is executing on the RIO, but it will be controlled and monitored by the development environment on your laptop.  You’ll be watching the action as if it’s happening on your screen, but the action is actually occurring remotely on your robot.

Starting the debugger is almost the same action as deploying code with GradleRIO.  Execute the “debug” command instead of “deploy”:

debug_remote_menu

This command will build and deploy code in debug mode which will configure the RIO to communicate back to your debugger.  Visual Studio Code will also switch into debug mode (as indicated by the Debug icon in the activity bar on the left edge of the window).

Breakpoints

The first important concept in remote debugging is the setting of “breakpoints” in your program.  A breakpoint is a location in your program that you want to watch.   When your robot’s thread of execution reaches that point, the program will freeze and your debugger will come alive.

Inline breakpoints

To create a breakpoint, click to the left of the line numbers in your program.  Below, we’ve created a breakpoint on line 51 of the teleopPeriodic method, indicated by a little red dot:

debug_remote_normal_breakpoint.png

Start the Driver Station software and enable teleop mode.  The normal execution of a robot program is that the RIO will execute teleopInit once and then start executing teleopPeriodic.   When the RIO reaches the breakpoint on line 51, it will pause execution as below:

debug_remote_debug_mode

There is a lot of information going on in this window:

  • In the upper left sidebar you see all the local variables of the teleopPeriodic method, There’s also the “this” variable that you can expand to see all the Robot’s instance variables.
  • Below the Variables section is the Watch section, which lets you add arbitrary expressions to be evaluated.
  • In the lower left of the sidebar is the Call Stack, which tells you what method called your current method, and what method called that method, etc.  The call stack actually lists all the Java threads currently running on the RIO, but you may have to stretch out the window to see them all.
  • Below the Call Stack, there is a list of Breakpoints.  In the above illustration, you would need to collapse the call stack to see the breakpoints.  You can edit or enable/disable breakpoints here.
  • Above the editor window is the debug toolbar:

debug_remote_toolbar.png

The “Continue” tool will cause program execution to resume, until it reaches the next breakpoint.  The “Step Over” tool executes the next line of code.  “Step in” will drill into a method. “Step out”  pops out of the current method to the method in the call stack that called it.  At every step, you can watch the variables change.  You’ll be able to see the code go through “if” statements and loops.

Also, take a look at the “Debug” menu at the top of the window.  Particularly useful in the Debug menu are options to temporarily disable all breakpoints and then later enable all breakpoints.  Disabling breakpoints lets you perform normal robot operations for a while.  Then you can enable breakpoints to examine specific scenarios.

Conditional breakpoints

Note that in our above example, we encounter the breakpoint every single time we execute teleopPeriodic.  We could have put the breakpoint inside the “if” statement, in which case the breakpoint would stop only when the “slowMode” variable was true.

It is often useful to set “conditional” breakpoints that only fire when certain conditions arise.  The conditional breakpoint is indicated by a little red dot with an equals sign in it.  Create one by right-clicking to the left of the line number and specify “Add Conditional Breakpoint”.

For instance, below we have a  breakpoint on line 55 that only fires when both leftSpeed and rightSpeed are greater than 0.5.

debug_remote_conditional_breakpoint

Exception breakpoints

You can also specify that the debugger stops operation when an exception is thrown.  Look in the Breakpoints section at the bottom of the Debug sidebar and enable “Caught Exceptions”.  Exception breakpoints can be especially useful when you’re trying to diagnose unexpected exceptions.

Note that VS Code will break on all exceptions.  Other IDEs allow you to break on specific exception types.

Logpoints

A logpoint is like a breakpoint, but it merely prints a message out to the console instead of stopping.  This is like debugging with print statements, except that you can enter them in the debugger without having to recompile.  Create one by right-clicking to the left of the line number and specify “Add logpoint”.  Logpoints are indicated by a little red diamond.

You can cause logpoints to print out variable values by putting the variables in curly braces.  Below is a logpoint that will print out three variables:

debug_remote_logpoint.png

Examining program state

The Variables section of the debug sidebar will answer many of your questions about what’s going on inside your program.  Spend time exploring the local and instance variables to see what’s in the objects.  Familiarize yourself with the state of health programs so you can better spot error conditions.

The Variables section also allows you to change the values of variables.  Just double-click on any number, boolean, or String value and you can give it a new value.  This feature can let you test specific scenarios, such as “What will happen if my gyro returns a negative value?”.

If you are monitoring specific variables or variable expressions, park them in the Watch section.  They will be reevaluated whenever the program stops.  You can add expressions directly in the Watch section, or you can right-click on them in the code editor and select “Debug: Add to Watch”.

Debugging robot programs with Eclipse

The program on your robot is running within a Java Virtual Machine (JVM).  Remote debugging is possible because JVMs contain features to support it.  The mechanism for debugging is called the Java Platform Debugger Architecture (JPDA).    Visual Studio Code has an extension that connects to JPDA, but so does nearly every other Java development environment.  The debugging functions will be similar on other IDEs, but the user interface may be different.

Eclipse has an excellent built-in Java debugger.  The user interface is different from VS Code, but (in my opinion) it makes better use of you screen space.

debug_remote_eclipse_3.png

Eclipse’s Gradle plugin allows you to execute the GradleRIO deploy task.  Enabling remote debugging is a slight variation on the deploy task.

  1. Go to the Gradle Tasks view and find embeddedtools > deploy.  Right-click on the deploy task and select “Open Gradle Run Configuration”.
    debug_remote_eclipse_1a.png
  2. The Run Configuration dialog will pop up for the “deploy” task.
    debug_remote_eclipse_1b
  3. Click on the Arguments tab and add the debugMode project property.  Then hit the OK button to save.
    debug_remote_eclipse_1c
  4. Next, you’ll need to set up a Remote debugging configuration.  From the Run menu, select “Debug Configurations…”
    In the Debug Configuration dialog, add a new entry under “Remote Java Application”.
    debug_remote_eclipse_2
    Specify a host address that will connect to your roboRIO (either 10.te.am.2 or 172.22.11.2) and set the port number to 8349.

To do remote debugging in Eclipse, you will first deploy the code in debugMode using your new run configuration.  Then, you will attach to the remote process with your new debug configuration.

Debugging robot programs with IntelliJ

IntelliJ also an excellent Java debugger.  It is built-in, no extension needed.  The function and user interface is similar to Eclipse.

debug_remote_intellij_3

To set up remote debugging in Intellij:

  1. From the Run menu, select “Edit Configurations…”
  2. Create a Gradle configuration with a task of “deploy” and arguments turning on the debugMode
    debug_remote_intellij_1
  3. In the same Run/Debug Configurations dialog, create a new Remote configuration for port 8349 and for a host address that connects to your roboRIO.
    debug_remote_intellij_2

To do remote debugging in Intellij, you first deploy the code using your new deploy configuration.  Then, attach to the RIO using the new Remote configuration.

 

When not to use the Debugger

There are times when the debugger isn’t the right tool.   Robots operate in real-time, so freezing time disconnects them somewhat from real-world processing.    For instance, if you are debugging while motors are moving, stopping the action will the change the physics of your situation.  If you stop a command that has a timeout, the timeout may expire while you’re staring at the code, which change the robot’s behavior.  If you’re investigating at problem related to real-time interactions, you may choose to set logpoints or to use printing, logging, or ShuffleBoard instead.

Overall though, I hope this exercise has sold you on the use of the debugger.  It will be a tremendously useful tool for problem solving.  All serious programmers should learn to use the remote debugger.

Further Reading:

 

Tutorial

IntelliJ with GitHub

Programming as a team introduces special challenges. You’ll need extra communication to keep everyone productive, and additional tools to keep from losing work.

Professional environments use Revision Control Systems to store the code, communicate the changes, and keep people from overwriting each other’s work.  FRC programming teams should also use Revision Control.

Probably the most popular revision control system right now is git, a distributed version control system created by Linus Torvalds, the same guy who created Linux. You can use git from the command line, or from within development environments such as Eclipse, IntelliJ, and Visual Studio Code.  GitHub is a web-based hosting service for git, and the GitHub corporation is a FIRST sponsor.  All programming mentors and students can get free GitHub accounts, and FIRST teams can get upgraded Team Accounts.

To say that git is “distributed” means that every programmer will have a copy of the code, along with the history of the changes.  There is also one remote repository of the code out on the internet. Programmers will occasionally pull changes from the remote repository to their local copy and occasionally push their own changes up to the remote repository.  In this way, everyone eventually has the same code and the same history.

Combinations of the code files are called “commits“, and the word “commit” here is both a noun and a verb.  Committing your changes creates a commit that you can retrieve later.

OK, I know that that was a lot of information.  Honestly, git is a really deep subject, and companies that use it develop really complicated methodologies for its use.  I do not recommend that FRC teams try to use everything in the git toolkit, or try to emulate commercial practices.  Especially at first.  Instead, let’s lay out the minimal functions.

Installing and configuring git

IntelliJ provides an excellent user interface to git, much better than the UI in Eclipse or VS Code.  However, the git package is separate from IntelliJ.  You must install it on your laptop.  Instructions are at:  https://git-scm.com/ .

You should configure git to know who you are.  This information will be added to the repository very time you commit.  Open up a terminal window and execute the following:

git config --global user.email "myEmailAddress@whereever.com"
git config --global user.name "My real name"

Cloning an existing repository

Suppose that there is a repository on GitHub that you’d like to download to your laptop.  Making a local copy is called making a clone.

Consider the code repository at:  https://github.com/firebears-frc/testrobot0.  Go ahead and visit that page in a browser.  Press the green button labeled “Clone or Download” and then press the little clipboard button.  This will copy the repository’s formal URL into your clipboard.

vsc_git_clone

Now go to IntelliJ:

  1. From the main menu select File > New > Project from version control > git
  2. Paste your git URL into the “Clone Repository” dialog.  Click “OK” and open the new project in the current window.
  3. A dialog may appear asking if you want to import a Gradle project.  You do.
    If the dialog gets lost, open your project in the Project tool window.  Right-click on the build.gradle file and select “Import Gradle Project”.

At this point you now have a clone of the repository on your machine.  You won’t be able to push changes up to the remote repository unless the owner has granted you permission, but you can read, edit, and deploy this code to the robot.

Creating a new repository

Suppose you have a robot project on your local machine that has never been under git control, but you’d like to upload it into GitHub.   Open your project in IntelliJ and then:

  1. From the menu select VSC > Import into Version Control > Share Project on GitHub.
  2. Log on with your GitHub account:
    intellij_github_login.png
  3. Specify the repository name and description:
    intellij_github_share
  4. Make the initial commit of all your files:
    intellij_github_commit_1
  5. Now go to your browser and visit the page on https://github.com for your new repository.  You should now see all the files listed on the web page.

Note that this process has initialized your local project to be tracked by git.    You’ll notice that there is now a “Version Control” tab at the bottom of the window that will open the Version Control tool window.  The “Local Changes” tab will show files that have been added or modified since your last commit.

intellij_github_vc.png

Also notice the branch indicator in the lower right corner of the screen.  This will be used when you start managing multiple branches in your repository.

Committing changes to the code

From now on, when you add files, delete files, or modify files, git and IntelliJ will keep track of how your code differs from the most recent commit.  The Local Changes tab keeps track of what has changed.  When you are ready to make a commitment, select the files, right-click, and select “Commit”.

intellij_github_commit_2

Type in a commit message.  Try to write informative messages, since you and others will be reading this later.  Good messages say things like “Updated autonomous commands for new encoder” or “Code changes after first regional”.   Bad messages contain jokes or gibberish or say things like “changed stuff”.

intellij_github_commit_3

After entering a useful message, hit the “Commit” button.  This will commit your changes locally, but will not yet push those changes upstream to Github.

Pulling changes back from the repository

Suppose someone else has made changes to the code and pushed them up to the remote repository.  You’d like to fetch those changes and merge them into our code.  This is called doing a pull from the remote.

You can pull at any time, but it is usually best to commit your code locally before pulling.  That is to say, commit the code but don’t push it up yet.  Follow the directions in the previous section to do the commit.

To pull down changes, select from the main menu:  VCS > Git > Pull.   The best case scenario (which is usually what happens) is that upstream changes will be seamlessly added to your code and everything will work perfectly.

One thing that might go wrong is that the changes pulled in will invalidate or undo something you are doing.  You should always look over the incoming changes.

The worst case scenario is that someone else will have changed files that you are working on, and you will need to “merge” changes.  The Conflicts dialog will show which files are in conflict:

intellij_github_merge_1

For each conflicting file, you will have three options

  • Accept Yours : ignore all changes in the remote repository and stick with your changes.
  • Accept Theirs : overwrite this file with the file from the remote repository.
  • Merge: Manually decide how the conflict will be resolved.  This involves picking out individual changes will be copied from your branch or from the remote branch.  If neither change looks right, you can edit text in the middle panel any way you like:intellij_github_merge_2.png

After you’ve modified a conflicted file and saved the changes, go back to the Local Changes view.   After merging all the conflicts, perform another “Commit”.

Pushing your changes up to the repository

If you are ready to release your changes to the rest of the group, you can push your commits up to the remote repository.  Use the menu options VCS > Git > Push.

Synching with the remote repository

There’s an important discipline that everyone must develop with respect to the remote repository, which is that you should always pull in remote changes before pushing up your own.  If there are incoming changes, then you must recheck the merged code to verify that it is OK.

With multiple programmers, you should perform the following steps manually:

  1. Commit your changes locally.
  2. Pull remote changes, and deal with any merge conflicts.
  3. Verify that the merged code compiles correctly and that the code works correctly.  If there are any problems, fix them and then go back to step 1.
  4. Push all commits to the remote repository.

Further Reading:

Tutorial

Creating Java Programs with IntelliJ

Creating GradleRIO FRC robot programs in IntelliJ is quite easy.

Step 0: The prerequisites

At this point you should already have installed Java and set up IntelliJ.

You must be connected to the internet the first time you build the project.  After the first build, you can build in offline mode.

Also, you should obtain and run the WPILib one-step installer (available at the beginning of the 2019 season).  Even if you’ll be developing with InteliJ,  you’re likely to need the tools and project templates included in this package.

Step 1: Create a new Robot Project

There are currently several ways to create a basic WPILib robot project:

  • Create a new robot project with VS Code using the WPILib extension.
  • Create a project with RobotBuilder.  You will need a recent version of RobotBuilder that generates GradleRIO projects.  The 2019 software release will contain all new tools, including RobotBuilder.  Or, you can build the latest version from GitHub.
    RobotBuilder creates a full command-based project, so it may be more complicated than what is described in Step 3 below here.
  • Uncompress a copy of the Quickstart.zip file and make a copy of the “java” directory.  Rename the directory to whatever you like.

Now, whichever method you use, add an empty directory called “vendordeps”.   Your project should now look like this:

intellij_program_files

Inside IntelliJ, open the File menu and select File > Open.  Select your project root directory and hit the “OK” button. The “Import Gradle” dialog will appear. Hit “OK” again and open the project in the current window.   The “Gradle” tool window on the right side of the window should populate with all the GradleRIO tasks.

Third party dependencies

If you intend to use any third-party software, you will need to add some JSON files to the vendordeps directory.  The best way to get these files is to get the official installers.  Examples of third party packages include:

Picking a JDK

By default, your IntelliJ project will use your JAVA_HOME environment variable to determine where Java is stored on your laptop.

However, it is possible to have multiple Java Development Kits (JDKs) installed on your laptop.  If you need pick a specific JDK (which IntelliJ will refer to as an SDK), you should select File > Project Structure > Project  from the main menu.  From the Project Structure dialog you can configure a new SDK or configure a previously defined SDK.

Set your team number

Open the build.gradle file and modify the team number setting, probably around 17:

intellij_program_gradle.png

First Build

Open the Gradle tools window.  You should see your new project listed.  Open your project’s icon and select the “build” folder and then double-click on the “build” task.  This should successfully build your new FRC Java project.

Step 3: Program to control one motor

If you started your program in RobotBuilder, you may already have mostly complete program.  If you started with the Quickstart example, your program is mostly just in one Robot.java file.  We can augment the Quickstart example to control a motor.

Back in the Project tools window, double-click on that Robot.java file.  This is your main Java program for controlling the robot.

All of the code in Robot.java is useful, but for simple programs it is optional.  To keep this tutorial really simple, we’re going to delete everything except robotInit() and teleopPeriodic().   Also we’re going to tweak the “import” statements a bit:

intellij_program_edit

For this example, assume we have a joystick connected to drivers’ station and a motor controller connect to the roboRIO.  We’ll create two variables around line 7 to represent them:

Joystick stick;
SpeedController motor;

Now we’ll instantiate the objects inside the robotInit() method:

public void robotInit() {
    stick = new Joystick(0);
    motor = new WPI_TalonSRX(2);
}

For my example, I’m using a Talon SRX connected to CAN ID 2.  If you’re using any other motor controller, just change the line to reflect your hardware.

Next, change your teleop mode so it reads the joystick, and sets the speed of the motor:

public void teleopPeriodic() {
    double speed=stick.getY();
    motor.set(speed);
}

The getY() function tells us how for forward or backwards the joystick has been pushed.  The speed value will be a number between -1.0 and 1.0.

From the Gradle tools window you can now build or deploy the program.

 

Step 4:  Drive your robot

Start up the FRC Driver Station software.  You should see green bars next to “Communications”, “Robot Code”, and “Joysticks”.  Also, you should see your correct team number.  If the team number is wrong, click the Gear icon on the left side to get to the setup panel.

vsc_program_driver

Click the “Enable” button to initialize teleoperated mode.  You should now be able to drive the motor with the joystick.

Consider for a moment what’s going on with the code.  The robotInit() method was called once, and then teleopPeriodic() is being called 50 times a second.  Each call of teleopPeriodic() reads the joystick and passes that value into the motor.

Further Reading:

Tutorial

Installing IntelliJ

IntelliJ is a sophisticated professional development environment for Java.  It is produced by the Jetbrains company, which also produces Android Studio, CLion for C++ development, and PyCharm for Python.  Although IntelliJ is a commercial product, there is Community Edition that is free to use.

FRC robot programs will be built using GradleRIO, which can execute from inside any development environment, including IntelliJ.

Step 0:  Install prerequisites

You must install Java.  Even if you will be developing in C++, you’ll need Java installed to run IntelliJ and GradleRIO.  You should define your JAVA_HOME environment variable to point to your JDK installation.  Often setting JAVA_HOME is considered optional, but I have seen many strange situations resolved after this variable has been properly set.

You should obtain and run the WPILib one-step installer (available at the beginning of the 2019 season).  Even if you’ll be developing with IntelliJ,  you’re likely to need the tools and project templates included in this package.

It is highly recommended (though not strictly required) that you also install git, instructions for which are at: https://git-scm.com/ .

Step 1: Download and install IntelliJ

IntelliJ is available for Windows, Macintosh, and Linux.  Download the installer from https://www.jetbrains.com/idea/download.  Select download on the “Community” version.

intelij_install_0

Run the installer, if possible as the Administrator.  After installation, you’ll probably have to reboot your machine.

intelij_install_1

The first time you start IntelliJ, it will go through setup dialogs.  You can safely take all the default options.

IntelliJ is a big, sophisticated program, but it’s pretty user friendly.  Text editors will appear in the center of the window.  The tabs on the edges of the windows open up “tool windows” on the sides.

intellij_install_windowTo get you started:

  1. The Project tool window lists all the files in your project.  Double-click on them to pop up an editor.
  2. The Structure tool window summarizes the contents of the file you are editing. Double-click on anything to navigate to that item.
  3. The Gradle tool window lists all the tasks that can be executed when building your project.  Double-click to execute.

Step 2: Build a simple project

Creating  complete robot programs in IntelliJ is a lesson I’ll defer to another tutorial.  For now, you can download an existing project and verify that IntelliJ can build robot programs.

  1. If you start with the startup dialog, Select “Check out from Version Control” .  If you are already in the IntelliJ window, select File > New > Project from Version Control > Git.   Give the URL value of: https://github.com/firebears-frc/testrobot0.git and then hit the Clone button.
  2. Open the “Project” tool window on the left of the screen.  Expand the testrobot0 project to see all the files.  Right-click on the build.gradle file to get a popup menu.  Select the “Import Gradle project” item, which will likely be the last item on the list.
  3. Importing will take another minute.  After this “Gradle” tool window will become available on the right side of the window.
  4. When importing is done, you should also see testrobot0 in your Gradle tool window.  Open this item and then open “build”.  Double-click on the “assemble” task.  This should successfully compile the program.
  5. Under embeddedtools, double-click on the “deploy” task to deploy the program to your robot.  This will fail if you aren’t connected to a roboRIO.  But, no harm will have been done.

Further Reading: