rozum robotics Pulse User manual

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 2 | 52
TABLE OF CONTENTS
WARNING SIGNS AND THEIR MEANINGS......................................................................... 4
1GENERAL DATA ................................................................................................................ 5
Glossary .................................................................................................................................. 6
2ENABLING ACCESS TO API............................................................................................ 8
3DESCRIPTION OF API FUNCTIONS.............................................................................. 9
3.1 Requests to get parameters and states of the arm (GET)........................................... 9
3.1.1 Getting the actual arm position................................................................................. 9
3.1.2 Getting the actual motion status.............................................................................. 10
3.1.3 Getting the actual status of servo motors................................................................ 11
3.1.4 Getting the actual arm pose..................................................................................... 12
3.1.5 Getting actual tool properties.................................................................................. 13
3.1.6 Getting the actual tool shape................................................................................... 14
3.1.7 Getting the actual position of the arm base............................................................. 15
3.1.8 Getting the arm ID .................................................................................................. 16
3.1.9 Getting the signal level on a digital output............................................................. 16
3.1.10 Getting the signal level on a digital input............................................................... 17
3.1.11 Getting data about obstacles in an arm environment.............................................. 18
3.1.12 Getting data about a specific obstacle in the arm environment.............................. 21
3.1.13 Getting the hardware versions of the arm components........................................... 24
3.1.14 Getting the software versions of the arm components............................................ 24
3.1.15 Getting the arm version........................................................................................... 25
3.2 Requests to set parameters, states, and actions (PUT, POST)................................. 26
3.2.1 Setting a new arm position...................................................................................... 26
3.2.2 Setting a new arm pose........................................................................................... 28
3.2.3 Asking the arm to open the gripper......................................................................... 29
3.2.4 Asking the arm to close the gripper........................................................................ 30
3.2.5 Asking the arm to relax........................................................................................... 31
3.2.6 Asking the arm to go to the freeze state.................................................................. 31
3.2.7 Asking the arm to move to a pose........................................................................... 32
3.2.8 Asking the arm to move to a position..................................................................... 34
3.2.9 Setting high signal level on a digital output............................................................ 36

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 3 | 52
3.2.10 Setting low signal level on a digital output............................................................. 37
3.2.11 Recovering the arm after an emergency ................................................................. 38
3.2.12 Adding an obstacle to the arm’s environment ........................................................ 38
3.2.13 Setting the arm into a transportation pose............................................................... 41
3.2.14 Quitting the untwisting mode.................................................................................. 42
3.2.15 Setting tool properties............................................................................................. 43
3.2.16 Setting the tool shape.............................................................................................. 45
3.2.17 Setting a new zero point position............................................................................ 46
3.3 Requests to delete parameters of the arm (DELETE).............................................. 47
3.3.1 Removing all obstacles from the arm environment................................................ 47
3.3.2 Removing a specific obstacle from the arm environment ...................................... 48
ANNEX 1. RESPONSE/ REQUEST SCHEMAS.................................................................... 49
Position schema....................................................................................................................... 49
Pose schema............................................................................................................................. 49
Motor status array schema .................................................................................................... 49
Tool info schema ..................................................................................................................... 50
Tool shape schema .................................................................................................................. 50
Obstacle schema...................................................................................................................... 51
Version schema........................................................................................................................ 52

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 4 | 52
WARNING SIGNS AND THEIR MEANINGS
Below are the warning symbols used throughout the manual and explanations of their meanings.
The sign denotes important information that is not directly related to safety, but that the
user should be aware of.
The sign indicates important safety precautions the user should follow.

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 5 | 52
1GENERAL DATA
The REST Application Programming Interface (API) described in this reference guide implements
the functionality for monitoring and controlling motion of the PULSE robotic arm (also, robotic
arm or arm) and its work tool (also, tool).
API requests are in the JSON format; API responses are in the JSON and/or in the plain text format.
All returned values are either double numbers or text strings.
API access for reading and writing motion parameters is based on the HTTP (v 2.0) methods listed
in Table 1-1.
Table 1-1:Supported HTTP methods
Method
Purpose
GET
to get the actual pose / position of the robotic arm (rotation angles and coordinates
of its joints)
to get the actual state of the robotic arm (e.g., idle)
to get the actual state of the servo motors in the arm joints (e.g., voltage, rotor
velocity)
to get actual properties (e.g., rotation angles, position coordinates) and shape of
the work tool
to get the actual position of the arm base (rotation angles and coordinates)
to get the unique identifier (ID) of the robotic arm
to get the signal level (HIGH or LOW) on a digital output
to get the signal level (HIGH or LOW) on a digital input
to get data about a single or all obstacles within the arm environment
to get data about the hardware versions of the arm components
to get data about the software versions of the arm components
to get data about the arm version
PUT
to set/change the pose/position of the robotic arm (rotation angles and
coordinates of its joints)
to set/change the arm state (e.g., relax or freeze)
to open the gripper
to close the gripper
to set the signal level on a digital output to HIGH or LOW
to recover the arm after an error
to add an obstacle to the robot environment for collision detection
to finish untwisting and quit the untwisting mode
to set the arm into the transportation pose
POST
to set properties (e.g., rotation angles, coordinates) and shape of the work tool
to set a new position (rotation angles and coordinates) of the arm base
DELETE
to remove a single or all obstacles from the arm environment

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 6 | 52
Glossary
Table 1-2 lists and defines essential terms used throughout the reference guide.
Table 1-2:Essential REST API terms
Term
Definition
Axis
An axis is a moveable structural component of the PULSE robotic arm
comprising a servomotor to enable its rotation. In all, the PULSE robotic
arm includes six axes located on the robotic arm as illustrated below:
Zero point
It is the origin point for measuring distances along the x, y, and z
coordinate axes. Its original physical location is at the center of the arm
base as shown below.
It is possible to change the zero point location using the
POST/Base request (see Section 3.2.16).

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 7 | 52
Tool center point
(TCP)
It is the point, relative to which all arm poses, positions, and movements
are defined. Its original physical location is at the center of the arm wrist
as shown below.
Using the POST/tool/info request (see Section 3.2.15), you
can relocate the TCP to any position within the tool or
beyond it.

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 8 | 52
2ENABLING ACCESS TO API
You have to enable API access at least once at first switching.
Before you attempt to enable API control, the PULSE arm should be:
connected to the control box, the work tool, the emergency button
connected to a local network
connected to a power supply
switched on and ready for operation
For connection and switching instructions, refer to HARDWARE INSTALLATION
MANUAL.
To enable API control of the PULSE arm, follow the instructions below:
1. Check that the arm is ready for operation. The green LED on the control box should be
constantly on, and the LED on the arm wrist should be steady green.
2. Start the PULSE DESK user interface as described in the USER MANUAL.
3. In the displayed starting screen of the PULSE DESK interface, click the Main Menu button.
4. In the displayed menu, select Configure. PULSE DESK displays the Configure screen.
The Configure screen

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 9 | 52
5. In the Configure screen, switch the Enable remote API access toggle to the enabled state.
Disabled state
Enabled state
6. Click Apply to confirm.
Now, you can proceed to work with available API functions.
3DESCRIPTION OF API FUNCTIONS
The section describes in detail the REST API functions you can use to control the PULSE robotic
arm and its work tool (a gripper), as well as to monitor the arm's motion parameters.
3.1 Requests to get parameters and states of the arm (GET)
3.1.1 Getting the actual arm position
Path:
GET/position
Description: The function returns the actual position of the PULSE robotic arm, which is
described as a set of x, y, and zcoordinates, as well as roll, pitch, and yaw rotation angles. The
coordinates define the actual distance (in meters) from the zero point of the robotic arm to the tool
center point (TCP) along the x, y, and zaxes accordingly. Roll stands for the TCP rotation angle
around the xaxis; pitch—the TCP rotation angle around the yaxis; yaw—the TCP rotation angle
around the zaxis. All rotation angles are in radians and relative to the zero point.
Related REST API functions: PUT/position, PUT/positions/run
Response content type: application/json, text/plain
Response body:
HTTP status code
Response schema/ type
200 OK
Position schema
500 Internal Server Error
String
503 Service Unavailable
String
Response examples:
200 OK
{
"point": {
"x": 0.3,
"y": -0.4,
"z": 0.2
},
"rotation": {
"roll": 3.14,
"pitch": 0,
"yaw": 0.5
}
}

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 10 | 52
500 Internal Server Error
"Robot does not respond"
503 Service Unavailable
"Robot unavailable in emergency state"
3.1.2 Getting the actual motion status
Path:
GET/status/motion
Description: The function returns the actual state of the robotic arm. Possible arm states are as
follows:
IDLE
The arm is not in motion, but is fully functional and ready for operation.
ZERO_GRAVITY
The arm is in the zero gravity mode, which means the user can move it by hand to set a
motion trajectory.
RUNNING
The arm is in motion.
MOTION_FAILED
Motion is impossible due to incorrect motion settings.
ERROR
The arm stops moving due to an error and goes into the freeze mode, retaining its last position.
The user can recover the arm, using the PUT/recover function.
EMERGENCY
Motion is impossible due to an emergency. In this case, an emergency is a fatal failure that
causes the control box to switch off and the arm to stop without retaining its position. Recovery
with the PUT/recover function is not possible.
Response content type: text/plain
Response body:
HTTP status code
Response schema/ type
200 OK
String enum: [IDLE, ZERO_GRAVITY, RUNNING,
MOTION_FAILED, EMERGENCY, ERROR]
500 Internal Server Error
String
503 Service Unavailable
String
Response examples:
200 OK
"IDLE"
500 Internal Server Error
"Robot does not respond"
503 Service Unavailable
"Robot unavailable in emergency state"

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 11 | 52
3.1.3 Getting the actual status of servo motors
Path:
GET/status/motors
Description: The function returns the actual states of the six servo motors integrated into the joints
of the robotic arm. The states are described as an array of six objects—one for each servo motor.
Each object includes the following properties:
Angle—the actual angular position (degrees) of the servo's output flange
Rotor velocity—the actual rotor velocity (RPM)
RMS current—the actual input current (Amperes)
Phase current—the actual magnitude of alternating current (Amperes)
Supply voltage—the actual supply voltage (Volts)
Stator temperature—the actual temperature (degrees C) as measured on the stator winding
Servo temperature—the actual temperature (degrees C) as measured on the MCU PCB
Velocity setpoint—the user-preset rotor velocity (RPM)
Velocity output—the motor control current (Amperes) based on the preset velocity
Velocity feedback—the actual rotor velocity (RPM)
Velocity error—the difference between the preset and the actual rotor velocities (RPM)
Position setpoint—the user-preset position of the servo flange (degrees)
Position output—rotor velocity (RPM) based on the position setpoint
Position feedback—the actual position of the servo flange (degrees) based on the encoder
feedback
Position error—the difference between the preset and the actual positions of the servo flange
(degrees)
Response content type: application/json, text/plain
Response body:
HTTP status code
Response schema/ type
200 OK
Motor status array schema
500 Internal Server Error
String
503 Service Unavailable
String

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 12 | 52
Response examples:
200 OK
[
{
"angle": 168.89699,
"rotorVelocity": -0.00064343837,
"rmsCurrent": 0.01,
"voltage": 47.795017,
"phaseCurrent": 0.01,
"statorTemperature": 27.990631,
"servoTemperature": 31.739925,
"velocityError": -0.022674553,
"velocitySetpoint": -0.02331799,
"velocityOutput": 0.01,
"velocityFeedback": -0.00064343837,
"positionError": 0.0385437,
"positionSetpoint": 168.93799,
"positionOutput": 0.01,
"positionFeedback": 168.89944
}
]
The example is one object containing properties for a single servo. In reality, the array
in the response includes six similar objects.
500 Internal Server Error
"Robot does not respond"
503 Service Unavailable
"Robot unavailable in emergency state"
3.1.4 Getting the actual arm pose
Path:
GET/pose
Description: The function returns the actual pose of the robotic arm. An arm pose is a set of output
flange angles (in degrees) of the six servos in the arm joints.
Response content type: application/json, text/plain
Related REST API functions: PUT/pose, PUT/poses/run
Response body:
HTTP status code
Response schema/ type
200 OK
Pose schema
500 Internal Server Error
String
503 Service Unavailable
String

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 13 | 52
Response examples:
200 OK
{
"angles": [
61,
-98,
-122,
-49,
89,
-28
]
}
500 Internal Server Error
"Robot does not respond"
503 Service Unavailable
"Robot unavailable in emergency state"
3.1.5 Getting actual tool properties
Path:
GET/tool/info
Description: The function returns actual properties of the last tool preset by the user, in particular:
name —any random name of the work tool defined by the user (e.g., “gripper”).
actual TCP position, including:
point —x, y, and zcoordinates defining the TCP offset (in meters) along the x, y, and z
axes accordingly from its original location.
rotation angles —roll, pitch, and yaw. Roll stands for the actual TCP rotation angle
around the xaxis; pitch—the actual TCP rotation angle around the yaxis; yaw—the
actual TCP rotation angle around the zaxis. All rotation angles are in radians and
relative to the physical center point of the arm base.
Related REST API functions: GET/tool/shape, POST/tool/info, POST/tool/shape
Response content type: application/json, text/plain
Response body:
HTTP status code
Response schema/ type
200 OK
Tool info schema
500 Internal Server Error
String
503 Service Unavailable
String

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 14 | 52
Response examples:
200 OK
{
"name": "gripper",
"tcp": {
"point": {
"x": 0,
"y": 0,
"z": 0.31
},
"rotation": {
"roll": 0,
"pitch": 0,
"yaw": 0
}
}
}
500 Internal Server Error
"Robot does not respond"
503 Service Unavailable
"Robot unavailable in emergency state"
3.1.6 Getting the actual tool shape
Path:
GET/tool/shape
Description: The function returns the actual properties defined by the user for a specific tool to
describe the tool shape, in particular:
radius —radius of the work tool (in meters) measured from its physical center point.
begin —the start x, y, and zcoordinates of the work tool capsule measured as a distance
(in meters) along the corresponding axes from the original TCP.
finish —the end x, y, and zcoordinates of the work tool capsule measured as a distance
(in meters) along the corresponding axes from the original TCP.
Related REST API functions: GET/tool/info, POST/tool/info, POST/tool/shape
Response content type: application/json, text/plain
Response body:
HTTP status code
Response schema/ type
200 OK
Tool shape schemaTool info schema
500 Internal Server Error
String
503 Service Unavailable
String

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 15 | 52
Response examples:
200 OK
{
"shape": [
{
"radius": 0.03,
"begin": {
"x": 0,
"y": 0,
"z": 0
},
"endPoint": {
"x": 0,
"y": 0,
"z": 0.24
}
}
]
}
500 Internal Server Error
"Robot does not respond"
503 Service Unavailable
"Robot unavailable in emergency state"
3.1.7 Getting the actual position of the arm base
Path:
GET/base
Description: The function returns the actual position of the arm's zero point in the user
environment. The actual zero point position is described as a set of x, y, and zcoordinates, as well
as roll, pitch, and yaw rotation angles. The coordinates define the offset (in meters) from the
physical center point of the arm base (original zero point) to the actual zero point position along
the x, y, and zaxes accordingly. Roll stands for the rotation angle around the xaxis; pitch—the
rotation angle around the yaxis; yaw—the rotation angle around the zaxis. All rotation angles are
in radians and relative to the physical center point of the arm base.
Related REST API functions: POST/base
Response content type: application/json, text/plain
Response body:
HTTP status code
Response schema/ type
200 OK
Position schema
500 Internal Server Error
String
503 Service Unavailable
String

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 16 | 52
Response examples:
200 OK
{
"point": {
"x": 0.3,
"y": -0,4,
"z": 0.2
},
"rotation": {
"roll": 3.14,
"pitch": 0,
"yaw": 0.5
}
}
500 Internal Server Error
"Robot does not respond"
503 Service Unavailable
"Robot unavailable in emergency state"
3.1.8 Getting the arm ID
Path:
GET/robot/id
Description: The function returns the unique identifier (ID) of the robotic arm. The ID is an
alphanumeric designation that consists of individual servo motor identifications.
Response content type: text/plain
Response body:
HTTP status code
Response schema/ type
200 OK
String
500 Internal Server Error
String
503 Service Unavailable
String
Response examples:
200 OK
"1346466AFG872"
500 Internal Server Error
"Robot does not respond"
503 Service Unavailable
"Robot unavailable in emergency state"
3.1.9 Getting the signal level on a digital output
Path:
GET/signal/output/{port}

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 17 | 52
Description: The function returns the actual signal level on the digital output specified in
the {port} parameter of the request path.
ATTENTION! SPECIFYING THE {port} PARAMETER IS MANDATORY!
A digital output is a physical port on the back panel of the control box. Since the control box has
two digital outputs, the parameter value can be either 1 (corresponds to Relay output 1) or
2 (corresponds to Relay output 2).
The function returns either of the following values:
LOW—default user-defined state (e.g., LED off)
HIGH—change of the user defined state (e.g., LED on)
For location of digital outputs, refer to the Hardware Installation Manual.
Related REST API functions: PUT/signal/output/{port}/high, PUT /signal/output/{port}/low
Response content type: text/plain
Response body:
HTTP status code
Response schema/ type
200 OK
string enum: [HIGH, LOW]
412 Precondition Failed
String
500 Internal Server Error
String
503 Service Unavailable
String
Response examples:
200 OK
"HIGH"
412 Precondition Failed
"Unable parameter value {13}"
500 Internal Server Error
"Robot does not respond"
503 Service Unavailable
"Robot unavailable in emergency state"
3.1.10Getting the signal level on a digital input
Path:
GET/signal/input/{port}
Description: The function returns the actual signal level on the digital input specified in the {port}
parameter of the request path.
ATTENTION! SPECIFYING THE {port} PARAMETER IS MANDATORY!
A digital input is a physical port on the back panel of the control box. Since the control box has
four digital inputs (DI), the parameter can have any integral value between 1 (corresponds to DI1)
and 4 (corresponds to DI4).

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 18 | 52
The function returns either of the following values:
LOW—default user-defined state
HIGH—change of the user defined state
For location of digital outputs, refer to the Hardware Installation Manual.
Response content type: text/plain
Response body:
HTTP status code
Response schema/ type
200 OK
string enum: [HIGH, LOW]
412 Precondition failed
String
500 Internal Server Error
String
503 Service Unavailable
String
Response examples:
200 OK
"HIGH",
"LOW"
412 Precondition Failed
"Unable parameter value {13}"
500 Internal Server Error
"Robot does not respond"
503 Service Unavailable
"Robot unavailable in emergency state"
3.1.11 Getting data about obstacles in an arm environment
Path:
GET/environment
Description: The function returns data about all obstacles preset within the arm’s environment.
An obstacle is any object, such as a control box or a wall, in the way of an arm to be taken into
consideration for collision detection. An obstacle can be one of the following types:
BOX—typically used to describe obstacles with a shape reminding that of a box.
CAPSULE—preferred for objects of cylindrical shape or having complex structure and
irregular outlines. To describe an obstacle of complex structure, it is possible to use
multiple capsules.
PLANE—recommended for describing plain-surface objects, such as a wall or a table.
Depending on the total quantity of obstacles preset in a given environment, the response of the
function can contain one or more data arrays. Each array comprises the following data:
Obstacle type—a geometric pattern, roughly describing the shape of an obstacle for
collision detection purposes—BOX, CAPSULE, and PLANE.

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 19 | 52
Name—any random name as defined by the user for a specific obstacle type (e.g.,
“first_box”).
Obstacle properties—spatial location and/or dimensions of a specific obstacle.
Each obstacle type has its own set of properties as described in the table below.
Type
Properties
BOX
-sides—the x, y, and z coordinates defining the dimensions of an obstacle
(i.e., length, width, depth).
-position—a set of the x, y, and z coordinates, as well as roll, pitch and yaw
angles defining the location of an obstacle in space.
The coordinate values are distances (in meters) along the x, y, and z axes
accordingly, measured from the obstacle’s center point relative to the zero
point (see Glossary).
Roll, pitch and yaw are rotation angles (in radians) of the obstacle’s center
point relative to the zero point.
CAPSULE
-radius—the radius (in meters) of the capsule shape incorporating an
obstacle, measured from the obstacle’s center point
-start point—the starting x, y, and z coordinates (in meters) of the capsule
shape length relative to the zero point
-end point—the end x, y, and zcoordinates (in meters) of the capsule shape
length relative to the zero point
PLANE
-points—at least three points constituting a single plane; each of the points
is described as a set of x, y, and zcoordinates (in meters) on the plane
Related REST API functions: GET/environment/{obstacle}, PUT/environment,
DELETE/environment, DELETE/environment/{obstacle}
Response content type: application/json, text/plain
Response body:
HTTP status code
Response schema/ type
200 OK
Obstacle schema
500 Internal Server Error
String
503 Service Unavailable
String

ROZUM ROBOTICS API REFERENCE GUIDE
Rev.6, valid from Q2 2019
Page 20 | 52
Response examples:
200 OK
[
{
"obstacleType": "BOX",
"name": "example_box",
"sides": {
"x": 0.1,
"y": 0.1,
"z": 0.1
},
"position": {
"point": {
"x": 1,
"y": 1,
"z": 1
},
"rotation": {
"roll": 0,
"pitch": 0,
"yaw": 0
}
}
},
{
"obstacleType": "CAPSULE",
"name": " example_capsule",
"radius": 0.1,
"startPoint": {
"x": 0.5,
"y": 0.5,
"z": 0.2
},
"endPoint": {
"x": 0.5,
"y": 0.5,
"z": 0.2
}
},
{
"obstacleType": "PLANE",
"name": "example_plane",
"points": [
{
"x": -0.5,
"y": 0.2,
"z": 0
},
{
"x": -0.5,
"y": 0,
"z": 0
},
{
"x": -0.5,
"y": 0,
"z": 0.1
},
]
}
]