General

In this part of the documentation is the description of the environment SCChart, the inherent hierarchy and the handling of error messages.
The environment is simulated based on the behavior of each train moving along the same system of tracks in parallel SCChart regions. Except for some error cases described below there is not much interaction between the separate trains. The environment was divided into a hierarchy, where the main SCChart implements some variable bindings and misbehavior and error checking. Also 11 parallel regions are modeled, each of them containing a copy of the train SCChart. The train SCChart again implements some error checking and bindings. Furthermore it imports the wagon SCChart twice, modeling front and rear wagons respectively. The wagon SCChart is the biggest model, beside the usual error checking it implements the entire track layout and simulates the movements of one wagon on the tracks according to the given inputs from the interface.

Wagon SCChart

Although this chart is the bottom most in the environment hierarchy, it is also the core and implements the entire movement of a single wagon along the tracks. For easier understanding of the functionality, it is also split into multiple steps, each handling a specific part and case.

The exact position of each wagon is tracked by three variables: track holds the track of the wagon (e.g. 25 standing for KH_ST_1, 39 standing for OC_LN_5, 32 standing for KIO_LN_1 etc. as described in the interface), pos is telling the position of the wagon on the track in mm, starting from the beginning of the track in its main travel direction. A bit more complicated is the variable branch. It saves the position on a track with branches. Here the value stands for the track this branch is leading to (eg. the branch KH_LN_4 on the track KH_LN_2 is the branch that should be taken on the Kicking Horse Pass for every train driving forwards through it). Pieces of such tracks, that do not lead to another track are numbered with -1 as the main track piece and -2, -3 and -4 for further pieces not leading directly to another track. The values -2 to -4 only appear in the three stations, -2 being the short piece between points 1 and 2, -3 the one between points 2 and 3 and -4 being the last one between points 3 and for on KH_ST_0. This can represent every possible position a train can be on the railway.
An example:
track = 40, position = 10, branch = 32 represents a wagon standing on OC_ST_0 ( track = 40), standing on the piece coming from the KIO_LN_1 (branch = 32) between the transition of the tracks and the diamond point with the numbers 27 and 28. On that piece it stands just 10mm behind the beginning of the track (position = 10).

The wagon SCChart updates the pos value based on the power given to its track and updates the track. The pos and branch values are updates according to the track length and point position values for each possible case. If a contact position is crossed, a signal will as defined in the interface will be forwarded.

Another big part of this SCChart is part of the error handling. Some errors can be checked at this level already. For instance a wagon crossing a point from two branches to one, with the point being branched to the branch the wagon was not coming from. This deficient point state and some other errors are documented in the interface page under errors.

Train SCChart

This SCChart contains two references to the wagon chart representing the front and rear wagon of a train and thus defining the whole area a train will stretch over. Those two wagons are also the only ones with magnets activating the contacts. This is a relatively lightweight implementation to track an entire train and all its interactions with the interface. 

Further error checking that is available at the level of the train is checked here. If a point that the train is occupying is branched while the train is standing on top of it, an error is thrown. Likewise if the train has different power levels on two tracks it is positioned on, another error is thrown. Details can be found in the error interface again.

Environment SCChart

This is the main chart to be executed when simulating the railway environment. It imports the train SCChart 11 times for the up to 11 trains that can drive on the railway simultaneously. Next to that the behavior of the railway crossing and collision error checking between trains is implemented here. Every other lamp, signal and so on are also added just like mentioned in the interface and acts as forwarding of the input as own outputs again.

The trains' positions get set up here, as explained in the next section.

Usage

The project can be built the standard way by building it with KIELER with an executable environment as a result. This is best viewed together with the railway visualization, described on its own page.

While executing, the input train_setup has to represent the starting positions of all trains, with the values for each track as described in the interface in the initial tick. Trains should only start on the tracks 8 to 10, 25 to 29 and 41 to 43 (IC, OC and KH stations) with negative values -25 to -29 standing for trains starting on the kicking horse station in reverse direction. Trains that should not be modeled should have their train_setup set to 0. The inputs track_speeds and points should then be set according to the desired movement of the trains. Testing a program with the environment first is safer, as errors and collisions are easily visible when viewing the error outputs or the visualization. Besides it is far less costly when something badly programmed interacts with the modeled railway.

To get the environment executed in sync with the controller from this project the file EnvCont or EnvCont_Linux has to be launched by KIELER after both the environment and controller project are imported and successfully built.