Tutorial

Eclipse with Github

Programming alone is sometimes difficult, but one programmer can only do so much. It’s better to work as a team. Groups of programmers can share the load, but having multiple people working on the same code adds additional 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

You are not required to install git, since there is a version packaged within Eclipse.  However, you may choose to install it anyway.  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 the Eclipse Preferences dialog and select Team > Git > Configuration.  Add user settings for “user.email” and “user.name”:

eclipse_git_config

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 Eclipse:

  1. From the main menu select File > Import…
  2. In the Import dialog, select Git > Projects from Git.
  3. Select Clone URI
  4. The Source Git Repository page should already be populated from your clipboard.
  5. For Branch Selection, select at least the “master” branch
  6. For Location Destination, make sure you’ve selected a plausible location, such as in your Documents directory.
  7. Specify the project type.  In this case, choose to import existing Eclipse projects.  Hit the Finish button

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 the project in Eclipse and then open a browser to https://github.com.

  1. In the browser, log into your GitHub account.  Click on a green button that says either “New” or “New Repository”.
    vsc_git_new_repo.png
  2. Github will ask for a repository name.  Give it the same name as project directory on your laptop.  You can also specify a description. Probably you should make it a public repository.
    However, do not add a README file or a .gitignore file or a license file.  Your GitHub remote repository must be totally empty at this point.
  3. After creating the repository, your browser will go to a page which displays your new repository URL.  Copy this value into your clipboard.
  4. In Eclipse, right-click on the project name and select Team > Share Project…
    1. Check the box for “Use or create repository or create new one.
    2. Click on the Location of your project
    3. Click the “Create Repository” button
    4. Click the “Finish” button.  Your project will now be initialized as a local git repository.
  5. Now you need to commit all your files.  Right-click on the project and select Team > Commit… This will expose the Git Staging view.
    1. Drag all files from “Unstaged Changes” to “Staged Changes”
    2. Type in a Commit Message describing this commit.  Normally you should put in something informative, but in this case just say “Initial commit”.
    3. Click Commit and Push…
    4. The Destination Git Repository dialog will be filled in based on your clipboard.
    5. Click the Next button twice to get to the “Push Confirmation” dialog.  Push the Finish button.
  6. Now go back to your browser and visit the page for your new repository.  You should now see all the files listed on the web page.

Committing changes to the code

From now on, when you add files, delete files, or modify files, git and Eclipse will keep track of how your code differs from the most recent commit.  The Git Staging view keeps track of what has changed.  When you are ready to make a commitment, drag the files you want committed into the “Staged Changes” area.  Usually you’ll commit all changes, but you might choose to just stage a subset.

eclipse_git_commit0

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

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, right-click on the project and select Team > 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.  Check the Problems view in Eclipse to see if new errors have been added.  Recompile and run any relevant tests.

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 Git Staging view will show which files are in conflict.

eclipse_git_merge1

Right click on one of the conflicted files and and select the Merge Tool, which will show the differences between your commit and the incoming commits.  In the picture below, local changes are on the left and incoming are on the right.  Edit the left pane to be the compromise between these changes.

eclipse_git_merge2.png

After you’ve modified a conflicted file and saved the changes, go back to the Git Staging view and drag the into the “Staged Changes” area.   After merging all the conflicts, hit the “Commit” button.

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.

If you are the only programmer working on a repository, you can push changes from the Git Staging view and its “Commit and Push…” button.

eclipse_git_commit

If  there are multiple programmers, you should just “Commit”.   Later, you can push all changes by right-clicking the project and selecting Team > Push to Upstream.

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

Installing Eclipse

Eclipse is a sophisticated professional development environment for Java, C++, and other languages.   Eclipse was the officially supported development environment for FRC for the 2015 through 2018 seasons.  In 2019, WPILib has shifted their focus to developing in Visual Studio Code, but you’ll find that Eclipse is still an excellent platform for FRC development.

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

Step 0:  Install prerequisites

You must install Java.  Even if you will be developing in C++, you’ll need Java installed to run Eclipse 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 Eclipse,  you’re likely to need the tools and project templates included in this package.

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

Step 1: Download and install Eclipse

