Latest revision as of 12:22, 1 June 2023

The Train Describer feed provides low-level detail about the position of trains and their train reporting number through a network of berths. Usually, but not always, a berth is associated with a signal - but there are locations (such as terminal platforms at stations) where there may be more than one berth. From each berth, there are zero or more other berths which a train description may step in to. A step between berths represents movement of the train from one berth to another. Some of these steps may be one-way, some may be two-way.

To access the TD data feed, you must select and subscribe to the appropriate geographical topic(s) on the My Feeds page on the Data Feeds website (see the about the feeds page.)

See also the list of train describers page, where you will find information on specific TD's including user contributions & documentation provided by Network Rail such as S-Class data, maps and stepping data.

Topics

Train Describer messages (C-Class and S-Class) are presented on a single ActiveMQ topic named TD_ALL_SIG_AREA. Previously, they were also available on a number of separate topics however the mappings had not been updated for many years.

For historical reference, the geographical topics were:

Former topic	Description
TD_SE_SIG_AREA	Scotland - East
TD_SW_SIG_AREA	Scotland - West
TD_LNE_NE_SIG_AREA	London North Eastern - North East
TD_MC_EM_SIG_AREA	Midlands & Continental - East Midlands
TD_LNE_GN_SIG_AREA	London North Eastern - Great Northern
TD_LNW_LC_SIG_AREA	London North Western - Lancashire and Cumbria
TD_LNW_C_SIG_AREA	London North Western - Central
TD_LNW_WMC_SIG_AREA	London North Western - West Midlands Central
TD_WCS_SIG_AREA	West Coast - South
TD_ANG_SIG_AREA	Anglia
TD_KENT_MCC_SIG_AREA	Kent and Midlands & Continental
TD_SUSS_SIG_AREA	Sussex
TD_WESS_SIG_AREA	Wessex
TD_WTV_SIG_AREA	Western - Thames Valley
TD_WWC_SIG_AREA	Western - West Country
TD_WWM_SIG_AREA	Western Wales and Marches

Message types

The Train Describer feed has seven message types, split into two classes. See individual pages for further details.

C-Class Messages provide information about train describer berths and descriptions
S-Class Messages provide signalling state information

Cross-midnight bug

There is a known issue with the TD feed that can cause a very small number of messages to be given an incorrect timestamp. The NR TD feed assumes that all TD events occur on the date they are received by the feed. This assumption is almost always correct but can be wrong for messages received <1s before midnight. Such messages can easily be spotted and corrected by comparing the timestamp in the message to the current time (in UTC) and adjusting by 24 hours if there is a large difference.

The impact of this is very minor, usually only 3-5 messages out of the approx. 1.5-2 million published by the feed on a typical day. However, it may affect latency monitoring of the feed, so affected messages should be corrected or ignored in such calculations.

Examples and Source Code

