Getting Started

Strongback is a Java library for FRC robots, and to use it you must first install the library onto your development machine and set it up properly. This can be tedious and somewhat complicated, so we’ve created the Strongback Command Line Interface (or CLI) tool to easily install, upgrade and use different versions of the Strongback Java Library. The Strongback CLI consists of a single, entirely self-contained executable program — simply download the correct one for your operating system and run it to:

  • list the Strongback Java Library versions that are available,

  • install, upgrade, restore, or uninstall the Strongback Java Library version,

  • create a new Java project that uses Strongback,

  • decode a binary data file recorded by the Strongback library running on a robot, and

  • show information about the installed versions of the Strongback Java Library and WPILib for Java library

The rest of this chapter will show you how to download and use the Strongback CLI tool and use it to install the Strongback Java Library.

Prerequisites

The Strongback Java Library is designed to work with the WPILib for Java library, and to cleanly integrate with your robot Eclipse projects created with the WPILib plugin for Eclipse.

So, before you install or use Strongback, be sure to install the latest stable version of the 2017 WPILib plugins for Eclipse, or if you’ve installed an earlier version simply use Eclipse’s "check for updates" feature to automatically upgrade the WPILib plugins.

Note

You can install the WPILib plugins into Eclipse, but it’s not fully initialized until you use them to create a new robot project and enter your team number. So if you’ve not yet created a new robot project using the WPILib plugins, do that before continuing!

Running the Strongback CLI on Windows

The Strongback CLI tool for Windows is called strongback.exe, and you can download a ZIP file containing this application from the Strongback CLI release page. Find the most recent release, download that release’s …​-windows.zip, and extract its strongback.exe file into any directory that is already included in or that you can add to the %PATH% environment variable. For simplicity, we recommend your home directory, e.g., C:\Users\<you>.

After you’ve extracted the file and added the directory to your %PATH%, open up a command window and run the following command:

strongback info

This will show you the installed versions of the Strongback Java Library and WPILib for Java library. If you can run this successfully from several different directories, then you’ve correctly set up the %PATH%.

Tip
Terminal on Windows

Throughout this book we give command that start with $. Mac and Linux users can simply copy and paste these as-is, but Window’s cmd.exe command window uses a very different syntax. We trust that you can translate these commands so they’ll work on Windows — for example, using backward slashes instead of forward slashes in paths.

However, we suggest considering a better terminal. GitHub for Windows is a lighter-weight native installation of the Git tools, but more importantly it includes Git BASH, an excellent full-featured terminal application that looks and behaves like terminals on OS X and Linux. In fact, all of the commands throughout this document should work as-is in Git BASH, with one exception: in Git BASH, you must always run the Strongback CLI use strongback.exe rather than strongback.

Running the Strongback CLI on Linux

The Strongback CLI tool for Linux is a self-contained executable called strongback, and downloading it takes just a few commands. We recommend placing the strongback tool in any directory on your $PATH other than your home directory. If you don’t have admin privileges or don’t know where else to put it, you can use the following commands to create a bin directory in your home directory and add that directory to you path:

$ cd ~
$ mkdir -p ~/bin
$ echo "PATH=\${HOME}/bin:\${PATH}" >> ~/.bashrc
$ source ~/.bashrc

Then, run the following commands to download the strongback executable into your bin directory, though be sure to replace the 1.2.2 version with the latest version:

$ cd ~/bin
$ curl -L https://github.com/strongback/strongback-cli/releases/download/v1.2.2/strongback-cli-1.2.2-macos.tar.gz | tar -xvz

That’s it! Open up a new terminal and run:

$ strongback info

This will show you the installed versions of the Strongback Java Library and WPILib for Java library.

Running the Strongback CLI on MacOS or OS X

The Strongback CLI tool for MacOS and OS X 10.7 or later is a self-contained executable called strongback, and downloading it takes just a few commands. We recommend placing the strongback tool in any directory on your $PATH other than your home directory. If you don’t have admin privileges or don’t know where else to put it, you can use the following commands to create a bin directory in your home directory and add that directory to you path:

$ cd ~
$ mkdir -p ~/bin
$ echo "PATH=\${HOME}/bin:\${PATH}" >> ~/.bashrc
$ source ~/.bashrc

Then, run the following commands to download the strongback executable into your bin directory, though be sure to replace the 1.2.2 version with the latest version:

$ cd ~/bin
$ curl -L https://github.com/strongback/strongback-cli/releases/download/v1.2.2/strongback-cli-1.2.2-macos.tar.gz | tar -xvz

That’s it! Open up a new terminal and run:

$ strongback info

This will show you the installed versions of the Strongback Java Library and WPILib for Java library.

Viewing help

The Strongback CLI has built-in help, which you can see by running strongback help to display something like:

Usage:

   strongback <command> [<args>]

