Application Program Interface (API)

The Application Program Interface (API) provides the user the ability to develop
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. kinematics robots
lengths, software travel ranges, joint directions, tool frame, TCP location, etc.
Mathematical routines to handle homogeneous transformation matrices are
available as well as trigonometrically 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 Hans-Thoma-Str.26a 60596 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info.er@easy-rob.com www.easy-rob.com
 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 similar 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.

The right is reserved to make technical changes and improvements 2/8

EASY-ROB™ Stefan Anton Hans-Thoma-Str.26a 60596 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info.er@easy-rob.com www.easy-rob.com
 Many 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 3/8

EASY-ROB™ Stefan Anton Hans-Thoma-Str.26a 60596 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info.er@easy-rob.com www.easy-rob.com
 API-DYN - Dynamics

The dynamics option allows considering 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 developing
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 model. Furthermore, a special position controller such as an
adaptive or a robot model 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 user’s requirements.

The right is reserved to make technical changes and improvements 4/8

EASY-ROB™ Stefan Anton Hans-Thoma-Str.26a 60596 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info.er@easy-rob.com www.easy-rob.com
 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 available for
further calculations.

The right is reserved to make technical changes and improvements 5/8

EASY-ROB™ Stefan Anton Hans-Thoma-Str.26a 60596 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info.er@easy-rob.com www.easy-rob.com
 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 elasticity’s 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 6/8

EASY-ROB™ Stefan Anton Hans-Thoma-Str.26a 60596 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info.er@easy-rob.com www.easy-rob.com
 Example for API-INV

Load the robot, "univ_inv.rob" from the /EASY-ROB/ApplicationLib/Kinematics/ 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
-> cRobot Kinematics

-> Kinematics 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 translated
by 500 mm in Y - Direction.
API-function:
frame *bT0 = *inq_bT0(void)
returns the pointer, to read
and write the values.
Figure API-09: Input Dialog:

A selection of
"6 - Inverse Kinematics ID"
in 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

The right is reserved to make technical changes and improvements 7/8

EASY-ROB™ Stefan Anton Hans-Thoma-Str.26a 60596 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info.er@easy-rob.com www.easy-rob.com
 Example for API-IPO

Menu: Robotics
-> cRobot Motion Planner
-> Motion Planner 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
the functions:
vq = *inq_ipo_path_vq()
Figure API-11: Input Dialog for motion planner data vx = *inq_ipo_path_vx()
ov = *inq_ipo_path_ov_pro()

Menu: Robotics
-> cRobot Motion Planner
-> Ipo Joint Code API-IPO
will open the Selection Dialog
to prompt the user to choose
the function for the user
defined motion planner for the
"Joint/PTP" 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 8/8

EASY-ROB™ Stefan Anton Hans-Thoma-Str.26a 60596 Frankfurt/Main Germany Tel. +49 69 677 24-287 Fax. +49 69 677 24-320 info.er@easy-rob.com www.easy-rob.com