;------------------------------------------------------------------------
;
;  E A S Y - R O B  Robotic Simulation Tool
;
;                   Stefan Anton
;
;  Version 1.0 Copyright c 1996 - All Rights Reserved
;
;  internet: 100744.135@compuserve.com
;
;  http://ourworld.compuserve.com/homepages/stefan_anton
;
;------------------------------------------------------------------------
;
;  M A N U A L . T X T
;
;------------------------------------------------------------------------

Contents

0. Preface
1.  User Panel and System files
2.  Input menue windows
3.  Output windows
4.  Load and save Tools, Robots, Cells etc.
5.  Modify and save the world view
6.  3D-CAD System
7.  Create a robot program
8.  Load and run a robot program
9.  Joint Recording
10. Create a robot kinematics
11. Robot kinematic in universal coordinates and
    DH notation
11.1 Passiv Joints
11.2 Universal coordinates
11.3 Denavit Hartenberg (DH) parameter
12. User defined inverse kinematics

Questions and Answers

;------------------------------------------------------------------------
0. Preface

Dear User,

This manual is a Quick Reference Manual with the goal to give you
an introduction, how to use EASY-ROB.

You can get a detailed manual with mathematical background if you want.

Before continuing reading this file, I suggest to read the README.TXT
first.


;------------------------------------------------------------------------
1. User Panel and System files

When you start EASY-ROB a floor in wire frame appears. In its middle
a green coorsys shows the world coorsys. This location has the coordinates
p= {0, 0, 0}. At the bottom line you can start an action by mouse click.
Click with the left mouse button. 

The bottom line looks like,

 -1 +1 -2 +2 -3 +3 -4 +4 -5 +5 -6 +6 AX KART HYBR ADJ. MENUE EXIT -+*_

If you like to know more about every function in this line press the <F1> key. 
A help window with case sensitive help appears. This information is in the 
file help.hlp.

The best way to start is to get an overview about existing files, the meaning
of there extensions, syntax, etc.

Your "main" directory (\EASY_ROB\ recommended) contains documentation
files (*.txt), help files (*.hlp), configuration files (*.dat) and the 
executable file easyrobx.exe plus needed DLL's, drivers, etc.

The tool, robot, cell, etc. files are located in an other (your project 
directory, \MY-PROJ\ is the default directory). I suggest you create for every 
project a specific directory and a configuration file with the path for this directory.

Example:

The first line of your configuration file looks like
WORKDIR = c:\EASY_ROB\new_proj
when the created directories name is .\new_proj.

To use your new configuration file, maybe with the name new_proj.dat, you
have to start EASY-ROB by 

easyrobx.exe new_proj.dat  ...That's all

Following files belong to a project:

*.tol  contains the robots tool and graphic information
*.rob  contains the robot and tool and graphic information
*.vie  contains view information
*.prg  contains a robots program
*.rec  contains joint values for a robot
*.bod  contains graphic of the environment (body)
*.cel  contains tool, robot, body and view information and the name of
       robots program and its recording filename.

The contents of all files is in ASCII, so it is easy to change these files
with an editor.

Use your preferred editor.

The configuration file gives you the possibility to specify your
preferred editor.

EDIT = my_edit

You can edit all files in your project directory from EASY-ROB.

1. Select the  'MENUE'  from bottom line
2. Select  'Miscellaneous'  from "selection menue window"
3. Select  'edit sys-files'  from "selection menue window"

Now select and edit the file you want, for example your
configuration file.

For further explanations step 1 to 3 is abbreviated by the sequence
MENUE -> Miscellaneous -> edit sys-files -> config file.

If you like to edit a robot file, you have to load a robot before, go

MENUE -> Load -> Robot -> *.rob file.


The best thing to do now is to try this with EASY-ROB to get a better feeling for 
it and return to this manual.


--->  1st  TRAINING  <---


Everything works OK ? That's fine. (if not, don't worry)


;------------------------------------------------------------------------
2. Input menue windows

In general the user panel consists of a bottom line, where you can start
an action by mouse click, and 5 types of windows and the On-line help
with the <F1> key at any time.


1st Window type, "selection menue window"
A selection menue window prompts you to select a file, a configuration, 
etc. by mouse click.


2nd Window type, "toggle menue window"
A toggle menue window prompts you to switch s.th. ON or OFF like
the TCP Trace or everything in wire frame, etc. The colour for
ON is green, for OFF is red. You have to click "quit" or  press enter 
to continue your work with this new settings.


