Help

Connection

Dorna 2 controller is equipped with a Raspberry Pi 4B computer and Raspberry Pi OS to host a WebSocket server and sends and receives data. The default hostname, username and password for the controller is,

# hostname
dorna

#username
dorna

# password
dorna

SSH has been enabled by default on the controller. For example one can SSH to the robot controller via,

# SSH to the robot
ssh dorna@dorna

You can connect to the controller through Ethernet link or WIFI.

For secure and fast communication link we recommend using Ethernet.


IP address

In order to connect to the robot controller, the IP address of the controller is necessary. There are many methods and online resources discussing this issue. For example, Raspberry PI documentation.

Use display. Connect a display to the controller box, through micro HDMI port on the side of the controller. Open a terminal and simply type hostname -I which will reveal your controller IP address.

Here we discuss to other popular methods to find the robot IP address without a display:

Router devices list. Connect your robot to your router. In a web browser navigate to your router’s IP address e.g. http://192.168.1.1, which is usually printed on a label on your router; this will take you to a control panel. Then log in using your credentials, which is usually also printed on the router or sent to you in the accompanying paperwork. Browse to the list of connected devices or similar (all routers are different), and you should see some devices you recognize. Some devices are detected as PCs, tablets, phones, printers, etc. so you should recognize some and rule them out to figure out which is your robot. Also note the connection type; if your robot is connected with a wire there should be fewer devices to choose from. For example,

# SSH to the robot via its IP address
ssh dorna@192.168.1.9
In this example the controller IP address is: 192.168.1.9

No router. Multicast DNS is supported by the controller. One can directly connect the controller to a computer via Ethernet cable, and use the default hostname.

# SSH to the robot via hostname
ssh dorna@dorna

WebSocket server

The controller WebSocket server runs automatically when the controller is turned on. Connect to the WS server via port 443 of the controller, and its IP address. The WS URL is,

ws://controller_ip_address:443

For example,

# Example 1. Robot IP address is: 192.168.1.9
ws://192.168.1.9:443

# Example 2. Use the robot hostname: dorna
ws://dorna:443

Coordinate system

Dorna 2 is a five-axis robotic arm, with five rotary joints  j0, j1, j2, j3, j4. Each joint has a predefined positive (+) and negative (-) rotary direction.

In the image below, the green curved arrows define the positive rotary direction for the associated joint.
So, at any moment the position, orientation and the geometry of the robot can be uniquely identified by the values of the five joints  (j0, j1, j2, j3, j4).

Positive rotary direction for each joint.

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


Joint coordinate system: (j0, j1, j2, j3, j4)

joint coordinate system

As we mentioned earlier given the values of the five joints we can uniquely identify the orientation 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.

Cartesian coordinate system: (x, y, z, a, b)

cartesian coordinate system

Another important concept in the robot is the position of the tip of the toolhead of the robot (tool center point, or TCP) with respect to the robot base. We use Cartesian coordinate system along with two other parameters to represent this point.

In this system, x, y, z represent the position of TCP in the Cartesian coordinate system and,

  •  a is the angle between the tool head and the XY-plane, i.e.  a = j1 + j2 + j3
  •  b is equal to  j4, i.e.  b = j4

Mounting

Install and operate the robot either on the ground or to the ceiling. The base of the robot has four through holes of size 8.4 which can be used with M8 screws. Make sure that the mounting surface is completely flat, firm and sturdy.

Mounting pattern

Joint limit

Each joint in the robot has a limited range of rotary motion, known as joint limit (upper and lower limits). We use some of these hard limits for homing the robot as well. So, make sure that the robot is not hitting these hard limits, and only touches them when necessary. Hitting these limits with force, can cause physical damage to the robot and harm the homing process.

Notice that, depending on the robot orientation, some additional limits may apply to each joint.

Joint Range of motion Lower limit Upper limit
j0 355 -175 180
j1 270 -90 180
j2 284 -142 142
j3 270 -135 135
j4 Infinite N/A N/A

Setting joints

Setting the robot joints is the process of identifying the real value of the joints and assigning them to the robot. There are multiple hard stops available on the robot and can be used to identify the true value of a joint. In the homing process we put the robot on a specific orientation, where the value of the joints are known to us.

