Wiki source code of Interfaces and Rulesets

Last modified by cbu on 2025/01/30 12:05
Show last authors
1
2
3 {{toc/}}
4
5 == Management of railway components ==
6
7 === Trains ===
8
9 * Each train has a trainnumber.\\
10 ** Apart from identification the trainnumber is used for prioritization, when multiple trains compete for the same track.
11 ** Lower numbers mean higher priorities, e.g. train 0 has the highest priority.
12 ** Priorities can't be changed dynamically.
13 * Each train has one home-track.
14 * For binding purposes the variable should have the name **trainNum**.
15
16 The numbering is derived from the initial positions of the trains.
17
18 |=(((
19 trainNum
20 )))|=(((
21 Starting track
22 )))
23 |(((
24 0
25 )))|(((
26 KH_ST_1
27 )))
28 |(((
29 1
30 )))|(((
31 KH_ST_2
32 )))
33 |(((
34 2
35 )))|(((
36 KH_ST_3 (r)
37 )))
38 |(((
39 3
40 )))|(((
41 KH_ST_4 (r)
42 )))
43 |(((
44 4
45 )))|(((
46 IC_ST_3
47 )))
48 |(((
49 5
50 )))|(((
51 IC_ST_2
52 )))
53 |(((
54 6
55 )))|(((
56 OC_ST_2
57 )))
58 |(((
59 7
60 )))|(((
61 OC_ST_1
62 )))
63 |(((
64 8
65 )))|(((
66 KH_ST_5
67 )))
68 |(((
69 9
70 )))|(((
71 IC_ST_1
72 )))
73 |(((
74 10
75 )))|(((
76 OC_ST_3
77 )))
78
79 === Tracks ===
80
81 * Stopping on tracks without contacts is **not** allowed!
82 * Tracks without contacts must be reserved and used with an adjacent "safe" track.
83 * When requesting multiple locks, deadlocks must be prevented
84 * Three different speed settings are available, adjusted to the individual trains:
85 ** NORMAL - Normal driving speed
86 ** CAUTION - Speed when slowing down while waiting for permissions (and optionally for branch points)
87 ** SLOW - Driving into a station
88
89 === Contacts ===
90
91 * Contact events should only be read when it is clearly determined which train will trigger this event.
92 * Subsequently contact events should only be read while holding the corresponding lock.
93
94 === Stations ===
95
96 * --Each station has one drive-through track for each possible direction:--
97
98 |=(% style="margin-left: 60.0px;" %)(% style="margin-left: 60.0px;" %)
99 (((
100 --station--
101 )))|=(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
102 (((
103 --drive-through track--
104 )))
105 (% style="margin-left: 30.0px;" %)|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
106 (((
107 --IC_station--
108 )))|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
109 (((
110 --IC_ST_1--
111 )))
112 (% style="margin-left: 30.0px;" %)|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
113 (((
114 --OC_station--
115 )))|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
116 (((
117 --OC_ST_3--
118 )))
119 (% style="margin-left: 30.0px;" %)|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
120 (((
121 --KH_station--
122 )))|(% style="margin-left: 30.0px;" %)(% style="margin-left: 30.0px;" %)
123 (((
124 --KH_ST_5--
125 )))
126 (% style="margin-left: 30.0px;" %)|(% colspan="1" style="margin-left: 30.0px;" %)(% colspan="1" style="margin-left: 30.0px;" %)
127 (((
128 --KH_station(r)--
129 )))|(% colspan="1" style="margin-left: 30.0px;" %)(% colspan="1" style="margin-left: 30.0px;" %)
130 (((
131 --KH_ST_1--
132 )))
133
134 * If the preferred station track is blocked the trains can switch to any other free track.
135 While **cleanup** is active the trains on IC_ST_1, OC_ST_3 or KH_ST_1 circle until all tracks are done.
136
137 == Rulesets ==
138
139 === Logging ===
140
141 * All log messages must be prefixed. For Station-2-Station controllers the prefix** [trainnum][ST-ST]** must be used.
142 * The variable **debug** indicates verbose logging.
143 * Station-2-Station controllers should produce a log message when entering a new train segment even without verbose logging.
144 * With verbose logging every state can produce a log message as an entry action.
145 * Function //println(String str)// must be used to produce textual output.
146 * //printf()// or other IO functions must not be used, because output may not be flushed correctly.
147
148 === Codestyle ===
149
150 * Use entry-/exit-actions instead of actions on transitions, if possible.
151 * If using hostcode, only use functions delivered by our own C-Interface and not the Höhrmann-API.
152
153 === Deadlock Prevention ===
154
155 * When attempting to reserve more than one segment (entering a station, passing a junction) a separate protocol for deadlock prevention must be adhered to.
156 * In each tick the controller must check if only partial permissions were granted.
157 * If partial permission was granted the train waits for one tick and releases all locks.
158 * In the following tick the locks are requested again.
159 * As a special case the controllers passing through KIO_LN_0 or KIO_LN_1 must wait an additional tick after releasing the requests.
160 * Another special case for the KHIC-Controller: A train is at KIO_LN_0 and requests OC_ST_4, IC_ST_0 and the tracks of the IC-Station. If the train gets the permission for OC_ST_4 but not for IC_ST_0 and any of the tracks of the IC-Station, the controller waits for an additional tick before re-requesting, so that a train with a lower priority, which travels along the OC-Circle, can pass. It was observed, that this change makes the traffic more fluent.
161 * A sample controller can be found in the repository at [[/doc/deadlocks/resolve_deadlock.sct>>url:https://git.rtsys.informatik.uni-kiel.de/projects/PRAK/repos/14ss-railway/browse/doc/deadlocks/resolve_deadlock.sct||shape="rect"]]
162 * Further deadlock avoidance is implemented in the ICKHS and OCKHS controllers. If the circle ICKH-KHIC-Circle (OCKH-KHOC-Circle) is full (which means, that all trains have the status "brake"), then one of the trains travels the IC-Circle (OC-Circle), to unlock the deadlock. Our tests have shown, that it is still possible, that the same train has to unlock the deadlock again, so that it never reaches its destination, but at least the other trains reach their destination. This concept could also be adapted to the OCOC and ICIC controllers. Use with care, as these controllers have not been tested to exhaust. Basically the controller wraps the ICKH and ICIC (OCKH and OCOC) controller. If the circle is full (checked at hostcode.c), the slightly changed ICKH (OCKH) controller is aborted or not even started, and instead, the ICIC (OCOC) controller is started. At the hostcode.c file, there is an array, which keeps track of the status of all tracks, where 0 means OFF, 1 means REV or FWD and 2 means BRAKE. To keep it simple, the tracks, where the 11-trains are initially standing are initialized with 2.