Eclipse is available for Windows, Macintosh, and Linux. Download the installer from https://www.eclipse.org/downloads .  As of this writing, the latest version of Eclipse is called Photon.  If possible, run the installer as Administrator.  The installer will offer you several versions of the program.  Pick either “Eclipse IDE for Java Developers” or “Eclipse IDE for C/C++ developers”.

eclipse_install_installer

Eclipse is a big program, and you should consider looking at the online documentation. Here are a few concepts to get you started:

  1. There are a lot of things going on in the main Eclipse window.  Editors appear in the middle of the window.  This is where you modify code. The tabbed panels surrounding the editors are called Views. Views give you information about your whole project and allow you perform important actions, such as build and deploy code.  There are more views available than are currently displayed, and you can add them from the Window > Show View menu.
    For now, important views to know about include:

    1. The Package Explorer view on the left side shows all available projects.  From here you can open projects and then drill down to find files which can then be edited.
    2. The Outline view on the right side shows a table of contents of any file you are editing.
    3. The Problems view on the bottom shows things that are wrong with your code.  If there is a compile error in the code, you will see it here.
  2. The Preferences dialog allows you to change some Eclipse configurations.  On Macintoshes this can be opened from the Eclipse menu.  On all other computers it is under the Windows menu.
    Also, right-clicking on any project within the Package Explorer view will let you open the Properties dialog for that project.  The project Properties dialog lets you reconfigure the project.
  3. You can extend the functionality of Eclipse by adding plugins.  Plugins are managed from the Help menu, starting with the menu items for “Install New Software…” and “Eclipse Marketplace…”

eclipse_install_eclipse

Once Eclipse starts up, you should verify that it will be using your preferred Java installation. Open the Preferences dialog and then click on “Java” and then “Installed JREs”.  Make sure that your preferred JDK installation is present and is checked.

eclipse_install_jre.png

Step 2: Install the Gradle plugin

Now we’ll want to install a plugin to Eclipse that makes it easier to build and deploy your robot programs.  Click on the Help menu and select “Eclipse Marketplace…”  In the dialog’s find box, type “Buildship Gradle”.  Click the Install button for the Gradle plugin.  Eclipse will need to restart to complete installation.

eclipse_install_plugin

After the restart, open the Eclipse Preferences dialog and click on the “Gradle” item.  Make sure that “Gradle wrapper” is selected.  Apply and close.

Click on the Window menu and select “Show View…” and “Other…”.  Find the “Gradle” item and select “Gradle Tasks”.   The Gradle Tasks view is where you will build and deploy your robot programs.

Step 3: Build a simple project

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

  1. Go to https://github.com/firebears-frc/testrobot0/releases/ and download testrobot0.zip . Uncompress this ZIP file onto your laptop, probably in your Documents folder.
  2. From the File menu, select Import…
  3. In the Import dialog select General and then Existing Projects.  Select your new testrobot0 directory as the root.  Hit the Finish button.  This will create a new testrobot0 project in your Package Explorer.
  4. You should also see testrobot0 in your Gradle Tasks view.  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:

Tutorial

Creating Java Programs with Eclipse

Creating GradleRIO FRC robot programs in Eclipse is quite easy.

Step 0: The prerequisites

At this point you should already have installed Java and set up Eclipse with the Buildship Gradle plugin.

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 Eclipse,  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 (plus or minus the BSD license file):

eclipse_program_files.png

There’s one tiny change you must make to the build.gradle file before importing into Eclipse.  Open build.gradle in a text editor and set you team number at about line 17:

eclipse_program_gradle

Then, inside Eclipse, open the File menu and select File > Import > Gradle > Existing Gradle Project.  Select your project root directory and hit the “Finish” button.  It may take a while the first time you load a Gradle project, because Eclipse must download the dependencies off the internet.

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:

First Build

Open the Gradle Tasks view.  You should see your new project listed. From the tasks view, 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.

Check the Problems view.  There should be no errors in your project.

 

Step 2: Make the project your own

Your minimal project is too generic, and you should now tweak it for you and your team.

In the Package Explorer, open the src/main/java folder.  Drill into the packages to reveal the Robot.java file.

