Data

Snapshot

This endpoint is used to get a snapshot of the Robot's state. Use this method to get the current state, but consider using the streaming mechanism instead of polling this endpoint for updates.

The snapshot is divided into different properties, here is the list of its content:

  • control: the control state of robot
    • state: a string describing the state of the Robot, can be either ready, error, running, paused, stopping, backdriving, updating, disabled or shutting_down (see this section for more information about control states)
    • loop_count: an integer describing how many loop did the Robot did for the current toolpath
    • loop_target: an integer describing how many loop the Robot must do for the current toolpath
    • toolpath_name: a string containing the name of currently uploaded toolpath, WARNING: this may be invalid if the corresponding toolpath is changed or deleted after the upload, use control.toolpath_hash for identification purpose
    • toolpath_hash: a string containing the hash of the currently uploaded toolpath, can be used to identify which toolpath is uploaded
    • run_mode: a string containing the current run mode of the Robot, can be automatic, teach or not_running
  • global: physical properties of the robot
    • estop: a boolean indicating if the estop is engaged (true) or released (false)
  • global.inputs: the state of the inputs of the Robot (see I/O overview)
    • d0: a boolean indicating the state of the first digital input on the base
    • d1: a boolean indicating the state of the second digital input on the base
    • d2: a boolean indicating the state of the third digital input on the base
    • d3: a boolean indicating the state of the forth digital input on the base
    • ee_a0: a boolean indicating the state of the first analog input on the end effector in volts
    • ee_a1: a boolean indicating the state of the second analog input on the end effector in volts
    • ee_d0: a boolean indicating the state of the first digital input on the end effector
    • ee_d1: a boolean indicating the state of the second digital input on the end effector
  • global.outputs: the state of the outputs of the Robot (see I/O overview)
    • d0: a boolean indicating the state of the first digital output on the base
    • d1: a boolean indicating the state of the second digital output on the base
    • d2: a boolean indicating the state of the third digital output on the base
    • d3: a boolean indicating the state of the forth digital output on the base
    • ee_d0: a boolean indicating the state of the first digital output on the end effector
    • ee_d1: a boolean indicating the state of the second digital output on the end effector
  • scheduler: the state of the Scheduler
    • enabled: a boolean describing if the Scheduler is enabled
    • start_time: a string (format: 13:58:59) describing the time when the Scheduler will automatically start the Robot, relevant only if the Scheduler is enabled
    • stop_time: a string (format: 13:58:59) describing the time when the Scheduler will automatically stop the Robot, relevant only if the Scheduler is enabled
  • servos.telemetry.position: an array of float representing the joint angles in radians
  • servos.telemetry.temperature: an array of float representing the temperature of each joint in Celsius
  • servos.telemetry.velocity: an array of float representing the velocity of each joint in degree/s

Request

GET /api/v1/data/snapshot

Payload

NONE

Reply (example)

{
  "snapshot": {
    "control": {"loop_count":1,"loop_target":1,"run_mode":"not_running","state":"disabled"},
    "global": {"estop":true},
    "global.inputs": {"d0":false,"d1":false,"d2":false,"d3":false,"ee_a0":0.031,"ee_a1":0.053,"ee_d0":false,"ee_d1":false},
    "global.outputs": {"d0":false,"d1":false,"d2":false,"d3":false,"ee_d0":false,"ee_d1":false},
    "scheduler": {"enabled":false},
    "servos.telemetry.position": [-0.20671021938323975,0.9430434703826904,-2.4597175121307373,-0.016586674377322197,-1.7134130001068115,-0.011601083911955357],
    "servos.telemetry.temperature": [47,34.619998931884766,33.369998931884766,34.75,34.5,34.369998931884766],
    "servos.telemetry.velocity": [0,0,0,0,0,0]
  }
}

or an error.

Editing properties

This endpoint allows you to edit the physical properties of the Robot. It must receive a list of properties and their associated values from this list:

  • outputs.d0: a boolean indicating the state of the first digital output on the base
  • outputs.d1: a boolean indicating the state of the second digital output on the base
  • outputs.d2: a boolean indicating the state of the third digital output on the base
  • outputs.d3: a boolean indicating the state of the forth digital output on the base
  • outputs.ee_d0: a boolean indicating the state of the first digital output on the end effector
  • outputs.ee_d1: a boolean indicating the state of the second digital output on the end effector

