Skip to content

REST API of the Web Server (Current)

Jump to bottom
Bernhard edited this page Oct 15, 2024 · 14 revisions

The organisation of the API is based on the functionalities needed by different user roles: administrator, controller, driver, uploader, and monitor. The API end points are defined in the main function of the server.c file. Note that almost all parameters are passed via HTTP Post (form) data, not via the URL. The response code is used to indicate success or failure of a request. Usually the response code is 200 (OK), 400 (Bad Request), or 501 (Not implemented). For the exact response code behaviour, you do have to study the source code.

Administrator

Maintain overall control of a railway platform at all times.

Startup

Start up the digital railway control boards and initialises the railway components (e.g., points, signals, trains) to defaults.

  • HTTP-Method: POST
  • Endpoint: /admin/startup
  • Parameters: None
  • Return value(s): None

Shutdown

Release all grabbed trains and shuts down the digital railway control boards.

  • HTTP-Method: POST
  • Endpoint: /admin/shutdown
  • Parameters: None
  • Return value(s): None

Setting the track output state

Set the power state of all track outputs.

  • HTTP-Method: POST
  • Endpoint: /admin/set-track-output
  • Parameters:
    • state: integer encoding the state for the requested power state of all track outputs, where: 0 = off, 1 = stop, 2 = soft_stop, 3 = go
  • Return value(s): None

Setting the verification option

Set whether plugins will be verified upon upload.

  • HTTP-Method: POST
  • Endpoint: /admin/set-verification-option
  • Parameters:
    • verification-option: boolean, true (enable) or false (disable)
  • Return value(s): None

Setting the verification url

Set the URL of the verification server to use for verification on upload.

  • HTTP-Method: POST
  • Endpoint: /admin/set-verification-url
  • Parameters:
    • verification-url: string with the verification server url to set
  • Return value(s): None

Releasing a train (forced)

Release a grabbed train.

  • HTTP-Method: POST
  • Endpoint: /admin/release-train
  • Parameters:
    • train: string with the name of the train to force-release
  • Return value(s): None

Setting the speed of a train

Set the DCC speed step of a train.

  • HTTP-Method: POST
  • Endpoint: /admin/set-dcc-train-speed
  • Parameters:
    • train: string with the name of the train whose speed is to be set
    • speed: integer with the requested DCC speed step between 0 and 126, inclusive
    • track-output: string with the name of the digital railway control board to broadcast the requested DCC speed step.
  • Return value(s): None

Controller

Control the track elements (points and signals) of a railway platform, and manage the routes for trains.

Release a route

Release a route.

  • HTTP-Method: POST
  • Endpoint: /controller/release-route
  • Parameters:
    • route-id: string with the id of the route to be released
  • Return value(s): None

Set point

Set the aspect of a point.

  • HTTP-Method: POST
  • Endpoint: /controller/set-point
  • Parameters:
    • point: string with the id of the point whose aspect to set
    • state: string with the aspect to set, usually "normal" or "reverse"
  • Return value(s): None

Set signal

Set the aspect of a signal.

  • HTTP-Method: POST
  • Endpoint: /controller/set-signal
  • Parameters:
    • signal: string with the id of the signal whose aspect to set
    • state: string with the aspect to set, usually "aspect_go" or "aspect_stop" or "aspect_caution" or "aspect_shunt" (not every signal supports every aspect)
  • Return value(s): None

Set peripheral

Set the aspect of a peripheral.

  • HTTP-Method: POST
  • Endpoint: /controller/set-peripheral
  • Parameters:
    • peripheral: string with the id of the peripheral whose aspect to set
    • state: string with the aspect to set, possible values depend on peripheral
  • Return value(s): None

Get the interlocker

Get the name of the interlocker in use.

  • HTTP-Method: POST
  • Endpoint: /controller/get-interlocker
  • Parameters: None
  • Return value(s):
    • String with the name of the interlocker, if an interlocker is in use. No return value if no interlocker is selected.

Set interlocker

Set an interlocker to be used. Note, this will only succeed if no interlocker is currently in use, i.e., "unset interlocker" has been invoked before successfully. Furthermore, the interlocker to be set must already be installed/provided. Use the upload role "get/refresh interlockers" to get a list of currently installed interlockers.

  • HTTP-Method: POST
  • Endpoint: /controller/set-interlocker
  • Parameters:
    • interlocker: string with the name of the interlocker to use
  • Return value(s):
    • String with the name of the interlocker now set if successful, otherwise no return value.

Unset interlocker

Unset an interlocker from use.

  • HTTP-Method: POST
  • Endpoint: /controller/unset-interlocker
  • Parameters:
    • interlocker: string with the name of the interlocker to unset
  • Return value(s): None

