Help

1.Basics of Dorna operation

In this section you will learn about the geometry and coordinate system of Dorna. Also you will find details about the installation of Dorna and toolheads to it.

1.1.Coordinate system

Dorna is a five-axis robotic arm, with five rotary joints J0 through J4. Each joint has a predefined positive (+) and negative (-) rotary direction.

The blue curved arrows define the positive rotary direction for the associated joint.

So, at any moment the position of the robot and its geometry can be uniquely identified by the values of the five joints (J0, J1, J2, J3, J4).

We can also define the XYZ Cartesian coordinate system for the robot. In this scenario the origin (X=0, Y=0, Z=0) is the center of the bottom plane of the robot (base), where robot touches the ground. After fixing the origin, we set X,Y axis in a manner that they form the bottom plane, while Z axis forms the height.

Another important concept in the robot is the position of the tip of the toolhead of the robot (head). We use two different coordinate systems to identify this position.

(J0, J1, J2, J3, J4) coordinate system

As we mentioned earlier given the values of the five joints as a tuple we can uniquely identify the position of the head of the robot.

To be more precise

  • J0 is the angle between the second arm (L1) and X axis in the XY plane (the rotation of the robot around the Z axis).

  • J1 is the angle between L1 and X axis in the XZ plane.

  • J2 is the angle between L1 and third axis (L2).

  • J3 is the angle between L2 and fourth axis (L3).

  • J4 is the rotation of the fifth axis.

(X, Y, Z, A, B) coordinate system

In this system, X,Y and Z represent the position of the head of the robot in the Cartesian coordinate system and,

  • A is the angle between the tool head and the X,Y-plane (A = J1+J2+J3)

  • B is equal to J4 (B = J4).

1.2.Installation of the arm

You can install and operation Dorna either on the ground or to the ceiling. The base of the robot has four through holes of size 1/4″ (6.35) which can be used with 1/4-20 inch screws or M6 metric screws. 

Make sure the surface is completely flat, firm and sturdy. 

1.3.Installation of toolheads

You can attach different toolheads to the head of Dorna using any combination of the 9 different tapped holes on the head of Dorna. Screw size of 6-32 can be used for attaching toolheads to Dorna. We recommend at least using two screws to securely attach the toolhead.

Please note that:

  1. If you plan to use X,Y,Z coordinate for programming Dorna, you need to update the toolhead length in the software or API after attaching a new toolhead. So, the X,Y,Z coordinate will be calculated based on the new toolhead length.
  2. For most toolheads, it is recommended to install the toolhead after homing the arm so the toolhead does not interfere with the homing operation.

2.Software

In this help section we will provide details about the general functionality of Dorna software.

2.1.Download and installation

You can download the latest version of Dorna software on the software page. After you have installed the downloaded file, launch the application. You will be redirected to a web browser where Dorna software is launched as a web app.

2.2.Robot connection

In order to connect the robot to your computer follow these steps:

  1. Connect the USB cable to the controller box and to the computer. You do not need to turn the controller box on for making a connection.
  2. In the software select tool > Connection.
  3. Select the proper USB port from the menu and click connect. If no USB connection is available, or connection failed try to physically reconnect the USB cable and reconnect again.

2.3.Homing

After USB connection is successfully established between the robot and the software, the robot needs to be homed. The term homing in this context means setting the absolute robot coordinates to a known coordinate. The homing of the robot is achieved one axis at a time and during the process the robot searches for the known position of homing sensors.

Before running the homing process, always put the robot in the rest position:

​Homing steps:

  1. Select Tool > Homing.
  2. There are four homing buttons, one for each joint 1, joint 2 and joint 3, and one for joints joint 3 and Joint 4 together.

  3. Click on Start homing to start the homing process for the joint(s) associated to that button.

Homing usually takes few seconds, during this period, any interrupts such as jogging or running a script will terminate the homing process.

  • If the homing process is successful, then the homing status changes from Not homed to Homed.

  • The robot is homed if all the joints are homed. In this case, a green dot appears on the top left side of the homing icon.

Notice: If for some reason homing process was not successful, disconnect the USB port (physically) from the computer and try to reconnect again. Then follow the homing steps again.

2.4.Calibration

In most cases, when you start working with Dorna for the first time, the value assigned to each joint after the homing process has an offset from the true value of the joint. In this case, we need to calibrate the device and assign the true values to each joint. This is specially important if you plan to work with Dorna in X-Y-Z coordinates as the offset will introduce an error to the X, Y, Z values.

For calibration follow these steps:​

  1. Follow the homing process for all axes. The calibration process does not work if the robot is not homed first.
  2. Move the joints by jogging Dorna at slow speed, to a known position. A typical known position is where all joints are exactly 0 according to the coordinate system of Dorna:You will observe the value that is read for each joint in the software is different from the expected value (which is all zero values in this example). It is because the robot is not calibrated yet.
  3. Select Tool > Calibrate.
  4. Insert the true value of each joint in the respective boxes and click Apply. In the example above, you need to insert zero value for all joints.

From now on, the robot joints will show the true value based on the calibration accuracy. The calibration needs to be done only once. The result of the calibration is saved in a config file inside the software folder and whenever the robot is homed, the calibration values are applied.

If you need to modify the calibration values, you can always repeat the above process.

2.5.Toolhead length

In Dorna software you can update the length of the toolhead (tool length) based on the toolhead that you are using. The correct length of the toolhead is specially important if you work in X-Y-Z coordinate system, and you are interested in X, Y, Z values of the tip of the toolhead. If you are interested in X, Y, Z values of the robot head, or you prefer to work in joint’s coordinates, you might want to leave the toolhead length at its default value.