Note that this endpoint requires the Robot lock to be acquired because you are affecting the physical Robot. Moreover, only administrators can edit data properties.

Request

POST /api/v1/data/globals

Payload (example)

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

where changes is a list of properties to change with a new value.

Reply (example)

  • If everything worked
{
  "changes": DATA_PROPERTIES
}

where DATA_PROPERTIES will be an object containing one or more of the sub-properties outlined in Snapshot, depending on what data has changed

  • If one or more property was invalid
{
  "error":{
    "status":8,
    "title":"1 invalid change(s)",
    "details":[
      {"index":0,"error":"unknown property: outputs.d5"}
    ]
  }
}
  • If one or more property could not be changed properly
{
  "error":{
    "status":0,
    "title":"1 error(s) encountered",
    "details":{
      "changes":[
        {
          "error": {
            "error_code": 1,
            "title": "internal error",
            "details":null
          }
        }
      ]
    }
  }
}

or an error.

Stream

A stream of events is available in the form of a Websocket connection.

As for any Websocket connection, it requires the standard headers (i.e. Upgrade, Sec-Websocket-Key, Sec-Websocket-Version and Sec-Websocket-Protocol). Most of them are managed by your browser or Websocket library (depending on your environment), however you need to specify Sec-Websocket-Protocol manually.

The Sec-Websocket-Protocol should be a list of two protocols containing your Session token prefixed by SessionToken_ and object.

Request

