Actin  Version 5.5.1
Software for Robotics Simulation and Control
Actin SDK Training Examples

Introduction

The training examples provided with the Actin SDK are designed to help you learn how to apply the SDK libraries to solve problems in robotics motion control. The examples build on each other, so following them in order (rather than jumping around) will help.

To make the learning easier, we’ve provided two visualization tools:

  • Actin Render module – this simple renders the robot model in a graphics window.
  • ActinViz – this provides model visualization, UI interaction, and a script editing window with syntax highlighting for EcScript, the Actin scripting language.

Prerequisites

To get the most of these training examples, you should already be familiar with the content of these training courses offered by Energid:

  • Actin Concepts
  • Actin Core

Examples

There are 8 examples included with the training. For each example we’ve provided the code to run the example. The example topcis are listed below. The following pages will explain how each examples works and the relevant Actin SDK classes that are used in the code.

  1. Load UR5 Robot Model, list links and joints.
  2. Load Robot and execute motion in simulation.
  3. Load Robot, execute move with render window display.
  4. Load Robot, execute move using EcScript, with render window display.

The following examples use ActinViz (AV) and EcScript. We’ve provided the source code for ActinViz, written in C++ and Qt QML so that you can create your own, modified graphical UI. This relies on our actin_qml library.

  1. UR10 Simple Motion
  2. UR10 Simple Grasping
  3. UR10 Simple Welding
  4. UR10 Simple Assembly

Finding the Example Files

The example source code, binaries and training data are distributed across these folders, relative from your install folder.

    example source code : ./actin/training/examples
    example data        : ./actin/data/training
    example binaries    : ./actin/build/bin

The examples are built from within the build folder, and then executed from within the build/bin folder

Setting up your Environment

A shell script (or .bat file) is located in the build folder for you to set your environment variables. These include paths to data, toolkits.

    $ source build/SETUP.sh

In addition, we recommend that you add one for your actin install folder to reduce the typing as you work through these examples.

    $ export ACTIN_HOME=~/Energid/actin

Building the Examples

The code for the training examples is located in actin/training. In order to include this in your cmake build, you'll have to edit the config.cmake file in the actin directory to include training. E.g.:

    set(EC_REPOSITORIES     "stable;toolkits;data;actin_qml;osgqtquick;training" CACHE STRING "" FORCE)

Notice that training has been added to the list of repositories to build.

Follow these steps to build training (assuming you are usinng Ninja for fast builds)

    $ cd $ACTIN_HOME/build
    $ cmake .. -G Ninja
    $ ninja

Main.cpp

This is the same for the first four examples. The general idea is to provide a very simple console application that starts each example.

  • initialize the Actin license handler
  • create an instance of Example1 class
  • call setup and run methods for the example1
  • shutdown the license handler.

Any exceptions thrown will print out the exception text.

Example Explanation

The four examples are similar in the way the code is designed and the build is run. We'll explain the first example in some detail, and then point out whats different for examples 2..4.

Example 1 : Load Robot Sim

This simple "hello world" example loads an Actin model from a file and prints out information from the system/state of the model. This example loads a EcSystemSimulation (Actin Viewer format), then gets the EcStatedSystem from it. It could easily be changed to load a EcSystemControlExecutive, or an EcStatedSystem directly.

Goals

The goal of this example is to show how to link to and include the Actin libraries. Another goal is to show how to load a model and print out some of its system parameters and its state.

Code Review

Code Explanation: example1.cpp

setup() : check for a valid Actin license and load the simulation model. The UR5.ecz file is the simulation model, an XML file compressed with gzip. The models files are located in the actin/data/training/models directory.

run() : Calls a function to describe the manipulators and then to describe the state of each manipulator. In Actin, a model can have multiple manipulators, including objects that the robot interacts with. For example, if grasping a part, the part is also considered a manipulator with appropriate bounding volumes and rendering mesh.

loadSimulation() : loads the simulation file using the EcXMLObjectReaderWriter. The simulation contains the stated system, which is comprise of the system, configuration, and state.

describeManipulators() : for each manipulator, iterate through its links and describe the link.

describeLink() : links are chained in a parent, child relationship. This is a recursive function that walks down the chain and print out the text label for each link.

describeState() : The state of the system contains the positions, velocities and accelerations for each joint in the manipulator. This function prints a table of these values for each manipulator. In this example, the robot is not moving.

Classes Referenced:

Actin Types and Macros

The code makes use of the Actin SDK types (in ecTypes.h, part of the SDK stable library) in order to support cross platform builds for linux, windows, macOSX and real time operating systems (RTOS) in both 64 bit and 32 bit architectures. Some examples in this code are:

  • EcU32 : typedef for an unsigned 32 bit integer.
  • EcInt32 : typedef for 32 bit integer (signed)
  • EcReal : typedef for single precision floating point number
  • EC_PRINT : macro for formatted print output with multiple levels for debugging.

