Migration Guide¶

This page will help you to migrate your API from one version of the Robot to another, explaining any change in format, endpoint renames, etc.

Note that each section builds on top of each other, so if you are upgrading from 2.1.2 to 4.0.0, you might need to consult the section about Upgrading to 3.0.0, Upgrading to 3.0.1, Upgrading to 3.1.0, Upgrading to 3.2.0 and Upgrading to 4.0.0.

You can find all Choreograph releases here.

Upgrading to 4.9.0¶

No changes required.

Software Avoidance Zones¶

More details about this feature here

This is an addition and will not affect current usage of the API.

You can now specify zones (defined as cuboids) where the robot won't go as part of a toolpath. More details here.

Endpoints affected:

Go To TCP Config¶

As stated above, the Go To endpoint now supports the Software Avoidance Zones argument, but also the TCP configuration, which is already supported by the Toolpath and Calculation endpoints.

Endpoints affected:

POST /api/v1/controls/go_to

Forward Kinematics result¶

Using Software Avoidance Zones with Forward Kinematics calculation can result in a failure. In this case, the corresponding endpoint will follow the same result syntax as the Inverse Kinematics one (format documented in Upgrading to 4.0.0).

Endpoints affected:

PUT /api/v1/calc/forward_kinematics

Upgrading to 4.8.0¶

No changes required.

Collision Detection¶

This is an addition and will not affect current usage of the API.

You can now enable the collision detection feature of your Robot. Collision events put the Robot in the new collision state. The collision must be acknowledged by the user to return the Robot to a ready state. Two endpoints have been added, one to configure the feature, the other to acknowledge collisions. Refer to the technical reference for further details of this feature.

POST /api/v1/data/globals

Upgrading to 4.2.0¶

No changes required.

Toolpaths' hash¶

The hash for each of your saved toolpaths will have changed due to internal changes to enable Analog I/O support. No action is required unless you use the hash of a toolpath for sanity checking, etc.

Endpoints affected:

Analog I/O¶

This is an addition and will not affect current usage of the API.

The base's analog I/Os can now be accessed. They are each composed of a float value and a string mode (voltage or current), check the affected endpoints documentation for more details.

Endpoints affected:

Upgrading to 4.1.0¶

No changes required.

Upgrading to 4.0.0¶

Due to confusion around error codes in calculation endpoints, we have made the reply format more explicit. Previously, the result of an IK call might have looked like this for success:

{
  "ik": {
    "result": "success",
    "joints": [-2.3, 0, 0, 0.32, 0, 0.78]
  }
}

and like this for an error:

{
  "ik": {
    "result": "ik",
    "joints": [0, 0, 0, 0, 0, 0]
  }
}

While we document all the result codes, it is easy to misinterpret the error as a genuine result. Thus the same replies would now look like this, success:

{
  "ik": {
    "result": "success",
    "joints": [-2.3, 0, 0, 0.32, 0, 0.78]
  }
}

And error:

{
  "ik": {
    "result": "error",
    "error": "ik_failure"
  }
}

Summary of the changes:

result is now either success or error
when result is error, we also include an error property which will correspond to a code in the Motion errors table
Motion errors were renamed to make it more explicit that you are dealing with an error (e.g. ik_failure instead of ik)
joints is now always omitted when dealing with an error, thus avoiding the false impression that you are dealing with a legitimate result

Note that these changes apply not only to the calculation endpoints (nudge and rotate reply format is nearly identical to inverse_kinematics), but also to the Toolpath Trajectory format, more specifically to the setpoints property of a segment.

A segment (including valid and invalid setpoints) would previously look like this:

  ...
  {
    "type":"segment",
    "result":false,
    "waypoints":[1,2],
    "setpoints":[
      {"result":"success","joints":[0,1,0,1,0,0]},
      {"result":"ik","joints":[0,0,0,0,0,0]}
    ]
  }
  ...

Compared to the current:

  ...
  {
    "type":"segment",
    "result":false,
    "waypoints":[1,2],
    "setpoints":[
      {"result":"success","joints":[0,1,0,1,0,0]},
      {"result":"error","error":"ik_failure","joints":[0,0,0,0,0,0]}
    ]
  }
  ...

Note that joints might still be returned when the setpoint is invalid but there is no guarantee it is a meaningful value, don't use it or rely on it in your code.

Endpoints affected:

Upgrading to 3.2.0¶

We have changed the result when editing a property (mostly used for setting the Robot digital outputs) to better match the one given by snapshot.

Given the following request:

POST /api/v1/data/globals

{
  "changes": [
    {"key": "global.outputs.d0", "value": false},
    {"key": "global.outputs.d1", "value": true}
  ]
}

You would previously receive, given no errors:

{
  "changes": [
    {"global.outputs.d0": false},
    {"global.outputs.d1": true}
  ]
}

Starting with this version, you would receive the following, which match the snapshot format:

{
  "changes": {
    "global.outputs": {"d0":false,"d1":true,"d2":false,"d3":false,"ee_d0":false,"ee_d1":false}
  }
}

Endpoints affected:

POST /api/v1/data/globals

Upgrading to 3.1.0¶

