Documentation



Prerequisites

1. Install Java JDK

2. Install Eclipse

1. Install Java JDK

2. Install Gradle

3. Install IntelliJ

Setting Up Your First GradleProject with a build.gradle File

Once you have the prerequisites installed, we’ll get started by setting up a project that depends on the IHMC Valkyrie package, which contains all of the code needed to simulate the NASA Johnson Space Center Valkyrie Humanoid robot in IHMC’s Simulation Construction Set, as well as the code needed to run our software on the real Valkyrie robot. We’ll do this by setting up a Gradle project which references some IHMC Maven artifacts.

Create the Project Directory Structure and the build.gradle File

Create a directory called GradleProject and create the folder where your source code lives; the Java convention enforced by Gradle is to have your source code live at src/main/java. You should have a layout on disk like this:

GradleProject
├── src
│   └── main
│       └── java
└── build.gradle

Create the build.gradle File

In your GradleProject folder create a file named build.gradle with the following contents:

apply plugin: 'java'

repositories {
   maven {
      url  "http://dl.bintray.com/ihmcrobotics/maven-release" // IHMC Code releases
   }

   maven {
      url  "http://dl.bintray.com/ihmcrobotics/maven-vendor" // Third-party libraries that we have vendored for various reasons
   }

   /*  
    *  Maven repos hosted at IHMC for some legacy vendored
    *  dependencies we have not been able to vendor on Bintray yet.
    *  This will be going away eventually.
    */
   maven {
        url "https://bengal.ihmc.us/nexus/content/repositories/thirdparty/"
   }

   jcenter() // One of the central Maven repos. You can also use mavenCentral() instead or in addition to.
}

dependencies {
   compile 'us.ihmc:Valkyrie:0.9.0' // <- Group: us.ihmc, Artifact: Valkyrie, Version: 0.9.0
}

Once you have the prerequisites installed, we’ll get started by setting up a project that depends on the IHMC Valkyrie package, which contains all of the code needed to simulate the NASA Johnson Space Center Valkyrie Humanoid robot in IHMC’s Simulation Construction Set, as well as the code needed to run our software on the real Valkyrie robot. We’ll do this by setting up a Gradle project which references some IHMC Maven artifacts.

Create the Project Directory Structure and the build.gradle File

Create a directory called GradleProject and create the folder where your source code lives; the Java convention enforced by Gradle is to have your source code live at src/main/java. You should have a layout on disk like this:

GradleProject
├── src
│   └── main
│       └── java
└── build.gradle

Create the build.gradle File

In your GradleProject folder create a file named build.gradle with the following contents:

apply plugin: 'java'

repositories {
   maven {
      url  "http://dl.bintray.com/ihmcrobotics/maven-release" // IHMC Code releases
   }

   maven {
      url  "http://dl.bintray.com/ihmcrobotics/maven-vendor" // Third-party libraries that we have vendored for various reasons
   }

   /*  
    *  Maven repos hosted at IHMC for some legacy vendored
    *  dependencies we have not been able to vendor on Bintray yet.
    *  This will be going away eventually.
    */
   maven {
        url "https://bengal.ihmc.us/nexus/content/repositories/thirdparty/"
   }

   jcenter() // One of the central Maven repos. You can also use mavenCentral() instead or in addition to.
}

dependencies {
   compile 'us.ihmc:Valkyrie:0.9.0' // <- Group: us.ihmc, Artifact: Valkyrie, Version: 0.9.0
}

Import GradleProject

The Eclipse IDE for Java Developers Mars.1 or higher has the Buildship plugin pre-installed. Buildship is a tool that brings Gradle integration to the Eclipse IDE.

Launch Eclipse

The first time you launch Eclipse, it will ask you to choose your workspace. Note that in Eclipse, your Workspace does not need to be where your code lives. Select any location you please.

Import GradleProject

Select File -> Import to open the Import wizard, and select Gradle Project under Gradle:

Import Gradle Project

Now click Next to bring up the Buildship wizard:

Buildship welcome screen

Click Next, then click Browse next to the field for “Project root directory”, and browse to and select the GradleProject directory that you created:

Select the GradleProject directory

Click Finish to kick off the Gradle build. The Buildship plugin will run Gradle in order to generate the IDE-specific configuration files for managing the project via the Eclipse GUI. This step may take a while; Buildship must pull in some of the Gradle runtime, analyze the structure of the project (our structure is very simple), and download all of the artifacts required for Valkyrie to work, including Valkyrie itself.

