The toolpath endpoints are divided in two categories: the ones that affect a saved toolpath and the ones that work on an unsaved toolpath given as argument. The latter will be presented in the Unsaved actions category.

Note that every user has their own toolpaths, they are not shared between users by default (see Sharing to learn more about that).

Terms

Toolpath

A toolpath is the JSON representation of what you are seeing when programming the Robot in the Interface. It contains 3 properties: metadata, timeline and waypoints.

metadata is an object containing information about the toolpath. It supports multiple properties: - default_velocity: which is a float representing to which percent of maximum speed will the robot moves if not overridden on a waypoint basis (between 0 (exclusive) and 1 (inclusive)). - analog_modes: which is an object containing multiple properties (see I/O section for more information): - i0: mode of the first analog input (base), a string that can be either voltage (V) or current (mA) - i1: mode of the second analog input (base), same as previous - o0: mode of the first analog output (base), same as previous - o1: mode of the second analog output (base), same as previous - output_on_error: an object similar to one of type output-set (see next paragraph about timeline) which will be executed if an error while the robot is running this toolpath - next_label_id: an integer indicating the next label_id a waypoint can use (see waypoints specification below), usually just the last used one + 1 (but can skip a few numbers)

timeline is an array representing a list of actions to execute to complete the toolpath. Each action has different properties, here is the list sorted by type:

  • home: define where the Robot must be at the start of the toolpath, must be place before any trajectory and only once, in the root timeline (not in a grid, if, etc)

    • waypoint_id: an integer corresponding to the index in the waypoints array that represent the home
  • trajectory: this can either represent a move to a waypoint or a passthrough waypoint used in other trajectories

    • waypoint_id: an integer corresponding to the index in the waypoints array that the Robot should move to/passthrough
    • pass_through: a boolean that represent if the waypoint is a passthrough (optional)
    • trajectory: used to denote a move to this waypoint (no passthrough), can be either joint_space (fastest motion but may not maintain tool orientation), linear (will move in a straight line and maintain tool orientation) or spline (will make an arc and maintain tool orientation), note that the trajectory will go through the all previous passthrough waypoints since the last non-passthrough one (where possible, only spline at the moment)
    • time/velocity: used when moving to a waypoint (no passthrough), these properties are used to describe how fast the robot will go to the waypoint, you can choose either:
      • time: a float representing the number of seconds the robot should take to go to the next waypoint
      • velocity: a float representing the percentage (0-1) of the maximum speed of the robot that should be used to go to the next waypoint
      • none: if neither of these attributes are given, it will default to velocity mode using the toolpath default_velocity
  • output-set:

    • io: an object representing the IO to set (see see I/O defintion)
    • value: a boolean (for digital) or a float (for analog) describing the value to be set to the output described by io (see I/O for more information)
  • wait: will make the Robot wait at its current position until the condition is valid

    • condition: the condition to be tested, see the condition list next
  • restart: will stop the toolpath and restart from the start, need the last trajectory before this action to be the same as the one at the beginning of the toolpath, can only be placed at the end of if action branch

  • grid: allows you to define a 2D table (with rows and columns) over which the Robot will iterate with a special waypoint representing the current cell

    • cols: an integer for the number of columns of the table
    • rows: an integer for the number of rows of the table
    • w0: an integer corresponding to the index in the waypoints array of the waypoint defining the first corner of the table (note that w0-wx and w0-wy must be perpendicular segments)
    • wx: an integer corresponding to the index in the waypoints array of the waypoint defining the column (X) corner of the table
    • wy: an integer corresponding to the index in the waypoints array of the waypoint defining the row (Y) corner of the table
    • timeline: the timeline to be executed for every cell of the table, can contain the same actions as the root timeline (including grid actions). This timeline can also hold a special waypoint of the type grid-waypoint.
  • grid-waypoint: variable waypoint that changes position depending on the iteration of its parent grid

    • time/velocity: same as for waypoint types
    • z_offset: a float that represent the offset from the grid plane (less is under, more is above), expressed in meters
  • if: allows you to fork your timeline in different branches, each branch has a condition, the first valid one of the list will determined the branch taken by the Robot, if no condition are valid, the entire action will be ignored

    • branches: the list of possible branches

      • condition: the condition to be tested, see the condition list next
      • timeline: the timeline to be executed, can contain the same actions as the root timeline (including if actions)