Driver

Select and drive a train that is on a railway platform

Grab a train

Grab a train for driving.

  • HTTP-Method: POST
  • Endpoint: /driver/grab-train
  • Parameters:
    • train: string with the name of the train to grab
    • engine: string with the name of the train engine to use for defining the train's driving behaviour
  • Return value(s):
    • String with the format "<session-id>,<grab-id>", where:
      • session-id: (long) integer, number for identifing the servers current session
      • grab-id: integer, number that identifies the train driver with respect to this specific train-grabbing action
    • No return value if this grab request is unsuccessful.

Release a grabbed train

Release the train. Invalidates the connection between train driver and train identified by the grab-id provided when the train was grabbed.

  • HTTP-Method: POST
  • Endpoint: /driver-release-train
  • Parameters:
    • session-id: integer with session id
    • grab-id: integer with grab id
  • Return value(s): None

Request route

Request a route for a grabbed train from a source to a destination signal.

  • HTTP-Method: POST
  • Endpoint: /driver/request-route
  • Parameters:
    • session-id: integer with session id
    • grab-id: integer with grab id
    • source: string with id of the source signal
    • destination: string with id of the destination signal
  • Return value(s):
    • String, which contains...
      • in case of success: number, which is the identifier of the granted route
      • in case of a valid request but failure to grant a route: textual description of why no route was granted
    • No return value if request is invalid, e.g. if the grab id is unknown to the server or if the session id does not match the current server session

Request route by id

Request a specific route (by its ID) for a grabbed train.

  • HTTP-Method: POST
  • Endpoint: /driver/request-route-id
  • Parameters:
    • session-id: integer with session id
    • grab-id: integer with grab id
    • route-id: integer with id of the route to request
  • Return value(s):
    • String, which contains...
      • in case of success: "granted"
      • in case of a valid request but failure to grant the route: textual description of why the route was not granted
    • No return value if request is invalid, e.g. if the grab id is unknown to the server or if the session id does not match the current server session

Get direction for a train

Get a trains required physical driving direction for a given route.

  • HTTP-Method: POST
  • Endpoint: /driver/direction
  • Parameters:
    • train: string with the name of the train
    • route-id: integer with the id of the route
  • Return Values:
    • String with "forwards" or "backwards" (refers to the physical orientation of the locomotive with respect to the source signal, i.e. whether the front of the locomotive should be facing towards or away from the signal respectively). No return value if the request is invalid, i.e. if the train or route-id are not known to the server.

Drive route

Drive a grabbed train along its granted route in automatic or manual mode. In automatic mode, the server controls the train's speed, in manual mode the driver has to set the speed manually, though the server will attempt to stop the train from overshooting the end of the route in both modes (this does not always work flawlessly). Note: If the train reaches the very end of the route (last segment, usually past the destination signal), the server will release the route automatically. If the train stops before the end of the route, the route is not automatically released.

  • HTTP-Method: POST
  • Endpoint: /driver/drive-route
  • Parameters:
    • session-id: integer with session id
    • grab-id: integer with grab id
    • route-id: integer with the id of the route to drive
    • mode: string with the desired mode, either "automatic" or "manual"
  • Return value(s):
    • String with "Route [Route-ID] driving completed" when train has been driven along the route and has reached the destination. No return value if an error/problem is encountered during driving that prevents finishing the route safely. If the route is released manually whilst the route is being driven via this drive-route functionality, the server considers this to be the same as the train reaching the end of the route, i.e. it will stop the train and return as in a normal success case.

Set train speed (DCC)

Set the DCC speed of a grabbed train.

  • HTTP-Method: POST
  • Endpoint: /driver/set-dcc-train-speed
  • Parameters:
    • session-id: integer with session id
    • grab-id: integer with grab id
    • speed: integer with dcc speed between (and including) 0 and 126
    • track-output: string with the name of the digital railway control board
  • Return value(s): None

Set train speed (calibrated)

Set the speed of a grabbed train to a calibrated level, which shall be defined in the configuration for the train in question.

  • HTTP-Method: POST
  • Endpoint: /driver/set-calibrated-train-speed
  • Parameters:
    • session-id: integer with session id
    • grab-id: integer with grab id
    • speed: integer with calibration level in the range 0 to 9, though actual valid values depend on train configuration; 9 is the maximum allowed level at the moment
    • track-output: string with the name of the digital railway control board
  • Return value(s): None

Emergency stop

Perform an emergency stop for a grabbed train.

  • HTTP-Method: POST
  • Endpoint: /driver/set-train-emergency-stop
  • Parameters:
    • session-id: integer with session id
    • grab-id: integer with grab id
    • track-output: string with the name of the digital railway control board
  • Return value(s): None