If you started with the Quickstart.zip, the base package will be “frc.robot”. You can change it to almost anything, but a good choice would be to your team name or number.  Right-click on the package name and select Refactor > Rename…    Specify your new package name and hit OK.  Next, double-click on the build.gradle file, which will pop open an editor.  This file controls the build process.   If there is a ROBOT_CLASS variable, make sure it uses your new package name.  Hit Control-S to save.

Go back to the Gradle Tasks menu and execute build > build.  Everything should build successfully.  If your robot is connected, you can also deploy code by selecting the embeddedtools > deploy task.

 

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 Package Explorer, 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:

eclipse_program_1

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.

At this point, check the Problems view and verify that there are no compiler errors.  From the Gradle Tasks view 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

VS Code with GitHub

So you’re developing code for your robot, but where should you store the master copy of that code?  Keeping everything on a single laptop is a terrible plan;  you at least need backups, maybe multiple backups.  Also, you want to keep the history of the development. You might want to compare the code used in two different competitions. And, if the code worked yesterday but fails today, you want to know what has changed.  In professional software environments, the code is usually stored in a Revision Control System.  FRC teams should also follow this practice.

Software Revision Control systems are databases for storing computer software.  They track the history of all changes to the software and allow groups of programmers to share large programs.  They allow anyone on your team to retrieve the current program, or see the versions of the program from the past. 

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 git

If you don’t already have git software installed on you laptop, the basic instructions are at:  https://git-scm.com/ .  Alternate instructions are at:  https://www.atlassian.com/git/tutorials/install-git .

After installing, 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 Visual Studio Code.

  1. Open the Command Palette by hitting the F1 key (or Control-shift-P on Windows or Command-shift-P on Macintosh).
  2. Type “git clone” and hit the return key.
  3. VS Code will ask for the repository URL.  Paste the URL in and hit return.  You may also need to give your GitHub username and password.
  4. VS Code will ask for the parent directory in which to save the code.  Typically this might be your machine’s Documents directory.
  5. VS Code will ask you if you want to open the repository.  Yes, you do.

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 the project folder into VS Code and then open a browser to https://github.com.

  1. In the browser, log into your GitHub account.  Click on a green button that says either “New” or “New Repository”.
    vsc_git_new_repo.png
  2. Github will ask for a repository name.  Give it the same name as project directory on your laptop.  You can also specify a description. Probably you should make it a public repository.
    However, do not add a README file or a .gitignore file or a license file.  Your GitHub remote repository must be totally empty at this point.
  3. After creating the repository, your browser will go to a page which displays your new repository URL.  Copy this value into your clipboard.
  4. In VS Code, open the Command Palette and type “git”.  Select “Git: Initialize Repository”.  A file dialog will pop up.  Click on the “Initialize Repository” button.  Your project will now be under local git control, although no files have yet been committed.  The “Source Control” icon in the Activity Bar will now have a blue circle with the number of uncommitted files.
  5. Now you need to commit all your files.
    1. Click on the “Source Control” icon in the Activity Bar.
    2. Click on the plus icon next to Changes.  This will cause all files to be “staged” for a subsequent commit action.
    3. Type in a message describing this commit.  Normally you should put in something informative, but in this case just say “Initial commit”.
    4. Click check-mark icon.  All files are now locally committed.vsc_git_commit
  6. Now we need to add a connection from your local repository to the remote repository.  You must now open a terminal window by typing control-back-quote.  (If you can’t find this key, you can pop down the “View” menu and select “Terminal”).  Type the following lines, with your repository URL pasted into the appropriate spot:
    git remote add origin repository-url
    git push -u origin master

Now go back to your browser and visit the page for your new repository.  You should now see all the files listed on the web page.

Comitting changes to the code

In the Activity Bar there is an icon that opens the Source Control sidebar.  This is where we can manage our git status.

vsc_git_sidebar1

From now on, when you add files, delete files, or modify files, git and VS Code will keep track of how your code differs from the most recent commit.  The Source Control sidebar show you which files have changed.

Let’s make some small changes.  Click to the Explorer tab. Create a README.md file and type some text to describe your current file.  Next, make a minor change to Robot.java, such as modifying a comment.  Click back to the Source Control sidebar and you will see a list of the two files you’ve changed.

vsc_git_sidebar2