How to home the robot. First, turn off the motors and put the robot in, j0 = 180, j1= 180, j2 = 1-42, j3 = 135, j4 = 0 (this orientation has been depicted below). Make sure that all the joints are are touching their associated hard stop. You can put slight force on top and side of the robot (negative Z-direction and negative Y-direction) to make sure that all the joints are touching their hard stops. Once the robot is in this position, set the joints to.

j0 = 180 
j1 = 180
j2 = -142
j3 = 135
j4 = 0 

Notice that, each time the controller box turned on, or the robot encoder cable is conned to the controller box, we need to set the joints. After setting the joints, the robot maintain its position via encoder, even if the motors are disabled.


Installation of toolheads

You can attach different toolheads to the head of the robot using any combination of the 8 different tapped holes available on the robot flange. There are 4 X M3 and 4 X 6-32 tapped holes available for attaching toolheads. We recommend at least using two screws to securely attach the toolhead.

For most toolheads, it is recommended to install the toolhead after homing the arm so the toolhead does not interfere with the homing process.


Set tool length

When using the robot it is important to define the tool length exactly in the way you are using it in your application.

The tool length is calculated in mm, and is defined by the exact distance between the robot flange frame and the tip of the end effector (along the Z direction).

You can update the tool length based on the toolhead that you are using. The correct tool length value is specially important if you work in the Cartesian coordinate system, and you are interested in (x, y, z, a, b) values of the TCP. If you prefer to work in joint’s coordinates, or you are interested in X, Y, Z values of the robot flange you might want to leave the TCP at its default value (default value is 0).

In the left image the tool length is set to 0 mm (default value), and in the right image the tool length is set to 20 mm.


Inputs and outputs

Dorna provides multiple options for connecting peripherals as inputs or outputs to the robot. You can write to the outputs or read the input values in the I/O section of the software.

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

Type Description
Digital inputs 16 pins (8 in front of the box)
Digital outputs 16 pins (8 in front of the box)
PWM 5 pins (2 in front of the box)
ADC 5 pins

Digital I/O pins voltage level is 3.3V and any voltage higher than 3.3V might damage the controller.


API

Dorna 2 uses a WebSocket based API for communication between the user and the robot controller. After establishing a WebSocket connection via the IP address of the robot, the user and controller will exchange real time commands from user software to the controller and messages from controller to the user software, in order to control the robot and receive its current status. Here, we will go over the set of commands and messages of the API.


Format of commands and messages

Each command that the user sends to the controller and each message that the controller sends to the user is a string in JSON format. The general format of a command / message is as the following:

{"key1" : value1, "key2" : value2, ... , "keyn": valuen}

Where string  "keyi" is the name of the i-th parameter and  valuei is its value.

Notice that the order in which key, value pairs are presented in the command or message is not important.

Each command that is sent to the controller has a required  "cmd" field which specifies the name of the command. Each command can have an optional  "id" field (key) with a positive integer value. The ID is used to follow the status of the command through the messages that are returned to the user. In the following sections, we will describe the set of messages and commands and their corresponding key value pairs.


Messages

Controller sends, multiply type of messages; positionsinputs and command status.


Position

These messages are sent periodically to the user and report the position of the robot in real time with a rate of approximately 30 times a second. Each message has the value of all joints of the robot and Cartesian coordinates of the TCP. In addition to that, each of these messages has the velocity and acceleration of the robot in the space of the motion. Here is an example of such a message:

{"j0":3.4 , "j1":1.2 , "j2":97.3 , "j3":22 , "j4": 32.76 , "j5":0 , "j6":0 , "j7":0 , "x":122.3 , "y":674.3 , "z":95.4 , "a":342 , "b":32.6 , "c":0 , "d":0 , "e":0, "vel":120.43, "accel": 804.11}

Input

These messages are sent upon change in any of the input values and they include the input values of all 16 input pins. Here is an example of such a message:

{"in0":0 , "in1":0 , "in2":1 , "in3":1 , "in4": 0 , "in5":0 , "in6":1 , "in7":0 , "in8":1 , "in9":0 , "in10":1 , "in11":0 , "in12":1 , "in13":0 , "in14":0 , "in15":0}

Command status

