EASY-ROB™

3D Robot Simulation Tool

Technical Product Description

Application Program Interface (API)

The Application Program Interface (API) provides the user the ability to develope
own functions written in C programming language for user defined

- inverse kinematics (API-INV)

- motion planning (API-IPO)
- and dynamics (API-DYN)

API-INV - Inverse Kinematics

The API for inverse kinematics is used when a robot kinematics is created based
on universal coordinates or Denavit Hartenberg (DH) parameter and the inverse
kinematics problem has to be solved. Many exported functions from the EASY-
ROB™ data base give full access to all needed robot data, i.e. kinematic robots
lengths, software travel ranges, joint directions, tool frame, TCP location, etc.
Mathematical routines to handle homogeneous transformation matrices are
available as well as trigonometrical functions for angle, triangle and trapezoid
calculations.

Prototypes: er_dvlp.h c-header file

Library: easyrobw.lib

Cartesian Folder: .\easy_rob\er_dvlp\ Joint solution

location VC++ project er_kin.dsw vector
Robot C file: inv_user.cpp float
Basis to Tip Functions: inv_kin_user_1(frame *T)- *inq_q_solut()
*inq_T() inv_kin_user_12(frame *T) Dimension = DOF
Variable Input: Cartesian location, Robot Base to Tip int inq_num_dofs()
frame *inq_T()
Variable Output: Set of joints/axis values
float *inq_q(int soln)
int soln = inq_config()
EASY-ROB is the current robot configuration
Data Base Warning vector int *inq_warnings()
[WARN_OK, -SINGULAR, -UNREACH,
Library: -CNFG, -NO_INVKIN, -SWE_EXCEED]
easyrobw.lib Example Standard Robot RRR:RRR type, modelled
in universal coordinates with
Kinematic 6 DOF and 8 configurations
lengths & int inv_kin_user_2(frame *bTt)
attributes Result Dynamic Link Library Dll er_kin.dll
in folder .\easy_rob\

Result: er_kin.dll

Figure API-01: Interfaces for inverse kinematics

The right is reserved to make technical changes and improvements

EASY-ROB™ Stefan Anton Bruchfeldstr.4 60528 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info@easy-rob.com www.easy-rob.com

API-Description.doc 18. Jan. 01

 EASY-ROB™
3D Robot Simulation Tool
Technical Product Description

Application Program Interface (API)

The inverse kinematics routine is called during TCP jogging using the mouse and
during program execution in CP mode after every interpolation step
*inq_ipo_data_dt_ipo().
Using the function call rob_kin_inv(frame *base_to_tip) forces the
calculation for the inverse kinematics solution. This function can be called from
everywhere within the API.

Kinematic
Robot Chain
Output:
Robot Joints
*inq_q_solut()

TOOL: Tip to TCP

*inq_tTw()
Input: = tTw
TCP
Robot Base to Tip Tip
*inq_T() = bTt
*inq_bTt()
Robot Base to TCP
Robot Base to first Joint *inq_bTw()
*inq_bT0() = bTt * tTw

World Word to Robot Base

Origin *inq_iTb()

Figure API-02: Transformation Chain

API-IPO - Motion Planner

In a semilar way as for the inverse kinematics solution, an Application Program

Interface (API) for the motion planning respectively the interpolator exist. The build-
in motion planning routines inside the EASY-ROB BASIC module implemented for
the point to point (PTP) and continuous path (CP) motion type. The continuous
path motion type covers linear (LIN) and circular (CIRC) motion. The API for the
motion planning allows it to develop user defined functions written in C for the
motion types PTP, LIN and CIRC.

Before the robot starts to move to its new target location, the preparation routine,
which returns the required motion time for that move, is called. Afterwards,
supposed the preparation was successful, the execution routine is called in every
interpolation step to calculate intermediate locations for the robots TCP. Many

The right is reserved to make technical changes and improvements

EASY-ROB™ Stefan Anton Bruchfeldstr.4 60528 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info@easy-rob.com www.easy-rob.com

API-Description.doc 2/8 18. Jan. 01

 EASY-ROB™
3D Robot Simulation Tool
Technical Product Description

Application Program Interface (API)

exported functions give full access to the current motion planning values such as
programmed speeds and accelerations.

Prototypes: er_dvlp.h c-header file

Library: easyrobw.lib

Joint & Folder: .\easy_rob\er_dvlp\