3rd Window type, "real_value menue window"
A real_value menue window prompts you to enter a value. The range for
the value is also given. If your value is outside of these bounds the value
is rejected. If no bounds given, you are allowed to give every value.
Go with the Up and Down Arrow to the next value. Press enter to 
continue your work with these new values.


4th Window type, "string menue window"
A string menue window prompts you to enter a string.. Not all characters
are allowed. If you save your robot for example in a '*.rob' file the 
current path and the filename appears in this menue. 
With the Left Arrow you delete the last character. With the Right Arrow
you go step by step through this string to the right. In case of
save a file the correct extension is appended automatically.
Go with the Up and Down Arrow to the next string. 
Press enter to continue your work.


5th Window type, "confirm menue window"
A confirm menue window prompts you to confirm an action. You
will asked to overwrite an exiting file, etc.


;------------------------------------------------------------------------
3. Output windows

EASY-ROB has an 'information' and a 'status' output window. You will
notice that a message in one of these windows disappears immediately.
If you like to see the 5 last messages go

MENUE -> Miscellaneous -> display status messages
or
MENUE -> Miscellaneous -> display info messages

After displaying these messages your are asked, "delete messages ?"

NOTE: All messages are saved in the current monitoring file MONI.MSG


- On line output of the robots joint values and position data.
This output appears on the left side of your screen. To switch this 
output window ON go

MENUE ->  Miscellaneous -> Switch on off -> Show joint & position data


- Program window
When running a robot's program, a program output window appears at
the bottom of your screen. You can switch this window  ON or OFF by

MENUE ->  Miscellaneous -> Switch on off -> Show Program Window

or use an ERC (Easy Rob Command) in your program
ERC PRG_WIN ON/OFF.


;------------------------------------------------------------------------
4. Load and save Tools, Robots, Cells etc.

Load the table cell, go

MENUE -> Load -> Cell -> table.cel file.

The  table is loaded now and consists of a tool, robot, robot program, 
joint recording and the environment the table (bodies). In this situation
you can load another robot or tool or program or recording or bodies.
The current one is superseded then. You can save this cell with
maybe a new robot or new tool or new base location of the robot in
a new cell file, go

MENUE -> Save -> Cell -> my_cell file.

A cell saves the current view, the current loaded program and
the current loaded joint recording file name.

It is also possible to unload a robot and a program and save only
the rest.


;------------------------------------------------------------------------
5. Modify and save the world view

The button name is 'ADJ.' (adjustment). Click this button and a new
bottom line appears.

In this mode you can rotate, translate the world in different coorsys.
The best is you start EASY-ROB, go to this point and press the
 <F1> Key for on-line help. Try each action, you will see what happens

If you found a nice view for your cell, you can save the current view in a 
*.vie file, go

MENUE -> Save -> View -> my_view.vie.

You are also able to load an existing view, go

MENUE -> Load -> View -> select a *.vie file

You can load a view with the ERC LOAD VIEW my_view inside
a program. This is very useful.


;------------------------------------------------------------------------
6. 3D-CAD System

EASY-ROB is a 3D graphic and animation tool for robotic simulation.
A simple 3D-CAD System is provided to modify and create simple
bodies like a block, cylinder, pyramid, spheres, etc.

Go MENUE -> 3D CAD System

Important is that you always work with a current body. If you
create a new one, this is then the current one. To see, which is
the current body, switch the coorsys on, see below > 3D CAD 
coorsys ON/OFF.

In this 3D CAD System you have 3 Groups. Each group contains
a number of bodies.

Tool  - grp
Robot - grp
Body  - grp is default

Explanation of each function:

>Select   a Group
- select a group for 3D CAD manipulation

>Select   a Body from Group
- select a body from current group for 3D CAD manipulation

>Create new Body
- create a new body. This body is appended to the current group
  You are prompted to select a body type and to enter the
  geometric data. If the robot group is selected you have
  to give an 'ax_idx' value. This value specifies the joint
  number where this new body is attached to.
  Press enter to continue your work with new data.

>Modify selected Body
- modifies the geometric data of current body.
  A real_value menue window appears and prompts you to 
  enter new geometric values. Press enter to continue your
  work with new data.

>Grab/Release Body to/from Robot Tip
- grab or release current body to/from the robot's tip

