Configuration


In this tutorial, we will go over Dorna’s configuration file. Some of the main parameters that describe the robot’s behavior are stored in the configuration file.

The configuration file is formatted in YAML. YAML is a human-readable language and can be used in many applications where data is being stored. The configuration file is called config.yaml, and it is located in the main directory of the API.

Below is config.yaml. Give it a quick look, and then we will review the parameters.

# =================================================================
# unit
# =================================================================
unit: 
  # inch or mm
  length: "inch"

# =================================================================
# axis
# =================================================================
axis: 
  # number of axes: 5 or 6
  number: 5

# =================================================================
# speed
# =================================================================
default_speed:
  xyz: 100
  joint: 1000

# =================================================================
# jerk
# =================================================================
default_jerk:
  xyz: [50 , 50, 50, 300, 300, 300]
  joint: [300, 300, 300, 300, 300, 300] 

# =================================================================
# Calibration
# =================================================================
calibrate:
  j0: 0
  j1: 145
  j2: -90
  j3: 0
  j4: 0

# =================================================================
# Toolhead
# =================================================================
toolhead:
  # length of the toolhead is based on the unit
  x: 1.74

# =================================================================
# limit
# =================================================================
# all values are in deg
limit:
  # j0: [j0 minimum, j0 maximum]
  j0: [-175.0, 175.0]
  # j1: [j1 minimum, j1 maximum]
  j1: [-175.0, 160.0]
  # j2: [j2 minimum, j2 maximum]
  j2: [-130.0, 130.0]

# =================================================================
# Motion 
# =================================================================
motion:

  # Junction Integration Time
  # jt:0.01 Lower limit - probably will fail
  # jt:0.75 Good value for slower machines
  # jt:1.00 Nominal value
  # jt:1.20 Good value for fast machines
  # jt:5.00 Upper limit. Absolutely will fail 
  jt: 1

  # Path control mode
  # gpa: 0 Exact path mode, gpa:1 Exact stop mode, gpa:2 Continuous mode
  gpa: 2

  #Chordal tolerance in mm
  ct: 0.01   

Axis


The axis parameter stores the number of axes for the robot. Dorna is a 5-axis robotic arm, and by default, the number of axis is set to 5. However, using a toolhead with an additional degree of freedom, or mounting Dorna on a rail, would increase the number of axes to 6. Note, the only valid values for the axis parameter are 5 or 6.

Key Value Notes
number 5 or 6 Number of axes in the robot

Unit


The unit parameter sets the length unit system for the robot. By setting the unit system, every quantity with that dimension will be interpreted in that unit system, unless otherwise specified. For example if the length unit system is set to mm, then every quantity with the distance dimension will be interpreted in mm.

Key Value Notes
length "mm" or "inch" length unit system, default is inch

Limit


The limit parameter sets the rotary limit for the three joints, j0, j1 and j2. If a joint has a rotary limit [a , b], then that joint can not go above b degrees, and below a degrees. So, setting the limits is a very helpful way to make sure that the robot will not crash into itself. Here are the keys and the associated values.