These messages report the status of each command that is sent to the controller, from the time that command is submitted, to the time that the execution of the command is completed. These messages will only be sent to the user if the corresponding command has an "id" field with a positive value. The returned message will have the same id as the command itself. An example of such a message is as follows:

{"id":12, "stat":2}

It means that the command with id = 12, is in status = 2. The "stat" field can take different values with the following interpretations:

  • 0: it means that the command has been received by the controller and has no error.
  • 1: it means that the command execution has begun. Note that after commands are received and processed by the controller, they will be submitted to a queue. Depending on the queue type and the position of the command in the queue, the actual execution of the command will be at a later time. When stat 1 is received, it indicates that the command execution has just started by the controller.
  • 2: it means the execution of the command is now completed. Some commands run almost instantly. For those commands there is no delay between receiving stat 1 and stat 2 of the command. For example reading an input value will be executed instantly. However, for some other commands, such as move commands or pause commands, the time that the command starts and the time that the command is completed, are different. Users can use the stat 2 indicator, to sync different events with the completion of certain commands.
  • Negative values: it means that the command has an error and it will not be executed. The stat value represents the type of error that has happened.

Order of processing commands

The robot has two different queues for processing commands; normal priority queue and high priority queue.

Normal priority queue is designed for commands that need to run sequentially and the order matters in their execution, such as move commands.

Sometimes, while executing commands in the normal priority queue, the user needs to issue some higher priority commands that need to be executed immediately upon being received by the controller. For instance, assume that the user needs to halt the robot immediately. In that case if the halt command sits in the same queue as the normal priority commands, it will be executed after all other commands are finished, which is useless. Another use case is reading input values. Sometimes, the user needs an input value of the controller, after a certain command is finished. In that case the read command should be placed after the desired command in the normal priority queue.

There are other instances, where the user needs to read the input value immediately without waiting for completion of other commands in the normal priority queue. In that case, the user has to submit a read input command to the higher priority queue.

Some commands are only assigned to a specific queue by the controller. For other commands, the user has the option to submit them to the normal priority queue or high priority queue. For such commands, the "queue" field specifies the queue of the command. If "queue" is set to 1, the command will be submitted to the high priority queue and will be executed instantly. If "queue" is set to 0, the command will be submitted to the normal priority queue, and will be launched only after all other commands before it are processed.


Commands

Joint move

This command moves the robot from the current point to a new point with a certain speed and acceleration. In this motion the robot moves the joints simultaneously and uniformly to get to the end point.

The joint move provides the fastest way to get from one point to another point, and the motion path forms a line in the joint space.

Key, value pairs

Key Value Required Description
“cmd” “jmove” Yes Moves the robot to a new point on a line path in the joint space.
“id” Int (>0) No Id can be any non negative integer. If id is not provided, status of the command will not be returned from the controller.
“j0”, “j1”, …, “j7”, or “x”, “y”, “z”, “a”, “b”, “c”, “d”, “e” Double Yes The position of the target point. Either you have to use joint representation of the target point by specifying joint values j0, j1, …., j7 or the Cartesian representation by specifying x, y, z, a, b, c, d, e. In joint representation, at least one of the joint values j0, … j7 should be present in the command and their values are in degrees. The joints that are not presented will remain the same after motion is completed. If no joint is present in the command, then the target point should be presented using Cartesian coordinates x, y, z, a, b, c, d, e. In Cartesian coordinate representation, the value of any missing coordinate will not change after the command is completed.
“rel” 0 / 1 No This value specifies if the move command is relative or absolute. If it is set to 0, the move command will be absolute and the joint or Cartesian coordinates in the command will represent the target joint or Cartesian coordinates. Otherwise, the move command will be relative, and the joint or Cartesian coordinates in the command will be added to the current joint or Cartesian coordinates to achieve the target joint or Cartesian coordinates. If this field is not present, the last given value will be used.
“vel” Double (>0) No The maximum velocity in the joint space in degree/second. If this field is not present, the last given value will be used.
“accel” Double (>0) No The maximum acceleration in the joint space in degree / second2. If this field is not present, the last given value will be used.

Example

{"cmd":"jmove", "id":12, "j0":10, "j3":-20, "rel":1, "vel":234}