Conditions can be either:

  • time (only for wait): condition is invalid until a certain duration is reached

    • duration: a float for the duration to wait for, in ms
  • input or output-test: these conditions both test that an input or output (respectively) has a certain value

    • io: an object representing the IO to check (see I/O defintion)
    • operator: in case of an analog I/O, this string describes how to test if the value is valid, can be either equal (must be the exact value), below (value < thresholds.lower), above (value > thresholds.upper), inside (thresholds.lower < value < thresholds.upper) or outside (value < thresholds.lower && thresholds.upper < value)
    • thresholds: in case of an analog I/O with operator other than equal, an object containing 2 properties: upper and lower describing the thresholds used by the operator property
    • value: a boolean (for digital) or a float (for analog with a equal operator) describing the value we are expecting for io

waypoints is an array of waypoint that can be used by the timeline actions of type trajectory (their waypoint_id being their index in this array). A waypoint can be used any number of times in any order. Each waypoint contains 2 properties:

  • label_id: a number used to identify a waypoint in space and in the timeline, the ordering can be any way you want but a number cannot be repeated (though some can be skipped)
  • label: optional, a string to help identify a waypoint (maximum 16 characters)
  • joints: an array of 6 floats the joint angles of the Robot at this waypoint

Example

{
  "metadata": {
    "default_velocity": 1,
    "next_label_id": 4,
    "analog_modes": {"i0": "voltage", "i1": "voltage", "o0": "voltage", "o1": "voltage"}
  },
  "timeline": [
    {"type": "home", "waypoint_id": 0},
    {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 1, "time": 2},
    {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 2}
  ],
  "waypoints": [
    {"label_id": 1, "joints": [0, 0, 0, 0, 0, 0]},
    {"label_id": 2, "joints": [0, 1, 0, 1, 0, 0]},
    {"label_id": 3, "joints": [1, 1, 0, 1, 0, 1]}
  ]
}

See more examples in the corresponding section

Trajectory

A trajectory is the JSON representation of the setpoints that the Robot will follow to execute a toolpath. It is an array containing several objects representing either segments to move from one waypoint to another or other information.

error is a string explaining an error encountered during generation of the trajectory, it can be completely absent. If it is present, it could either be a soft error (timeline is present but invalid) or a hard error (timeline is completely absent).

timeline is an array representing a list of actions to execute to complete the toolpath, it is pretty close to the one from the toolpath. Each action has different properties, here is the list sorted by type:

  • segment: the result of the corresponding trajectories from the toolpath

    • result: a boolean representing if every setpoint is valid
    • setpoints: an array of setpoint, each containing:

      • result: a string representing a motion error
      • joints: an array of float representing the joint angles of the Robot at this setpoint
      • position: an object containing three properties (x, y and z) representing the position of the end-effector at this setpoint
    • waypoints: an array of integers corresponding to the index in the waypoints array that the Robot is moving from/to/through (an integer of -1 express a grid-waypoint)

  • output: exactly the same as in toolpath

  • wait: exactly the same as in toolpath
  • grid: the result of the corresponding grid from the toolpath

    • iterations: an array of actions (can contain the same actions as the root timeline) for every iteration of the grid
  • if: the result of the corresponding if from the toolpath, with the same properties

  • restart: exactly the same as in toolpath

Example

