Lock

These endpoints allow you to interact with the Robot lock.

Status

This endpoint returns the status of the lock.

Request

GET /api/v1/controls/lock

Payload

NONE

Example replies

  • If unlocked
{
  "owner": "none",
  "status": "unlocked"
}
  • If locked (by admin)
{
  "owner": "admin",
  "status": "locked"
}
  • If owned
{
  "owner": "you",
  "status": "locked"
}

or an error.

Where

  • owner can be either: you (locked by you), admin (locked by an admin), user (locked by an user) or none (unlocked) (see this section for more details on users' role)
  • status can be either: locked or unlocked

Locking

This endpoint tries to acquire the lock, fails if the Robot is already locked. Note that the lock will expire after 60 seconds if not renewed.

Request

POST /api/v1/controls/lock

Payload

NONE

Example replies

  • If unlocked
{
  "owner": "you",
  "status": "locked"
}
  • If locked
{"error":{"error_code":3,"title":"lock already owned by someone else","details":null}}

or an error. (See this section for details on the meaning of owner and status)

Renewing

This endpoint renews the lock (reset its expiration to 60 seconds) if already held, fails otherwise.

Request

PUT /api/v1/controls/lock

Payload

NONE

Example replies

  • If locked by you
{
  "owner": "you",
  "status": "locked"
}
  • Else
{"error":{"error_code":3,"title":"you don't own the robot lock","details":null}}

or an error. (See this section for details on the meaning of owner and status)

Unlocking

This endpoint releases the lock if already held, fails otherwise.

Request

DELETE /api/v1/controls/lock

Payload

NONE

Example replies

  • If locked by you
{
  "owner": "none",
  "status": "unlocked"
}
  • Else
{"error":{"error_code":3,"title":"you don't own the robot lock","details":null}}

or an error. (See this section for details on the meaning of owner and status)

Controls

Note that all of these endpoints require the Robot lock to be acquired because you are affecting the physical Robot.

State

These endpoints allow you to control the state of the Robot. This state can be any of these values:

  • ready: Robot is in stand-by, awaiting instructions
  • error: Robot encountered an error, you need to call reset_errors to make it ready again
  • running: Robot is executing a motion (triggered by either run, home, go_to or go_to_advanced)
  • paused: Robot was paused during a motion by pause, you can either resume (switch to running) or cancel (switch to ready)
  • stopping: Robot will stop once it finish the current loop, can still be paused, triggered by stop_loop
  • jogging: Robot can be jogged, see Jogging to learn more about entering and exiting jog mode and jogging the Robot
  • backdriving: Robot is in Teach-By-Example mode, triggered by pressing the button near the end-effector, release it to go back to ready

Apart from run, every endpoint is a POST request with no payload. Replies are also similar, thus they are all grouped in this category.

Run

Start the selected toolpath, change from ready to running.

This endpoint requires a run mode to be specified.

POST /api/v1/controls/run

Payload

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

where LOOP_NUMBER is an integer describing the number of loops that the Robot should do, note that 0 means indefinitely (you need to manually stop the Robot) and MODE is either automatic or teach (see here for more information).

Home

Move to the first waypoint of the selected toolpath, change from ready to running.

POST /api/v1/controls/home

Pause

Pause the current motion, change from running to paused.

POST /api/v1/controls/pause

Resume

Resume the current motion, change from paused to running.

POST /api/v1/controls/resume

Cancel

Cancel the current motion, change from paused to ready.

POST /api/v1/controls/cancel

Stop Loop

Stop the Robot after the current loop is finished, change from running to stopping.

POST /api/v1/controls/stop_loop

Reset Errors

Reset the Robot error, change from error to ready.

POST /api/v1/controls/reset_errors

Reply

  • If it works

204 No Content

  • If it fails
{
  "error":{
    "status":1,
    "title":"ERROR_WRONG_STATE",
    "details":"Robot not running"
  }
}

Scheduling

This endpoint enables control of the scheduler which can automatically start and stop the Robot depending on the current time. Caution: Scheduled toolpaths always run in automatic mode.

Request

POST /api/v1/controls/scheduler

Payload

  • To enable it
{
  "enabled": true,
  "start_time": TIME_STAMP,
  "end_time": TIME_STAMP,
}

where TIME_STAMP is a string representing the start and end of the range when the Robot should run using the following time format: HH:MM:SS.

  • To disable it
{
 "enabled": false
}

Reply

  • When enabled
{
  "event":{
    "details":"Scheduler enabled (from 14:27:32 to 15:27:32)",
    "name":"EVENT_SCHEDULER_UPDATE"
  }
}
  • When disabled
{
  "event":{
    "details":"Scheduler disabled",
    "name":"EVENT_SCHEDULER_UPDATE"
  }
}

Go to

This endpoint moves the Robot to a set of joint angles. You can also provide optional arguments to change the duration or max speed of the movement. The default is a max speed of 0.250 (i.e. 250mm/s, which is the maximum).

This endpoint requires a run mode to be specified.

Request

POST /api/v1/controls/go_to

Payload

{
  "mode": "teach",
  "joints": [0, 0, 0, 1.7, 0.5, -1]
}

With optional max_speed

{
  "mode": "teach",
  "joints": [0, 0, 0, 1.7, 0.5, -1],
  "max_speed": 0.2
}

With optional time

{
  "mode": "teach",
  "joints": [0, 0, 0, 1.7, 0.5, -1],
  "time": 3
}
  • mode can be either automatic or teach (see here for more information)
  • joint is an array containing the joint angles of the Robot expressed in radians, e.g. [0, 0, 0, 1.7, 0.5, -1]
  • optional time is a float to specify how long the motion should take (in seconds)
  • optional max_speed is a float to specify the maximum speed the robot end-effector will reach during this motion (in m/s)

Please note: only one of time or max_speed can be used in a request, not both simultaneously.

Reply

It will receive a state update as in the previous section.