cartesian VC++ project er_ipo.dsw
target C file: ipo_user.cpp Joint &
locations Functions: Preparation: cartesian
int ipo_jnt_prep_user_1..12 intermediate
int ipo_lin_prep_user_1..12 locations
int ipo_circ_prep_user_1..12
(void **ipo_usr_ptr)
Execution:
ipo_jnt_exec_user_1..12
EASY-ROB ipo_lin_exec_user_1..12
Data Base ipo_circ_exec_user_1..12
(float ctime, void **ipo_usr_ptr)
Library: Variable Input: Preparation:
easyrobw.lib Pointer for user defined data structure,
Start and Target locations
Interpolation Variable Output: Return values
control data IPO_OK: Preparation successful
IPO_IN_POSITION: Target already reached
IPO_ERROR: Preparation fails, no execution
user defined data structure **ipo_usr_ptr
required time for this move
float *inq_ipo_prep_t_bahn()
Variable Input: Execution:
current time ctime
user defined data structure **ipo_usr_ptr
Variable Output: Intermediate locations and speeds
Return values:
1: execution is called until return valus is 0
0: execution is called until
ctime <= ..t_end
Example see ipo_user.cpp
Result Dynamic Link Library Dll er_ipo.dll
in folder .\easy_rob\

Result: er_ipo.dll

Figure API-03: Interfaces for motion planner

The right is reserved to make technical changes and improvements

EASY-ROB™ Stefan Anton Bruchfeldstr.4 60528 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info@easy-rob.com www.easy-rob.com

API-Description.doc 3/8 18. Jan. 01

 EASY-ROB™
3D Robot Simulation Tool
Technical Product Description

Application Program Interface (API)

API-DYN - Dynamics

The dynamics option allows to consider the dynamic model of the robot and the
position controller during simulation. The build-in dynamics routine for the dynamic
robot model uses a simple uncoupled 1st order model in the discrete z-space
defined by the inertia, the viscous friction and the gear ratio for each joint. Based
on the system step, the discrete model is calculated. The build-in position controller
is represented by the well known PPI Cascade Controller with pseudo analog PI
velocity controller. During the robots motion a green trace shows the desired TCP
location (generated by the motion planner) and a red trace the actual location of
the robots TCP. An output window shows the errors in joint and cartesian space at
any time. The Application Program Interface (API) for Dynamics allows to develop
user defined functions written in C for the dynamic robot model and the position
controller. Herein it will be possible to consider the real non linear coupled model of
the robot and use an integration algorithm such as Runge Kutta to solve the
inverse dynamic modell. Furthermore, a special position controller such as an
adaptive or a robot modell based controller can be implemented.

user defined data structure user defined data structure

**dyn_cntrl_usr_ptr() **dyn_model_usr_ptr()

desired joint values PPI - Position Controller Robot Model

q = joint error dq = *inq_dq() Control Signal
uc = v_dyn
*inq_q_solut() dq = q - q_dyn
v = kpp * dq *inq_uc()
dv = v - v_dyn uc
+ aux1 * v_solut v_dyn = f(uc,data)
dt = inq_dt_cntrl() dt_sys = inq_dt_sys()
actual joint values Integration value q_dyn += v_dyn * dt_sys
q_dyn = uc_kiv += kpv * kiv
*inq_q_dyn() *dv * dt Output:
Output: Control signal, q_dyn: actual joint
uc = kpv * dv + uc_kiv v_dyn: actual speed

actual joint speed

v_dyn =
*inq_v_dyn()

Figure API-04: Interfaces for dynamics, position controller and dynamic robot model

The above general structure shows the main important data flow between position
controller and the dynamic robot model. The algorithm for position controller and
robot model could be very complex, depending on the users requirements.

The right is reserved to make technical changes and improvements

EASY-ROB™ Stefan Anton Bruchfeldstr.4 60528 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info@easy-rob.com www.easy-rob.com

API-Description.doc 4/8 18. Jan. 01

 EASY-ROB™
3D Robot Simulation Tool
Technical Product Description

Application Program Interface (API)

The position controller with following I/O data.

Prototypes: er_dvlp.h c-header file

Library: easyrobw.lib

Folder: .\easy_rob\er_dvlp\
Desired VC++ project er_dyn.dsw
and actual C file: dyn_user.cpp
locations Functions: int dyn_cntrl_user_1..12 Control signals for
and speeds (void **dyn_cntrl_usr_ptr) each joint:
Input: Pointer for user defined data structure, float *inq_uc()
Current desired and actual locations,
Control parameter:
Example: PPI-Cascade
*inq_cntrl_kpp(): superimposed PosCntrl
EASY-ROB *inq_cntrl_kpv(): P - underlying VelCntrl
Data Base *inq_cntrl_kiv(): I - underlying VelCntrl
*inq_cntrl_aux1..3(): auxiliary values
Library: gear ratio, robot attributes, etc.
easyrobw.lib Variable Output: Error, actual joint error,
control signal float *inq_uc()
Control Example see file dyn_user.cpp
parameter, dyn_cntrl_user_1(void **usrptr)
sample time Result Dynamic Link Library Dll er_dyn.dll
in folder .\easy_rob\

Result: er_dyn.dll

Figure API-05: Interfaces for dynamics, position controller