{
  "trajectory":{
    "error":"Issue when calculating setpoints in segment 2",
    "timeline":[
      {
        "type":"segment",
        "result":true,
        "waypoints":[0,1],
        "setpoints":[
          {"result":true,"joints":[0,0,0,0,0,0],"position":{"x":-7.450581e-09,"y":-8.960835e-09,"z":0.87608004}},
          {"result":true,"joints":[0,0.015708419,0,0.015708419,0,0],"position":{"x":-0.009381651,"y":-8.963586e-09,"z":0.8751266}},
          {"result":true,"joints":[0,0.06184666,0,0.06184666,0,0],"position":{"x":-0.0368351,"y":-8.841464e-09,"z":0.8714761}},
          {"result":true,"joints":[0,0.13551569,0,0.13551569,0,0],"position":{"x":-0.08023663,"y":-8.81831e-09,"z":0.8630344}},
          {"result":true,"joints":[0,0.2320866,0,0.2320866,0,0],"position":{"x":-0.13597472,"y":-8.296349e-09,"z":0.84717435}},
          {"result":true,"joints":[0,0.3454915,0,0.3454915,0,0],"position":{"x":-0.19910753,"y":-7.2620256e-09,"z":0.8217965}},
          {"result":true,"joints":[0,0.46860474,0,0.46860474,0,0],"position":{"x":-0.2639095,"y":-5.243951e-09,"z":0.78635556}},
          {"result":true,"joints":[0,0.59369063,0,0.59369063,0,0],"position":{"x":-0.324785,"y":-3.1792637e-09,"z":0.7424749}},
          {"result":true,"joints":[0,0.7128897,0,0.7128897,0,0],"position":{"x":-0.37727186,"y":7.7707146e-10,"z":0.69389987}},
          {"result":true,"joints":[0,0.818712,0,0.818712,0,0],"position":{"x":-0.4187373,"y":1.0110071e-09,"z":0.64581126}},
          {"result":true,"joints":[0,0.9045085,0,0.9045085,0,0],"position":{"x":-0.44847688,"y":1.2187056e-09,"z":0.6037789}},
          {"result":true,"joints":[0,0.9648882,0,0.9648882,0,0],"position":{"x":-0.4671931,"y":5.098958e-09,"z":0.57274425}},
          {"result":true,"joints":[0,0.99605733,0,0.99605733,0,0],"position":{"x":-0.47611254,"y":5.1815814e-09,"z":0.55629635}},
          {"result":true,"joints":[0,1,0,1,0,0],"position":{"x":-0.47720417,"y":5.1921547e-09,"z":0.5541963}}
        ]
      },
      {
        "type":"segment",
        "result":false,
        "waypoints":[1,2],
        "setpoints":[
          {"result":true,"joints":[0,1,0,1,0,0],"position":{"x":-0.47720414,"y":5.109149e-09,"z":0.5541963}},
          {"result":false,"joints":[0,0,0,0,0,0],"position":{"x":-0.4771906,"y":-0.000024764217,"z":0.5541963}}
        ]
      }
    ]
  }
}

Listing

This endpoint allows you to list your toolpaths stored on this Robot. Note that this list is "light", i.e. it doesn't include the toolpath representation nor the trajectory as these informations can be heavy on calculation and bandwidth.

Request

GET /api/v1/toolpaths

Payload

NONE

Reply

{
  "toolpaths":[
    {"id":1,"name":"First"},
    {"id":2,"name":"Two"},
    {"id":3,"name":"Interpolation"},
    {"id":4,"name":"Linear + Passthrough"},
    {"id":5,"name":"I/O + Wait"},
    {"id":6,"name":"Branches"},
    {"id":7,"name":"Grid"}
  ]
}

or an error.

Creating

This endpoint allows you to create a new toolpath using a name and a toolpath representation.

Request

POST /api/v1/toolpaths

Payload

{
  "name": "New toolpath",
  "toolpath": TOOLPATH_OBJ
}

where TOOLPATH_OBJ is a valid toolpath.

Reply

{
  "status":"toolpath created",
  "toolpath":{
    "id":8,
    "name":"test1"
  }
}

or an error.

Retrieving

This endpoint allows you to retrieve the toolpath representation of a given toolpath.

Request

GET /api/v1/toolpaths/TOOLPATH_ID

