Train variables are designed to oversee the use of QTU throttles in a layout where each track section is connected to its own QTU output. The essential attributes this arrangement provides includes:
A known track length attached to each throttle output (even if the length varies with turnout setting).
Dead-reckoning can track the position of each train as it travels along the known track length.
The train travels from one QTU throttle to another in a pre-defined sequence (as defined by the route it has chosen).
The benefits of using train objects to oversee operations include:
Train speed (and brake & inertia) can be controlled in one place.
Provides a single data line of the screen for the use to observe and control train settings.
Constant display of which track section a train is on and how far it has moved.
Dead-reckoning position and stopAt positions are measured in distance (not integral numbers as used in the QTUs).
Speed limits stored against any throttle are implemented by the train object.
Throttle settings (speed after inertia and feedback) are copied from one throttle to the next to ensure smooth transitions between sections.
The following data elements are stored in each train variable, and are visible in the trains window.
|
Element name |
Read/Write |
Description |
|
speed |
R/W |
Defines how fast this train should travel. Values from 0 (stopped) to 100 (full speed) are allowed. Copied to QTUs. |
|
dir |
R/W |
Direction. Currently this field does nothing as it is NOT copied to the QTUs as they might be wired in opposite directions for some movements. |
|
brake |
R/W |
When brake is non-zero the speed sent to the throttle is temporarily set to zero and so the train will slow (gradually if momentum is applied) to a stop. When brake is set back to zero the train will (gradually) resume the speed setting in the speed value. Copied to QTUs. |
|
mom |
R/W |
Momentum, also called inertia. Defines how rapidly the train can change speed during acceleration, deceleration and braking. Values range from 0 (no inertia, train changes speed instantly) to 255 (quite gentle speed changes). Copied to QTUs/ |
|
length |
R |
Reports the length of the train once a measurement has been taken. Length is the sum of head, tail and pickup. |
|
cal |
R/W |
The dead-reckoning calibration coefficient calculated for this train. Is set once the train has been calibrated. Zero until then. |
|
currentQtu |
R |
Which QTU (and hence track) the train the train is traversing. |
|
locoPos |
R |
Where on 'currentQtu' the train is presently, measured in DR distance units. |
|
trackLength |
R |
How long the 'currentQtu' track section is, in DR distance units. |
|
fullSpeed |
R |
|
|
speedLimit |
R |
The current speed limit, or zero if none applies presently. |
|
noCurrent |
R |
The time that no current has been detected for this train. A useful indication of dirty track or derailment. |
|
head |
R |
The measured length from the leading edge of the train to the first pickup. |
|
tail |
R |
The measured length from the first pickup to the trailing edge of the train. |
The following methods are available for each train:
|
Method name |
Description |
|
headPosition (&qtu) x=headPosition (&q1) |
Returns the distance that the front of the train has travelled in the specified section. If the train has not yet arrived in the specified section (but is due to do so) then the distance will be negative. If the train has travelled on to further sections the distance will be longer than the length of the specified section. |
|
tailPosition (&qtu) |
Returns the distance the rear of the train has travelled in the specified section. Refer to headPosition for further details. |
|
stopAt (&qtu, distance, flags) stopAt (&qtu, distance, flags, entryGap) stopAt (&qtu, dist, fl, entryGap, exitGap) |
Tells the train to stop when the front of the train reaches 'distance' along specified section. Flags can be: 0=front, 1=center, 2=rear, 4=fit and adjust the stopping location so that the fron/center/rear of the train is at the location specified. If 'fit' is added to the flags then an adjustment is made to ensure that the train fits in the section – useful if you tell a long train to stop early in a section. If the train will not fit then it stops at the end of the section and overflows into the previous one. Entry gap indicates how much empty track is required at the entry of the section, perhaps to clear a turnout. Exit gap indicates how much empty track to leave at the exit of a section. |
|
addQtu (&qtu) addQtu (&qtu, length) addQtu (&qtu, &realQtu, length) addQtu (&qtu, extra params, length) |
Adds the specified QTU to the end of the route this train is following. This must be done before any other methods referencing the same QTU. If more than one parameter is given then length is the last parameter and specifies how long the track is, measured in your chosen distance units and this value is used by the dead-reckoning system. If the second parameter is a pointer to a QTU then it is taken to be a physical QTU that is shared among several sections. The first parameter is assumed to be a virtual QTU – one declared but not physically equipped. Extra parameters can include one numeric value – an entry length which is added to the length parameter. This is useful where track lengths vary – for example if the track is preceded by a turnout. Other extra parameters include any number of CTC segments, see description for addCtcCells for a description. |
|
addCtcCells (ctc cell, …) eg. addCtcCell ([3,2,1], “L13”) |
Any number of CTC cell definitions which can include any mix of cell addresses and meta data names. This method has the same effect as adding the same list of parameters to the previously executed addQtu call. The CTC cell list is used to animate the CTC diagram showing where the train is and how much of the track it occupies. It is important that the first few cells are added in the correct sequence otherwise the animation could be reversed. |
|
setQtuLength (&qtu, length) |
Defines how long the track section is electrically. This assumes that any variable lengths such as might occur with turnouts has already been handled. |
|
setEntryLength |
|
|
setDefaultLengths (head, tail) |
Sets initial head and tail so that the train has a guessed length instead of zero which counts as uncalibrated. Having a default length means that tracks behind are released and points cleared at that distance. |
|
addQtuLength (&qtu, length) |
Add to the previously defined length for this track section. Might be used if a turnout at the exit of the section were to be set after the train has entered. |
|
removeQtu (&qtu) |
Releases a QTU from this train after the train has cleared that section. Must be done before adding the Qtu to another section. If a QTU is virtual and has a real QTU associated with it then removing either will remove both. |
|
sensorChanged (&qtu, distance, state) |
Indicate that a position sensor has changed state in this section. This is used to calibrate and refine the measured lengths of this train. It is important that this method be called as soon as possible after the end of the train passes the sensor. The distance parameter defines where the sensor is, and the state indicates '1' for train present, '0' otherwise. |
|
locoPosition |
The position of the first loco pickup along the section. Not normally useful. |
|
addSpeedLimit (&qtu, position, speed) |
Stores a speed limit at the position (measured in DR distance units) along section &qtu for the specified scale speed (measured in the units used when setSpeedCal is called). Note that the qtu must already be added to a train. |
|
setSpeedCal (speed) |
Stores a speed setting that represents a scale train speed of 100. Units could be MPH, KPH or anything you choose. This affects speed limit calibrations. |
|
setDefaultCal (cal) |
Saves a global calibration setting that will be used for all uncalibrated trains. |
|
getTrNo (&qtu) |
Return the train number using the specified QTU. Any train object can be queried for this data. |
|
loadDb () |
Load location, calibration, head & tail lengths and min & max speeds from the “trains” table in the database. |
|
loadLocoData (loco number) |
Lookup calibration data in the database table “locos” for the given loco number in the locoid column. |
|
setTrainColour (colour, extent) |
Specifies the colour to be used in animating the CTC diagram (if ctc cells are given in addQtu () or addCtcCells (). If extent is supplied it defines the colour of track booked for the train and is specified either as a colour, or a percentage. If a percentage is less than 100 it darkens the train colour for use as extent, if over 100 it brightens it. |
|
setFirstClassName (name) |
Define the name of the first class we are using. The name should be the name of a constant and subsequent constants are used for other classes. If the class of a train is set to a numeric value then this is used to convert the numeric into a label, for the trains window display and subsequent database save. |
For an example of how these are used, look at an auto-generated script, generated from a TDL file that specifies QTU & DR, such as jax9.
Last updated 26 Oct 2010
© Howard Amos 2007-2010