In order to change the toolhead length:

  1. Select Tool > Toolhead.

  2. Measure the length of the toolhead (L3) and put it in the Tool length box.

  3. Click Apply.

​​

The tool length is calculated in inch, and it is the length between the center of J3 joint and the end of the toolhead.

2.6.Speed and jerk

Max speed

Max speed is the maximum speed of the robot in the joint’s space or in X-Y-Z space. You can change the max speed values in the max speed box.

Max Jerk

Jerk is the rate of change in acceleration which is the third derivative of position as a function of time. Dorna uses a constant jerk motion profile. When a joint starts from zero speed, it uses a constant jerk to accelerate up to a max speed. Then the speed is constant until a deceleration is needed. At that moment, the speed is reduced to zero through a constant jerk which is set by max jerk value.  You can configure the maximum jerk value for any joint in this section. 

Scale

Using the scale sliders,  we can scale both max speed and max jerk. For example, if the max jerk for joint 0 (J0) is set to be 1,000, then by moving the slider on the jerk scale to the 50% the max jerk value for J0 will be 500. 

Notice that the max speed and Jerk is per-joint. Diagonal / multi-joint traverses will actually occur at the fastest speed the combined set of joints and the geometry will allow and may be faster than the individual joints max speeds. For example, if max speed for J0 and J1 are set to 1000 deg/min then, for a 45 degree traverse in J0 and J1 the toolhead would travel at 1414.21 deg/min.

​Also, note that every speed and jerk in the system passes through the scale values. Forex ample, if the sliders set to 0% in the, the robot will not move, no matter how large are the maximum speeds and jerks. 

 

2.7.Inputs and outputs

Dorna provides multiple options for connecting peripherals as input or outputs to the robot. You can write to the outputs or read the input values in the I/O section of the software. Use the Tool > Digital IO panel to control and monitor the I/Os.

Furthermore, you can work with inputs and outputs within the scripts using the appropriate methods.

General purpose digital I/O

Dorna has 4 digital input pins (P1, P2, P3, P4) which are indicated by input1, input2, input3, input4 pins in the software. It also has 4 digital output pins (P5, P6, P7, P8) which are indicated by output1, output2, output3, output4 in the software.

Digital I/O pins voltage level is 3.3V and any voltage higher than 3.3V might damage the controller. The pins have a mode of operation which you can modify in the software.

  • Active high pins are 3.3V when their logical value is 1 and are at 0V when their logical value is 0.
  • Active low pins are 0V when their logical value is 1 and are at 3.3V when their logical value is 0.

Notice that changing the mode for each output, turns off all the outputs, including and the laser.

Servo

You can connect and control a PWM controlled servo to Dorna. Servo motor can be used as the actuator of a gripper or other independent toolheads. Servo connector on the controller box provides a PWM pin, a +6V pin and a GND pin. You can adjust the PWM pin duty cycle and hence the rotation of the servo motor from the I/O panel. Note that the Servo value changes from 0 to 1000, where 0 corresponds to completely open gripper and 1000 corresponds to completely close gripper.

Laser

Laser output pins are connected to a power mosfet that turns on and off a 12V output pin on the controller box. You can use the 12V to turn on and off accessories connected to the controller box. The rated current for the 12V output is 1A.

Stepper

Dorna provides the connection needed for a stepper motor that could be connected to the controller box and can be controlled in coordination with the 5 axes of the robot. In order to connect a stepper motor, you need to add the stepper motor driver of your choice to the controller box. First connect the control pins of the driver to the m6 motor control pins on the controller board. Next, connect the A+A-B+B- pins on the controller board to the corresponding pins of the driver. Finally, provide the DC power of the driver either through the 36V power supply of the controller box, or your own power supply. The extra axis is called j5 axis in joint space or C axis is X-Y-Z space.

2.8.Jogging controls

Jogging

Using the jogging buttons, you can control the robot either in joint’s space or in X-Y-Z space. Jogging speeds and jerks are the max speed and max jerks as specified in the software. Note that scale values will affect the speed and jerk during jogging. 

Go to

By entering the values of your target point, wither in joint’s space or X-Y-Z space, in go to section and hitting go button, the robot will directly move to the target point at maximum speed and maximum jerk values.

 

2.9.Updating firmware

You can directly update the firmware from Update Firmware section in the software. When the process is completed, disconnect and reconnect the USB cable to the computer and connect the software to the robot again. 

If update firmware process failed, try to physically disconnect the USB cable and connect it, and then repeat the process again.

3.Script commands

By using the methods explained in this section, you can write a program to control the robot in the software. The methods define the motion of the robot, or control the I/O pins. These same methods are also used in Python API to write Python scripts for more complex tasks.

You can either directly write the methods in the scripting section of the software, or use the helper functions provided in the software to add the methods easier.

Each method has is written as a JSON string.  The two main keys for each method are “command” and “prm” ({“command”: …, “prm”: …}). The “command” key holds the name of the method, and the “prm” key holds the parameters for that specific method.

In the following subsections we describe each method and its parameters.

3.1.Move

This command moves the robot to a given point in space. During a move command, the robot moves from an initial point (start point), to the end point. The end point positions can be given either in the joint coordinate system or the Cartesian coordinate system format. The path profile can also be in joint space or in Cartesian space. For details of the parameters and format see Dorna Github wiki page.

3.2.Wait for input

This command stops the program and waits for the inputs to match the input pattern. If the pattern appeared then the program proceeds. For details of the parameters and format see Dorna Github wiki page.

3.3.Set IO

This command is sets outputs, mode of inputs and outputs, laser and servo values. For details of the parameters and format see Dorna Github wiki page.

3.4.Sleep

This command suspends execution for the given number of seconds. For details of the parameters and format see Dorna Github wiki page.