where TOOLPATH_ID is an integer representing the identifier of the toolpath, it is given when listing toolpaths or creating a new toolpath.

Payload

NONE

Reply

{
  "toolpath":{
    "id":8,
    "name":"test1",
    "toolpath":TOOLPATH_OBJ
  }
}

where TOOLPATH_OBJ is a valid toolpath representation.

or an error.

Building

This endpoint allows you to retrieve the toolpath representation and trajectory of a given toolpath.

Request

GET /api/v1/toolpaths/TOOLPATH_ID/build

where TOOLPATH_ID is an integer representing the identifier of the toolpath, it is given when listing toolpaths or creating a new toolpath.

Payload

NONE

Reply

{
  "toolpath":{
    "id":8,
    "name":"test1",
    "toolpath":TOOLPATH_OBJ,
    "trajectory":TRAJECTORY_OBJ
  }
}

where TOOLPATH_OBJ is a valid toolpath and TRAJECTORY_OBJ is a valid trajectory.

or an error.

Updating

This endpoint allows you to update an existing toolpath.

Request

PUT /api/v1/toolpaths/TOOLPATH_ID

where TOOLPATH_ID is an integer representing the identifier of the toolpath, it is given when listing toolpaths or creating a new toolpath.

Payload

{
  "name": "test2",
  "toolpath": TOOLPATH_OBJ
}

Reply

{
  "status":"toolpath updated",
  "toolpath":{
    "id":8,"name":"test2"
  }
}

or an error.

Deleting

This endpoint allows you to delete a given toolpath.

Request

DELETE /api/v1/toolpaths/TOOLPATH_ID

where TOOLPATH_ID is an integer representing the identifier of the toolpath, it is given when listing toolpaths or creating a new toolpath.

Payload

NONE

Reply

{
  "status":"toolpath deleted",
  "toolpath":{
    "id":8,"name":"test2"
  }
}

or an error.

Using

While most of these endpoints deal with creating, retrieving, deleting toolpaths, this one doesn't change the actual database of toolpaths but select one to be used by the Robot. By using (or if you like, selecting) a toolpath, the Robot will calculate the motion, preload it into memory and will be able to replay it when asked (see controls).

Note that because there can only be one selected/used toolpath at the same time, this endpoint requires the lock to be held. As the toolpath is compiled into setpoints, this operation can take a while.

Request

POST /api/v1/toolpaths/TOOLPATH_ID/use

where TOOLPATH_ID is an integer representing the identifier of the toolpath, it is given when listing toolpaths or creating a new toolpath.

Payload

NONE

Reply

{
  "event":{
    "details":"Toolpath uploaded",
    "name":"EVENT_STATUS"
  }
}

or an error.

Unsaved actions

All the previous endpoints dealt with "saved" toolpaths that are actually stored in the Robot. These following ones allow you to interact with the Robot without saving anything in the database.

Sharing

This endpoint allows you to share a given toolpath with another user.

Request

POST /api/v1/toolpath/share

Payload

{
  "name":"cool toolpath",
  "user_id":USER_ID,
  "toolpath":TOOLPATH_OBJ
}

