Choreograph API can be used to control the robot, interact with toolpaths, read and write data to the robot and process calculation with the robot model.

Safety Warning: Please use caution when using Eva, we recommend you read and understand the Robot's run modes before producing any motion.

REST

This API is a REST API, it means it is accessed through HTTP, using different HTTP methods (GET, POST, PUT, etc), HTTP headers (Authorization, Content-Type, etc) and HTTP paths (/api/v1/users, /api/v1/toolpaths, etc).

Any HTTP client can be used to communicate with it, e.g. requests in Python, curl in Shellscript or your browser JavaScript environment.

This document will present the different headers needed for correct usage of the API, as well as the method, path and payload required by each endpoints (i.e. functions). Finally, the expected results will be presented, including error cases, with examples.

Status codes

The API will always answer with a 200 status code if everything went well. Any other code represents an error.

Code Meaning
400 Error while parsing the arguments
401 This endpoint requires to be authenticated (see Authentication)
403 This endpoint requires an admin role (see Roles)
404 Requested resource not found
415 Invalid Content-Type (see Content-Type)

Errors

Every error returned by the API will have the same format:

{"error":{"error_code":ERROR_CODE,"title":ERROR_TITLE,"details":ERROR_DETAILS}}

The ERROR_CODE will be an integer from the following table, which will identify the kind of issue. It is sometimes complementary to the status code of the reply, sometimes purely redundant (e.g. in case of timeout).

Code Meaning
3 Lock related (robot already locked, unlocking without holding the lock) (see Lock)
4 Role related (insufficient permissions) (see Roles)
5 Authentication related (logged out, invalid token, etc) (see Authentication)
6 Header format (invalid Authorization header, etc)
8 Validation (invalid arguments)

The ERROR_TITLE will be a string description of the issue in a human-readable format.

The ERROR_DETAILS will vary depending on the issue, it may be a string giving more context and information on the error, a list of such strings, etc. It may be null

Example

{"error":{"error_code":5,"title":"invalid Authorization token","details":null}}

Content-Type

This API only accepts and outputs JSON, therefore it requires your request to contains a Content-Type header with the value of application/json.

Example