Double-clicking on any filename will pop up a window outlining your changes.  Hovering your cursor over any filename will reveal action buttons to discard the changes or to stage the file to be comitted.

If you are happy with the changes then you can commit them into git. You do not need to commit all the changed files.  Selecting which ones to commit is called “staging” the changes.  In this case, click the “+” button next to both files to stage them both.

vsc_git_sidebar3

Now type in a message and click the check-mark button. Your changes are now committed to the local repository.

One note about commits: only commit code that you know to be good.  It is bad form to commit code that won’t compile or has some significant problem.  We share code with other programmers by sharing commits.  You don’t want to be the person who breaks other people’s code.

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.

Within the Source Control sidebar of VS Code, click on the three little dots to get the More Actions menu.

vsc_git_pull

Select “Pull” from the menu.  This should merge in all changes from the remote repository.

If the incoming changes are in different files from your own changes, then the new adds/updates/deletes will be applied to your collection of files.

If someone has modified a file that you are working on, but where those changes do not overlap your changes, then git will try to cleverly merge the incoming changes into your file.  This might be perfectly fine, or it might break your code.  These things happen.  Keep calm and fix the code.  It is your responsibility to fix and test your code before pushing it up to the repository.

However, if the incoming changes overlap with your changes, then git will declare a “merge conflict” which you must resolve before you can commit and push.  VS Code will show you each conflict and give you options on how to handle it.  If none of the offered options are correct, you may choose to just edit the file until it is right.  When all code has been fixed, you must stage and commit all changed files.

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.

Open the More Actions menu and select “Push”.  Done.

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.

There is a “Sync” option in the More Actions menu that will do the pull and push in one step.  This can be a nice feature if no one else is working on your code.  If multiple people are working, then Sync does increase the risk that the repository will contain combinations of files that do not work together.  With multiple programmers, you should avoid Sync and perform the following steps manually:

  1. Commit your changes.
  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 Robot Programs with VS Code

Now that you’ve got Visual Studio Code installed and configured for WPILib, you can start creating robot programs.  The WPILib extension contains a wizard to get you going quickly.

You can start coding before the robot exists, but if you have a physical robot available, so much the better.  For this example, let’s assume we have the roboRIO set up on a test board, with a joystick, one motor and one motor controller.

Step 1: Create a new Robot Project

Start up VS Code.  If the WPILib extension is properly loaded, then every window’s title bar will have a red hexagon around the letter “W”.  This is a button that will open up the Command Palette to show all the WPILib commands.

wpilib_logo

Click on the “W” button, and select “Create a new Project”.

vsc_program_palette

This will pop open the WPILib Project Creator window.

vsc_program_creator

There are three buttons just under the welcome message.

  • The first button lets you choose either Template or Example.  Templates are bare-minimum projects that can be the basis for your robot program. Examples are projects for specific purposes.  Examples can also be the basis for your work, but they are especially useful to demonstrate different robot functions.
  • The second button lets you choose either Java or C++ programs.
  • The third button picks a specific Template or Example.

For this example, we’ll specify a Java template for “Iterative Robot”.   Fill in a parent folder, project name, and your team number.  Generate the project and open it in the current window.

Once generated, VS Code will open the File Explorer sidebar, so you can see all the new files created.  Go ahead and look at everything. In particular note that all the Java source code is under the “src” directory.  Also, take a look at the “build.gradle” file which controls how the project is compiled and deployed.

This project is a complete robot program.  You could deploy it to your robot, although it doesn’t do anything yet.  Click on the “W” button and select “Build Robot Code”.  All code will be compiled locally, and you should see the message “BUILD SUCCESSFUL”.

Step 2: Program to control one motor

From the File Explorer, open up the “Robot.java” file.  This is the program executed by your robot.  Read through the whole file.

vsc_program_0

The robot will execute Robot.java as follows:

  • When the robot starts executing the program, it will initialize all class variables, and will then call robotInit().  Then, no matter what mode it is in, it will call robotPeriodic() repeatedly.  The standard for FRC robots is to attempt 50 calls a second.
  • When the robot transitions into autonomous mode, it will call autonomousInit() once and then call autonomousPeriodic() repeatedly.
  • When the robot transitions into teleoperated mode, it will call teleopoInit() once and then call teleopPeriodic() repeatedly.
  • There are also methods for testInit(), testPeriodic(),  disabledInit(), and disabledPeriodic().   These are not often used.

