Skip to content

End Points

Jump to bottom
Jan Červený edited this page Mar 26, 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>",  # e.g. "PBR-01"
  "device_class": "<device class>",      # e.g. "PSI"
  "device_type":  "<device type>",       # e.g. "PBR"
  "address":      "<device address>"     # e.g. "/dev/usb/port0"
}

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.

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>",  # e.g. "PSI-PBR-01-task-measure-all-01"
  "task_class": "<task class>",      # e.g. "PSI"
  "task_type":  "<task type>"        # e.g. "PBR_measure_all"
}

All requests must provide a unique task_id and a valid task_class and task_type - check complete list of supported tasks or their documentation.

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.

Command

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

{
  "device_id":  "<target device id>",                                                     # e.g. "PBR-01"
  "command_id": "<ID of the command as specified in the Device's interpreter>",           # e.g. "3"
  "arguments":  "[<arguments ordered as expected by the command, separated by a comma>]", # e.g. "[30]"
  "source":     "<the signature of the command>",                                         # e.g. "manual"
  "await":      "<wait for command result>"                                               # e.g. True
}

The request must include the target device's device_id and valid command_id as specified in the device's interpreter (available in the documentation of individual devices). 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. The optional field await allows to wait for the command to be executed and result is obtained in the response; otherwise, result is stored in the events (False by default). Please note the command execution is not stored in events if await is True.

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 valid 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 log-ID. To retrieve only more recent data than a specific log-ID, you can pass the last known log-ID in the URL:

http://<ip>:<port>/data?device_id=<id>&type=<type>&log_id=<log-ID>

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

http://<ip>:<port>/data?device_id=<id>&type=<type>&time=<YYYYmmddHHMMSSfff>

Keep in mind that time-stamp and log-ID are mutually exclusive (cannot be combined) and make sure to use correct format YYYYmmddHHMMSSfff for the time-stamp.

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

{
  "<log-ID>": {
    "time": datetime,  # time of measurement
    "value": float,    # value of measured quantity
    "dev_id": str,     # identification of associated device
    "var_id": str,     # identification measured quantity
    "attribute": int,  # a special flag (check docs)
    "note": str        # additional information
  }, 
  ...
}

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

{
  "<log-ID>": {
    "dev_id": str,      # identification of associated device
    "event_type": int,  # identification of the event
    "time": datetime,   # time of occurrence
    "command": int,     # identification of associated command
    "args": list,       # arguments of the command
    "response": dict,   # content of the event
  }, 
  ...
}

Additionally, use endpoint http://<ip>:<port>/data?device_id=<id>&type=<type> to obtain latest log-ID for the data type.

End

The option to terminate 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>",           # e.g. "task"
  "target_id": "<id of the task or device>"  # e.g. "PSI-PBR-01-task-measure-all-01"
}

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 this device to exist 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.

Ping

In order to check which devices are connected and which tasks are currently running, 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 fixed according to the documentation or reported.

Clone this wiki locally