Interfaces and Rulesets

Management of railway components

Trains

• Each train has a trainnumber.
  
  • Apart from identification the trainnumber is used for prioritization, when multiple trains compete for the same track.
  • Lower numbers mean higher priorities, e.g. train 0 has the highest priority.
  • Priorities can't be changed dynamically.
• Each train has one home-track.
• For binding purposes the variable should have the name trainNum.

The numbering is derived from the initial positions of the trains.

Tracks

• Stopping on tracks without contacts is not allowed!
• Tracks without contacts must be reserved and used with an adjacent "safe" track.
• When requesting multiple locks, deadlocks must be prevented
• Three different speed settings are available, adjusted to the individual trains:
  • NORMAL - Normal driving speed
  • CAUTION - Speed when slowing down while waiting for permissions (and optionally for branch points)
  • SLOW - Driving into a station

Contacts

• Contact events should only be read when it is clearly determined which train will trigger this event.
• Subsequently contact events should only be read while holding the corresponding lock.

Stations

• Each station has one drive-through track for each possible direction:

• If the preferred station track is blocked the trains can switch to any other free track.
  While cleanup is active the trains on IC_ST_1, OC_ST_3 or KH_ST_1 circle until all tracks are done.

Rulesets

Logging

• All log messages must be prefixed. For Station-2-Station controllers the prefix [trainnum][ST-ST] must be used.
• The variable debug indicates verbose logging.
• Station-2-Station controllers should produce a log message when entering a new train segment even without verbose logging.
• With verbose logging every state can produce a log message as an entry action.
• Function println(String str) must be used to produce textual output.
• printf() or other IO functions must not be used, because output may not be flushed correctly.

Codestyle

• Use entry-/exit-actions instead of actions on transitions, if possible.
• If using hostcode, only use functions delivered by our own C-Interface and not the Höhrmann-API.

Deadlock Prevention

• When attempting to reserve more than one segment (entering a station, passing a junction) a separate protocol for deadlock prevention must be adhered to.
• In each tick the controller must check if only partial permissions were granted.
• If partial permission was granted the train waits for one tick and releases all locks.
• In the following tick the locks are requested again.
• As a special case the controllers passing through KIO_LN_0 or KIO_LN_1 must wait an additional tick after releasing the requests.
• A sample controller can be found in the repository at /doc/deadlocks/resolve_deadlock.sct