To keep this tutorial really simple, we’re going to delete everything except robotInit() and teleopPeriodic().  Your bare-minimum robot program is below.  Once you’ve modified it, hit the “W” button and try to “Build Robot Code”;  you should get a successful build.

vsc_program_1

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.

Hit the “W” button and build robot code again.  You should get BUILD SUCCESSFUL.

Step 3: Build and deploy

Now, connect all the hardware.  Your laptop should connect to the roboRIO, either through USB, Ethernet, or through the radio.  The joystick should be attached to the laptop.

Hit the “W” button and choose “Deploy Robot Code”.  VS Code will compile the project again and deploy it out to the roboRIO.  You should see BUILD SUCCESSFUL in the terminal window.  The RioLog window will open inside VS Code.

vsc_program_deploy

The most common failure at this point is “Target roborio could not be found at any location”, which means that you’ve failed to make a network connection to the robot.  Debug all the physical connections or maybe try a different way of connecting to the robot.  Sometimes you will need to disconnect from all other networks, so VS Code isn’t trying to find your robot out on the open internet.

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.

Note that the RioLog window in VS Code is still connected and will show you console output from the roboRIO.

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 VS Code

Note that the following document was written while we were still in the 2019 alpha test of WPILib.  When the 2019 software is officially released, it will include a one-step installer that sets up almost everything into a single frc2019 directory, including a customized version of Visual Studio Code. So, some of the following may be unnecessary, but there is still some good information about VS Code.  Also, you could use the following to roll your own environment, or experiment with developmental versions of WPILib.

When the new software is officially released, it is recommended that you use the one-step installer.

Starting in 2019, the officially supported development environment for FRC software development will be Visual Studio Code. That’s not to say that you cannot use Eclipse, IntelliJ, or vim if you want. In fact, if your team is happy with another environment, then you can safely stick with it. However, the excellent support from the WPILib team will be behind Visual Studio Code.

The first thing to know is that Visual Studio Code is not the same as Visual Studio. Visual Studio is a heavyweight Integrated Development Environment, primary for working with Microsoft applications. Visual Studio Code (let’s call it VSCode) is a much lighter text editor with an extension mechanism. The WPILib team will be providing a new extension for FRC development.

FRC robot programs will be built using GradleRIO, which can also be executed from Eclipse, IntelliJ or from the command line.

Step 0: Install prerequisites

You must install Java.  Even if you will be developing in C++, you’ll need Java installed to run GradleRIO.  You must define your JAVA_HOME environment variable, since VSCode uses it to find your Java install.  After installing, you should be able to execute “java -version” at a command prompt and get back the current version of the java runtime.  Execute “javac -version” to get back the version of the java compiler.

You must install git, instructions for which are at: https://git-scm.com/ Even if you aren’t using git, VSCode expects it.  After installing, try executing “git –version” at a command prompt.  If it prints back the git version number, you’ve installed it correctly.

If you will be doing C++ development, you must install the compiler toolchains at: http://first.wpi.edu/FRC/roborio/toolchains/

Step 1 : Download and install VSCode

VSCode is available for Windows, Macintosh, and Linux. Download the installer from https://code.visualstudio.com/download . If possible, run the installer as Administrator.

Once installed, VSCode will start up at the Welcome screen

vsc_install_vsc

VSCode is pretty feature rich, and you should definitely start reading the documentation and memorizing the keyboard shortcuts.  Here are a few concepts to get started:

  1. The icons on the left edge make up the “Activity Bar”.  Clicking on the icons will open up the “Sidebar” which offers more functions.
    The icon on top opens the “Explorer” sidebar which shows all the files that you can edit.
    The squarish icon on bottom opens the “Extension” sidebar, which lets you manage software extensions for VSCode.
    Hitting control-B (or command-B on a Mac) will toggle away the sidebar, so you can make full use of screen space.
  2. Holding the control key down and hitting the back-quote character will open a terminal panel on the lower part of the screen.  (The back-quote character is usually in the upper left corner of your keyboard, just under the Esc key).   You’ll probably need to get comfortable with terminals and command lines when developing with VSCode.
    Hitting control-back-quote again will toggle the terminal away.
  3. The F1 key will open the “Command Palette” at the top of the screen.  Also, you can hit control-shift-P on Windows or Linux.  Macintosh users can hit Command-Shift-P.  The Command Palette lets you invoke special commands inside VSCode.  It’s pretty good about offering you suggestions for what you want to do.  Many of these functions are available from menus or from keyboard shortcuts, but you’ll find yourself using the Command Palette a lot.
    The FRC extension for WPILib adds new commands to the Command Palette for building robot code and reconfiguring your robot development environment.