where USER_ID is a valid user unique identifier (which can be retrieved using Users' listing), it describes the user with which you want to share a toolpath and TOOLPATH_OBJ is a valid toolpath.

Reply

{
  "status":"toolpath shared",
  "toolpath":{
    "id":-1,
    "name":"cool toolpath",
    "sharer":USER_ID
  }
}

where USER_ID is the user identifier provided in the payload.

or an error.

Calculating

This endpoint corresponds to the Building one, it allows you to retrieve the trajectory of a given toolpath's toolpath.

Request

PUT /api/v1/toolpath/calc

Payload

{
  "toolpath":TOOLPATH_OBJ
}

where TOOLPATH_OBJ is a valid toolpath.

Reply

{
  "trajectory":TRAJECTORY_OBJ
}

where TRAJECTORY_OBJ is a valid trajectory.

or an error.

Using

This endpoint corresponds to the Using one, it allows you to select a toolpath by just giving a toolpath. The same notes about running, locking and compiling apply.

Request

POST /api/v1/toolpath/use

where TOOLPATH_ID is an integer representing the identifier of the toolpath, it is given when listing toolpaths or creating a new toolpath.

Payload

{
  "toolpath":TOOLPATH_OBJ
}

where TOOLPATH_OBJ is a valid toolpath.

Reply

{
  "event":{
    "details":"Toolpath uploaded",
    "name":"EVENT_STATUS"
  }
}

or an error.

JSON examples

This section contains a few examples of toolpaths.

Interpolation

{
  "metadata": {
    "default_velocity": 1,
    "next_label_id": 5,
    "analog_modes": {"i0": "voltage", "i1": "voltage", "o0": "voltage", "o1": "voltage"}
  },
  "waypoints": [
    {"label_id": 1, "joints": [0, 0.5235988, -1.7453293, 0, -1.9198622, 0]},
    {"label_id": 2, "joints": [0, 1.0150836, 0.20450093, 0, -1.9198622, 0]},
    {"label_id": 3, "joints": [-1.8723892, 1.0150836, -1.555968, 0, -1.9198622, 0]},
    {"label_id": 4, "joints": [-0.6408849, 1.0150836, -2.3186321, 0, -1.9198622, 0]}
  ],
  "timeline": [
    {"type": "home", "waypoint_id": 0},
    {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 1},
    {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 2},
    {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 3},
    {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 0}
  ]
}

Linear + Passthrough

{
  "metadata": {
    "default_velocity": 1,
    "next_label_id": 7,
    "analog_modes": {"i0": "voltage", "i1": "voltage", "o0": "voltage", "o1": "voltage"}
  },
  "waypoints": [
    {"label_id": 1, "joints": [0, 0.5235988, -1.7453293, 0, -1.9198622, 0]},
    {"label_id": 2, "joints": [0.7246584, 0.034853294, -1.3462932, -1.7802324e-07, -1.8301524, 0.72465837]},
    {"label_id": 3, "joints": [-0.37476024, 0.9888687, -1.9834933, 2.8026742e-08, -2.146968, -0.37476024]},
    {"label_id": 4, "joints": [-0.7830396, 0.4468874, -2.087778, 1.5003569e-07, -1.5007017, -0.7830396]},
    {"label_id": 5, "joints": [0.4626438, 0.2402735, -2.112353, 1.3963421e-07, -1.2695131, 0.4626438]},
    {"label_id": 6, "joints": [0.78213555, 0.29602012, -2.1583045, 1.3130983e-07, -1.2793082, 0.7821356]}
  ],
  "timeline": [
    {"type": "home", "waypoint_id": 0},
    {"type": "trajectory", "trajectory": "linear", "waypoint_id": 2},
    {"type": "trajectory", "trajectory": "linear", "waypoint_id": 3},
    {"type": "trajectory", "pass_through": true, "waypoint_id": 4},
    {"type": "trajectory", "trajectory": "spline", "waypoint_id": 5},
    {"type": "trajectory", "trajectory": "linear", "waypoint_id": 1},
    {"type": "trajectory", "trajectory": "linear", "waypoint_id": 0}
  ]
}

I/O + Wait

{
  "metadata": {
    "default_velocity": 1,
    "next_label_id": 5,
    "analog_modes": {"i0": "voltage", "i1": "voltage", "o0": "voltage", "o1": "voltage"}
  },
  "waypoints": [
    {"label_id": 1, "joints": [0, 0.5235988, -1.7453293, 0, -1.9198622, 0]},
    {"label_id": 2, "joints": [0.8808525, -0.34430662, -0.9284578, -4.6631334e-09, -1.8688283, 0.8808525]},
    {"label_id": 3, "joints": [1.5390545, 0.21697286, -1.5133435, 6.8972117e-09, -1.8452221, 1.5390545]},
    {"label_id": 4, "joints": [-2.4881413, 0.2801666, -1.5664449, 2.7822468e-08, -1.8553144, 3.1321232]}
  ],
  "timeline": [
    {"type": "home", "waypoint_id": 0},
    {"type": "output-set", "io": {"location": "base", "type": "digital", "index": 0}, "value": false},
    {"type": "wait", "condition": {
      "type": "time", "duration": 5000
    }},
    {"type": "trajectory", "trajectory": "linear", "waypoint_id": 1},
    {"type": "waypoint", "waypoint_id": 2},
    {"type": "output-set", "io": {"location": "base", "type": "digital", "index": 0}, "value": true},
    {"type": "wait", "condition": {
      "type": "input", "io": {"location": "base", "type": "digital", "index": 0}, "value": true
    }},
    {"type": "trajectory", "trajectory": "linear", "waypoint_id": 2},
    {"type": "trajectory", "pass_through": true, "waypoint_id": 3},
    {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 0}
  ]
}

If

{
  "metadata": {
    "default_velocity": 1,
    "next_label_id": 6,
    "analog_modes": {"i0": "voltage", "i1": "voltage", "o0": "voltage", "o1": "voltage"}
  },
  "waypoints": [
    {"label_id": 1, "joints": [-2.9369467e-12, 0.4102193, -1.666564, -1.4284795e-17, -1.8852477, -2.9369755e-12]},
    {"label_id": 2, "joints": [0.2830496, -0.044686932, -1.2665379, -8.2055884e-08, -1.8303678, 0.2830496]},
    {"label_id": 3, "joints": [0.2830496, -0.04131393, -1.78083, -8.1780456e-08, -1.319449, 0.2830496]},
    {"label_id": 4, "joints": [-0.53279847, -0.27620706, -1.5215058, -4.5274876e-07, -1.3438802, -0.53279835]},
    {"label_id": 5, "joints": [0.69924986, -0.7378929, -0.3964239, -8.6449575e-08, -2.0072758, 0.69924986]}
  ],
  "timeline": [
    {"type": "home", "waypoint_id": 0},
    {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 1},
    {"type": "if", "branches": [
      {"condition": {
        "type": "input", "io": {"location": "base", "type": "analog", "index": 0}, "value": 0.5, "operator": "equal"
      }, "timeline": [
        {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 4},
        {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 4},
        {"type": "restart"}
      ]},
      {"condition": {
        "type": "input", "io": {"location": "base", "type": "analog", "index": 0}, "value": 0.25, "operator": "equal"
      }, "timeline": [
        {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 2},
        {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 3}
      ]}
    ]},
    {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 0}
  ]
}

Grid

{
  "metadata": {
    "default_velocity": 1,
    "next_label_id": 6,
    "analog_modes": {"i0": "voltage", "i1": "voltage", "o0": "voltage", "o1": "voltage"}
  },
  "waypoints": [
    {"label_id": 1, "joints": [0, 0.5235988, -1.7453293, 0, -1.9198622, 0]},
    {"label_id": 2, "joints": [0.35769856, 0.42620432, -1.6781543, -1.3969468e-08, -1.8896427, 0.35769856]},
    {"label_id": 3, "joints": [0.26869485, -0.07519664, -1.2348145, -6.9964107e-10, -1.8315814, 0.26869485]},
    {"label_id": 4, "joints": [0.46470055, -0.25279972, -1.0379537, -1.0726533e-08, -1.8508393, 0.46470052]},
    {"label_id": 5, "joints": [1.1476622, 0.8879967, -1.9438496, 2.3310825e-07, -2.0857406, 1.1476623]}
  ],
  "timeline": [
    {"type": "home", "waypoint_id": 0},
    {"type": "grid", "w0": 2, "wx": 1, "wy": 3, "cols": 5, "rows": 4, "timeline": [
      {"type": "grid-waypoint", "time": 3},
      {"type": "trajectory", "trajectory": "linear", "waypoint_id": 4}
    ]},
    {"type": "trajectory", "trajectory": "joint_space", "waypoint_id": 0}
  ]
}