Running Example 1

This explanation is for Linux (Ubuntu 16.04), for Windows is mostly the same thing, except for the creation of the environment variable and path slashes. Let’s assume that you installed the actin SDK in ~/Energid/actin, so we’ll create a shortcut to get there.

    $ export ACTIN_HOME=/home/Energid/actin
    $ cd $ACTIN_HOME
    $ cd build/bin
    $ ./trainExample1

This should produce the following console output:

    UR5 Manipulator Links:

    { Base, Shoulder, Elbow, Wrist1, Wrist2, Wrist3 }

    UR5 Manipulator System State:

    Joint |   Angle |   Velocity | Acceleration
     (ID) |   (deg) |  (deg/sec) | (deg/sec^2)
    ------|---------|------------|-------------
        1 |    0.00 |       0.00 |      0.00
        2 |  -40.78 |      -0.00 |      0.00
        3 |   69.61 |      -0.00 |      0.00
        4 | -123.75 |       0.00 |      0.00
        5 |  -78.05 |      -0.00 |      0.00
        6 |    0.00 |      -0.00 |      0.00

Further Excercises

In the interest of learning Actin, it would be educational to attempt a few modifications.

  • Try loading a different model and see how its set up
  • Add a "describeConfiguration" method to print out info on Attachments, and or collision maps.
  • Add to the "describeLink" method to print out more information about a link such as Named Frames, Bounding Volumes, Joint Parameters, etc.

Example 2 : Position Control

In this example, we create a position control system to move the robot using end effector sets. These sets define the motion constrain on the end effector - whether we constrain all 6 DOF or underconstrain which allows for more possible solutions of the end effector motion.

Goals

The goal of this example is to familiarize the developer with more advanced concepts like creating position control systems and creating EcEndEffector and EcEndEffectorSet. This example also shows how to call set the desired placement for an end effector, and call the calculateState method on the EcPositionControlSystem. This example also introduces a simple renderer, which is useful to visualize the motion of the model robot.

Code Review

Code Explanation: example2.cpp

Most of the function in example2 are the same as example1, with these exceptions:

generatePositionController() Creates a position controller and end effector set with 1 end effector frame. Also creates a velocity controller that is required for the position controller.

generateRenderer() Creates a render window, then pulls the visual system state from the window and passes it to the rendered. The visual system state contains the mesh and texture information to render the robot manipulator(s). After this, the robot can be rendered by just passing in the system state (see renderSystemState() next).

renderSystemState() using an updated system state, where the joints angles and link positions will have changed, this renders the robot manipulators in their current state.

run() This function runs a simulation in two parts, with a different number of time steps for each part.

Part 1 of the simulation: The position controller first sets the desired target pose of the end effector (position and orientation) and then runs in a loop, calculating the system state (name dynamicState here) each iteration. This updated system state is passed to the renderer.

Part 2 of the simimulation: The loop generates a series of desired positions along a circular path based on time elapsed. The robot moves the end effector in a circle in the XY plane performing three loops.

Additional Classes Referenced

Running Example 2

Assuming that you’ve already set up Example 1 and created an environment variable for a path to where you installed actin.

    $ cd $ACTIN_HOME
    $ cd build/bin
    $ ./trainExample2

Running the example will create a rendering window with the robot first moving to the target position, and then moving the end effector in a circular path.

Example 2 Render Example from Energid Technologies Corp. on Vimeo.

Further Excercises

In the interest of learning Actin, it would be educational to attempt a few modifications. Try generating a different type of constraint such as a pointEndEffector, to see how the motion changes. Try creating multiple control descriptions for different motion behaviors. Another useful modification would be to print out state information each timestep, to get joint position and velocity information. This can provide basis for a simple hardware interface if you were to send that information to a physical robot system.

Example 3 : Motion Scripts

This example is similar to example 2, except that it uses the class EcMotionScriptSequence to make motion creation easier for the programmer. In this example we create the same motion as in #2, but with much fewer steps.

Goals

The goals of this example are to introduce the concept of motion scripting using EcMotionScriptSequence, which provides a simpler interface to moving the manipulator than in the previous example. Motion script classes provide ready to use joint motions, end effector motions, tool paths, attachments, collision exclusions and more. These motion script objects handle convergence, speed scaling, blending, and provide an easier way to task an EcControlSystemExecutive.

This example also introduces the EcControlSystemExecutiveModifier, which is a simpler API that allows for easier interaction with the EcControlSystemExecutive.

Code Review

Code explanation: example3.cpp

run() This function gets a motion sequence and executes the sequence in a loop until complete. This is different form the previous example where we had to estimate the number of simulation timesteps to run. The EcControlSystemExecutiveModifier is used to calculate the system state and serves as a simpler API to the Actin Core library.

generateMotionSequence() A motion sequence allows the programmer to add a sequence of individual motions including target poses and waypoints and then execute the entire motion sequence at once. The function adds to motions to the sequence – the first to position the robot using joint angles and the second to move the end effector using waypoints.