Set train peripheral

Set a peripheral of a grabbed train.

  • HTTP-Method: POST
  • Endpoint: /driver/set-train-peripheral
  • Parameters:
    • session-id: integer with session id
    • grab-id: integer with grab id
    • peripheral: string with the name of the peripheral
    • state: string with the state to set the peripheral to
    • track-output: string with the name of the digital railway control board
  • Return value(s): None

Upload

Upload a train engine

Upload a train engine model.

  • HTTP-Method: POST
  • Endpoint: /upload/engine
  • Parameters:
    • file: file with an SCChart model (.sctx) of a train engine, name of the model in the file shall match the filename (without the extension); input/output interface shall match the default (input int requested_speed, bool requested_forwards; output int nominal_speed, bool nominal_forwards). If verification is enabled, there are further requirements for the train engine model, which are not all documented here - contact the maintainers in that case.
  • Return value(s):
    • If upload does not succeed, single line string with reason for failure. If successful, no return value.

List train engines

Get a list of (names of) available train engines.

  • HTTP-Method: POST
  • Endpoint: /upload/refresh-engines
  • Parameters: None
  • Return value(s):
    • Single line string with names of engines, each separated by ",".

Remove a train engine

Remove an uploaded train engine from the system.

  • HTTP-Method: POST
  • Endpoint: /upload/remove-engine
  • Parameters:
    • engine-name: string with the name of the engine to remove
  • Return value(s):
    • If removal does not (or only partially) succeed, single line string with reason for failure. If successful, no return value.

Upload an interlocker

Upload an interlocker written in BahnDSL.

  • HTTP-Method: POST
  • Endpoint: /upload/interlocker
  • Parameters:
    • file: File of the Interlocker, shall be a valid BahnDSL file with .bahn file extension
  • Return value(s):
    • If upload does not succeed, single line string with reason for failure. If successful, no return value.

List interlockers

Get a list of (names of) available interlockers.

  • HTTP-Method: POST
  • Endpoint: /upload/refresh-interlockers
  • Parameters: None
  • Return value(s):
    • Single line string with names of interlockers, each separated by ",".

Remove an interlocker

Remove an uploaded interlocker. An interlocker can only be removed if it is not currently in use. Also, the default interlockers bundled with the server are (usually) not removable.

  • HTTP-Method: POST
  • Endpoint: /upload/remove-interlocker
  • Parameters:
    • interlocker-name: string with the name of the interlocker to remove
  • Return value(s):
    • If removal does not (or only partially) succeed, single line string with reason for failure. If successful, no return value.

Monitor

Provide information about the state of a/the railway.

List trains

Get a list of trains and their grab-status. All trains configured in the config files will be listed.

  • HTTP-Method: POST
  • Endpoint: /monitor/trains
  • Parameters: None
  • Return value(s):
    • Multiline String with info on all known trains, one line per train, where a line has the shape "<train-name> - grabbed: <yes/no>"; for example "cargo_db - grabbed: yes".

Get state of a train

Get the state of a train.

  • HTTP-Method: POST
  • Endpoint: /monitor/train-state
  • Parameters:
    • train: string with the name of the train whose state to get
  • Return value(s):
    • Single line string with entries, each separated by " - " (space dash space). Example with the first three entries: "grabbed: yes - on segment: seg1, seg2 - on block: block1"
      • grabbed: "yes" or "no"
      • on segment: list of segment ids which the train occupies if any, separated by ", "
      • on block: id of block which the train occupies if any
      • orientation: orientation of the train ("left" or "right")
      • speed step: the currently set DCC speed step
      • detected speed: the speed converted to km/h (written as "<speed> km/h"), speed 0 if the train does not support reporting its speed in km/h
      • direction: the driving direction of the train ("forwards" or "backwards")

List train peripherals

Get a list of peripherals of a train.

  • HTTP-Method: POST
  • Endpoint: /monitor/train-peripherals
  • Parameters:
    • train: string with the name of the train whose peripherals to get
  • Return value(s):
    • Multiline string, one line per peripheral, where a line has the shape "<peripheral-name> - state: <on/off>"

Get track outputs

Get a list of track outputs.

  • HTTP-Method: POST
  • Endpoint: /monitor/track-outputs
  • Parameters: None
  • Return value(s):
    • Multiline string, one line per track output, where one track output line has the shape "<track-output-name> - state: <state-of-track-output>". The different values for the state are {off, stop, soft stop, go, go + ignore watchdog, prog, prog busy, busy, query, off}. Note that these may change depending on the version of BiDiB supported by the server.

Get points

