SimSig WTT and WTR file format

Last modified 2014-04-07

Introduction

This page describes the format of the v2 SimSig WTT timetable files and WTR timetable rules files used in executable simulations. The Loader can read this format but does not generate it.

General concepts

The WTT and WTR files are binary files, not text.

The formats are described in terms of "units"; some types of unit are defined in terms of other types.

The word "must" indicates an absolute requirement. Any file not conforming to this requirement is not a valid SimSig file. The wording "should X but may Y" indicates that either X or Y must apply; software generating files is strongly recommended to choose option X, but software reading files needs to be aware that Y could happen instead. Option Y is more likely to be made invalid if the format changes.

Byte values are shown within boxes; sequences of boxes are read from left to right (that is, the leftmost box comes first in the file). Each box holds one byte unless it contains "..." or otherwise says so. All numbers are decimal. Three letter codes such as BRK are ConvData names for data items.

Adjacent units should be consecutive in the file, but there may be any number of bytes with value 0 between units.

Basic units

The following types of unit are used throughout these format descriptions.

I-unit

An I-unit holds an integer. There are three possible encodings. The shortest possible one should be used for any given value, but longer ones may be used.

In each case the value is stored in 2s-complement little-endian form. Thus the first format can be used for values between -128 and +127 inclusive, and the second format for values between -32768 and +32767 inclusive. Thus

S-unit

An S-unit holds a string. There are two possible encodings. For strings of up to 255 characters, the shorter one should be used but the longer one may be used.

In both cases the length gives the number of characters in the string. Thus:

Q-unit

A Q-unit holds a truth value or option. There are two possible encodings:

B-unit

A B-unit holds several truth values or options. It is encoded as an I-unit; the value must be positive. The value is broken into individual bits, with 1 meaning the option is chosen and 0 meaning it is not. The bits are numbered from 0 as the least significant bit. Thus:

Unused bit values should be set to 0.

T-unit

A T-unit holds a time in seconds past midnight. It has the same representation as an I-unit. Thus:

Counted units

A counted-XXX-unit represents a list of XXX-units. It consists of an I-unit giving the number of XXX-units (which might be zero) followed by that number of XXX-units. For example:

WTT files

A WTT file consists of:

• WTT-header-unit
• counted-train-type-unit
• counted-timetable-unit

WTT-header-unit

A WTT-header-unit consists of:

• S-unit, must be "SIMSIGT2"
• I-unit, must be 2
• S-unit, SIM
• S-unit, NAM
• S-unit, DES
• T-unit, STT
• T-unit, END

train-type-unit

A train-type-unit consists of:

• S-unit, name of the train type
• S-unit, DES
• I-unit, BRK
• I-unit, SCL
• I-unit, CSH
• Q-unit, FRT
• I-unit, MXS
• I-unit, LEN
• B-unit, PWR

The SCL and CSH values should be present but may both be omitted (but not only one). The BRK, PWR, and SCL values are encoded as follows:

timetable-unit

A timetable-unit consists of:

• S-unit, headcode; however, if the last character is "+" then that is not part of the headcode but, rather, indicates IOT=T.
• I-unit, BRK
• Q-unit, RWR
• I-unit, RRP
• I-unit, DLY
• Q-unit, DLW
• I-unit, ENT, or -1 if SDP is present
• S-unit, DES
• S-unit, ENP or SDP
• I-unit, MXS
• I-unit, CSR
• B-unit, SCL
• Q-unit, ETD
• Q-unit, FRT
• I-unit, LEN
• Should be:
  • Q-unit, must be true, ignored
  • S-unit, UEP
  • B-unit, PWR (bits 0 to 3), PWS (bits 8 to 11)
  • B-unit, EWN (bits 0 to 3), SPT (bit 4), BON (bit 5), ENA (bit 6), AQT (bit 7), EOT (bit 8), AEP (bit 9).
    The encoding for EWN is 0=no, 1=on phone, 3=ready to enter, 4=on entry queue.
  but may instead be:
  • B-unit, PWR (bits 0 to 3), SPT (bit 4), BON (bit 5), AQT (bit 7), PWS (bits 8 to 11, but if bit 6 is clear, then PWS equals PWR and bits 8 to 11 are ignored), EOT (bit 12), EWN (bits 13 and 14), AEP (bit 15).
    The encoding for EWN is 0=no, 1=on phone, 2=on phone (case 2), 3=ready to enter.
    If EWN equals 1 or 2, then ENA=T.
    If EWN is non-zero, then UEP is the same as ENP; otherwise it is unset.
• S-unit, TYP
• counted-timing-point-unit

The encodings of BRK and PWR are the same as above; PWS is the same as PWR. SCL should be present but may be omitted.

If ENT does not begin with "E" and the simulation does not have an entry point with that name, the Loader will prefix an "E" and try again.

timing-point-unit

A timing-point-unit consists of:

• S-unit, timing point code; however, if the first character is "*" then that is not part of the timing point but, rather, indicates AUI=T.
• T-unit, DEP, negated to indicate SDO=T
• T-unit, ARR
• S-unit, PLT
• S-unit, LIN
• S-unit, PTH
• I-unit, ENA in units of half a minute
• I-unit, PTA in units of half a minute
• stopping-unit
• counted-action-unit

stopping-unit

A stopping-unit should consist of:

• B-unit, PAS (bit 0), TLS (bit 1), DPD (bit 2), PPD (bit 3), NPD (bit 4), STP (bits 6 to 8), BER (bit 12). Bit 9 is set if ADJ is not omitted.
• I-unit, ADJ in metres (may be omitted if zero)

but may consist of:

• Q-unit, PAS
• Q-unit, DPD

in which case TLS is false, PPD and NPD are U, STP is Default, and ADJ is 0.

STP is encoded as follows:

action-unit

An action-unit consists of:

• I-unit, encoding the action type
• I-unit, encoding the ACI state; this may be omitted if zero
• S-unit, giving the relevant headcode

The action type is encoded as follows:

The ACI state is encoded as follows:

WTR files

A WTR file consists of:

• WTR-header-unit
• counted-rule-unit

WTR-header-unit

A WTR-header-unit consists of:

• S-unit, must be "SIMSIGRULES"
• S-unit, must be the same as SIM in the WTT-header-unit

rule-unit

A rule-unit consists of:

• S-unit, headcode of the controlled train
• I-unit, RUL
• S-unit, LOC
• T-unit, TIM
• S-unit, headcode of the controlling train
• I-unit, ignored, should be zero
• I-unit, ignored, should be zero

The RUL value is encoded as follows:

Back to the SimSig index. Back to the Rail index. Back to Clive's home page.