SimSig WTT and WTR file format

Last modified 2007-01-03

Introduction

This page describes the format of the SimSig WTT timetable files and WTR timetable rules files.

The intention of the SimSig development team is that any changes to this format will be upwards-compatible. However, this cannot be guaranteed.

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.

2 value
3 lsb msb
4 lsb nlsb nmsb msb

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

2 250
 represents the value -6
3 16 4
 represents the value 1040.

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.

6 length char ... char
 the length is an unsigned value from 0 to 255
12 lsb nlsb nmsb msb char ... char
 the four bytes form an unsigned little-endian integer giving the length

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

6 3 65 66 67
 represents the string "ABC"
12 3 0 0 0 65 66 67
 also represents the string "ABC"
6 0
 represents the empty string ""

Q-unit

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

8
 represents false, no, or unticked
9
 represents true, yes, or ticked

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:

2 5
 represents the options corresponding to bits 0 (value 1) and 2 (value 4)
3 130 1
 represents the options corresponding to bits 1, 7, and 8

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:

2 120
 represents the time 00:02
3 242 28
 represents the time 02:03H

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:

the counted-S-unit
2 2 6 1 65 6 2 66 67
 represents the list of strings ("A", "BC")
the counted-I-unit
2 3 3 16 4 2 67 2 254
 represents the list of three numbers (1040, 67, -2)
the counted-XXX-unit
2 0
 represents an empty list

WTT files

A WTT file consists of:

WTT-header-unit

A WTT-header-unit consists of:

train-type-unit

A train-type-unit consists of:

The CSL and CSH values should be present but may be omitted. The BRK and PWR values are encoded as follows:

BRK PWR
Encoding  Meaning
0 VSlow
1 Slow
2 Med
3 High
4 Metro/Light
  
Bit  Meaning
0 AC
1 3rd-rail
2 4th-rail
3 Diesel

timetable-unit

A timetable-unit consists of:

The encodings of BRK and PWR are the same as above.

timing-point-unit

A timing-point-unit consists of:

stopping-unit

A stopping-unit should consist of:

but may consist of:

in which case TLS is false.

action-unit

An action-unit consists of:

The action type is encoded as follows:

Encoding  Meaning
0 Next
1 DR
2 DF
3 Join

WTR files

A WTR file consists of:

WTR-header-unit

A WTR-header-unit consists of:

rule-unit

A rule-unit consists of:

The RUL value is encoded as follows:

Encoding  Meaning
0 MAAE
1 MAAL
2 MAAA
3 NOTIF
4 DAA
5 DAE
6 DAL
7 DAJ
8 DAD
9 DAF
10 MX
11 MAAJ
12 MAAD
13 MAAF

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