Get a list of points.

  • HTTP-Method: POST
  • Endpoint: /monitor/points
  • Parameters: None
  • Return value(s):
    • Multiline string, one line per point, where one point line has the shape "<point-id> - state: <target-state-of-point> " (the trailing space is no typo). Additionally, for some points at the end of the line there's an additional entry about whether the target state has been reached; if present it says "(target state reached)" or "(target state not reached)" depending on the situation of the point. If such additional info is provided, no trailing space is present.

Get signals

Get a list of signals.

  • HTTP-Method: POST
  • Endpoint: /monitor/signals
  • Parameters: None
  • Return value(s):
    • Multiline string, one line per signal, where a line has the shape "<signal-id> - state: <target-state-of-signal>"

Get point aspects

Get the aspects that a particular point supports.

  • HTTP-Method: POST
  • Endpoint: /monitor/point-aspects
  • Parameters:
    • point: string with id of the point whose aspects to get
  • Return value(s):
    • Single line string with the names of supported aspects, separated by ", ". E.g., could be "normal, reverse".

Get signal aspects

Get the aspects that a particular signal supports.

  • HTTP-Method: POST
  • Endpoint: /monitor/signal-aspects
  • Parameters:
    • signal: string with id of the signal whose aspects to get
  • Return value(s):
    • Single line string with the names of supported aspects, separated by ", ". E.g., could be "aspect_go, aspect_caution, aspect_stop".

Get segments

Get a list of segments with information about occupancy.

  • HTTP-Method: POST
  • Endpoint: /monitor/segments
  • Parameters: None
  • Return value(s):
    • Multiline string, one line per segment, where a segment line has the shape "<segment-id> - occupied: <yes/no>". If occupied is "yes", and at least one dcc address has been detected on the segment, then the line also contains (appended) info on the occupying trains, in the shape of: " trains: <list-of-train-ids>", where in the list of train ids the entries are separated by ", ". If no train is known for a detected dcc address, the corresponding entry is "unknown".

Get reversers

Get a list of (track loop) reversers.

  • HTTP-Method: POST
  • Endpoint: /monitor/reversers
  • Parameters: None
  • Return value(s):
    • Multiline string, one line per reverser, where a line has the shape "<reverser-id> - state: <unknown/off/on>"

Get peripherals

Get a list of peripherals.

  • HTTP-Method: POST
  • Endpoint: /monitor/peripherals
  • Parameters: None
  • Return value(s):
    • Multiline string, one line per peripheral, where a line has the shape "<peripheral-id> - <peripheral-state-name>: <peripheral-state-value>"

Get verification option

Get whether train engines will be verified upon upload (Verifier not included in this project - only if swtbahn-verifier is setup and configured).

  • HTTP-Method: GET
  • Endpoint: /monitor/verification-option
  • Parameters: None
  • Return value(s):
    • String with shape "verification-enabled: <true/false>".

Get verification url

Get the URL to the verification server currently configured (related to the not-yet-open-source swtbahn-verifier).

  • HTTP-Method: GET
  • Endpoint: /monitor/verification-url
  • Parameters: None
  • Return value(s):
    • String with shape "verification-url: <currently-set-url>". If no URL is set, the url is represented in the string as "null".

Get granted routes

Get a list of currently granted routes along with the trains which the routes are granted to.

  • HTTP-Method: POST
  • Endpoint: /monitor/granted-routes
  • Parameters: None
  • Return value(s):
    • Multiline string, one line per granted route, where a line has the shape "route id: <route-id> train: <id-of-train-to-which-the-route-is-granted>". If no routes are granted, it is the single line string "No granted routes" instead.

Get route

Get the details of a route.

  • HTTP-Method: POST
  • Endpoint: /monitor/route
  • Parameters:
    • route-id: string with id of the route whose details to get
  • Return value(s):
    • Multiline string, with the following 'entries', one entry per line, in shape "<entry>: <value>". The entries as follows. Note that every entry except route id and status has two spaces preceding it on its line:
      • route id: route id
      • source signal: id of the source signal
      • destination signal: id of the destination signal
      • orientation: "clockwise" or "anticlockwise"
      • length: real/float length of the route, usually in centimeters
      • path: path of the route in terms of track elements the train passes in order of route progression, elements separated by ", "
      • sections: List of sections (blocks) the route traverses, elements separated by ", "
      • points: List of points the route traverses, elements separated by ", "
      • conflicting route ids: List of route ids conflicting with the route
      • status: empty line behind "status:", separates static information above from dynamic info below
      • granted conflicting route ids: List of route ids of granted routes that are conflicting with the route; if no conflicting routes are granted the value is "none"
      • route clear: "yes" if route is clear of obstacles, otherwise "no"
      • granted train: name of the train the route is granted to, if the route is not granted this is "none"
Clone this wiki locally