This command will move j0, 10 degrees and j3, -20 degrees relative to their current position. Other joints will not change. The maximum velocity will be 234 deg/sec and acceleration will be at the last given value. Note that if “rel” is set to 0, then the robot will move to the coordinates, j0 = 10 and j3 = -20.

Error codes

Stat Value
-1 General error
-100 Final position is out of range
-102 Midpoint is out of range for circle
-103 Midpoint is not provided for circle
-104 Velocity coefficient is out of range
-105 Acceleration coefficient is out of range
-106 Jerk coefficient is out of range
-107 Velocity should be positive
-108 Acceleration should be positive
-109 Jerk should be positive
-110 Point out of range on the path
-111 Circle cannot be realized
-300 Halt already in process
-400 Alarm activated

Rapid move

This command is the same as the jmove command, except that the values of speed and acceleration are presented as numbers between 0 to 1 which are the fraction of the maximum value that they can take for the current motion trajectory.

Key, value pairs

Key Value Required Description
“cmd” “rmove” Yes Similar to jmove command
“id” Int (>0) No Similar to jmove command
“j0”, “j1”, …, “j7”, or “x”, “y”, “z”, “a”, “b”, “c”, “d”, “e” Double Yes Similar to jmove command
“rel” 0 / 1 No Similar to jmove command
“vel” Double (>0 and <=1) No The maximum velocity of the motion as fraction of the maximum possible velocity for this motion. If this field is not present, the last given value will be used.
“accel” Double (>0 and <=1) No The maximum acceleration of the motion as fraction of the maximum possible acceleration for this motion. If this field is not present, the last given value will be used.

Example

{"cmd":"rmove", "id":5, "j1":35, "j3":45, "rel":0, "vel":0.3}

This command will move j1 to 35 and j3 to 45. The controller will calculate maximum possible velocity of the motion, which is a function of the maximum speed of motors for joints 1 and 3 and the shape of the trajectory. Then the maximum velocity is set as 0.3 of the maximum possible velocity.

Error codes

Same as jmove command


Line move

This command moves the robot from the current point to a new point with a certain speed, and acceleration on a line in Cartesian space.

Key, value pairs

Key Value Required Description
“cmd” “lmove” Yes Moves the robot to a new point on a line in Cartesian space.
“id” Int (>0) No Similar to jmove command
“j0”, “j1”, …, “j7”, or “x”, “y”, “z”, “a”, “b”, “c”, “d”, “e” Double Yes Similar to jmove command
“rel” 0 / 1 No Similar to jmove command
“vel” Double (>0) No The maximum velocity in the Cartesian space in mm/second. If this field is not present, the last given value will be used.
“accel” Double (>0) No The maximum acceleration in the Cartesian space in mm/second2. If this field is not present, the last given value will be used.

example

{"cmd":"lmove", "id":12, "x":5, "y":12, "rel":1, "vel":100}

This command will move the toolhead, x coordinate 5mm and y coordinate 12mm at velocity 100 mm/s. Notice that the target point can be given either in joints or Cartesian coordinates.

Error codes

Same as jmove command.


Circle move

This command moves the robot toolhead on a circle from a starting point to a final point by passing through a midpoint, for a number of turns with a certain speed and acceleration. An optional parameter “space”, specifies whether the circle is drawn in Cartesian space (default) or in joints space. Another optional parameter “dim”, defines the dimension of the circle. If dim is set to k, only the first k coordinates will form the circle and the remaining coordinates will move on a line that connects the initial point and final point. As a result only the first k dimensions are important for the mid point of the circle. The default value of dim is 3, which draws a planar circle in x,y,z space.
Positions of a circle can be given in joint space or in Cartesian space. Also they can be either relative or absolute depending on the parameter “rel”. In relative mode, all positions are relative to the starting point of the circle.

Key, value pairs

