Example 1: The Mobile Simulation - ihmcrobotics/ihmc-open-robotics-software-tutorials GitHub Wiki

Introduction

Welcome! In this tutorial, we will create a simple child's mobile toy.

Going through this tutorial will help familiarize yourself with the structure of an SCS simulation program, and by the end of the tutorial set, you should be able to create and simulate a simple passive system with pin joints. Let's get to the steps. If you haven't done so already, visit Setting up the Development Environment to set up the project in your development environment.

Understanding the Contents of the Project

Before we hop into the simulation, let's try to understand the code a bit better.

1. MobileDefinition.java defines the child's mobile toy using a tree structure of 21 gimbal joints (63 degrees of freedom total). The class creates a top (fixed) link that serves as the base of the mobile, and then creates a gimbal joint at the top of the mobile, attaches a crossbar to the top gimbal joint, and proceeds to attach a new gimbal joint on each point of the cross bar. On each point of the smaller crossbar, another gimbal joint is added with a toy link attached.

2. MobileSimulation.java sets up and starts (launches SCS) the simulation environment where we can add the mobile toy defined in MobileDefinition.java.

Let's take a deeper look at the contents of each file, starting with MobileSimulation.java.

MobileSimulation.java

To start a new Simulation Construction Set (SCS) environment, we use the following two lines of code.

SimulationConstructionSet2 scs = new SimulationConstructionSet2(SimulationConstructionSet2.impulseBasedPhysicsEngineFactory());
scs.start(true, false, false);

The following SCS GUI should generate.

When a robot is added in the simulation, graphs and buttons appear to set some SCS parameters and visualize some of the robot data.

We'll go into these a bit more when we need them during simulation. Before adding a robot, there are some basic parameters and settings for SCS that you should get familiar with. For that, I invite you to read through the code in the files. The code in each project of this tutorial has been notated heavily for user clarification, and to fully understand how the controllers work, it would be good practice to read through the provided class files before or after running the simulations.

MobileRobot.java

Let's add a robot to the mix. We first setup the definition of the robot using the class RobotDefinition in SCS, which allows to define robots based on joints and rigid bodies. The class is included in SCS and allows to setup VisualDefinitions, define properties such as mass and inertia, define controllers, and more. Extending the class is an easy way to make a new type of robot. The robot is created and added to the simulations using:

MobileDefinition mobile = new MobileDefinition();
scs.addRobot(mobile);

In order to build this mobile child's toy for our simulation, we will use two types of SCS objects: JointDefinitions and RigidBodyDefinitions.

The RigidBodyDefinition object includes the definition of the physical properties (Mass, Center of Mass offset vector, Moment of Inertia, ...) of a rigid body. The JointDefinition object is used to define the connections between links. JointDefintion describes the motion constraint between RigidBodyDefinitions. SCS provides a variety of JointDefinitionss to build robots such as: SixDofJointDefinition, SphericalJointDefinition, PlanarJointDefinition, PrismaticJointDefinition, or FixedJointDefinition. To represent the gimbals on the mobile toy, we will define a gimbal joint consisting of serial RevoluteJointDefinitions.

For a more thorough explanation, I invite you to read through the code in the file. The code in each project of this tutorial has been notated heavily for user clarification, and to fully understand how the robot is built (both in the simulation and on the controller side), it would be good practice to read through the provided class files before or after running the simulations.

Run the Simulation

Now we are ready to simulate the mobile. Open the file MobileSimulation.java:

In the newly opened Java editor, right click anywhere on the code then in the context menu select "Run As" > "Java Application":

Soon enough, SCS should appear. By clicking on the three black bars on the top left of the window the Variables and Registries will show. You can search for variables by typing the variable name in the field just on top of the list.

Click on the Simulate button to see the mobile animate:

To see the names/functions of each button, hover over them.

Here are some SCS tools to experiment with:

• Click and drag your mouse cursor on the graph change the position of the current time stamp/index (the black vertical bar).
• Use the Goto In Point_/_Goto Out Point buttons to place the current index at the beginning or end of the simulation.
• Press the Play button to playback the simulation in real-time from the current index.
• To get a closer look at the movement in the graphs, click on the Zoom in button (plus sign).
• In the variable list, variables can be searched for by name and added to a graph (drag and drop). SCS has a variety of useful features dedicated to efficiently debugging controllers. As part of a user-friendly feedback process, many classes create tons of YoVariables that are available via the SCS GUI. YoVariables act just like regular variables, such as a double but are called YoDouble. The real difference is that YoVariables can be monitored in SCS, allowing for the tracking of individual objectives and thus ensuring that every stage inside the program is behaving as expected. As an example, try searching for one of the joint positions by typing q_joint&X to find all joint positions for X and then drag and drop one of the variables into any one of the graphs. For reference, the notation of variable is as follows:

For the joint state:

• q: position or angle of a joint
• qd or qDot: linear or angular velocity
• qdd: acceleration of the joint
• tau: torque at the joint

For PD control gains:

• k or kp: proportional gain (stiffness)
• b or kd: derivative gain (dampening)

When you're ready, move on to the next example of this tutorial, Example 2: Simple Pendulum without Controller.