Gradle Plugin Support

IntelliJ IDEA supports Gradle SDK version 1.2 and later, and the Gradle plugin is bundled with IntelliJ IDEA and activated by default. If the plugin is not activated, enable it on the Plugins tab of the File > Settings (Windows and Ubuntu) or IntelliJ IDEA > Preferences(OSX) menu.

You can find more detailed information about Gradle and IntelliJ on IntelliJ’s website.

Opening/Importing GradleProject

If you have just started IntelliJ IDEA, you will be presented with the Welcome screen.

welcome screen

Choose Open from the Welcome screen, or if IntelliJ IDEA is already open choose File/Open from the menu bar.

import build gradle project

From the Open File or Project dialog traverse the directory structure and select the GradleProject folder or the build.gradle file and select OK.

There are several things to note in the next dialog, which have been marked:

import build gradle project

  1. We highly recommend unchecking the option for using separate modules per source set
  2. If you are using a local Gradle distribution, you will need to identify the Gradle Home; typically this is the directory above the bin directory that contains the gradle executable. In this example, using Homebrew for OS X, we identify /usr/local/opt/gradle/libexec; if you were to look inside of this directory you would see /usr/local/opt/gradle/libexec/bin/gradle. On other operating systems this location may change; for example, in Ubuntu, you may need to traverse several symlinks due to the way apt-get installed packages are configured in order to find the actual Gradle Home.
  3. If this is your first time launching IntelliJ IDEA, the “Gradle JVM” option will be empty and will make allusions to Java Home. Another option is to have already added a “Project SDK” to IntelliJ using the Wizard. This can be done prior to importing the build.gradle by selecting Configure -> Project Defaults -> Structure and using the New button to add a JDK installation to IntelliJ IDEA:

configure project structure

add sdk

Wait few minutes while IntelliJ IDEA imports GradleProject and obtains the dependencies specified in the build.gradle file:

downloading dependencies

Create The ValkyrieDemo Class In Your Project

Open the Java Perspective

You’ll want to have the Java Perspective open before you create and edit your class. After importing the Gradle Project you are often left with the Gradle Tasks window open and the Java Perspective minimized. Click the maximize perspective button on the right of the Eclipse IDE window to expand the Java Perspective.

Wizard Search

Once expanded you should see the GradleProject selected on the left and Java on the top right.

Wizard Search

Create a New Class to Run the Valkyrie Simulation

Press Ctrl+N (Cmd+N on OS X) to bring up the “New” wizard, type out “Class” to filter down to the “Class” option, and then click Next.

Wizard Search

Java classes are organized by “packages”. Many IHMC packages start with us.ihmc, you can use your organization, a personal website, or whatever you’d like as your package. Here we’re going to use us.ihmc.demo as the package, and ValkyrieDemo as the name of the class. Fill out this information and click Finish:

New Class Wizard

Fill in the class to look like the following:

package us.ihmc.demo;

import us.ihmc.avatar.DRCFlatGroundWalkingTrack;
import us.ihmc.avatar.drcRobot.DRCRobotModel;
import us.ihmc.avatar.initialSetup.DRCGuiInitialSetup;
import us.ihmc.avatar.initialSetup.DRCRobotInitialSetup;
import us.ihmc.avatar.initialSetup.DRCSCSInitialSetup;
import us.ihmc.commonWalkingControlModules.desiredHeadingAndVelocity.HeadingAndVelocityEvaluationScriptParameters;
import us.ihmc.commonWalkingControlModules.highLevelHumanoidControl.factories.WalkingProvider;
import us.ihmc.jMonkeyEngineToolkit.GroundProfile3D;
import us.ihmc.simulationconstructionset.HumanoidFloatingRootJointRobot;
import us.ihmc.simulationconstructionset.SimulationConstructionSet;
import us.ihmc.simulationconstructionset.util.ground.FlatGroundProfile;
import us.ihmc.valkyrie.ValkyrieRobotModel;