Additional Classes Referenced

Running Example 3

The output for this example will display in the 3D render window.

    $ cd $ACTIN_HOME
    $ cd build/bin
    $ ./trainExample3

Further Excercises

In the interest of learning Actin, it would be educational to attempt a few modifications. Try creating some more complex motion sequence using the EcMotionScriptSequence. Try creating additional motion library objects such as:

Another useful modification would be to print out state information each timestep, to get joint position and velocity information. This can provide basis for a simple hardware interface if you were to send that information to a physical robot system.

Example 4 : C++ Code + EcScript

Goals

The goal of this example is to introduce motion scripting using EcScript, instead of creating the motion script objects using C++. In this example, the motion is created as a string, and parsed into a EcMotionScriptObject using the EcMotionScriptObject::parseScript method.

Code Review

Code explanation: ./examples/example4.cpp

In this example, we use the EcScript language to define the motions which specify a move joint motion and a way-point sequence.

This example results in the same motion as the previous example; expressed using the motion script is shown below. The motion sequence contains two motions: move_joint and pose_seq. The pose sequence specifies a serial of waypoints define by (x,y,z) position (r,p,w) rotation expresses as Euler angles.

You can compare the previous example code to the loadMotionScript function which defines this EcScript code block as a string.

    (motion_seq
      (move_joint 0 (180.0deg -90.0deg 90.0deg 0.0deg 0.0deg 90.0deg) 1.0 1e-6)
      (pose_seq 0 1 0
            (move_pose 0 1 0 ((0.2 0 0.35)(0 -90deg -90deg)) 1.0 0.02)
            (move_pose 0 1 0 ((0.2 0.1 0.45)(0 -90deg -90deg)) 1.0 0.02)
            (move_pose 0 1 0 ((0.2 0.1 0.65)(0 -90deg -90deg)) 0.1 0.02)
            (move_pose 0 1 0 ((0.2 0 0.35)(0 -90deg -90deg)) 0.1 0.02)
            )
    );

The EcScript language, used by Actin has a large number of easy to use functions for motion control. You’ll find the documentation on our website Actin Motion Library and EcScript)

Adddional Classes Referenced

EcMotionScriptObject

Running Example 4

The output for this example will display in the 3D render window.

    $ cd $ACTIN_HOME
    $ cd build/bin
    $ ./trainExample4

Further Excercises

Try creating some more complex motion sequence using EcScript. Try creating additional motions using:

  • move_joint
  • move_pose
  • move_pose_rel
  • speed
  • pose_seq
  • move_linear
  • move_circular
  • interp_pose_seq
  • set_ee_set
  • set_control_description
  • set_tcp
  • attach_manip
  • detach_manip
  • exclude_collision
  • include_collision
  • motion_seq
  • motion_para

Also try introducing more variables, and using boolean control logic.

Another useful modification would be to print out state information each timestep, to get joint position and velocity information. This can provide basis for a simple hardware interface if you were to send that information to a physical robot system.

ActinViz and EcScripts

For training, we've provided source and binary for ActinViz - a small application where you can load and test out EcScript to control the robot(s) in the simulation. Wath the video below for a quick introduction.

Goals

The goal of this example is to show how its possible to create a user facing application built on Actin motion control and motion scripting. Another goal is to introduce how Actin libraries can work with QML to create an interactive rendering of the Actin model. This also introduces some more advanced EcScript, that shows attachments, collision exclusion, and some natural tasking motions (using point ee to grab a sphere, etc).

The ActinViz dev tool for trying out EcScript commands

The simulation models used in training are found in:

    actin/data/training/models

and the scripts that go with the models are found in:

    actin/data/training/scripts

Four different models with matching scripts are provided, progressing from easy to more complex.

Model/Script Name Description
UR10SimpleMotion A UR10 robot on table demonstrating a simple motion.
UR10SimpleGrasping A UR10 robot with suction gripper attaching to a ball and moving the ball.
UR10SimpleWelding A UR10 robot that following a welding toolpath with the end effector.
UR10SimpleAssembly A UR10 robot that assembles three distinct parts.

UR10 = Universal Robots Model 10 (10 kg payload)

These examples scripts show how to refer to different manipulators, change motion constraint sets, attach and detach objects, and change the collision map dynamically when picking up objects. The script examples can help you can quickly learn how to setup and coordinate motion without having to write C++ code.

Overview of EcScript

For a detailed exmplantion of commands, visit the EcScript EcScript page

Each of the four scripts, listed above, presents new script command introducing more complex motion with each example.

Here is a listing of the commands with documentation links used in the example scripts.

Motion Commands

Collision Attachments, Tool Offset Commands

Define Commands

Other Commands

The scripts also use boolean and arithmetic operators in a pre-fix format (this is Lisp like)

    + - * /

as well as and the assigment operator which appears like this

    :=