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
$./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

    :=