Key Value Required Description
“cmd” “cmove” Yes Moves the robot toolhead on a circle in Cartesian or joint space.
“id” Int (>0) No Similar to jmove command
“j0”, “j1”, …, “j7”, or “x”, “y”, “z”, “a”, “b”, “c”, “d”, “e” Double Yes Similar to jmove command
“mj0”, “mj1”, “mj2”, “mj3”, “mj4”, “mj5”, “mj6”, “mj7” or “mx”, “my”, “mz”, “ma”, “mb”, “mc”, “md”, “me” Double Yes The coordinates of a midpoint on the circle. The circle will connect the current position to the target position by passing through the midpoint. Note that only the first dim (default = 3) coordinates of the midpoint matter in making the circle.
“turn” Int (>=0) No Number of turns of the circle. If not present, the default value of 0 is used. For any number of turns larger than 0, the robot will make the additional complete turns before stopping at the target point.
“dim” Int (>0) No Determines the dimension of the circle. If it is not present the default value of 3 is used.
“space” 0 / 1 No If space is 0, the circle will be in joint space. If the space is 1, the circle is in Cartesian space. If it is not present the default value of 1 is used.
“rel” 0 / 1 No If rel is set to 0, both midpoint and target point are interpreted as absolute coordinates. If rel is set to 1, both midpoint and target point values are treated relative to the initial point of the circle. If this field is not present, the last given value will be used.
“vel” Double (>0) No The maximum velocity on the circle. If this field is not present, the last given value for a move command will be used.
“accel” Double (>0) No The acceleration on the circle. If this field is not present, the last given value will be used

Example

{"cmd":"cmove", "id":15, "x":10 "y":10, "mx":6 , "my":8, "mz":130, "turn":2, "rel":0}

This command will move the toolhead, on a circle that starts from the current position and passes mx = 10, my = 8 and mz = 130 point. And it will stop at x = 10, y = 10, and z, a, b, c, d, e values will be the same as the initial point. The robot will make two extra full turns since turn = 2.

Error codes

Same as jmove command.


Halt

This command will force the robot to stop the motion immediately by decelerating from the current speed to zero speed. All remaining commands in the queue of the robot will also be deleted. Until the halt motion is completed, no new command except the “alarm” command (see “alarm” section), will be accepted by the robot.

The halt motion by default uses the same deceleration as the original move command acceleration that is being stopped by the halt command. However, using parameter “accel” (default is 1), the user can increase the deceleration rate. If the “accel” parameter is present, the controller will stop the motion by deceleration rate which is the “accel” parameter of the halt command multiplied by the “accel” parameter of the original command. This will help the robot to decelerate faster during emergency halt commands.

Key, value pairs

Key Value Required Description
“cmd” “halt” Yes Halts the robot by decelerating to zero speed.
“id” Int (>0) No Similar to jmove command
“accel” Double (>=1) No If present, the robot will decelerate to zero speed by deceleration rate which is the “accel” times the original command “accel” parameter. Otherwise, the robot will decelerate with the deceleration value equal to the original move command acceleration parameter. Note that this parameter cannot be less than 1.

example

{"cmd":"halt", "id":1, "accel":7.5}

Immediately after receiving this command, the robot will decelerate at the rate of 7.5 * accel to full stop, where accel is the parameter value from the original move command.

Error codes

Stat Value
-1 General error
-2 Accel value provided is not valid
-300 Halt already in process
-400 Alarm activated

Alarm

While in motion, if the robot hits into an obstacle such that the motors can no longer follow the designated path, the robot will go into an alarm state. In the alarm state, all commands that are already submitted to the controller, will be deleted and the existing motion command will be immediately suspended and the robot will abruptly stop its motion. No new commands will be accepted by the controller, until an alarm clearing command is first issued to the robot by the user. The user has to clear any obstacle on the motion of the robot before clearing the alarm. After the alarm is cleared, the robot will run new commands as usual.
In addition to accidents that will force the robot into the alarm mode, the user can also manually send an alarm command to the robot, which will cause exactly the same behavior from the robot. For instance, if the user can detect an obstacle that will hit the robot shortly, and the time or distance to the obstacle is not large enough for a halt command to operate properly, the user can send an alarm command. When the robot receives the command, it will stop the motion immediately, without proper deceleration, and will remove all commands from its queues. A subsequent alarm command is needed to clear the existing alarm state of the robot.

Key, value pairs

Key Value Required Description
“cmd” “alarm” Yes Forces the robot into an alarm state or clears an already existing alarm state.
“id” Int (>0) No Similar to jmove command
“accel” 0 / 1 No If alarm has value 1, the robot will be forced into alarm mode. If the value is 0, the existing alarm will be cleared. If it is not present, the current value of alarm will be returned.

