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":{"status":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":{"status":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":{"status":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. Note that because state change are returned, all of these support a ?mode=DATA_MODE query argument.

Run

Start the selected toolpath, change from ready to running.

POST /api/v1/controls/run

Payload

{
  "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).

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
{
  "state":{
    "control_status.loop_target":1,
    "control_status.robot_state":"running",
    "logging":[
      {"message":"2018-01-02T18:19:24+0000 control_status.robot_state changed to running","level":"state"},
      {"message":"2018-01-02T18:19:24+0000 control_status.loop_target changed to 1","level":"state"}
    ]
  }
}
  • 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.

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 endpoints moves the Robot to a set of joint angles. You can also provide optional arguments to change the duration or velocity of the movement. The default is a velocity of 50% maximum speed.

Request

POST /api/v1/controls/go_to

Payload

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

With optional velocity

{
  "joints": [0, 0, 0, 1.7, 0.5, -1],
  "velocity": 0.2
}

With optional time

{
  "joints": [0, 0, 0, 1.7, 0.5, -1],
  "time": 3
}
  • 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 velocity is a float between 0 and 1 to specify the percentage of the maximum speed that should be used

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

Reply

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