Actin®  Version 5.2.0
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 exampels 2..4.

Example 1 : Load Robot Sim

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:

EcActinLicenseHandle Ec::Application EcXmlObjectReaderWriter EcStatedSystem EcSystemSimulation EcIndividualManipulator EcManipulatorLink EcManipulatorLinkVector EcXmlRealVector

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.

Run 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

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.

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

EcRenderWindow EcPositionControlSystem EcManipulatorSystemState EcCoordinateSystemTransformation EcManipulatorLinkConstPointerVector EcFrameEndEffector EcEndEffectorSet EcControlExpressionCore EcExpressionScalarConstant EcControlExpressionJointRateFilter EcControlExpressionEndEffectorErrorFilter EcExpressionGeneralColumn EcControlExpressionContainer EcIndividualVelocityControlDescription EcVelocityControlSystem EcVector

Running Example2

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.

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.

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

EcVisualizableStatedSystem EcControlSystemExecutiveModifier EcMotionScriptObject EcMotionScriptSequence EcEndEffectorMotionMoveJoint EcOrientation EcCoordinateSystemTransformation

Running Example3

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

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

Example 4 : C++ Code + EcScript

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

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.

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 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

motion_seq move_joint move_pose move_circular

Collision Attachments, Tool Offset Commands

include_collision exclude_collision attach_manipulator detach_manipulator set_tool_offset

Define Commands

def_pose def__u32 def_trans def_rot

Other Commands

get_frame

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

    :=
Created by Energid Technologies www.energid.com
Copyright © 2016 Energid. All trademarks mentioned in this document are property of their respective owners.