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 configurationtime
: an administrator changed the time configurationnetwork_fallback
: when the robot fell back on another network because the configured one was unavailableMESSAGE_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 eitherready
,error
,running
,paused
,stopping
,jogging
orbackdriving
(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 toolpathcontrol.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 enabledscheduler.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 enabledscheduler.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 inputglobal.inputs.d1
(read-only): a boolean indicating the state of the second digital inputglobal.inputs.d2
(read-only): a boolean indicating the state of the third digital inputglobal.inputs.d3
(read-only): a boolean indicating the state of the forth digital inputglobal.inputs.a0
(read-only): a float indicating the value of the first analog inputglobal.inputs.a1
(read-only): a float indicating the value of the second analog inputglobal.inputs.a0_mode
: a string indicating the mode of the first analog input that can be eithervoltage
orcurrent
global.inputs.a1_mode
: a string indicating the mode of the second analog input that can be eithervoltage
orcurrent
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 alwaysvoltage
global.inputs.ee_a1
(read-only): a float indicating the value of the second analog input (end-effector), mode is alwaysvoltage
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 outputglobal.outputs.d1
: a boolean indicating the state of the second digital outputglobal.outputs.d2
: a boolean indicating the state of the third digital outputglobal.outputs.d3
: a boolean indicating the state of the forth digital outputglobal.outputs.a0
: a float indicating the value of the first analog outputglobal.outputs.a1
: a float indicating the value of the second analog outputglobal.outputs.a0_mode
: a string indicating the mode of the first analog output that can be eithervoltage
orcurrent
global.outputs.a1_mode
: a string indicating the mode of the second analog output that can be eithervoltage
orcurrent
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