Example

{"cmd":"alarm","alarm":0}

This command will clear the alarm state of the robot. It has to be issued after the robot enters the alarm state.

Response

Key Value Description
“cmd” “alarm”  
“alarm” 0 / 1 The value of alarm. 0 means that the system is not in alarm state, and 1 means that the system is in alarm.
“id” Int (>0) Same id as the original command.

Example

If the user sends the following command

{"cmd":"alarm","id":7}

This command will return the value of the alarm. For example:

{"cmd":"alarm","alarm":0, "id": 7}

Error codes

None


Sleep

With this command, the controller sleeps for the number of seconds specified in the command. It can be used to create delay between execution of motion commands or other commands in the normal priority queue as it executes in a normal priority queue in the same order that it was received by the controller.

Key, value pairs

 

Key Value Required Description
“cmd” “sleep” Yes Sleep between motions.
“id” Int (>0) No Id can be any non negative integer. If id is not provided, status of the command will not be returned from the controller.
“time” Double(>0) Yes Time is the amount of delay in seconds.

Example

{"cmd":"sleep", "time":5}

After finishing all commands before this command, the robot waits for 5 seconds, before starting the next command.

Error codes

Stat Value
-21 Time field is missing or invalid
-300 Halt already in process
-400 Alarm activated

Input

This command will read the value of all the inputs. The command by default will report the input values immediately. However, by setting the queue value to 0, the user can send the command to the normal priority queue, where the input values will be reported after all other commands before it are concluded.

Key, value pairs

Key Value Required Description
“cmd” “input” Yes Read input values.
“id” Int (>0) No Id can be any non negative integer. If id is not provided, status of the command will not be returned from the controller.
“queue” 0 / 1 No If the value is 0, the command will be submitted to the normal priority queue. Otherwise, it will be submitted to the high priority queue. The default value 1.

Response

Key Value Description
“cmd” “input”  
“id” Int (>0) Same id as the original command.
“in0”, “in1”, …, “in15” 0 / 1 The value of each input.

Example

{"cmd":"input", "id":5}

This command will read the input values and will respond with a message as follows which specifies the current value of each input pin.

{"cmd":"input", "id":5, "in0":0 , "in1":0 , "in2":1 , "in3":1 , "in4": 0 , "in5":0 , "in6":1 , "in7":0 , "in8":1 , "in9":0 , "in10":1 , "in11":0 , "in12":1 , "in13":0 , "in14":0 , "in15":0}

Error codes

Stat Value
-300 Halt already in process
-400 Alarm activated

Probe

This command will match the input values with the pattern that the user specifies. Whenever such a pattern appears at the input pins, the controller will send a response which is the value of each joint at the time that the match happens. This command could be useful for homing an actuator with a sensor connected to an input pin. Note that the controller will only send the response after the first match happens and consequent matches won’t be responded. This command by default will be submitted to the high priority queue. By setting queue value to 0, the command will be submitted to the normal priority queue.

Key, value pairs

Key Value Required Description
“cmd” “probe” Yes Match input values with a given pattern.
“id” Int (>0) No Id can be any non negative integer. If id is not provided, status of the command will not be returned from the controller.
“in0”, “in1”, …, “in15” 0 / 1 No Probe command will wait until the value of each input that has a key in the command matches its value. If an input key is not present, its value wont impact the match.
“queue” 0 / 1 No If the value is 0, the command will be submitted to the normal priority queue. Otherwise, it will be submitted to the high priority queue. The default value 1.

Response

Key Value Description
“cmd” “input”  
“id” Int (>0) Same id as the original command.
“j0”, “j1”, …, “j7” Double The value of each joint when the pattern matches.

Example

{"cmd":"probe", "id":11, "in4":0, "in7":1}

This command will wait until the input 4 value is 0 and input 7 value is 1. Then it will send a message that includes the values of all joints at that moment.

{"cmd":"probe", "id":11, "j0":12.3, "j1":2.11, "j2":85, "j3":653.4, "j4":56.34, "j5":67.32, "j6":23.74, "j7":90.00}

Error codes

Stat Value
-300 Halt already in process
-400 Alarm activated

 