We have removed the flat data mode from all /data/* endpoints. object mode (which was the default) is now the only supported mode.

Here is an example of the difference.

flat mode:

{
  "control.loop_count": 1,
  "control.loop_target": 1,
  "control.robot_state": "ready"
}

object mode:

{
  "control": {
    "loop_count": 1,
    "loop_target": 1,
    "robot_state": "ready"
  }
}

In summary, flat mode would flatten all the properties of the data endpoints (including arrays, expressing them as property.0, property.1, etc), while object mode group them under sub-properties.

Note that if you weren't adding ?mode=flat to the affected endpoints, this should make no difference for you.

Endpoints affected:

Upgrading to 3.0.1¶

In order to further improve the security of API tokens, we had to delete all of them. You will need to create new API tokens in order to use the API/SDK again.

Upgrading to 3.0.0¶

This update adds a lot of safety mechanisms around the motion of the robot and thus breaks a lot of endpoints. Here is a quick overview of the changes:

Toolpath format has changed, a migration endpoint is provided to alleviate the pains of migrating toolpaths stored off the Robot
Speed is now expressed in m/s instead of a "percentage of the maximum speed" on all endpoints (Toolpath, Go To, etc)
Every motion endpoint requires a run mode, following the ISO 10218-1
Lock needs to be renewed more frequently in teach mode to ensure the user stays connected, otherwise the Robot will stop
API tokens are now used to request a Session Token instead of used directly for authentication
Error's status has been renamed to error_code

Toolpath format changes¶

See this section for more details about the changes and how to adapt your toolpaths (note that the ones stored on your robots are automatically migrated).

In summary:

velocity (and its matching default_velocity) was replaced by max_speed (and default_max_speed), which is expressed in m/s instead of a "factor of the maximum speed of the Robot on the given segment for this kind of motion", the previous method didn't relate well to what would happen when the robot was running (as it would depend on the maximum speed of the type of motion) and gave no guarantees on the final running speed
duration and time are expressed in seconds instead of milliseconds and it cannot be set to 0 anymore
waypoints' label field cannot be an empty string
metadata has two new properties tcp_config and payload which help when attaching tools/payloads to the end effector

Endpoints affected:

Speed as m/s¶

Any endpoint using velocity or percent_speed was replaced with max_speed which is expressed in m/s instead of a "factor of the maximum speed of the Robot on the given segment for this kind of motion", the previous method didn't relate well to what would happen when the robot was running (as it would depend on the maximum speed of the type of motion) and gave no guarantees on the final running speed.

Thus a request to make the Robot go to the joint angles [0, 0, 0, 0, 0, 0] at a half-speed, which might have looked like this:

POST /api/v1/controls/go_to

{
  "joints": [0, 0, 0, 0, 0, 0],
  "velocity": 0.5
}

Will now look like this (0.75m/s is half the maximum speed of 1.5m/s of the Robot):

{
  "mode": "automatic",
  "joints": [0, 0, 0, 0, 0, 0],
  "max_speed": 0.75
}

Note that we also added a mode for the motion, see next section to learn more.

Endpoints affected:

POST /api/v1/controls/go_to

Run modes & Lock¶

Following the ISO 10218-1, we have introduced two run modes: automatic and teach. You can find more details about the difference between them and when you should use which here.

In summary:

teach mode caps the speed of the Robot to 0.250 m/s and will stop the Robot if the Lock isn't renewed at least every 5 seconds, as it needs to enforce a user (human or application) being in control at all time
automatic mode caps the speed of the Robot to the maximum of 1.5 m/s and will not stop the Robot if the Lock isn't renewed (the renew period is also longer: 5 minutes)
Usage: teach mode is required for backdriving and homing but should also be used when testing new motions/toolpaths and when the Robot is working close to humans, automatic mode should be used when other safety mechanisms are in place to protect people and equipments (clear procedures, estop, light curtains, cage...)

The previous section already showcases how to include the mode for /controls/go_to so we will demonstrate how to do that for /controls/run. Previously, you will start a motion using:

POST /api/v1/controls/run

{
  "loop": LOOP_NUMBER
}

You will now need to amend the payload to read:

{
  "mode": MODE,
  "loop": LOOP_NUMBER
}

Endpoints affected:

API authentication¶

Previously, you could use the API token generated on your Profile page on Choregraph directly, e.g.:

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

In order to improve security and safety, you now need to first create a Session Token with your API_TOKEN before you can use it.

Thus you will first need to create a session token, which you can invalidate when you are done and that you need to renew if you want to use it for more than 30 minutes. Once you have a Session Token you can pass it to a request as before, the only difference is that we now use the standard Bearer keyword instead of our custom API.

A standard workflow looks like:

POST /api/v1/auth HTTP/1.1
Host: eva.automata
Accept: */*
Content-Type: application/json

{"token": API_TOKEN}

Which gets you:

{"token": SESSION_TOKEN}

Which you can now use as before:

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

Endpoints affected: all

Error format¶

Previously, every error would follow this format:

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

We have renamed status to error_code, giving the following format:

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

This helps distinguish our ERROR_CODE from the HTTP status codes.

Endpoints affected: all

Upgrading to 2.1.2¶

No changes required.

Upgrading to 2.1.0¶

No changes required.