public class ValkyrieDemo
{
   public static void main(String[] args)
   {
      DRCRobotModel robotModel = new ValkyrieRobotModel(DRCRobotModel.RobotTarget.SCS, false); // Construct the Valkyrie robot model for simulation.
      DRCGuiInitialSetup guiInitialSetup = new DRCGuiInitialSetup(true, false); // Helper configuration object for setting up the Simulation GUI
      final double groundHeight = 0.0; // No magic numbers!
      GroundProfile3D groundProfile = new FlatGroundProfile(groundHeight); // Construct a ground profile

      DRCSCSInitialSetup scsInitialSetup = new DRCSCSInitialSetup(groundProfile, robotModel.getSimulateDT()); // Helper configuration object for setting up Simulation Construction Set
      scsInitialSetup.setDrawGroundProfile(true); // Make ground profile visible
      scsInitialSetup.setInitializeEstimatorToActual(true); // Seed the state estimator with a perfect starting configuration

      double initialYaw = 0.0; // No magic numbers!
      DRCRobotInitialSetup<HumanoidFloatingRootJointRobot> robotInitialSetup = robotModel.getDefaultRobotInitialSetup(groundHeight,
                                                                                                                      initialYaw); // Helper configuration object for the robot starting configuration

      boolean useVelocityAndHeadingScript = true; // No magic... booleans?
      boolean cheatWithGroundHeightAtForFootstep = false; // No magic... booleans?

      HeadingAndVelocityEvaluationScriptParameters walkingScriptParameters = new HeadingAndVelocityEvaluationScriptParameters();
      DRCFlatGroundWalkingTrack flatGroundWalkingTrack = new DRCFlatGroundWalkingTrack(robotInitialSetup,
                                                                                       guiInitialSetup, scsInitialSetup, useVelocityAndHeadingScript, cheatWithGroundHeightAtForFootstep,
                                                                                       robotModel, WalkingProvider.VELOCITY_HEADING_COMPONENT, walkingScriptParameters); // Construct a Flat Ground Walking Track, a re-usable sim environment we use to validate the basics of the walking algorithm

      SimulationConstructionSet scs = flatGroundWalkingTrack.getSimulationConstructionSet(); // Construct the SCS instance
   }
}

Once GradleProject has been imported into IntelliJ IDEA, the project window should open.

new project window

Open the “Gradle projects” Tool Window

1. Hide/Show Tools tabs

In the lower left corner of the project window you will see the Hide/Show tools icon. If you do not see the Gradle tab on the right select this icon to show it.

2. Open the “Gradle projects” Tool Window

On the right of the project window you should see a Gradle tab, select it to expand the “Gradle projects” tool window.

3. List Gradle Dependencies

Select the triangle next to Dependencies in the “Gradle projects” tool window. You should now see a full list of dependencies. These libraries have been automatically downloaded from the remote repositories specified in your build.gradle script and linked to your project.

You can hide/show the “Gradle projects” tool window by selecting the Gradle tab on the right.

Create a New Class to Run the Valkyrie Simulation

Java classes are organized by “packages”. Many IHMC packages start with us.ihmc, you can use your organization, a personal website, or whatever you’d like as your package. Here we’re going to use us.ihmc.demo as the package, and ValkyrieDemo as the name of the class.

In the project tool window on the right, right click on the java folder, and select Java Class under the New menu.

create new class

Enter us.ihmc.demo.ValkyrieDemo for the Name field and select OK.

create new class

ValkyrieDemo Class

You should now see a skeleton of your ValkyrieDemo class. Replace the skeleton text with the following java source code:

package us.ihmc.demo;

import us.ihmc.avatar.DRCFlatGroundWalkingTrack;
import us.ihmc.avatar.drcRobot.DRCRobotModel;
import us.ihmc.avatar.initialSetup.DRCGuiInitialSetup;
import us.ihmc.avatar.initialSetup.DRCRobotInitialSetup;
import us.ihmc.avatar.initialSetup.DRCSCSInitialSetup;
import us.ihmc.commonWalkingControlModules.desiredHeadingAndVelocity.HeadingAndVelocityEvaluationScriptParameters;
import us.ihmc.commonWalkingControlModules.highLevelHumanoidControl.factories.WalkingProvider;
import us.ihmc.jMonkeyEngineToolkit.GroundProfile3D;
import us.ihmc.simulationconstructionset.HumanoidFloatingRootJointRobot;
import us.ihmc.simulationconstructionset.SimulationConstructionSet;
import us.ihmc.simulationconstructionset.util.ground.FlatGroundProfile;
import us.ihmc.valkyrie.ValkyrieRobotModel;