Output

This command will set the values of the output pins. The response will include the value of all outputs. The default queue for this command is a high priority queue. If the queue parameter is set to 0, then the command will be submitted to the normal priority queue.

Key, value pairs
Key Value Required Description
“cmd” “output” Yes Sets the output values.
“id” Int (>0) No Id can be any non negative integer. If id is not provided, status of the command will not be returned from the controller.
“out0”, “out1”, …, “out15” 0 / 1 No If any outi is present as a key, the value of the corresponding output will be set to the given value.
“queue” 0 / 1 No If the value is 0, the command will be submitted to the normal priority queue. Otherwise, it will be submitted to the high priority queue. The default value 1.

Response

Key Value Description
“cmd” “output”  
“id” Int (>0) Same id as the original command.
“out0”, “out1”, …, “out15” 0 / 1 The value of each output.

Example

{"cmd":"output", "out0":1, "out2":0, "id":5}

This command will set out0 to 1 and out2 to 0 and will return all output values.

{"cmd":"output", "id":5, "out0":1 , "out1":0 , "out2":0 , "out3":1 , "out4": 0 , "out5":0 , "out6":1 , "out7":0 , "out8":1 , "out9":0 , "out10":1 , "out11":0 , "out12":1 , "out13":0 , "out14":0 , "out15":0}

Error codes

Stat Value
-300 Halt already in process
-400 Alarm activated

PWM

This command will enable and disable pwm pins and will set their duty cycle and frequency to the desired values. The default queue for this command is a high priority queue. If the queue parameter is set to 0, then the command will be submitted to the normal priority queue. In response to this command, the state of all PWMs will be returned.

Key, value pairs

 

Key Value Required Description
“cmd” “pwm” Yes Sets the pwm parameters.
“id” Int (>0) No Id can be any non negative integer. If id is not provided, status of the command will not be returned from the controller.
“pwm0”, “pwm1”, “pwm2”, “pwm3”, “pwm4” 0 / 1 No If pwmi = 0, it will disable ith pwm pin. If pwmi = 1, it will enable ith pwm pin. If pwmi is not given as a key, its state won’t change.
“duty0”, “duty1”, “duty2”, “duty3”, “duty4” Double(>=0 and <=100) No If dutyi is present as a key, duty cycle of the ith pwm will be set to its value which is the percentage of the period that the pwm will be on.
“freq0”, “freq1”, “freq2”, “freq3”, “freq4” Double(>=0 and <=120,000,000) No If freqi is present as a key, frequency of the ith pwm pin will be set to its value.
“queue” 0 / 1 No If the value is 0, the command will be submitted to the normal priority queue. Otherwise, it will be submitted to the high priority queue. The default value 1.

Response

Key Value Description
“cmd” “pwm”  
“id” Int (>0) Same id as the original command.
“pwm0”, “pwm1”, “pwm2”, “pwm3”, “pwm4” 0 / 1 Indicates if each pwm pin is enabled or disabled.
“duty0”, “duty1”, “duty2”, “duty3”, “duty4” Double(>=0 and <=100) Indicates the duty cycle of each pwm pin.
“freq0”, “freq1”, “freq”, “freq3”, “freq4” Double (>= 0 and <= 120,000,000) Indicates the frequency of each pwm pin.

Example

{"cmd":"pwm", "id":10, "pwm0":1, "pwm2":0, "freq0":125}

This command will set the frequency of pwm0 to 125Hz and enable it. It will also disable pwm2. The response will have information about all pwm pins.

{"cmd":"pwm", "id":10, "pwm0":1, "pwm1":0, "pwm2":0, "pwm3":1, "pwm4":0, "duty0":5, "duty1":2, "duty3":32, "duty4":9, "freq0":125, "freq1":320, "freq2":450, "freq3":1200, "freq4":100}
Error codes
Stat Value
-300 Halt already in process
-400 Alarm activated
-601 Duty parameter is out of range
-602 Freq parameter is out of range

ADC

This command will read the value of all adc pins. The default queue for this command is a high priority queue. If the queue parameter is set to 0, then the command will be submitted to the normal priority queue.

Key, value pairs