Available commands include:
   decode        Converts a binary data/event log file to a readable CSV file
   help          Displays information about using this utility
   info          Displays the information about this utility and what's installed
   install       Install or upgrade the Strongback Java Library
   install-deps  Install the's 3rd party libraries in the current Strongback Java Library
                 as WPILib user libraries
   new-project   Creates a new project configured to use Strongback (only 1.x)
   releases      Display the available versions of the Strongback Java Library
   version       Display the currently installed version
   uninstall     Remove an existing Strongback Java Library installation

Additional help is available for each command with:

   strongback help <command>

The Strongback CLI tool has a number of commands. We’ve already seen the info command, and the version is similar but more concise. Let’s look at several other commands.

Listing available versions of the Strongback Java Library

The Strongback CLI makes it easy to list and install the available versions of the Strongback Java Library and to install any of these. Run the following command to list the available versions:

$ strongback releases

This will check the Strongback releases page and output something similar to:

Found 10 releases of the Strongback Java Library:
  1.1.7
  1.1.6
  1.1.5
  1.1.3
  1.1.2
  1.1.1
  1.1.0
  1.0.3
  1.0.2
  1.0.1

Installing the Strongback Java Library

The most powerful of the Strongback CLI tool’s commands is install, which allows you to easily install and upgrade any version of the Strongback Java Library. Simply run:

$ strongback install <version>

to install that version of the Strongback Java Library. Or, if you want to install the latest available version, simply run:

$ strongback install

and the CLI tool will check for the latest available release and install it. If you already have that version installed, the tool will report this and exit without changing anything. Otherwise, it will archive your existing version (if you have one installed) and then install the version you specified.

You can also use the install command to restore a version that was installed previously, making it really easy to switch between Strongback Java Library versions. For example, imagine that you’ve recently installed version 1.1.6 but want to try 1.1.7. You can upgrade to 1.1.7 with:

$ strongback install 1.1.7

and then later switch back to your previous 1.1.6 installation with:

$ strongback install 1.1.6

At any time you can switch back to 1.1.7 (or any other version) by running strongback install <version> again.

Adding Strongback to your project

You can use the Strongback CLI tool to create a new iterative Java robot project for Eclipse set up to use the Strongback Java Library, or update an existing Java robot project to use Strongback. Simply open a terminal, change to the directory where you want the project created, and run the following command:

$ strongback new-project MyRobotProject

and replace MyRobotProject with the name of your new or existing project. Note that this will not overwrite any of the existing files, so to do that add the --overwrite flag:

$ strongback new-project --overwrite MyRobotProject

By default, the Java package will be org.frc<teamNumber> where <teamNumber> is read from your WPILib for Java installation. If you want to use a different package, then supply the --package <packageName> flag. For example:

$ strongback new-project --package io.alphateam.robot MyRobotProject

See strongback help new-project for additional options.

Eclipse User Library for Strongback

Strongback Eclipse projects are set up to use a "Strongback" user library in Eclipse. That user library defines the location of all of the necessary Strongback JAR files (including the source JARs) and the JavaDoc.

When you use the Strongback CLI to create a new or update an existing Eclipse project, the Strongback CLI tool will look in the project’s parent directory for the Eclipse workspace. If it can find the workspace’s .metadata directory, the CLI tool will automatically update your workspace with a User Library defining the location of all of Strongback’s JARs, and it will then ask you to restart your Eclipse workspace.

However, if the CLI tool doesn’t find the Eclipse workspace, you will need to manually import the Strongback User Library into your Eclipse workspace:

  1. Open your Eclipse preferences

  2. In the dialog box, navigate to Java→Build Path→User Libraries in the left handle panel of the preferences dialog

  3. Press the "Import" button on the right side of the dialog box, and use the file chooser to locate the Strongback.userlibraries file inside the ~/strongback/java/eclipse directory.

  4. Press "OK" to import the user library and close the import dialog.

  5. Press "OK" to save the changes to the preferences and close the dialog box.

Compiling your project

Your project should be ready to compile in Eclipse, but you can also use Ant to compile, run the unit tests, and deploy code to the robot. For example, in a terminal go to your project’s directory:

$ cd MyRobotProject

You can run Ant with one or more targets:

  • clean removes all of the generated files.

  • compile compiles all of the project’s Java source code.

  • test runs compile if necessary and then runs all of the unit tests in the testsrc directory of the project (and will compile if needed).

  • deploy runs compile if necessary and then deploys the JAR files to the RoboRIO.

So, to force a recompile and run all of the tests, you can run this:

$ ant clean test

To deploy the code to your robot (just like with WPILib’s Ant scripts):

$ ant clean deploy

And of course, we recommend run the tests before deploying to be sure that nothing breaks:

$ ant clean test deploy

Testing with Strongback

You should add more JUnit test classes to the testsrc directory. When you do, you can run any or all of the tests from within Eclipse using the JUnit runner, or you can run them on the command line using Ant:

$ ant test

results matching ""

    No results matching ""