>Clone
- clone the current body with its attributes.
  User is prompted to enter how much clones he likes to have
  and a delta lengths for the location.
  The name of each body got a prefix 1 ... n.
Example:
Suppose you created a block, this block is located at
p= {0, 0, 0} at the world base coorsys. Now you clone this
block, 3 clones, enter for X = 0.5 [m] and for RotZ = 90 [deg].
Try this....
What happens is that every delta position for the clone is
related to its 'say' parent clone.

The clone function speeds up the creation process.

>Render
- modify the render of current body.
  Available renders are Flat and Wire.

>Colour
- modify the colour of current body.

>Name
- modify the name of current body.
  You have to enter a new name in a string menue window

>Clear
- clear current body after confirmation

>Clear   all Bodies in Group
- clear all Bodies in Group after confirmation

>Save   all Bodies
- save all Bodies in a body file *.bod

>Translate Rotate all Bodies
- translate and rotate all bodies reference positions
  with respect to the world coorsys. 
  Try this function, give 90deg about X axis,
  you will see what happens.

>Reference Position
- modify the reference position of current body.
  The reference position is related to the world coorsys.
  It's the same function like before, but for one (current) body.
  Try this function, give 90deg about X axis,
  you will see what happens.

>Position
- modify the position of current body.
  The position is related to the reference position.
  Try this function, give 90deg about Z axis or Y axis,
  you will see what happens. This give the bodies final location.
  A bodies final location in the world is
  body_location = Reference_Position * Position

> relative Position
- shift the position by the relative Position
  The new position is
  position = position * relative_position

>Move body by mouse
- You can move the current selected body with the mouse

>3D_CAD coorsys ON/OFF
- 2 coorsys are displayed
  1th gives the location of the reference position
  2nd gives the location of the body

>quit
- quit this menue


;------------------------------------------------------------------------
7. Create a robot program

Load one Robot first. Move the robot to a location you like.
Open a program stream, go

MENUE -> Robot Program -> create New Program

You are prompted to enter a filename, the extension (*.prg) is 
appended automatically.

Now save the current configuration of the Robot, go

MENUE -> Robot Program -> save config

When you edit this program (the current created program)
it will contain following 3 lines

PROGRAMFILE
! prgfln path\fln.prg 
config 1

To edit this program, go

MENUE -> Robot Program -> Edit   current created Program
It is possible to modify this program, for example
! this is my first program or
; this is also a comment


To save the robots location as PTP, go

MENUE -> Robot Program -> save PTP

Following program line is appended

PTP   0.5  0.0  0.3968     0.0   105.0     0.0
its 0.5m in X, 0.3968m in Z and 105deg about Y axis.


Move the robot to another location and save it 
as LIN , go

MENUE -> Robot Program -> save LIN
Following program line is appended

LIN   0.4  0.0  0.3968     0.0   105.0     0.0
X in now 0.4m. for example.

Now close the program, go

MENUE -> Robot Program -> Close  current Program

Following line is appended
ENDPROGRAMFILE


Print out the "Quick Programmers Reference Manual" to have an
overview about all program commands.

To run that program, you have to load it first, see next chapter.


;------------------------------------------------------------------------
8. Load and run a robot program

Load a program, go

MENUE -> RUN -> Load Program -> select program from list

Run the loaded program, go

MENUE -> RUN -> Run Program

That's all


;------------------------------------------------------------------------
9. Joint Recording

To create a Joint Recording file you have to open a stream, go

MENUE -> Save -> Joint Recording

You are prompted to enter a file name and
enter a number for example 3 if only every 3rd value has to
be saved.

Now move the robot in joint and or Cartesian space or run
a program. At every graphic simulation update the joint values
of the robot are saved to this recording file. You can close the
joint recording file , go again

MENUE -> Save -> Joint Recording

You are asked if you like to create a new one, ... 'say' no.

For a reanimation of a recording file you have to load
it first and run it. Go

MENUE -> Run -> Load Joint Recording -> select from list

Run the recording, go

MENUE -> Run -> Run Joint Recording

Syntax of a recording file:

q: joint1 joint2joint3joint4joint5joint6

If you have an own simulation program which generates the 
joint values, for example path planner, dynamics, etc., you
can create such a Joint Recording File and you will
have a 3D graphic animation of your movement, suppose
you designed your robot before.


;------------------------------------------------------------------------
10. Create a robot kinematic