Key Value Required Description
“cmd” “adc” Yes Reads ADC pins.
“id” Int (>0) No Id can be any non negative integer. If id is not provided, status of the command will not be returned from the controller.
“queue” 0 / 1 No If the value is 0, the command will be submitted to the normal priority queue. Otherwise, it will be submitted to the high priority queue. The default value 1.

Response

Key Value Description
“cmd” “adc”  
“id” Int (>0) Same id as the original command.
“adc0”, “adc1”, “adc2”, “adc3”, “adc4” Int(16 bit) Value of adc pins as a 16 bit integer.

Example

{"cmd":"adc", "id":1}

The response will include the value of all adc pins.

{"cmd":"adc", "id":1, "adc0":0, "adc1":33, "adc2":10, "adc3":0, "adc4":0}

Error codes

Stat Value
-300 Halt already in process
-400 Alarm activated

Joint

This command will set the joints values to the values given in the command. This command is always submitted to the high priority queue and upon being received by the controller, all other commands in the controller queue will be deleted. This command is particularly useful at the beginning of robot operation to set the joint values to some default values depending on the position of the robot. The return value from the controller will be the value of all the joints of the robot after the new values are applied. This command can be used to read the current value of joints if it is used with no joint input.

Key, value pairs

Key Value Required Description
“cmd” “joint” Yes Sets the joints values to the values provided in the command.
“id” Int (>0) No Id can be any non negative integer. If id is not provided, status of the command will not be returned from the controller.
“j0”, “j1”, …, “j7” Double No The value of each joint. If a joint is not present, its value will not change by the command.

Responce

Key Value Description
“cmd” “joint”  
“id” Int (>0) Same id as the original command.
“j0”, “j1”, …, “j7” Double The value of all joints will be returned.

Example

{"cmd":"joint","id":1, "j3":37.5, "j2":29}

This command will set the j2 and j3 values to the given values and return all joints values:

{"cmd":"joint","id":1, "j0":0, "j1":30.22, "j2":29, "j3":37.5, "j4":90.0, "j5":0, "j6":0, "j7":0}

Error codes

None


Motor

This command is used to turn the motors on and off. The user can turn motors off to either save power while the robot is not operational or to place the robot in a predetermined location as a homing process, or to hand train the robot by moving it to different locations manually and saving the positions of those points. Please note that when the motors are off, the robot still tracks positions of the motors, and as soon as the motors are on again, the motors can continue receiving motion commands. This command is submitted to the high priority queue. In response to this command the state of the motors is returned. This command without parameters can be used to read the current state of the motors.

Key, value pairs

Key Value Required Description
“cmd” “motor” Yes Turns motors on or off.
“id” Int (>0) No Id can be any non negative integer. If id is not provided, status of the command will not be returned from the controller.
“motor” 0 / 1 No 0 will turn motor off and 1 will turn it on. If this parameter is not present,

Response

Key Value Description
“cmd” “joint”  
“id” Int (>0) Same id as the original command.
“motor” 0/1 1 if the motors are on or 0 otherwise.

Example

{"cmd":"motor","id":1, "motor":1}

This command will turn on all the motors:

{"cmd":"motor","id":1, "motor":1}

Error codes

None


Tool length

With this command you can read or set the toolhead length. For accurate readings of x, y, z coordinates of the robot, the toolhead length should be set to the correct value. The response returned from the controller, is the toolhead length. This command always runs in the high priority queue and upon being received by the controller, all other commands in the controller will be deleted.

Key, value pairs

Key Value Required Description
“cmd” “toollength” Yes Changes the toolhead length.
“id” Int (>0) No Id can be any non negative integer. If id is not provided, status of the command will not be returned from the controller.
“toollength” Double(>0) No Toolhead length in mm. If this parameter is not present, the current value of the toollength will be returned and other commands in the controller wont be removed.

Response

 

Key Value Description
“cmd” “toollength”  
“id” Int (>0) Same id as the original command.
“length” Double (>0) The current value of the toolhead.

Example

{"cmd":"toollength","id":1, "toollength":22}

This command will set the toolhead length to 22mm. It will return a response as follows:

{"cmd":"toollength","id":1, "toollength":22}

Error codes

Stat Value
-300 Halt already in process
-400 Alarm activated
-701 Toolhead length is not Valid