Key Value Notes
j0 [j0_lower_limit, j0_upper_limit j0_lower_limit < j0_upper_limit
j1 [j1_lower_limit, j1_upper_limit j1_lower_limit < j1_upper_limit
j2 [j2_lower_limit, j2_upper_limit j2_lower_limit < j2_upper_limit

Calibrate


This parameter holds the calibration values for the joints j0, j1, j2, j3 and j4. By running the calibration and saving the values in a config file, we make sure that the joints always return the true values after homing process. The available keys and values are:

Key Value
j0 The calibration value for joint j0 in degrees.
j1 The calibration value for joint j1 in degrees.
j2 The calibration value for joint j2 in degrees.
j3 The calibration value for joint j3 in degrees.
j4 The calibration value for joint j4 in degrees.

Toolhead


It is necessary to adjust the length of the toolhead every time we change the toolhead. This parameter holds the length of the toolhead:

Key Value Notes
x toolhead_length The length is given in the robot length unit system

Default Speed


This parameter holds the default speed for the robot during a motion. There are two types of default speed:

  • joint: The default speed of the robot in the joint space, and is given in degrees per minute. This means it will be used only if the "path" parameter in a "move" command is equal to "joint".
  • xyz: The default speed of the robot in the Cartesian (xyz) space, and is given in the robot length unit system per minute. This only applies to the cases where the "path" parameter in a “move” command is equal to "xyz".
Key Value Notes
joint joint_default_speed deg / min
xyz xyz_default_speed length unit / min

Default Jerk


This parameter keeps the default jerk for the robot during a motion. The jerk values are usually very large, and the values here are divided by 1,000,000. Jerk is defined is the rate of change of acceleration. Like default speed, there are two types of default jerk:

  • joint: The default jerk of the robot in the joint space as an array (list) of size 5, and each element in the array is given in deg per minutes^3. The default joint jerk only applies to the situation where the "path" parameter in a "move" command is equal to "joint". The 5 elements in the array represents the default jerk for the 5 joints j0 to j4, respectively.
  • xyz: The default jerk of the robot in the Cartesian (xyz) space as an array (list) of size 5. The xyz default jerk only applies to the situation where the "path" parameter in a "move" command is equal to "line". The 5 elements in the array represents the default jerk for the 5 axes x, y, z, a and b, respectively. The first 3 axes x, y and z are given in the robot length unit per min^3, and the last 2 axes a and b are given in degree per min^3.
Key Value Notes
joint [j0_jerk, j1_jerk, j2_jerk, j3_jerk, j4_jerk] deg / min^3
xyz [x_jerk, y_jerk, z_jerk, a_jerk, b_jerk] length unit / min^3

Motion


This section keeps some of the motion parameters. Note that the values in congig.yaml are the suggested default values. Only change these values if necessary.

  • jt: Also known as the junction integration time is a key to set cornering velocity limits. jt is a normalized scaled factor that is normally set to 1.000. Set to less than 1 for slower cornering (less aggressive), greater than 1 (but probably less than 4) for more aggressive cornering.
  • ct: Also known as the chordal tolerance. Arcs are generated as sets of very short straight lines that approximate a curve. Each line is a “chord” that spans the endpoints of that segment of the arc. Chordal tolerance sets the maximum allowable deviation between the true arc and straight line that approximates it – which will be the value of the deviation in the middle of the line / arc. Setting chordal tolerance high will make curves “rougher”, but they can execute faster. Setting them smaller will make for smoother arcs that may take longer to execute. The default value is 0.01 mm.
  • gpa: Path control mode is a parameter to tell the robot how to behave at the end of each path. There are 3 modes for gpa. 0is the exact path mode (G61), 1 is the exact stop mode (G61.1), and 2 is the continuous mode (G64).
Key Value Notes
jt jt_value min: 0.01, max: 5, default: 1
ct ct_value default: 0.01 mm
gpa 0 = exact path, 1 = exact stop, 2 = continuous Path control mode

Editing the Configuration File


If you’d like to edit the values in the configuaration file, it’s best to use the methods provided in the API. Editing config.yaml directly is not advised because some of the parameters are interconnected. For instance, if you use the API to change the unit from inch to mm, the API will edit all of the entries with a length unit to the appropriate value in mm.

Here is a summary of those methods:

Method Notes
.config() Return the robot configuration object in a JSON object format.
.save_config(save_path = None) Write and save the robot configuration object into a YAML format configuration file located at save_path.
.axis() Return the number of axes in the robot in a JSON object format.
.set_axis(prm) Set the number of axes in the robot.
.unit() Return the unit system of the robot in a JSON object format.
.set_unit(prm) Set the unit system of the robot.
.limit() Return the robot joints limits information in a JSON object format.
.set_limit(prm) Set the joints limits of the robot.
.toolhead() Return the dimension of the toolhead in a JSON object format.
.set_toolhead(prm) Set the dimension of the toolhead.
.default_speed() Return the default speed of the robot in a JSON object format.
.set_default_speed(prm) Set the default speed of the robot.
.default_jerk() Return the default jerk of the robot in a JSON object format.
.set_default_jerk(prm) Set the default jerk of the robot.
.motion() Return the motion parameters of the robot in a JSON object format.
.set_motion(prm) Set the motion parameters of the robot.