The best way  to create a robot kinematic is to load an
existing robot file and modify its data.

Example:

The standard kinematic with kin_type=RRR:RRR and kin_id=1
is explained here. (see robot file robot.rob)

The first lines in this file are,

ROBOTFILE
! robotfln c:\bc4work\simrob\ROBOT.rob
name        Robot
kin_id      1
kin_type    RRRRRR
num_configs 8
kin_dof     6

Each robot file starts with the keyword ROBOTFILE, followed by 
a comment where this file is located on your Hard disk.
Important is the kin_id, in this case it is 1 and the kin_type according
to the kin_id. The number of possible configurations are 8 and the number
of DOFs are 6 for this robot.

The next few lines are,

! lz
lengths          0.5000     0.5000     0.7310     0.0000     0.0000     0.1000
! lx
offsets1         0.0000     0.0000     0.0000
! ly
offsets2         0.0000     0.0000     0.0000

this means vector l1 = {0, 0, 0.5}, l2 = {0, 0, 0.5} and l3 = {0,0, 0.731}.
Vector l1 gives the translation (x y z) from the coorsys fixed to joint 1 to
joint 2, etc. See also the graphic file kin.gif. If this sounds complicate,
start EASY-ROB, load this robot and switch the Robot coorsys 
and the wire frame ON, go

MENUE -> Miscellaneous -> switch_on_off -> Robot coorsys
MENUE -> Miscellaneous -> switch_on_off -> Wire frame

now you can see all the yellow robot joint coorsys.

To change the kinematic z-lengths an offsets-lengths, go

MENUE -> Robot Motion & Data -> Robot Kinematic data

a "real_value menue window" appears and prompts you to modify
the z-lengths and offsets-lengths.

If you enter for the offset lengths l1x = 0.2m for example, you
will see that joint 2 is shifted by 0.2m in x direction related to 
joint coorsys 1. Try this with other values.

Joint offsets: j_off_1 ... j_off_6:
The joint offsets determine the zero position of the robot.
Give 90 deg for j_off_3 and move the robot to 0 deg in all
joints. You see what happens. 

enter the robot file, go
MENUE -> Miscellaneous -> edit sys-files -> robot

move all joints to zero, go
MENUE -> Robot Motion & Data -> Robot Joint Position

Change the joint direction to positive or negative:

If you like to move joint 1 for example positive you can
modify the direction when you edit this robot file. Find
following line,

! sign
verpolt           1      1      1      1      1      1

and change it to

! sign
verpolt          -1      1      1      1      1      1

If you move joint 1 in positive direction again, you will notice
that the direction is changed. (verpolt is German language).

The robots file contains also graphic information. Use the
3D CAD System to create the graphic for your new robot.
Don't forget to switch the wire frame mode to OFF.

;------------------------------------------------------------------------
11. Robot kinematic in universal coordinates and
    DH notation

These two types of robot definition allow you to create
nearly every robot kinematic chain. In both cases you can
define at maximum 12 DOFs. These 12 DOFs called
activ joints in the kinematic chain of the robot. Passiv joints are 
inside (between two activ joints for example) or outside the 
kinematic chain. You can have 12 of them. A passiv joint can
have a mathematical dependency to an activ joint (coupling).
For complicated mathematical dependencies you can
use the md_f1() ... mdf12() functions in the inv_user.c file. 
Take a look to the template "uni_tmpl.cel".

;------------------------------------------------------------------------
11.1 Passiv Joints
Switch the robot coorsys ON and you will see that the coorsys
for activ Joints are yellow and the coorsys for the passiv joints
are green.

MENUE ->  Miscellaneous -> Switch on off -> Robot Coorsys to ON

When you define a passiv joint, you are asked for the Type and 
the Direction first.

The Type is translational 'T' or rotational 'R'
The  Direktion is X,Y or Z for the universal robot and always Z for DH

After this, you have to specify the chain type. A passiv joint could be
inside the kinematic chain 'C' or ouside '_'.

After this, you have to specify where this passiv joint is attached to.
  Each passiv joint is attached to an activ joint
  If more passiv joints are attached to one activ joint
  and they are inside the kinematic chain, then the
  2nd. passiv joint for example is attached to the first
  passiv joint, the 3rd passiv Joint is attached to the
  2nd..
If your robot has 3 DOF or 3 activ joints, your passiv joint could be
attached to activ joint 0 (this is the robot base) or to one of the
3 activ joints. The passiv joint is inserted after the activ joint.

