Skip to content

End Points

Jump to bottom
Matej Troják edited this page Mar 18, 2021 · 8 revisions

Device initiation

To initiate new device, send a POST request to http://<ip>:<port>/device with valid JSON data of the following structure:

{
  "device_id": "<unique device id>",
  "device_class": "<device class>",
  "device_type": "<device type>",
  "address": "<device address>"
}

All requests must provide a unique device_id; a valid device_class and device_type - check complete list of supported devices or their documentation; and an address on which DeviceControl can find the device (usually identification of a port).

Furthermore, certain devices may require multiple additional parameters to be passed in the POST request in order for the device to initiate and function properly. Always check the documentation for the targeted device in order to prevent errors.

If the device was successfully initiated, a response code of 200 will be received. If you received 400 as a response code, there was a problem with your request. Check body of the response to identify the particular issue.

Task initiation

To initiate a certain task, send a POST request to http://<ip>:<port>/task with valid JSON data of the following structure:

{
  "task_id": "<unique task id>",
  "task_class": "<task class>",
  "task_type": "<task type>",
  "additional_parameter": "<parameter>"
}

All requests must provide a unique task_id and a valid task_class and task_type.

Furthermore, certain task may require multiple additional parameters to be passed in the POST request in order for the task to initiate and function properly. In some cases, even encapsulation of other tasks is possible. Always check the documentation for the targeted task in order to prevent errors.

Response code will be 200 on success, 400 otherwise (check body of the response to identify a particular issue).

Command

In order to execute a particular command manually, send a POST request to http://<ip>:<port>/command with valid JSON data of the following structure:

{
  "device_id": "<target device id>",
  "command_id": "<ID of the command as specified in the Device's interpreter>",
  "arguments": "[<arguments ordered as expected by the command, separated by a comma>]",
  "source": "<a signature for the command>"
}

The request must include the target device's device_id and valid command_id as specified in the device's interpreter. The arguments field is optional in general but must be provided if the given command requires it. Otherwise, even though the command may be accepted, it will not be executed. The source field is optional as well and if not provided, a default external signature will be saved.

Ping

In order to check which devices are connected and which tasks are currently running, one may send a GET request to http://<ip>:<port>/ping. In the response, the server will provide a JSON with the the following pattern:

{
  "devices": {
    "<device id>": bool
  },
  "tasks": {
    "<task id>": bool
  }
}

Each device will have a Boolean value according to the result of its test_connection() method. Each task listed in the response should have a true value, as inactive tasks are to be automatically deleted. The occurrence of a false value indicates faulty implementation of the task and should be corrected according to the standards or reported.

Get data

To retrieve data measured for a specific device, send a GET request to http://<ip>:<port>/data?device_id=<id>&type=<type>. It is necessary to provide device_id in the request as the data are always device-related. Another argument is type, which is either values or events, determining what kind of data will be retrieved from the server.

Both values and events are identified by an id. To retrieve only more recent data than a specific ID, you can pass the last known ID in the URL:

http://<ip>:5000/data?device_id=<id>&type=<type>&log_id=<id>

or alternatively provide last known time-stamp of received data:

http://<ip>:5000/data?device_id=<id>&type=<type>&time=<YYMMDDHHMMSSfff>

Keep in mind that only one of these options may be used (cannot be combined) and ensure that the correct format is used when using the timeargument (YYMMDDHHMMSSfff).

In the case of values, the request returns a JSON response with the following structure:

{
  "<log_id>": {
    "channel': int, 
    "dev_id": str, 
    "note": bool, 
    "time": datetime, 
    "value": float, 
    "var_id": str
  }, 
  ...
}

and in the case of events it has the following structure:

{
  "<log_id>": {
    "command': int, 
    "args": list, 
    "dev_id": str, 
    "event_type": int, 
    "response": dict,
    "time": datetime
  }, 
  ...
}

End

The option to end devices and tasks is provided to the user at http://<ip>:<port>/end - a POST request with data of the following structure is expected:

{
  "type": "<device, task or all>", 
  "target_id": "<id of the task or device>"
}

To end a device, provide a string "device" in the type field and a valid device ID in the target_id field. To end a task, provide a string "task" in the type field and a valid task ID in the target_id field. Keep in mind that ending a device without ending tasks which expect the device to exists will cause these tasks to fail or the device to not be terminated properly.

TBD: this should be checked and such device cannot be terminated / all related tasks must be also terminated

To end all current devices and tasks, provide a string "all" in the type field. The target_id field is not necessary in this case.

TBD: not true, need to be fixed

Clone this wiki locally