Step 2 : Install language extensions

Click the square “Extension” icon on the Activity Bar.

If you will be doing Java development, type “Java Extension Pack” into the sidebar window.  Select the entry for “Java Extension Pack” and click the green Install button.  After the install is done, click the blue Reload button to restart VSCode.

vsc_install_java

If you will be doing C++ development, search for the “C/C++” extension.  Install and Reload.

vsc_install_three_dot

Note the three dots on the upper right corner of the sidebar.  VS Code calls this the “More Actions” button, and clicking on it will open a menu.  Select “Show Installed Extensions” from the menu.  If everything was successful, you should see your extensions listed in the sidebar.

Step 3 : Install the WPILib extension

At the time of this writing, you can get the alpha release of the WPILib extension from https://github.com/wpilibsuite/vscode-wpilib/releases .  Download the VSIX file.

Click the “Extension” icon on the Activity Bar to open up the Extension sidebar.  Click on the More Actions button on the upper right corner of the sidebar and select “Install from VSIX…”  Specify your new VSIX file.  Install and then hit the blue Reload button.

If you show installed extensions, you should now see the WPILib extension added.  The Command Palette will now offer WPILib commands.  There will also be a little “W” button in a red hexagon on the title bar of all windows. It pops open the Command Palette and lists all WPILib commands.

vsc_install_wpilib

Further Reading:

Tutorial

Installing Java for FRC programming

Note that the following document was written while we were still in the 2019 alpha test of WPILib.  When the 2019 software is officially released, it will include a one-step installer that sets up almost everything into a single frc2019 directory, including a copy of Java version 11.  This document is still good information, especially if you intend to use more than the standard VS Code environment.  If you intend to use VS Code, it is recommended that you:

  • Use the official installer.
  • Set your JAVA_HOME environment variable to the frc2019/jdk directory, as explained below.
  • Install git, as explained below.

If you intend to program your robot in Java, you will need to  install version 11 of the Java Development Kit onto your computer.

Actually, the first step might be to see if you already have Java installed.  Pull up a command window (the CMD program for windows or the terminal program on a Mac) and type the command

java -version

 

java_install_version1.png

If your terminal responds with a version of 11 or more, you might already be set.  Or, you might want to install the latest version, as described below.

Installing Java is really easy.  Let’s see how complicated I can make it.

Step 1: Downloading and Installing the JDK

You’ll want the JDK download for the latest version of Java SE 11 (which at the time of this writing was Java SE 11.0.1).

You can download Java at http://java.oracle.com.  This page changes occasionally, but you should click into the download section for “Java SE”.  From the “Java SE Downloads” page, look for the Java SE 11 section and click on the Oracle JDK download link.

Note that Java comes in two main distributions: the JRE and the JDK. The Java Runtime Environment (JRE) contains only the software to run Java programs.  The Java Development Kit extends the JRE to also let you compile new programs.  For our purposes, you always need the JDK.  Sometimes you’ll find a computer that has both the JRE and JDK installed.  This is perfectly OK, as long as your environment is configured to use the JDK installation.

java_install_download.png

From the JDK 1 Downloads page, accept the license agreement and then download the installer for your operating system.

Windows

There will be two choices for Windows installs, labeled “x86” and “x64”.  You almost certainly want the “x64” version, since the other version is for older 32-bit machines.

Download the installer and run it.  If possible, run the installer as the Administrator user.  After everything is done, you should see your new Java install under the C:/Program Files/Java directory.

Macintosh

Select the “osx” installer in the “dmg” format.  Download and run. Afterwards, you’ll see the installation under the /Library/Java/JavaVirtualMachines/ directory.