Network Rail Open Data Feeds
Data Feeds	About the Feeds • Account States • Durable Subscriptions • Example Code ( PHP / C# / Java / Ruby / Node.js) • Advanced Uses • FAQ • Release Notes
RTPPM	RTPPM Feed
Train Movements	Train Movements Feed • Train Activation • Train Cancellation • Train Movement • Train Reinstatement • Change of Origin • Change of Identity • Change of Location • TSPEED Field • Planned Cancellations • Cancellation Codes
TD	TD Feed • C-Class Messages • S-Class Messages • Train Describers • TD Berths
VSTP	VSTP Feed
TSR	TSR Feed • Route Codes
SCHEDULE	SCHEDULE Feed • TIPLOC Records • Schedule and Location Records • Association Records • CIF Codes • How Scheduling Works • Allowances
Reference Data	Reference Data Feed • TOC Codes • CIF Codes • Delay Attribution Codes • Identifying Locations (STANOX, TIPLOC, NLC and 3-Alpha Codes) • STANOX Geographical Areas • Train Planning data (BPLAN)

@@ Line 1: / Line 1: @@
-= Train Describer (TD) Feed =
+The Train Describer feed provides low-level detail about the position of trains and their train reporting number through a network of [[TD_Berths|berths]].  Usually, but not always, a berth is associated with a signal - but there are locations (such as terminal platforms at stations) where there may be more than one berth.  From each berth, there are zero or more other berths which a train description may step in to.  A step between berths represents movement of the train from one berth to another.  Some of these steps may be one-way, some may be two-way.
-== Overview ==
+To access the TD data feed, you must select and subscribe to the appropriate geographical topic(s) on the ''My Feeds'' page on the Data Feeds website (see the [[About_the_feeds|about the feeds]] page.)
-The Train Describer feed provides low-level detail about the position of trains and their train reporting number through a network of berths.  Usually, but not always, a berth is associated with a signal - but there are locations (such as terminal platforms at stations) where there may be more than one berth.
+See also the [[List_of_Train_Describers|list of train describers]] page, where you will find information on specific TD's including user contributions & documentation provided by Network Rail such as S-Class data, maps and stepping data.
-From each berth, there are zero or more other berths which a train description may move, or 'step' in to.  Some of these may be one-way, some may be two-way.
+= Topics =
-=== Topics ===
+Train Describer messages (C-Class and S-Class) are presented on a single ActiveMQ topic named '''TD_ALL_SIG_AREA'''.  Previously, they were also available on a number of separate topics however the mappings had not been updated for many years.
-Message are available in geographic feeds, as well as an country-wide feed.  The topic names are as follows:
+For historical reference, the geographical topics were:
 {| class="wikitable"
-!Topic
+!Former topic
 !Description
-|-
-|TD_ALL_SIG_AREA
-|All signalling areas
 |-
 |TD_SE_SIG_AREA
@@ Line 38: / Line 35: @@
 |TD_LNW_C_SIG_AREA
 |London North Western - Central
+|-
+|TD_LNW_WMC_SIG_AREA
+|London North Western - West Midlands Central
 |-
 |TD_WCS_SIG_AREA
@@ Line 62: / Line 62: @@
 |TD_WWM_SIG_AREA
 |Western Wales and Marches
+|-
 |}
-=== Message types ===
+= Message types =
-The Train Describer feed has seven message types:
-* '''CA''' - Berth Step, where a description moves 'from' a berth, 'to' another berth
-* '''CB''' - Berth Cancel, where a description is removed from a berth
-* '''CC''' - Berth Interpose, where a description is interposed (placed in to) a berth
-* '''CT''' - Heartbeat
-* '''SF''' - Signalling data update
-* '''SG''' - Signalling data refresh
-* '''SH''' - Signalling data refresh finished
-The CA, CB, CC and CT messages are referred to as C-Class, and the SF, SG and SH messages are referred to as S-Class.
-=== C-Class ===
-Messages are sent in JSON format, as follows:
-* {"CA_MSG":{"time":"1349696911000", "area_id":"SK", "msg_type":"CA", "from":"3647", "to":"3649", "descr"=>"1F42"}}
-* {"CB_MSG":{"time":"1349696911000", "area_id":"G1", "msg_type":"CB", "from":"G669", "descr"=>"2J01"}}
-* {"CC_MSG":{"time":"1349696911000", "area_id":"G1", "msg_type":"CC", "descr":"2J01", "to":"G669"}}
-* {"CT_MSG":{"time":"1349696911000", "area_id":"SA", "msg_type":"CT", "report_time":"1249"}}
-==== CA message ====
-The CA message is a 'step' message.  This moves the description from the 'from' berth, in to the 'to' berth, cancelling the description in the 'from' berth and overwriting any description in the 'to' berth.
-==== CB message ====
-The CB message is a 'cancel' message.  This cancels the description in the 'from' berth.
-==== CC message ====
-The CC message is an 'interpose' message.  This inserts the description in to the 'to' berth, overwriting any description in the 'to' berth.
-==== CT message ====
-The CT message is a 'heartbeat' message, periodically sent from a train describer.
-=== S-Class ===
-Messages are sent in JSON format, as follows:
-* {"SF_MSG":{"time":"1349696911000", "area_id":"WJ", "msg_type:"SF", "address":"3E", "data":"18", "report_time":"073814"}}
-* {"SG_MSG":{"time":"1349696911000", "area_id":"WJ", "msg_type:"SG", "address":"30", "data":"900000C0", "report_time":"073814"}}
-* {"SH_MSG":{"time":"1349696911000", "area_id":"WJ", "msg_type:"SH", "address":"30", "data":"900000C0", "report_time":"073814"}}
-S-Class messages report the status of the following signalling elements:
-* '''Signal aspects''' - whether the signal is displaying its most restrictive aspect or not
-* '''Points''' - whether the points are set normal or reverse
-* '''Route set''' - the route set from a signal to another signal or bay platform
-* '''TRTS buttons''' - the status of a Train Ready to Start button, used by train dispatch staff to indicate to the signaller that platform duties are complete
-* '''Level crossings''' - whether they are lowered or raised
-* '''Track circuits''' - whether a particular track circuit is occupied or not
-Not all train describers support S-Class data, and those that do may only support a subset of the available groups of data.  The [[List of TDs]] shows S-Class support.
-==== Interpreting S-Class data ====
+The Train Describer feed has seven message types, split into two classes. See individual pages for further details.
-Consider the S-Class data as a set of 2,048 bits, grouped in to bytes numbered from 0x00 to 0xFF.  Each bit relates to a particular signalling element.
+* [[C_Class_Messages | C-Class Messages]] provide information about train describer berths and descriptions
+* [[S_Class_Messages | S-Class Messages]] provide signalling state information
-Each time an element changes state, an SF message is sent with the value of the elements in the entire byte.
+= Cross-midnight bug =
+There is a known issue with the TD feed that can cause a very small number of messages to be given an incorrect timestamp.  The NR TD feed assumes that all TD events occur on the date they are received by the feed.  This assumption is almost always correct but can be wrong for messages received <1s before midnight.  Such messages can easily be spotted and corrected by comparing the timestamp in the message to the current time (in UTC) and adjusting by 24 hours if there is a large difference.
-Every few hours, the state of all bits is sent as a 'refresh' in a series of SG messages with the value of groups of four bytes.  These messages are terminated with an SH message.
+The impact of this is very minor, usually only 3-5 messages out of the approx. 1.5-2 million published by the feed on a typical day.  However, it may affect latency monitoring of the feed, so affected messages should be corrected or ignored in such calculations.
-To decode the set of addresses and bits in to signalling elements, several other sets of data are required:
+= Examples and Source Code =
+* [https://github.com/openraildata/td-example-python3 Python example]
+* [https://github.com/openraildata/td-trust-example-elixir Elixir example]
-* A mapping table containing a list of bits and the signalling elements to which they refer
+{{Navtable-DataFeeds}}
-* A diagram containing signal numbers, routes available from signals, point numbers and track circuit detail
-These translation tables are currently in the process of being gathered.
+[[Category:Train Describer Data]]
+[[Category:C Class Messages]]
+[[Category:S Class Messages]]