User Tools

Site Tools


wibed:unified-api

A crontab job in the nodes makes an HTTP POST request to the server to update and get information.

http://serverIP/api/wibednode/<node_id>

If a node with the specified node_id didn't exist before, it is added to the system with this call - ad-hoc insertion of nodes.

Nodes are only made available for experiments if they are in the IDLE status, time of last contact < DEAD_THRESHOLD and firmware version up to date (??).

Input

JSON object containing the following basic attributes:

model <STRING> The model of the node (only if status == 0).
version <STRING> Frimware installed on the node (only if status == 0).
status <INT> The status of the node.

Status can be one of:

0 - INIT (initial default state and state after upgrade)
1 - IDLE (waiting for orders)
2 - PREPARING (downloading and preparing the experiment (downloads tar.gz but not installs it))
3 - READY (overlay downloaded and ready to be installed)
4 - DEPLOYING (overlay installed and node is rebooting)
5 - RUNNING (node is ready for the experiment)
6 - RESETTING (node is resetting to its default configuration)
7 - UPGRADING (upgrading firmware)
8 - ERROR (some error detected)

Additional attributes in the JSON object (depending on status):

Status 1, 4 or 8:
commandAck <INT> ID of the last received command from the server (prevents resending of received commands).
results <LIST> Dict where key corresponds to the commandId and value to a 3-tuple (exitCode, stdout, stderr), describing the result of the execution of a command.
Status 8 (ERROR):
lastStatus <STR> Last status before error.
info <STR> Arbitrary information about error (can be null).

Output

JSON object containing different attributes depending on the node status and experiments running or upgrades available.

experiment <OBJ> Object describing experiment details.
upgrade <OBJ> Object describing firmware upgrade details.
commands <LIST> Dict where keys represent command ids and values command strings.
resultAck <INT> The id of the last result received from the node (prevents resending of received results).
reinit EMPTY A directive to set the node back to INIT state intializing also other values.
Experiment object
id <INT> Id of the experiment.
action <STR> One of PREPARE (download overlay), RUN (install overlay and reboot), FINISH (end and remove overlay).
overlay <STR> Identifier of the overlay which can then be used as: <serverUrl>/static/overlays/<overlay>.
hash <MD5> MD5 hash of the overlay
Upgrade object
version <STR> Identifier of the firmware version which can be obtained from: <serverUrl>/static/firmwares/<version>.
utime <INT> UNIX time to upgrade the node
url <URL> HTTP/FTP URL to download new firmware
hash <MD5> MD5 hash of the new firmware image

In experiment

Status = IDLE
{
  "experiment": {
    "id": <ID>,
    "overlay": <OVERLAYID>,
    "action": "PREPARE"
  }
}
Status = PREPARING
{}
Status = READY/RUNNING and Experiment Status = RUNNING
{
  "experiment": {
    "action": "RUN"
  }
  "commands": {
    "<COMMAND_ID": <COMMAND_STRING>,
    ...
  }
  "resultAck": <COMMAND_ID> // Similar to commandAck but for the results sent by the node.
  }
}

Outside experiment

Status = IDLE

If there's an upgrade available:

{
  "upgrade": {
    "version": <VERSION>
  }
}

If no upgrades are available:

{}
Status = PREPARING/READY/RUNNING
{
  "experiment": {
    "action": "FINISH"
  }
}
Status = UPGRADING
{}

Example

REQUEST = {
  "model": "lol",
  "version": "1.0.0",
  "status": 0
}
 
RESPONSE = {}

Node 1 is added to experiment with id = 2.

REQUEST = {
  "status": 1
}
 
RESPONSE = {
  "experiment": {
    "action": "PREPARE", 
    "id": 2, 
    "overlay": "124235"
  }
}

Node 1 starts installing overlay.

REQUEST = {
  "status": 2
}
 
RESPONSE = {}

Node 1 finishes installing overlay but experiment was not started yet.

REQUEST = {
  "status": 3
}
 
RESPONSE = {}

2 commands are added to the experiment and it is then started.

REQUEST = {
  "status": 3
}
 
RESPONSE = {
  "experiment": {
    "action": "RUN", 
  }
  "commands": {
    "1":"sudo ps -a",
    "2":"sudo yaupdate"
  }
}
REQUEST = {
  "status": 4
  "commandAck": 2
}
 
RESPONSE = {}

Node 1 finishes execution of command 1, with exit code 0, stdout = “LOL”, stderr = “”.

REQUEST = {
  "status": 4,
  "commandAck": 2,
  "result": {"1": [0, "LOL", ""]}
}
 
RESPONSE = {
  "resultAck": 1
}

Node 1 finishes execution of command 2, with exit code 2, stdout = “ROFL”, stderr = “MAO”.

REQUEST = {
  "status": 3,
  "commandAck": 2,
  "result": {"2": [2, "ROFL", "MAO"]}
}
 
RESPONSE = {
  "resultAck": 2
}

Experiment is then finished.

REQUEST = {
  "status": 3,
  "commandAck": 2,
  "result": {"2": [2, "ROFL", "MAO"]}
}
 
RESPONSE = {
  "experiment": {
    "action": "FINISH"
  }
}
REQUEST = {
  "status": 1
}
 
RESPONSE = {}
wibed/unified-api.txt · Last modified: 2014/01/09 02:40 by savemanos