evaalapi.md

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
# IPIN competition interface

A user is given one or more unique trial names `TRIAL` and a server URL for accessing the web API.

Accessing the server URL with a browser shows basic pointer to documentation and source code.

## API overview

The trial maintains a `trial timestamp` and a position estimate. Initially, the `trial timestamp` is 0.  The trial has not started, and this can be verified with

    GET /TRIAL/state

which will return a string starting with `0,-1`, meaning that the trial has not started yet.  Then the ILS starts a sequence of providing position estimates and getting data until the end of the trial.

In the usual workflow, the ILS provides a new position estimate every 0.5 s (the recommended value) and gets sensors data by issuing a series of commands (that is, HTTP requests) like this

    GET /TRIAL/nextdata?position=10.422057,43.718278,1&horizon=0.5

The position estimate is set, relative to the `trial timestamp`, then the `trial timestamp` is advanced by 0.5 s.  A number of comma-separated data rows are returned whose timestamps are in increasing order.  The data timestamps belong to the interval from the previous `trial timestamp` (included) to the current `trial timestamp` (excluded).

If no data rows are received, one of the following apply:

 - no data is available for the requested interval, but data are available further on; the position estimate is set; the `trial timestamp` is updated; return code is 200
 - no more data are available for this trial because the trial has finished normally; the position estimate is ignored; the `trial timestamp` is not updated; return code is 405
 - the trial has finished because of a timeout; the position estimate is ignored; the `trial timestamp` is not updated; return code is 405


### Data format

The data format is trial-dependent, in CSV (comma-separated values) format with the following contraints:

 - data is served as CSV-format text lines
 - the first numeric field is the line's timestamp
 - each line's timestamp is not less than the previous line's.


### Timeout

Ideally, data should be exchanged in real-time, as for on-site competitions, but this is not generally possible because of network processing delays and network latency.  As a compromise, a timeout is defined as follows.  Times are in seconds.

 - Let `p` be the clock time of the previous `nextdata` command
 - Let `h` be the `horizon` of the previous `nextdata` command
 - Let `c` be the clock time of the current `nextdata` command

For a real-time system, like an ILS for an on-site Track, we always have

    h == c-p

To account for processing delays and network latency, we define

 - `V` as the trial speed increase factor
 - `S` as the slack time
 - `s` as the remaining slack, which is initially set to `S`

Whenever a `nextdata` command is sent, the following is computed

    s += V*h - (c-p)
    if s>S then s=S
    if s<0 then Timeout

In any moment when `s>0` the time remaining until timeout is

    rem = p + V*h + s - current_clock

## Commands

This web API does not follow REST principles: all commands are HTTP requests using `GET`, and both the `nextdata` and `reload` commands can explicitly change the status of the system.  This architectural choice is done to reflect the normal workflow and minimise the number of web calls.  Moreover, the system status depends on the number of milliseconds since the first `nextdata` command, so generally speaking the system status changes even when no command is given.

### GET /TRIAL/state

Returns an ASCII one-line string of 7 comma-separated numbers followed by an unquoted string.  The 'V', 'S' and 'REM' values are relative to timeout computation.

 - `0,-1,V,S,0,0,0,POS`
   the trial has not started; `POS` is the initial position (a string)
 - `TS,REM,V,S,p,h,PTS,POS` (numbers are floats, times are in seconds, `POS` is a string) the trial is running; `TS` is the `trial timestamp`, `PTS` is the timestamp relative to the last position estimate `POS`; all numbers are non-negative apart from `REM`, which is negative if `nextdata` would return timeout
 - -`1,REM,V,S,p,h,PTS,POS`
   the trial has finished; `REM` is the slack time at the time of the last `nextdata` command; it is not less than 0 if the trial has finished normally and less than 0 if it has finished by timeout; the other parameters are those in effect after the last `nextdata` command issued when the trial was running

In Python, the string can be read with type checking by using
`parse("{trialts:f},{rem:f},{V:f},{S:f},{p:f},{h:f},{pts:f},{pos:S}", string)`

Returns error 404 if `TRIAL` does not exist.


### GET /TRIAL/nextdata (options position, horizon)

Sets the trial position estimate, returns an ASCII multiline string in comma-separated format, advances the timestap.  The first numeric field in each returned row is the `trial timestamp` in seconds, all other fields are trial-specific.

With option `position=POS` a position estimate is set relative to the `trial timestamp`.  `POS` is a string in a trial-dependent format.  For example, it can consist of three comma-separated numbers `longitude,latitude,height`.  Longitude and latitude are in degrees, ranging from -180.0 to 180.0.  Height is trial-dependent, for example it can be defined as an integer number indicating the floor number, where 0 is the ground floor, positive numbers are floors above ground and negative numbers are floors below ground.  The trial position estimate is set to `POS` if the trial is running and the `trial timestamp` is greater than 0: the position estimate at 0 is defined as the initial position.

After possibly setting the position estimate, data rows for the next H seconds are returned and the `trial timestamp` is updated.  Option `horizon=H` sets the horizon to a non-negative float (default `horizon=0.5`).  For example when no `horizon` option is present, the default of 0.5&nbsp;s is assumed, and all data rows are returned with timestamps greater or equal to `trial timestamp` and smaller than `trial timestamp` plus half a second.  Finally, the `trial timestamp` advances by H seconds.

Returns error 405 if the trial has finished, whether normally or because of a timeout; the position estimate is ignored; the `trial timestamp` does not change; returns the state data as with command `state`.

Returns error 422 if any option does not conform to the above rules; the position estimate is ignored; the `trial timestamp` does not change; no data are returned.

Returns error 404 if `TRIAL` does not exist.


### GET /TRIAL/reload

This command is used to set the state of the trial to not started.  It only works for test trials.

If the trial is reloadable, put it in the not started state and return its state.  Same if the trial
is not reloadable and no log was generated.

Delete the log file unless using option `keeplog`.

Returns error 422 if used on an official (not reloadable) trial.

Returns error 404 if `TRIAL` does not exist.


### GET /TRIAL/estimates

Returns the estimates in csv format with header.

The first line is the header: `pts,c,h,s,pos`.  The following lines contain 4 comma-separated numbers and an unquoted string: the position timestamp, the estimation wall clock, the horizon requested at estimation, the slack time at estimation and the position estimate.

Returns error 404 if `TRIAL` does not exist.

Returns error 405 in the nonstarted state, as no estimates exist.


### GET /TRIAL/log

Returns the log file in plain text format or, if using `xzcompr` option, in xz compressed form.

Returns error 404 if `TRIAL` does not exist.

Returns error 405 if no log file.


### GET /TRIAL/COMMAND

Returns error 403 unless `COMMAND` is one of the above commands

Returns error 404 if `TRIAL` does not exist.


<!-- Local Variables: -->
<!-- fill-column: 100 -->
<!-- End: -->