GET /api/v1/data/stream
Host: eva.automata
Accept: */*
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==
Sec-WebSocket-Version: 13
Sec-Websocket-Protocol: SessionToken_<session-token>, object

where <session-token> is your session token.

Payload

NONE

Reply

A stream of JSON events as presented in the following section or an error.

Received events

There are different events sent through the Websocket, they represent a change of state of the Robot.

All the events follow the following format:

{"type":EVENT_TYPE, EVENT_CONTENT...}

where EVENT_TYPE is a string identifying the event, EVENT_CONTENT is a set of extra properties that will be present in the object.

Users

See this endpoint for more details about users' information.

Created
  • Event type: user_created
  • Event content: "user": {"id":USER_ID, "email":USER_EMAIL, "role":USER_ROLE}
  • Triggered by: user creation (done by an administrator in the Interface)
  • Received by: everyone

Example

{
  "type": "user_created",
  "user": {"id":2,"email":"jean@perdu.com","role":"user"}
}
Updated
  • Event type: user_updated
  • Event content: "user": {"id":USER_ID, "email":USER_EMAIL, "role":USER_ROLE}
  • Triggered by: user email change or role promotion/demotion (done by an administrator in the Interface)
  • Received by: everyone

Example

{
 "type": "user_updated",
 "user": {"id":2,"email":"jean@perdu.com","role":"admin"}
}
Deleted
  • Event type: user_deleted
  • Event content: "user": {"id":USER_ID, "email":USER_EMAIL, "role":USER_ROLE}
  • Triggered by: user deletion (done by an administrator in the Interface)
  • Received by: everyone

Example

{
 "type": "user_deleted",
 "user": {"id": 2, "email": "jean@perdu.com", "role": "admin"}
}

Toolpaths

See this section for more details about toolpaths' information.

Created
  • Event type: toolpath_created
  • Event content: "toolpath":{"id":TOOLPATH_ID, "name":TOOLPATH_NAME, "hash":TOOLPATH_HASH}
  • Triggered by: toolpath creation (via POST /api/v1/toolpaths)
  • Received by: requesting user

Example

{
 "type": "toolpath_created",
 "toolpath": {"id":2,"name":"UseCase-Painting","hash":"40641b55f315e24dd86236cef4f7b3fc90f4caf05053d224cefa86e6bf27cff6"}
}
Updated
  • Event type: toolpath_updated
  • Event content: "toolpath":{"id":TOOLPATH_ID, "name":TOOLPATH_NAME, "hash":TOOLPATH_HASH}
  • Triggered by: toolpath update (via PUT /api/v1/toolpaths/TOOLPATH_ID)
  • Received by: requesting user

Example

{
 "type": "toolpath_updated",
 "toolpath": {"id":2,"name":"UseCase-PaintingV2","hash":"f6fce38617bb192da5e06a3b3508eeabf568784748ce7e59d8157e70bcc1ce74"}
}
Shared
  • Event type: toolpath_shared
  • Event content: "toolpath":{"id":TOOLPATH_ID, "name":TOOLPATH_NAME, "hash":TOOLPATH_HASH, "sharer":USER_ID}
  • Triggered by: toolpath share (via POST /api/v1/toolpath/share)
  • Received by: share target

Event content values:

  • USER_ID is the identifier of the user that triggered the share (see this endpoint for more details about users' information)

Example

{
 "type": "toolpath_shared",
 "toolpath": {"id": 2, "name": "UseCase-PaintingV2", "sharer": 1, "hash": "f6fce38617bb192da5e06a3b3508eeabf568784748ce7e59d8157e70bcc1ce74"}
}
Deleted
  • Event type: toolpath_deleted
  • Event content: "toolpath":{"id":TOOLPATH_ID, "name":TOOLPATH_NAME, "hash":TOOLPATH_HASH}
  • Triggered by: toolpath deletion (via DELETE /api/v1/toolpaths/TOOLPATH_ID)
  • Received by: requesting user

Example

{
 "type": "toolpath_deleted",
 "toolpath": {"id": 2, "name": "UseCase-PaintingV2", "hash": "f6fce38617bb192da5e06a3b3508eeabf568784748ce7e59d8157e70bcc1ce74"}
}

Lock changed

  • Event type: lock_status
  • Event content: "lock":{"owner":LOCK_OWNER, "status":LOCK_STATUS}
  • Triggered by: robot locking/unlocking (via these endpoints)
  • Received by: everyone

Event content values: see this section

Example

{
  "type": "lock_status",
  "lock": {"owner":"admin","status":"locked"}
}

Waypoint button pressed

  • Event type: backdriving
  • Event content: "waypoint":[0.3802471,0.98264056,-2.177648,0.014669139,-2.048694,0.30105293]
  • Triggered by: pressing the waypoint creation button on the robot head
  • Received by: lock owner

Event content

  • waypoint an array of the robot joint angles at the time of the waypoint button being pressed down

Example

{
  "type": "backdriving",
  "waypoint": [0.3802471,0.98264056,-2.177648,0.014669139,-2.048694,0.30105293]
}

State changed

  • Event type: state_change
  • Event content: "changes":DATA_PROPERTIES
  • Triggered by: robot data changes (when values are manually edited or with normal operations of the arm)
  • Received by: everyone

Event content values:

  • DATA_PROPERTIES will be an object containing one or more of the sub-properties outlined in Snapshot, depending on what data has changed

Example

{
  "type":"state_change",
  "changes": {
    "control": {"loop_count":2,"loop_target":10,"run_mode":"teach","state":"running"},
    "servos.telemetry.velocity": [0,0.5,0,0.3,0,0]
  }
}

Configuration changed

  • Event type: config_change
  • Event content: "kind":KIND_OF_CHANGE, "message":MESSAGE_STATUS
  • Triggered by: network/time change (done by an administrator in the Interface) or fallback to a different mode when the network connection is unavailable
  • Received by: everyone

Event content values:

  • KIND_OF_CHANGE will be a string describing the kind of change:
  • network: an administrator changed the network configuration
  • time: an administrator changed the time configuration
  • network_fallback: when the robot fell back on another network because the configured one was unavailable
  • MESSAGE_STATUS will be describing what is going on

Example

{
  "type": "config_change",
  "kind": "network",
  "message":"Warning: the network settings of this robot are changing, you may be disconnected"
}

Update started

  • Event type: update_in_progress
  • Event content: "message":MESSAGE_STATUS
  • Triggered by: update requested (done by an administrator using the update endpoint or in the Interface)
  • Received by: everyone

Event content values:

  • MESSAGE_STATUS will be describing what is going on

Example

{
  "type": "update_in_progress",
  "message":"Warning: the robot is updating, this operation may take a few minutes, you will be disconnected"
}