Linux

If you’re running Ubuntu or a similar Debian based linux, try executing:

sudo apt-get install openjdk-11-jre openjdk-11-jdk

For Ubuntu, the java installation will end up in /usr/lib/jvm/jdk-11.

For Fedora based Linux distributions, Oracle provides RPM packages.  You’ll probably want the “linux-x64.rpm” version, unless you have an old 32-bit machine.

Step 2: Setting your JAVA_HOME environment variable

Now that Java is installed, we must tell our software where to find it. We’ll want to put that directory path into a JAVA_HOME directory.

For all operating systems, the Java home directory will be the directory containing Java’s  “bin”, “jre”, and “lib” subdirectories.

Windows

Open up a File Explorer window and select the C drive.  Click into Program Files and then click into the Java directory.  Click into a directory named like your new JDK version.

Now click on the file path area and copy the text of the file path into the clipboard.  A typical Java home directory on Windows might be  C:\Program Files\Java\jdk-11 :

 

java_install_win_1

Next, open the Control Panel.  In the search box, type the words “environment variables”.  Click into the link for “Edit System Environment Variables”, which will pop up the System Properties dialog.  Click on “Environment Variables”.

Create a new System Environment Variable named JAVA_HOME, and paste in the value you just copied.

java_install_win_2.png

Next, click on the User Environment variable named “Path” and edit it.  Change it so the first thing in the Path variable is “%JAVA_HOME%\bin” .

Close out the variable and system dialogs.   Open up a CMD windows.  You should now be able to execute the “java -version” command and get back the current version number.

Macintosh

You’ll need to open a terminal window for this job.  Change directories to /Library/Java/JavaVirtualMachines/ .  In this directory you should see a directory whose name is similar to the Java version you just downloaded.  Change into that directory and then into the Contents/Home subdirectory.  That should be your new Java home directory.  For instance, if you installed jdk-11.0.1.jdk, then your Java home directory might be:  /Library/Java/JavaVirtualMachines/jdk-11.0.1.jdk/Contents/Home

java_install_mac_12.png

Change back to your user home directory and edit the file .bash_profile.   Create this file if it doesn’t already exist.  You’ll want to add the following two lines to the end of the file:

export JAVA__HOME=/Library/Java/JavaVirtualMachines/jdk-11.0.1.jdk/Contents/Home
export PATH=${JAVA_HOME}/bin:${PATH}

java_install_mac_2.png

Open a new Terminal window and test that you can execute “java -version” and get back a response.

Linux

Setting the environment variable in Linux is about the same as on a Mac, although you should add the variable definition to the .bashrc file, rather than the .bash_profile.  As above, run java -version to verify that the setup is correct.

Multiple versions of Java

You may have noticed that there are many versions of Java out there.

For the 2018 robot code, we must stick with version 8.  Newer versions will not work.  However, the WPILIB maintainers are committed to making all the new software work with version 11.   It’s perfectly OK to have multiple versions of Java installed on one computer.  Simply update the JAVA_HOME variable to point to your desired installation.

Visual Studio Code and GradleRIO will use the JAVA_HOME variable to find your desired Java installation.  If you develop using Eclipse, there may be an extra step in the Preferences dialog of defining your “installed JRE”.  You can then specify different JREs for different projects.  If you develop in IntelliJ, you can open the Project Structure to set a specific Software Development Kit for each project.

Note that there is also an open-source version of Java called OpenJDK.  This will work perfectly fine for FRC development.   In fact, the roboRIO executes Java programs using the Zulu JRE, which is derived from OpenJDK.  Right now, there’s not much downside to sticking with Oracle’s commercial JDK.

Install git

OK, this has nothing to do with Java. But, while you’re setting up your laptop, you might as well set up git.  Even if you don’t use git, you’ll need this later.

Git is the software version control system used by WPILib and many FRC teams.  For better or worse, git is the world’s most popular software configuration management system.  GitHub is a FIRST sponsor.  Individuals can get free GitHub accounts, and FIRST teams can get upgraded Team Accounts.

Instructions for installing git are at: https://git-scm.com . You might also take a look at:  https://www.atlassian.com/git/tutorials/install-git .  On Windows, do the installation as Administrator.

Further Reading