public class ValkyrieDemo
{
   public static void main(String[] args)
   {
      DRCRobotModel robotModel = new ValkyrieRobotModel(DRCRobotModel.RobotTarget.SCS, false); // Construct the Valkyrie robot model for simulation.
      DRCGuiInitialSetup guiInitialSetup = new DRCGuiInitialSetup(true, false); // Helper configuration object for setting up the Simulation GUI
      final double groundHeight = 0.0; // No magic numbers!
      GroundProfile3D groundProfile = new FlatGroundProfile(groundHeight); // Construct a ground profile

      DRCSCSInitialSetup scsInitialSetup = new DRCSCSInitialSetup(groundProfile, robotModel.getSimulateDT()); // Helper configuration object for setting up Simulation Construction Set
      scsInitialSetup.setDrawGroundProfile(true); // Make ground profile visible
      scsInitialSetup.setInitializeEstimatorToActual(true); // Seed the state estimator with a perfect starting configuration

      double initialYaw = 0.0; // No magic numbers!
      DRCRobotInitialSetup<HumanoidFloatingRootJointRobot> robotInitialSetup = robotModel.getDefaultRobotInitialSetup(groundHeight,
                                                                                                                      initialYaw); // Helper configuration object for the robot starting configuration

      boolean useVelocityAndHeadingScript = true; // No magic... booleans?
      boolean cheatWithGroundHeightAtForFootstep = false; // No magic... booleans?

      HeadingAndVelocityEvaluationScriptParameters walkingScriptParameters = new HeadingAndVelocityEvaluationScriptParameters();
      DRCFlatGroundWalkingTrack flatGroundWalkingTrack = new DRCFlatGroundWalkingTrack(robotInitialSetup,
                                                                                       guiInitialSetup, scsInitialSetup, useVelocityAndHeadingScript, cheatWithGroundHeightAtForFootstep,
                                                                                       robotModel, WalkingProvider.VELOCITY_HEADING_COMPONENT, walkingScriptParameters); // Construct a Flat Ground Walking Track, a re-usable sim environment we use to validate the basics of the walking algorithm

      SimulationConstructionSet scs = flatGroundWalkingTrack.getSimulationConstructionSet(); // Construct the SCS instance
   }
}

Create the Run Configuration for ValkyrieDemo

Now we will run the Valkyrie simulation from Eclipse, but the JVM requires more memory. We suggest at least 4GB.

Create the Run Configuration from Eclipse

With ValkyrieDemo.java open and active in the Java Perspective, choose Run\Run Configurations... from the menu. This will open the Run Configurations dialog. Select Java Application on the left as how to run your class, and then click the New launch configuration button above it.

NewRunConfiguration

You should now have a new Run Configuration under Java Application called ValkyrieDemo. Choose the Arguments tab and add -Xms4096m -Xmx4096m to the VM Arguments: text area. Now click Apply to save your configuration.

RunConfigurationVMSettings

You can click Run from the Run Configuration dialog to run the simulation, or from now on you can click the ‘Run’ button from the Eclipse Toolbar in the Java Perspective.

Now we will run the Valkyrie simulation from IntelliJ, but the JVM requires more memory. We suggest at least 4GB.

Create the Run Configuration from IntelliJ

Right click on ValkyrieDemo.java in your project window, and select Run 'ValkyrieDemo.main()' from the menu. This will start the simulator and preconfigure the application’s run configuration for you.

NewRunConfiguration

The simulation may or may not start up depending on your system, but for now quit the java application window or select the Stop button in thelower right.

NewRunConfiguration

Edit the Run Configuration

Now select Run/Edit Configurations... from the menu to open the Run/Debug Configurations dialog.

RunConfigurationVMSettings

Make sure that ValkyrieDemo is selected under Application. Now choose the Configuration tab, then in the VM Options: text field enter -Xms4096m -Xmx4096m. Finally, select OK to save your configuration and close the dialog.

Run the ValkyrieDemo Simulation

You can now run the ValkyrieDemo simulation by right-clicking ValkyrieDemo.java and selecting Run 'ValkyrieDemo.main()' or by selecting the run icon RunConfigurationVMSettings from the menu bar at the top to run the simulation while ValkyrieDemo is the currently selected run configuration.

Run ValkyrieDemo

Once your program launches you should see the SCS Splash Screen, followed by the Valkyrie simulation. Click the Simulate button. Valkyrie should settle and balance in a standing position.

Valkyrie Sim

To make Valkyrie walk, type “walk” in the Variable search field. Find the variable named “walk”, and set it’s value to “1.0”. If Valkyrie does not start walking, click the Simulate button, and Valkyrie should begin the flat ground walking track script. Congratulations! Everything is installed correctly!

Walking

If the simulation ‘crashes’, you will need to quit it and restart from your IDE.

Crashing

For a more detailed explanation of Gradle Projects, IHMC Robotics Libraries, and SCS, see the Documentation pages.