After this, you can specify a mathematical dependency to an activ joint.
Enter '+1' has the effect that this passiv joint will move (T or R) by the 
joint value of the activ joint number 1.Enter '-2'  has the effect that it 
moves by the negative joint value of activ joint number 2. Enter 'f1' does 
mean, that it uses the mathematic formula in function md_f1() in file
inv_user.c. The formula in md_f1() is user defined and could be for
example: -3*sin(q[0])+2*cos(q[1]) or whatever.

Finally you have to define the geometric data. This is the transformation
to the next (passiv or activ) joint. If your robot is a DH type, you have
to enter the theta, d, a, alfa parameter. If your robot is a universal
type you have to enter X,Y,Z,RotX, RotY and RotZ.

On-line Help is available at any time with the <F1> Key.

;------------------------------------------------------------------------
11.2 Universal coordinates
When you define an additionally robot axis, you are prompted
to specify if this axis translates in X,Y or Z, or if this axis rotates
about X,Y or Z. After this, you are asked for the geometric data. This 
is the transformation (X,Y,Z, RotX, RotY and RotZ) to the next 
activ or passiv joint. A 'universal' robot type can have 12 DOFs.

;------------------------------------------------------------------------
11.3 Denavit Hartenberg (DH) parameter
When you define an additionally robot axis, you are prompted
to specify if this axis translates Z, or if this axis rotates about Z
direction. After this, you are asked for the theta, d, a and alfa 
 values. The result of these four values is the same like the
'geometric data' from the universal robot type.

Translation: Tz(x+theta) * Tz(d) * Tx'(a) * Rx'(alfa)
Rotation:    Rz(q+theta) * Tz(d) * Tx'(a) * Rx'(alfa)

;------------------------------------------------------------------------
12. User defined inverse kinematics

File '.\ER_DVLP\inv_user.c' contains an example for the inverse 
kinematic routine for a standard RRR:RRR robot type with 8 
configurations. With the functions inv_kin_user_1(frame *T) and 
inv_kin_user_2(frame *T), you have two possibilities at the same time.

About 50 exported functions from the EASY-ROB base program 
allows you to access all kinematic robot data like the universal
and the DH parameter for the activ and passiv joints, and some 
useful math routines to multiply homogenous T-matrices or build
the invers of them, and a lot more functions. The prototypes are
defined in er_dvlp.h.

int _export inv_kin_user_1(frame *T) 
{
   return(WARN_OK);
}

frame T is the transformation from the robots base to the robots tip.
Type frame consists of the four 3 dimensional vectors
n - normal
o - orientation
a - approach
p - position.

If you have programed a new inv. kinematic function, you have to 
compile inv_user.c and build the er_kin.dll. For this you have to run 
the makefile er_kin.mak.

This makefile is generated with Borland C/C++ V4.02.
To run the makefile you have to type in at DOS prompt,

make -f er_kin.mak

or run the batch file

make_dll.bat.

Before you run the makefile, you have to make sure that
the pathes in your makefile are correct.

#
# set EASY-ROB Development Path
#
EASY_ROB_DVLP = ..\er_dvlp
This path determines where your inv_user.c is located.

#
#set target path for er_kin.dll
#
EASY_ROB = ..
This path determines where the result (er_kin.dll) is written to.
(.. means one up, it should the directory EASY_ROB where 
the program easyrobx.exe is located)

#
#set path for Borland C programs, Librarys and System Headers
#
#BC4_BIN = c:\bc4\bin
#BC4_LIB = c:\bc4\lib
#BC4_INC = c:\bc4\include
BC4_BIN = $(EASY_ROB_DVLP)\bc_bin
BC4_LIB = $(EASY_ROB_DVLP)\bc_lib
BC4_INC = $(EASY_ROB_DVLP)\bc_inc

Each of the directory \bc_bin, \bc_lib and \bc_inc contains a *.doc
files. This file gives information about the needed Borland C programs.

If a Borland C Compiler is already installed on your computer, you 
have to specify the path where the compiler is located (c:\bc4\ in my case).
Important: The (dos) path  must set to his directory. If not, program
16stub.exe is missed.

If you have any problem with it, contact me per email.

If you have another C-compiler, try it, maybe it works.

;------------------------------------------------------------------------
Questions and Answers

at the moment no Questions and no Answers.