Controls¶

Controls
- Lock
  - Status
  - Locking
  - Renewing
  - Unlocking
- Controls
  - State
    - Run
    - Home
    - Pause
    - Resume
    - Cancel
    - Stop Loop
    - Reset Errors
    - Acknowledge Collision
    - Reply
  - Scheduling
  - Go to
  - Collision Detection

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 5 minutes (or 5 seconds if running in teach mode, see run modes) 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, resetting its expiration to 5 minutes (or 5 seconds if running in teach mode, see run modes), 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
backdriving: Robot is in Teach-By-Example mode, triggered by pressing the button near the end-effector, release it to go back to ready
updating: Robot is running an update, no action can be initiated until it is finished, it should go back to ready once done
disabled: The emergency stop is pressed, no motion can be initiated until it is released, the Robot will go back to ready or error depending on the context
shutting_down: Robot is shutting down, no action can be initiated
collision: Robot has detected a collision. The user must acknowledge the collision to reset the Robot 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

Acknowledge Collision¶

After a collision has been detected the Robot stops and must have the collision event acknowledged by the user. On successful acknowledgement the Robot changes from collision to ready and can be moved once more.

POST /api/v1/controls/acknowledge_collision

Reply¶

If it works

204 No Content

If it fails

{
  "error":{
    "error_code": 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
}

With optional tcp_config and avoidance_zones

{
  "mode": "teach",
  "joints": [0, 0, 0, 1.7, 0.5, -1],
  "tcp_config": TCP_CONFIG,
  "avoidance_zones": AVOIDANCES_ZONES
}

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)
optional tcp_config property can also be specified in order to configure the TCP of the tool attached to the robot end-effector (see TCP configuration)
optional avoidance_zones property can also be specified in order to configure zones where the robot won't go (see Software Avoidance Zones)

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.

Collision Detection¶

This endpoint allows users to configure the collision detection feature of the Robot: enabling or disabling it and setting how sensitive the Robot is to collisions while enabled.

Detected collisions must be acknowledged before the Robot can be moved once more.

Please note, this is not a safety rated collision detection function and should not be used to guard against any injury of users by the Robot. Refer to the Eva user manuals for more information

This endpoint requires the Robot lock to be acquired, as you are affecting the physical Robot, and that the user has administrator privileges.

Request

POST /api/v1/controls/collision_detection

Payload

"enabled" is a boolean that enables or disables the feature.
"sensitivity" must also be sent when enabling the feature and can be one of: "low", "medium" or "high". Higher sensitivity means the lower the impact force which with stop the Robot, and vice versa.

For example, to enable the feature with "medium" sensitivity

{
  "enabled": true,
  "sensitivity": "medium"
}

Or to disable it

{
  "enabled": false
}

Reply

If it works

204 No Content

Or if it fails, an error.