The user defined structure allows the user to store all needed data for this specific
controller (adaptive-, state variable feedback- , force controller, etc.), such as
parameter or status data, which are needed for the next sampling step. When the
routine dyn_cntrl_user_x() is called for the first time, this user pointer is NULL and
allows the user to allocate memory and to defined all initial data settings. In the
next step, EASY-ROB™ will return this pointer, thus all data are availbale for
further calculations.

The right is reserved to make technical changes and improvements

EASY-ROB™ Stefan Anton Bruchfeldstr.4 60528 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info@easy-rob.com www.easy-rob.com

API-Description.doc 5/8 18. Jan. 01

 EASY-ROB™
3D Robot Simulation Tool
Technical Product Description

Application Program Interface (API)

Structure of the dynamic robot model

Prototypes: er_dvlp.h c-header file

Library: easyrobw.lib

Folder: .\easy_rob\er_dvlp\
Control VC++ project er_dyn.dsw
signals for C file: dyn_user.cpp Actual joint position
each joint Functions: int dyn_model_user_1..12
*inq_uc() *inq_q_dyn()
(void **dyn_model_usr_ptr) actual joint speed
Input: Pointer for user defined data structure, *inq_v_dyn()
Control signal from position controller
Model parameter:
gear ratio, robot attributes, etc.
Variable Output: Error, actual joint values:
EASY-ROB float *inq_q_dyn()
Data Base float *inq_v_dyn()
Example see file dyn_user.cpp
Library: dyn_model_user_1(void **usrptr)
easyrobw.lib Result Dynamic Link Library Dll er_dyn.dll
in folder .\easy_rob\
Robot model
parameter,
model
sample time

Result: er_dyn.dll

Figure API-06: Interfaces for dynamics, robot dynamic model

The user defined structure allows the user to store all needed data for this specific
dynamic robot model. This pointer works in the same manner as for the position
controller. Inside the API for the robot model, it is possible to integrate high
sophisticated calculations to solve the inverse dynamic robot model with
consideration of nonlinearities for frictions, coriolis and gravity forces, inertias and
maybe elasticities in the gear boxes. The solution for the complete model can be
solved using Runge Kutta for example.

The right is reserved to make technical changes and improvements

EASY-ROB™ Stefan Anton Bruchfeldstr.4 60528 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info@easy-rob.com www.easy-rob.com

API-Description.doc 6/8 18. Jan. 01

 EASY-ROB™
3D Robot Simulation Tool
Technical Product Description

Application Program Interface (API)

Example for API-INV

Load the robot, "univ_inv.rob" from the .\proj folder.

This robot with 6 rotational

joints is modeled in universal
coordinates. The yellow
colored coorsys show the
active joints. The robot base
position is in the world origin
(green color). The TCP
coorsys is visualized in blue
color. The Tip coorsys is in
white color.
Figure API-07: univ-inv.rob

Menu: Robotics
-> Robot Motion + Kinematics

-> Kinematic Data

will open this Selection Dialog
box. The user is prompted to
Figure API-08: Selection Dialog make a choice.

The transformation from the

st
robot base to the first (1 )
joint of this robot is tranlated
by 0.5m in Y - Direction.
Procedure:
frame T=*inq_bT0(void)
returns the pointer, to read or
modify the values.

Figure API-09: Input Dialog:

The right is reserved to make technical changes and improvements

EASY-ROB™ Stefan Anton Bruchfeldstr.4 60528 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info@easy-rob.com www.easy-rob.com

API-Description.doc 7/8 18. Jan. 01

 EASY-ROB™
3D Robot Simulation Tool
Technical Product Description

Application Program Interface (API)

A selection of
"4 - Inverse Kinematic No"
in the Dialog in Figure API-08
allows the user to choose the
function for the inverse
kinematics solution defined in
er_kin.dll.
"3 - DLL inv. kin #2"
will select function
"inv_kin_user_2(frame *)"

Figure API-10: Selection Dialog for inverse kinematics

Example for API-IPO

Menu: Robotics
-> Robot Motion Planner
-> Ipo Data
will open the Input Dialog to
set the control data for the
motion planner, such as ipo
step size, vq = joint speed,
vx = cartesian speed, joint
acceleration, ov = override,
etc.
Inside the API, you can read
and write all ipo data, using
Figure API-11: Input Dialog for Motion Planner ipo data
the functions:
vq = *inq_ipo_path_vq()
vx = *inq_ipo_path_vx()
ov = *inq_ipo_path_ov_pro()
Menu: Robotics
-> Robot Motion Planner
-> Ipo Joint Code
will open the Selection Dialog
to prompt the user to choose
the function for the user
defined motion planner for the
"Joint" motion type.
This selection will enable the
2 functions,
ipo_jnt_prep_user_1() and
Figure API-12: Selection Dialog for joint motion planner code ipo_jnt_exec_user_1().

The right is reserved to make technical changes and improvements

EASY-ROB™ Stefan Anton Bruchfeldstr.4 60528 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info@easy-rob.com www.easy-rob.com

API-Description.doc 8/8 18. Jan. 01