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:

Data format

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

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.

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

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.

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 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.