Totem’s software is written as a single Java application executed when power is first applied to the robot.  To speed up the development process the software is developed on a separate MS Surface tablet and then downloaded to the robot.  In most cases the software is tested in the Java development environment hosted on the Surface.  However there are occasions when the software must be tested on the robot itself (e.g., testing modules that interact with hardware).  Thankfully Java supports remote debugging – the ability to use the Java development environment to remotely debug the software executing on the robot.  This article describes the configuration required to accomplish remote debugging of the robot’s Java applications, assuming Eclipse is used as the host Java development environment.

Verify Java Run-Time Compatibility

On the Surface PC invoke the Eclipse Preferences dialog, then navigate to Java > Installed JREs:

On the Raspberry Pi type “java -version”:

Both JREs should use the same major version number – 1.8 in this case.

Create a Shell Script to Execute the Application with a Remote Debugging Listener

Java applications are packaged for deployment as a single standalone “jar” archive file.  Contained within the jar archive are the various application implementation artifacts (e.g., Java class files, images, etc).  Executing the application is accomplished by invoking the “java” command and passing the filename of the application’s jar file as a parameter.  To enable remote debugging additional parameters are provided specifying the network port on which java listens for connections by remote development environments.  Unfortunately several parameters must be specified containing rather cryptic syntax.

Rather than type a lengthy command each time we want to run the application we can create a shell script that provides a short, easy-to-type alias instead.  For example, the debug.sh shell script shown below executes the application within jar file totem.jar while creating a remote debugger listener on port 8000:

Now each time we want to remotely debug the totem.jar application we can simply type ./debug.sh to start the application.

Create an Eclipse Remote Debugging Configuration

Within the Eclipse development environment create a new remote debugging configuration by opening the Debug Configurations dialog.  Select the line titled Remote Java Application and then click the New icon located  at the top of the list.  In response Eclipse will create a new entry and display a panel listing the entry’s various configuration options.  The following image illustrates typical configuration values, assuming the listener is listening on port 8000 as shown in the previous step:

At this point the configuration is complete.  To remotely debug the application the first step is to start the application running on the robot by invoking the ./debug.sh command within the Raspberry Pi’s command window.  Then click the Debug button within Eclipse’s debug manager window (or invoke the link within the Debug menu) to connect the Eclipse debugger to the running application.  You can now set breakpoints and examine variable values in real-time as the application executes on the robot.