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.

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":{"status":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":{"status":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

All the API endpoints are protected by the means of API tokens. These tokens can be generated in the Interface (your email > Profile > API Tokens).

Once you have a valid token, you need to include it as a API token authorization through the corresponding HTTP header: Authorization.

Example

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

where API_TOKEN is the token generated by the Interface.

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.

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