GET /api/v1/users HTTP/1.1
Host: eva.automata
Accept: */*
Authorization: API 123-456-789
Content-Type: application/json
Content-Length: 0

Authentication

Please see the Auth section of the docs

Terminology & Concepts

Some clarification on the terms used in this document.

Role

Every user has a role which can be either admin (full access) or user (restricted access). When endpoints are described as "admin-only" it means that you need an API token from an administrator to execute the request.

Data Mode

Several endpoints that returns the state of the Robot supports a data mode argument. By default, flat is assumed, but this can be changed using query arguments (e.g. endpoint?mode=flat).

Joint angles

The joint angles is the set of rotations that represent a configuration of the Robot arm. Each rotation correspond to one joint rotation. Note that every angle is expressed in radians.

Examples

A rotation of [0, 0, 0, 0, 0, 0] corresponds to a straight, upright position.

A rotation of [0, 0.5235, -1.7453, 0, -1.9198, 0] corresponds to the default, "ready to pick" position.

End effector

The end effector is a term to designate the end of the robot where a tool can be fixed (like a gripper for example). It has a 3D position (x, y, z) which is relative to the center of the base plate of the robot (origin 0, 0, 0). It also has an orientation represented by 3 vectors (for x, y and z).

Toolpath

A toolpath is the path that the tool (end effector of the Robot) will follow.

Waypoints

A waypoint is a point in space corresponding to certain joint angles. Using a set of waypoints, one can create a toolpath by describing the different positions where the Robot must go through to complete the desired use-case.

They are usually represented only by their corresponding joint angles as their position can easily be deduced using forward kinematics.

Setpoints

The setpoints are a list of joint angles that must be followed by the Robot to execute a toolpath (move from one point to another).

Robot Lock

Because the API interacts with a physical object that can move and thus can create safety issues, a security mechanism was setup: the Lock.

Only one user (one API token to be more precise) can own the lock at a given time. This prevent conflict while controlling or changing the state of the Robot. The API contains different endpoints allowing you to interact with the Lock (see Controls > Lock).

If not renewed regularly, the lock is automatically released after 1 minute.

Updating

This endpoint allows you to install an update on the Robot.

Note that this endpoint requires the Robot lock to be acquired because you are affecting the physical Robot. Moreover, only administrators can install updates.

Request

POST /api/v1/config/update

Payload

The raw update package as downloaded from our website.

Reply

{
  "updating": true
}

or an error.

Version

This endpoint allows you to query the Robot's API version and software version.

Request

GET /api/versions

Reply

{
  "APIs": ["v1"],
  "robot": "3.0.0"
}

Where "robot" is the software version on Eva and "APIs" is an array of the api versions available.

I/O

This section provides a bit more information about how to use the I/O system of the Robot.

Definition

An I/O is defined by an object containing 3 properties (used in the toolpaths' output-set, input and output-test).

Properties: - location: a string that can be either base or end_effector - type: a string that can be either analog or digital - index: an integer describing which output to use

See the list section about which I/Os exist.

Modes & Values

When using an analog type for an I/O, you need to set an analog mode for them, which change the range of available values (given in floats). These can be set by changing them as a property or in the metadata of a toolpath.

Analog modes: - voltage mode: 0 - 10V - current mode: 4 - 20mA

When using a digital type for an I/O, just pass a bool value which will be 1 for true and 0 for false.

List

Currently, I/Os are available on two places on the Robot (location property): - base: the base board at the bottom of the Robot - end_effector: the board available at the end of the Robot end-effector

Each of these places support a certain number and type of I/O.

base types: - digital: it supports 4 I/O numbered between 0 and 3 - analog: it supports 2 I/O numbered between 0 and 1, both support all analog_modes

end_effector types: - digital: it supports 2 I/O numbered between 0 and 3 - analog: it supports 2 inputs numbered between 0 and 1, which only support voltage mode

TCP Configuration

The Tool Center Point of the Robot is configured using an object that contains two properties: - offsets: an object containing three properties (x, y and z) representing the 3D position of the tip of the tool in the end-effector space (in meters) - rotations: an object containing three properties (x, y and z) representing the rotations of the tool at its tip (in radians) - radius: a float representing the radius of the tool (in meters), the tool will be modeled as a cylinder of the given radius which allows better control over self-collision detection

tcp_config is an optional value on every endpoint that uses it. If not included, the TCP is considered to be the end-effector of the Robot. The Choreograph viewer also has a useful view of the TCP config on the Robot to help visualise the tool.

Here is an example TCP configuration, simulating a circular tool with a 100mm Z offset and 25mm radius:

{
  "tcp_config":{
    "offsets":{"x":0,"y":0,"z":0.1},
    "radius":0.025,
    "rotations":{"x":0,"y":0,"z":0}
  }
}

Run modes

Any motion of the Robot will have a mode; either automatic or teach (respectively equivalent to ISO 10218-1 automatic and manual modes).

The running mode affects two mechanisms: - Speed: In teach mode, the Robot's speed will be capped at 0.250 m/s, if a motion would faster then it is slowed down. In automatic mode, the speed has a higher uppper bound of 1.5 m/s. - Lock: In teach mode, the Robot Lock need to be renewed at least every 5 seconds, it also cannot be released until the motion is complete. If the Lock is not renewed within the 5 second interval it will be lost and the motion will be stopped (ISO 10218-1 protective stop). In automatic mode, the Lock need to be renewed every 5 minutes to be kept, but can be released/lost without incurring a stop in motion.

Please use caution when in automatic mode: as the Robot can run at full speed ensure the work area is clear of any obstacles or humans. As an example, we encourage users to use teach mode while near to the robot or programming toolpaths and automatic only once the Robot's path is known and well tested in a safe environment. If you are integrating Eva into your own product, please consider warning users when in automatic mode to clear the work area.

Some motions can only be run in teach mode (homing and backdriving), for all others motion types (go to and toolpath run) the user can choose between teach or automatic mode.

In case of a loss of connection with the Robot while using teach mode, it will take at least 5 seconds before coming to a stop by itself, thus always remember to use the E-Stop in case of an emergency!

Reference frames and orientation

The reference frame of Eva is centered at the base plate and it is oriented as shown in below:

quaternion refernce picture

When using the API, all cartesian distances are defined with respect to the origin of the above mentioned reference frame. The reference frame of the end effector has its origin at the center of the end effector, and sits on the plane defined by the outer aluminium flange. The orientation is described by a quaternion q=[q0, q1, q2, q3], with q0 being the scalar part of the quaternion and [q1, q2, q3] being the vector part of the quaternion. The reference quaternion qI=[1 0 0 0] is obtained for the upright position, for which all the joint angles are zero, that is [0, 0, 0, 0 ,0 ,0].

Kinematics and Singularities

When we use Eva, we generally want the robot to move to an X, Y, Z position with a defined orientation of the tool point. Eva takes this position and orientation input and, using a mathematical process called inverse kinematics, calculates the six individual joint angles needed to get there.

If this X, Y, Z position is outside of Eva's workspace or causes a self collision then the inverse kinematics process will return an error. A linear movement between two valid waypoints sometimes requires one or more joints to rotate very quickly. If the joint speeds exceed safe limits using a GoTo or Toolpath, the API produces a "singularity" warning.