Overview¶

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: Bearer SESSION_TOKEN
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.

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.

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"
}

Robot Name¶

This endpoint allows you to query the Robot's name.

Request

GET /api/v1/name

Reply

{
  "name": "Candid London Weaver"
}

Updating¶

This section has been moved here.

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). Whilst these positions can be set with positive or negative values, we recommend using only a positive z offset to avoid any potential collisions of the Robot and the tool - 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}
  }
}

Software Avoidance Zones¶

The Software Avoidance Zones is configured using an array containing up to 10 objects, each containing the following properties: - name: a string (which must be unique among all the Software Avoidance Zones of the same toolpath) that you can use as a reminder/reference of what the zone protects/represents - position: an object containing three properties (x, y and z) representing the 3D position of origin corner of the cuboid zone (in meters), these coordinates use the absolute coordinate system of the Robot space which is relative to the center of the base plate of the Robot - orientation: an object containing four properties (x, y, z and w) representing the quaternion defining the orientation of the cuboid - dimensions: an object containing three properties (x, y and z) representing the length of each dimension of the cuboid from the position (in meters) - avoid: a string which can be either inside or outside, representing if the Robot should avoid going inside the zone or outside the zone

avoidance_zones is an optional value on every endpoint that uses it. The Choreograph viewer also has a useful view of the zones to help visualize them.

Here is an example of a Software Avoid Zones configuration, simulating a single half-a-meter/side cube, positioned next to the Robot, parallel to the floor, that the Robot will avoid (e.g. representing another machine):

{
  "avoidance_zones": [
    {
      "name": "Printer",
      "position":{"x":0,"y":0.5,"z":0.5},
      "orientation":{"x":0,"y":0,"z":0,"w":1},
      "dimensions":{"x":0.5,"y":0.5,"z":0.5},
      "avoid":"inside"
    }
  ]
}

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 be faster then it is slowed down. In automatic mode, the speed has a higher upper 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 on the base plate and it is oriented as shown in the diagram below:

quaternion reference diagram

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's outer circular aluminium flange, and sits on the plane defined by the flange surface. The orientation of the reference frame relative to the base is described by a unit quaternion q=[q0, q1, q2, q3], with q0 being the scalar part of the quaternion and [q1, q2, q3] being the vector part. The reference quaternion q=[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]. Quaternion values for other common orientations are shown in the diagram.

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.