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.

Request

GET /api/v1/data/snapshot?mode=DATA_MODE

where DATA_MODE is the data mode.

Payload

NONE

Reply

{
  "snapshot": {
    "global.control.loop_target": 1,
    "global.control.robot_state": "ready",
  }
}

or an error.

Editing properties¶

This endpoint allows you to edit the global properties of the Robot. It must receive a list of global properties (without the global prefix) as seen here.

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?mode=DATA_MODE

where DATA_MODE is the data mode.

Payload (example)

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

where changes is a list of properties to change with a new value, see this section for the list of available properties (and if they are writable, etc).

Reply (example)

If everything worked

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

If one or more property was invalid

{
  "error":{
    "status":8,
    "title":"1 invalid change(s)",
    "details":[
      {"index":0,"error":"unknown property: global.outputs.d5"}
    ]
  }
}

If one or more property could not be changed properly

{
  "error":{
    "status":0,
    "title":"1 error(s) encountered",
    "details":{
      "changes":[
        {"error":{"status":1,"title":"internal error","details":null}}
      ]
    }
  }
}

or an error.

Stream¶

A stream of events is available in the form of a Websocket connection. This stream is two-way and can also be used to send events.

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 (without particular order): your API token prefixed by API_ and your data mode.

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: API_APITOKEN, DATA_MODE

where APITOKEN is the token generated by the Interface and DATA_MODE is the data mode.

Payload

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

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":"bk@automata.tech","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":"bk@automata.tech","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":"bk@automata.tech","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}
Triggered by: toolpath creation (via POST /api/v1/toolpaths)
Received by: requesting user

Example

{
 "type": "toolpath_created",
 "toolpath": {"id":2,"name":"UseCase-Painting"}
}

Updated¶

Event type: toolpath_updated
Event content: "toolpath":{"id":TOOLPATH_ID, "name":TOOLPATH_NAME}
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"}
}

Shared¶

Event type: toolpath_shared
Event content: "toolpath":{"id":TOOLPATH_ID, "name":TOOLPATH_NAME, "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}
}

Deleted¶

Event type: toolpath_deleted
Event content: "toolpath":{"id":TOOLPATH_ID, "name":TOOLPATH_NAME}
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"}
}

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"}
}

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 the data that changed, format will vary depending on the data mode of the websocket (see here for more information), content will vary depending on user role (see here for more information)

Example

{
  "type":"state_change",
  "changes":{
    "global.control.loop_target":1,
    "global.control.robot_state":"running",
    "logging":[
      {"message":"2018-01-02T12:41:58+0000 global.control.loop_target changed to 1","level":"state"},
      {"message":"2018-01-02T12:41:58+0000 global.control.robot_state changed to running","level":"state"}
    ]
  }
}

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"
}

Modes¶

The API has several way of representing the Robot's state called Data modes. The default is object.

Object mode¶

In Object mode (object), the state of the Robot is presented as a JSON object containing other JSON objects (with several level of nesting).

This mode represent well the hierarchy of the properties but can be difficult to parse or update.

Example

{
  "control": {
    "loop_count": 1,
    "loop_target": 1,
    "robot_state": "ready"
  }
}

Flat mode¶

In Flat mode (flat), the state of the Robot is presented as a JSON object where each property is a value of the state without any nesting.

This mode is ideal for easy updates (changesets).

Example

{
  "control.loop_count": 1,
  "control.loop_target": 1,
  "control.robot_state": "ready"
}

Properties¶

This section describes the different properties available on the Robot, for writing or reading. Properties will be shown in flat mode, see the previous section to understand how they would be presented in object mode.

Note that only administrators will receive every properties, regular users will only receive a subset. Moreover, not every property is readable or writable, read-only and write-only property will be flagged as well.

Control status¶

State & Loop¶

control.state (read-only, user): a string describing the state of the Robot, can be either ready, error, running, paused, stopping, jogging or backdriving (see this section for more information about control states)
control.loop_count (read-only, user): an integer describing how many loop did the Robot did for the current toolpath
control.loop_target (read-only, user): an integer describing how many loop the Robot must do for the current toolpath

In object mode, properties are grouped under control.

Scheduler¶

scheduler.enabled (read-only, user): a boolean describing if the Scheduler is enabled
scheduler.start_time (read-only, user): a string (format: 13:58:59) describing the time when the Scheduler will automatically start the Robot, relevant only if the Scheduler is enabled
scheduler.stop_time (read-only, user): a string (format: 13:58:59) describing the time when the Scheduler will automatically stop the Robot, relevant only if the Scheduler is enabled

In object mode, properties are grouped under scheduler.

Global¶

General¶

global.estop (read-only, user): a boolean indicating if the estop is pressed or released

In object mode, properties are not grouped.

Inputs¶

See I/O overview for more information.

global.inputs.d0 (read-only): a boolean indicating the state of the first digital input
global.inputs.d1 (read-only): a boolean indicating the state of the second digital input
global.inputs.d2 (read-only): a boolean indicating the state of the third digital input
global.inputs.d3 (read-only): a boolean indicating the state of the forth digital input
global.inputs.a0 (read-only): a float indicating the value of the first analog input
global.inputs.a1 (read-only): a float indicating the value of the second analog input
global.inputs.a0_mode: a string indicating the mode of the first analog input that can be either voltage or current
global.inputs.a1_mode: a string indicating the mode of the second analog input that can be either voltage or current
global.inputs.ee_d0 (read-only): a boolean indicating the state of the first digital input (end-effector)
global.inputs.ee_d1 (read-only): a boolean indicating the state of the second digital input (end-effector)
global.inputs.ee_a0 (read-only): a float indicating the value of the first analog input (end-effector), mode is always voltage
global.inputs.ee_a1 (read-only): a float indicating the value of the second analog input (end-effector), mode is always voltage

In object mode, properties are grouped under global.inputs.

Outputs¶

See I/O overview for more information.

global.outputs.d0: a boolean indicating the state of the first digital output
global.outputs.d1: a boolean indicating the state of the second digital output
global.outputs.d2: a boolean indicating the state of the third digital output
global.outputs.d3: a boolean indicating the state of the forth digital output
global.outputs.a0: a float indicating the value of the first analog output
global.outputs.a1: a float indicating the value of the second analog output
global.outputs.a0_mode: a string indicating the mode of the first analog output that can be either voltage or current
global.outputs.a1_mode: a string indicating the mode of the second analog output that can be either voltage or current
global.outputs.ee_d0: a boolean indicating the state of the first digital output (end-effector)
global.outputs.ee_d1: a boolean indicating the state of the second digital output (end-effector)

In object mode, properties are grouped under global.outputs.

Servos¶

Each servo has its own property, instead of repeating every property for every servo, we will represent the servo with an X which can be an integer between 0 and 5 (inclusive). Example: servo.X.telemetry.position can be servo.0.telemetry.position, servo.1.telemetry.position, ..., servo.5.telemetry.position. Note that in object mode, properties are grouped so that they contain an array of the values (one for each servo instead of having a different property for every servo). Example: servos.telemetry.position -> [0, 0, -1.7, 0, 0, 0].

Telemetry¶

servo.X.telemetry.position (read-only, received in a snapshot or if the Lock is held): a float representing the servo angle in radians