## Release notes for the UK Train System Cross-platform.NET Plugin for openBVE
(UkTrainSys.dll)

Plugin version: 0.3.1.9
Author: Anthony Bowden
Project homepage: http://railsimroutes.net/libraries/uktrainsys/
Target simulator: openBVE v1.2.9.2x upwards
Target CLI: Microsoft .NET 2.0 / Mono 2.x
Usage and redistribution: Open source (public domain, no conditions - credit appreciated though)

### Contents

- Introduction
- - Note for openBVE train developers
- Plugin features (current and planned)
- Starting states
- Plugin variables for train developers
- - General controls and safety systems
  - AI Support
  - Sound variables
- Virtual key assignments for train developers and users
- Beacon types for route developers
- - More information
  - A note regarding backwards compatiblity
  - Beacon types and the Automatic Power Control system
  - Beacon types and the AI Guard
  - Beacon types and the AI Support feature
  - Beacon types and the Automatic Warning System (AWS)
  - Beacon types and the Train Protection and Warning System (TPWS)
  - - For advanced developers - interleaving and nesting TPWS induction loops
  - Beacon Types and Legacy behaviour
- The UkTrainSys configuration file
- Information for programmers
- - General design principle summary
  - Cab Controls class
  - Safety System classes
  - Interlock Manager
  - Power supply classes
  - Sound playback
  - Offset Beacon Receiver Manager class
  - Source Code

### Introduction

The new UK Train System cross-platform .NET plugin (UkTrainSys.dll) is designed for use with UK mainline trains developed for openBVE. The inspiration behind the development of this plugin, is odakyufan's plugin for his Chashinai Railway project, as well as Simon Gathercole's previous generation of UKXXx.dll range of plugins for BVE 4. This new plugin is designed specifically for openBVE and written in C#, is cross-platform compatible, features the functionality of diesel and electric trains in a single assembly, and will feature more sophisticated simulation once the project develops further. This new plugin is also open source, as well as being released into the public domain.
Please note that this project is ongoing. This is an alpha version of the plugin, and this early version is intended primarily for testing and feedback from train developers, but anyone is welcome to give it a try, and non-Windows users of openBVE can also now benefit from plugin functionality with UK electric and diesel-eletric trains (to begin with).
This plugin is designed to be modular, and aims to simulate the major systems found in a range of UK trains in a realistic way, including the Automatic Warning System, Train Protection and Warning System, Driver Reminder Appliance, the Vigilance Device, and so-on. A simple AI guard is included, along with AI Support, which enables the plugin to assist openBVE's built-in AI human driver in automatically handling systems simulated by the plugin. Animations relating to the AI driver's interactions with cab controls are supported, as well. A range of power supplies are also simulated, including a battery, overhead supply, and a diesel engine. Other features, such as windscreen wipers and failure modes, will follow later.
Note for openBVE train developers:
If you are an openBVE train developer and decide to use the UkTrainSys plugin, then if you wish, you can contact me to let me know, and I can then let you know whenever the plugin is updated.
Trains which use Simon Gathercole's UKMUt.dll, or UKSpt.dll, can use UkTrainSys.dll instead, although some configuration changes may be necessary with the train in question (especially with regard to the guard's buzzer).
The development of this plugin is an ongoing project, and sometimes I might make changes which require your train to be updated. I'm not able to develop your train for you, but if a change to the plugin means that your train needs to be updated in order to continue working correctly, you can contact me for assistance, or I can make any necessary configuration changes for you, if necessary. :-)

### Plugin features (current and planned)

Current feature summary:

- Automatic Warning System (AWS);
- Train Protection and Warning System (TPWS) - Standard and Plus;
- Driver Reminder Appliance (DRA);
- Vigilance Device with reduced cycle time option;
- Traction and brake interlocks;
- Battery which can be discharged, recharged and overloaded;
- Overhead supply, including neutral sections;
- Pantograph, including ACB/VCB;
- Automatic Power Control;
- Power supply and electrical system circuit breakers (for future use);
- Diesel engine support, with starter motor/shutdown and randomised engine stalls;
- In-cab blower;
- Head and tail lights;
- AI guard for station stop monitoring and buzzer signals;
- AI Support which assists openBVE's AI human driver in automatically handling systems simulated by the plugin (including support for visible in-cab driver's hands and arms).

Planned feature summary:

- Windscreen wipers and rain effects;
- Overhead supplies catering for different supply voltages;
- More advanced diesel engine simulation;
- Continuous Automatic Warning System (CAWS) support
- Third rail power supply support;
- Tap-changer support;
- ERTMS/ETCS support;
- ATP support;
- RETB support;
- Tripcock support;
- Random failure modes.

### Starting states

openBVE supports three modes in which the state of the safety systems can be set upon starting a route. This is achieved via the `Route.Change` command, specified within a route file. Please see the Developing for openBVE section of the official openBVE homepage for more information.
The UkTrainSys plugin behaviour more closely matches openBVE's mode setting.
If `Mode` is -1: The train is already in service, the traction power supply is active (for example, the pantograph is raised), and the safety systems are already initialised and ready. The Driver Reminder Appliance (DRA) needs to be deactivated, however.
If `Mode` is 0: The traction power supply is active (e.g. pantograph raised), but the safety systems need to be initialised by turning the Master Switch on, and performing the startup/self-test procedure.
If `Mode` is 1: Then the traction power supply is NOT active (e.g. the pantograph is lowered), and the safety systems need to be initialised by turning the Master Switch on, and performing the startup/self-test procedure.

### Plugin variables (ats subjects) for train developers

The following is a list of the plugin variables and associated values, which are currently supported by the UkTrainSys.dll plugin. Plugin variables can be queried for use with animated 3D cabs (defined via the panel.animated file), or when being used with BVE 4-style 2D panels (defined via the panel2.cfg file) - in this latter case, plugin variables are referred referred to as "ats subjects". These variables can be used in the following ways:
Example: panel.animated file
[Object]
States = my_folder\my_object_0.csv, my_folder\my_object_1.csv
StateFunction = pluginState[201]
In the above example, if the value assigned to `pluginState[201]` equals 0, then state 0 (my_object_0.csv) is displayed. If the value assigned to `pluginState[201]` equals 1, then state 1 (my_object_1.csv) is displayed instead. If the value assigned to `pluginState[201]` equals a value less than 0, or greater than 1, then no object is displayed at all (as there are no objects associated with those state values).
Example: panel2.cfg file
[Pilotlamp]
Subject = ats7
DaytimeImage = d3d\AWS_sunflower.bmp
In the above example, if the value assigned to `ats7` (equivalent to `pluginState[7]`) equals 1, then AWS_sunflower.bmp is displayed. If the value assigned to `ats7` equals any other value, then no texture is displayed.
General controls and safety systems:

Plugin variable (pluginState[i]) | Values | Description
--- | --- | ---
0 (deprecated) | 0 - 1 | = 1 when the master switch is off
1 | 0 - 1 | = 1 when the master switch is on
3 | 0 - 1 | = 1 when the diesel engine is running
4 | 0 - 3 | > 0 depending upon whether the diesel engine starter button is depressed, or the starter motor is running [= 0: button released, starter motor off | = 1: button depressed, starter motor off | = 2: button released, starter motor running |
= 3 button depressed, starter motor running]
5 | 0 - 3 | > 0 depending upon whether the diesel engine stop button is depressed, or the engine is stopped [= 0: button released, engine running | = 1: button depressed, engine running | = 2: button released, engine stopped |
= 3 button depressed, engine stopped]
6 (deprecated) | 0 - 1 | = 1 when the AWS sunflower is not visible
7 | 0 - 1 | = 1 when the AWS sunflower is visible
8 | 0 - 1 | = 1 while the AWS reset button is depressed
9 | 0 - 1 | = 1 when the TPWS Brake Demand indicator should be illuminated
10 | 0 - 1 | = 1 when the TPWS Isolation indicator should be illuminated
11 | 0 - 1 | = 1 when the TPWS TSS Override indicator should be illuminated
13 | 0 - 1 | = 1 when the DRA is activated
14 | 0 - 1 | = 1 when the door interlock/hazard indicator should be illuminated
15 | 0 - 1 | = 1 when the left doors are open
16 | 0 - 1 | = 1 when the right doors are open
20 | 0 - 3 | > 0 when the headlight rotary switch is not in the off position [= 0: off | = 1: day | = 2: marker only | = 3: night]
21 | 0 - 1 | = 1 when the taillight switch is in the on position
22 | 0 - 3 | > 0 when the headlight proving indicators are illuminated [= 0: off | = 1: day | = 2: marker only | = 3: night]
23 | 0 - 1 | = 1 when the taillight proving indicators are illuminated
24 | 0 - 2 | > 0 when the horn lever is not in the forward position [= 0: forward | = 1: centred | = 2: backward]
25 (new) | 0 - 1 | = 1 while the guard's buzzer is playing
30 | 0 - 1 | = 1 when the pantograph is raised
31 | 0 - 1 | = 1 when the line volts indicator is illuminated
33 | 0 - 1 | = 1 when the vacuum circuit breaker indicator is illuminated
65 | 0 - 5 | > 0 when the BR 8x series power handle is not in the off position [= 0: off | = 1: run down | = 2: notch down | = 3: hold | = 4: notch up | = 5: run up]
198 | 0 - 1 | > 0 when the wiper rotary switch is not in the off position [= 0: off | = 1: slow | = 2: fast]
199 | 0 | (Reserved for the wiper position)
[200-256 ↓] | - | (Not implemented yet - range reserved for raindrops)

AI Support:

Plugin variable (pluginState[i]) | Values | Description
--- | --- | ---
50 | 0 - 1 | = 1 when the AI driver's arms/hands are visible (global setting)
51 | 0 - 1 | = 1 when the AI driver's arm/hand animation states have been initialised (use this with a null object, to show an invisible object while the animated object is being positioned upon being first displayed)
52 | 0 - 7 | > 0 when the AI driver's left hand is interacting with an in-cab control = 0: no interaction / transitioning to another control / not visible = 1: interacting with the power handle = 2: interacting with the reverser handle = 3: interacting with the headlight switch
= 4: interacting with the taillight switch
= 5: interacting with the pantograph up/reset button
= 6: interacting with the pantograph down button
= 7: interacting with the guard's buzzer button
53 | 0 - 3 | > 0 when the AI driver's right hand is interacting with an in-cab control = 0: no interaction / transitioning to another control / not visible = 1: interacting with the AWS reset button = 2: interacting with the DRA switch = 3: interacting with the horn lever

Sound variables:

Sound variable (sound.cfg) | Description
--- | ---
0 | The AWS "bing" (clear) sound
1 | The shortened AWS bing sound (self-test complete)
2 | The AWS horn sound (loops)
3 | The vigilance device beep sound (loops)
4 | The single buzzer sound
7 | The diesel engine starter motor switching on sound
8 | The diesel engine starter motor sound (loops)
9 | The diesel engine starter motor running down sound
10 | The diesel engine start sound
11 | The diesel engine stall on start sound
12 | The diesel engine idling sound (loops)
13 | The diesel engine revving up sound
14 | The diesel engine revving down sound
15 | The diesel engine stopping sound
16 | The wiper switch sound
17 | (Not implemented yet - reserved for the wiper sweep across wet windscreen sound)
18 | (Not implemented yet - reserved for the wiper sweep across dry windscreen sound)
24 | The generic switch sound
25 | The pantograph rising air release sound
27 | The vacuum circuit breaker "thwok" sound
28 | (Not implemented yet - reserved for the pantograph head arcing when failing to cut off power through a neutral section sound
29 | The pantograph sparking sound (on contact with the overhead line)
50 | The in-cab blower spinning up sound
51 | The in-cab blower looping sound
52 | The in-cab blower spinning down sound
60 | The left doors open recharge clicks sound
61 | The right doors open recharge clicks sound
62 | The horn lever pulled backward horn sound (used by the AI support)
63 | The horn lever pushed forward horn sound (used by the AI support)

### Virtual key assignments for train developers and users

The following virtual key assignments are used by the UkTrainSys plugin:

Virtual Key | Default keyboard assignment | Description
--- | --- | ---
A1 | Insert | The AWS reset button
A2 | Delete | The DSD pedal (Vigilance device)
B1 | Home | Wiper switch increase speed
B2 | End | Wiper switch decrease speed
C1 | Page Up | TPWS TSS Temporary Override
C2 | Page Down | TPWS/AWS/Vigilance Temporary Isolation (not prototypical)
D | 2 | Pantograph up/reset or diesel engine starter button
E | 3 | Pantograph down or diesel engine stop button
F | 4 | Headlight rotary switch
G | 5 | Taillight rotary switch
H | 6 | Driver to guard buzzer button
I | 7 | (Not used yet)
J | 8 | (Not used yet)
K | 9 | (Not used yet)
L | 0 | (Not used yet)
S | Space | DRA toggle switch

### Beacon types for route developers

The following beacon types are recognised by the UkTrainSys plugin (for details regarding how to use each beacon, please see further down):

Beacon Type | Purpose
--- | ---
20 | Represents a pair of Automatic Power Control (APC) magnets, or a neutral section, depending upon the optional data parameter
23 | Used to tell the AI guard whether or not an upcoming station has stopping location constraints which should be observed, or ignored
24 | Used by the AI guard; defines the start (or end) of station limits, and used to determine the location of the upcoming stopping location, and the permitted underrun and overrun distances in metres
50 | Used by the AI Support feature; the optional data determines which AI function to perform upon passing this beacon, or otherwise informs the AI Support of something for it to be aware of
44000 | Represents an AWS permanent magnet or electromagnet
44001 (deprecated) | Represents a permanently installed and energised AWS magnet (for use with permissible speed advanced warning indicator boards, for example)
44002 | Represents a TPWS Overspeed Sensor System (OSS) arming or trigger induction loop, associated with a signal
44003 | Represents a TPWS Trainstop Sensor System (TSS) arming or trigger induction loop, which is permanently energised.
44004 | Represents a TPWS Overspeed Sensor System (OSS) arming or trigger induction loop, which is permanently energised (for use with permissible speed advanced warning indicator boards, for example)

More information
openBVE's .Beacon command has the following format:
Track.Beacon Type; BeaconStructureIndex; Section; Data; X; Y; Yaw; Pitch; Roll
Please see the Developing for openBVE section of the official openBVE homepage for more information.
A note regarding backwards compatiblity
In many cases, the beacons recognised by the UkTrainSys plugin are the same as with Simon Gathercole's previous generation of C++ Windows-only plugins written for BVE 4. However, in some cases, UkTrainSys supports new, enhanced functionality via differently formatted beacon commands, while retaining backwards compatibility with beacon commands found in routes written with Simon's plugins in mind.
This documentation focuses on the new functionality which is provided by UkTrainSys, and openBVE route and train developers are encouraged to use the new functionality and beacon command parameters, if developing add-ons for openBVE. If you need to know about the legacy, backwards compatible beacon parameters and behaviours, then you can see the Legacy Behaviour section, further down.
Beacon types and the Automatic Power Control system
Beacon 20:
This beacon serves two purposes...
Firstly, it can represent a pair of Automatic Power Control (APC) magnets, used to trip open the air-blast/vacuum circuit breaker (ACB/VCB) between a pantograph and the traction power equipment, just before passing a neutral section in the overhead line equipment. The beacon can also be used to re-close the ACB/VCB if it is already open. For example:
1000, .Beacon 20;0
1046, .Beacon 20;0
This `.Beacon 20` command should be located where your APC magnets are required, both before and after the neutral section.
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.
Secondly, the `.Beacon 20` command can specify the start and end of the actual neutral section itself (i.e. the earthed, non-energised, 4 metre ceramic bead section, which is spliced into the overhead line). For example:
1030, .Beacon 20;-1;;-1
1034, .Beacon 20;-1;;-1
The `Data` parameter of -1 in these `.Beacon 20` commands, tells the UkTrainSys plugin to treat these as the start and end of the neutral section.
Note: the `BeaconStructureIndex` value is -1 here, as we don't want any object to be displayed at the location of this beacon. Please see the Developing for openBVE section of the official openBVE homepage for more information.
Putting it all together:
To simulate a fully equipped neutral section, your route file commands would be as follows:
1000, .Beacon 20;0, ; first pair of APC magnets
1030, .Beacon 20;-1;;-1, ; commencement of neutral section
1034, .Beacon 20;-1;;-1, ; termination of neutral section
1046, .Beacon 20;0, ; second pair of APC magnets

- When the train's Automatic Power Control (APC) recevier passes 1000 metres, the APC system will command open the air blast/vacuum circuit breaker (ACB/VCB), interrupting the power supply from the pantograph to the traction power equipment.
- When the APC receiver location is between 1030 and 1034 metres, overhead line voltage is lost completely.
- When the train's APC receiver passes 1046 metres, the APC system will command the air blast/vacuum circuit breaker to re-close, restoring the power supply from the pantograph to the traction power equipment.

If the train's pantograph inadvertently comes to a halt between 1030 and 1034 metres, then the train will have no power source, and you will have to either release the brakes and hope that your train is on an incline, such that it rolls out of the neutral section due to gravity, or you will have to declare a train failure. In the latter case, in reality, your train would need to be rescued by another train!
If the train's pantograph inadvertently comes to a halt between 1000 and 1030 metres, or 1034 and 1046 metres, then the air blast/vacuum circuit breaker can be re-closed manually, and the train can be moved, so that another attempt to coast through the neutral section can be made.
Beacon types and the AI Guard
Beacon 23:
This beacon is used to tell the AI guard whether or not an upcoming station has stopping location constraints which should be observed, or ignored (or rather, whether subsequent `.Beacon 24` commands should be ignored or not). If the stopping point is to be monitored, then the AI guard will signal the driver with audible buzzer codes if the train stops outside of the defined stopping location limits, provided the train is within defined station area limits. If the stopping location is to be monitored, the `Data` parameter should be a value other than 0, such as 1. For example:
.Beacon 23;-1;;1
Note: the `BeaconStructureIndex` value is -1 here, as we don't want any object to be displayed at the location of this beacon. Please see the Developing for openBVE section of the official openBVE homepage for more information.
Beacon 24:
This beacon is used by the AI guard, and serves three purposes. Firstly, it's presence alone determines the start (or end) of station limits. The location of the first `.Beacon 24` command following a `.Beacon 23` command in the route, determine the start of the station area limits, and the location of the second `.Beacon 24` command determines the end of the station area limits. This beacon is also used to determine the location of the upcoming stopping location, and it also used to determine the permitted underrun and overrun distances from this stopping location, in metres. Provided a `.Beacon 23` command with a `Data` parameter other than 0 was passed previously, the plugin will act upon the parameters passed via a `.Beacon 24` command.
As mentioned already, this beacon type should be placed twice; once before the station, and once after the station. The first `.Beacon 24` command before the station, defines the start of the station limits (the AI guard will monitor whether or not the train stops in the wrong place after passing this beacon), and should have a format as follows:
.Beacon 24;-1;;195 75 25 03
All the information which the plugin requires is passed via the `Data` parameter. The `Data` parameter must be at least 7 digits in length, and contain only numbers.
The first three digits represent the distance from the `.Beacon 24` command to the `.Stop` command, as defined in the route file (you'll need to work out this distance value yourself, and change the value if you subsequently relocate either the `.Stop` or `.Beacon 24` commands). In this example, the beacon is 195 metres from the `.Stop` command.
The 4th and 5th digits define the permitted underrun in metres. In this case, the permitted underrun is 75 metres.
Note: For best results, the `BackwardTolerance` parameter of openBVE's `.Stop` command, should match this value.
The 6th and 7th digits define the permitted overrun in metres. In this example, the permitted overrun is 25 metres.
Note: For best results, the `ForwardTolerance` parameter of openBVE's `.Stop` command, should match this value.
The 8th and 9th digits are OPTIONAL and can be omitted, if there is only one stopping location at the upcoming station. These specify how many cars a train must have at maximum, for the stopping point to apply to the train. In the above example, the stopping location specified by this beacon command, only applies if the train has 3 cars or less. If the train has 4 cars or more, then the beacon information is ignored. You should place a subsequent `.Beacon 24` command which specifies no cars at all, to act as a "catch all" for trains of any length.
Note: As the `Data` parameter must be at least 7 digits in length, you can insert zeros where necessary. For example, if your distance from the beacon to the `.Stop` command is 99 metres, then you would specify this as 099. As a more silly example, if the distance was 9 metres, then this would be specified as 009.
The second placement of this beacon, which defines the end of the station limits (once passed this beacon, the AI guard no longer monitors where the train stops), should have the following format:
.Beacon 24;-1;;0
Note: the `BeaconStructureIndex` value is -1 in the above examples, as we don't want any object to be displayed at the location of these beacons. Please see the Developing for openBVE section of the official openBVE homepage for more information.
Putting it all together:
So, in your route file, you would end up with something like the following, which allows for an `Underrun/BackwardTolerance` of 25 metres, and an `Overrun/ForwardTolerance` of 30 metres (simple example wtih only one stopping location):
1000, .Beacon 23;-1;;1
.Beacon 24;-1;;200 25 30
; --- Start of station platform at 1025m ---
1025, .Sta MyStation;10.0000;10.0130;;1;0;;;20;30;;0
1200, .Stop 0;25;30, ; All car stop point
; --- End of station platform at 1225m ---
1400, .Beacon 24;-1;;0
If you had a station with two stopping points - one for 3 car trains or less, and one for 6 car trains or less (but greater than 3), plus a third for any train which is greater than 6 cars in length, you could use the following in your route file (advanced example):
1000, .Beacon 23;-1;;1
.Beacon 24;-1;;150 50 99 03
.Beacon 24;-1;;225 50 25 06
.Beacon 24;-1;;225 25 25
; --- Start of station platform at 1025m ---
1025, .Sta MyStation;10.0000;10.0130;;1;0;;;20;30;;0
1150, .Stop 0;50;99;3, ; 3 car stop point (tolerances assume 3 * 25m length cars)
1225, .Stop 0;50;25;6, ; 6 car stop point (tolerances assume 6 * 25m length cars)
.Stop 0;25;25, ; >6 car stop point (assumes little, as any train length >6 cars is handled)
; --- End of station platform at 1250m ---
1400, .Beacon 24;-1;;0
If you wanted to disable AI guard monitoring of this station, for example if the train is not scheduled to stop in a particular route file, you can simply change `.Beacon 23;;;1` to `.Beacon 23;;;0`.
Final note: If you forget to place the final `.Beacon 24` command in your route file, then the AI guard will stop monitoring the stopping location, 500 metres after the stopping location which has been determined by UkTrainSys.
Beacon types and the AI Support feature
Beacon 50:
This beacon is used by the AI Support. Upon passing `.Beacon 50`, the optional `Data` parameter contains information which the AI Support feature can use to perform some action within the cab, in response to passing over this beacon. The `Data` parameter is an integer ranging from zero upwards. Currently supported values are as follows:

`Data` parameter | AI Support Instruction
--- | ---
0 | Sound the horn (lever forward first, then backwards)
1 | Sound the horn (lever backwards first, then forwards
40 | Informs the AI Support that the next stopping point is at the terminal station on the route. Only place this beacon 50 command prior to the last .Stop command in the route
41 | Instructs the AI Support to lower the pantograph (or stop the diesel engine), when the train next stops and the doors open (i.e. at a station). Only place this beacon 50 command prior to the last .Stop command in the route
920d xxxxx | Informs the AI Support that there is a neutral section ahead (or behind)

- d should be 1 (ahead);
- xxxxx should be a value between 00000 and 99999, which is the distance between the beacon and the neutral section, in metres.
  If d is 1, then UkTrainSys interprets the neutral section as being xxxxx number of metres ahead of the beacon location, and the beacon is ignored when travelling backwards. The AI doesn't currently drive backwards, so there's no need to handle reverse direction behaviour yet.
  You should pad your distance value with zeros where appropriate. For example, if your neutral section is 200 metres ahead, the distance passed to the plugin would be 00200. The full `.Beacon` command would therefore be:
  .Beacon 9201 00200
  Note: If the tap changer is enabled, then this takes up to 35 seconds to run down from notch 38. When deciding where to place a neutral section ahead beacon, you should check to see how far a train which is travelling at the permitted linespeed, can travel within at least 35 seconds. This will let you know where the beacon should be placed. If the tap changer is not enabled, then UkTrainSys will remember that the beacon has been passed, and will return the power handle to the off position, 5 seconds before reaching the calculated location of the neutral section. If you jump to a station, the information passed via the beacon is discarded.

For example:
.Beacon 50;-1;;0
The `Section` parameter of 0 in this `.Beacon 50` command, would instruct the AI Support feature to blow the horn, first by moving the horn lever forwards, then backwards.
Note: the `BeaconStructureIndex` value is -1 here, as we don't want any object to be displayed at the location of this beacon. Please see the Developing for openBVE section of the official openBVE homepage for more information.
Beacon types and the Automatic Warning System (AWS)
There is just a single beacon required for prototypical Automatic Warning System (AWS) simulation.
Beacon 44000:
This beacon represents either an AWS permanent magnet with it's south pole facing upwards, or an AWS electromagnet with it's north pole facing upwards (the latter is associated with a signal). Which of these the beacon represents, is determined by the optional `Data` parameter.
An AWS permanent magnet by itself, always primes the AWS, and starts a delay period which lasts for 1000 milliseconds. If this delay period elapses, an AWS warning is issued.
An AWS electromagnet should immediately follow an AWS permanent magnet, and the electromagnet is energised only when the associated signal is showing a clear (green) aspect. When the aforementioned permanent magnet primes the AWS, detection of the electromagnet within the delay period, causes an AWS clear indication to be issued. If the associated signal is showing a restrictive aspect (red or yellow), then the electromagnet is de-energised, and therefore it is not detected by the AWS equipment. Thus, the AWS delay period elapses, and an AWS warning is issued.
Note: As with the real AWS, if you drive at a very low speed over an AWS inductor, while the associated signal is showing a green aspect, then the AWS delay period may elapse before the electromagnet is reached, and an AWS warning will be issued. If the AWS warning is not acknowledged, then the warning will automatically clear upon passing the electromagnet (provided no brake demand has occured). So, when approaching a green signal at very low speeds, you may briefly hear the warning horn and be presented with the AWS sunflower, and then hear the AWS bell and see the sunflower instrument go black.
AWS inductor associated with a signal:
For an AWS inductor associated with a signal, use the following pair of `.Beacon 44000` commands:
100.0, .Beacon 44000;-1;;180, ; AWS permanent magnet (south pole)
101.0, .Beacon 44000;0;1;360, ; AWS electromagnet (north pole)
Firstly, note the spacing between the two `.Beacon 44000` commands - they should be 1 metre apart. There is no absolute limit, but this ensures reliable operation.
Secondly, note the order in which the commands appear - as with the real AWS, they must appear in this sequence, to work correctly in the normal (forward) direction of travel. If the order is reversed, then they would only be suitable for the opposite direction of travel.
Thirdly, the `Data` parameter of 180 in the first `.Beacon 44000` command, represents the magnet's south pole, and the `Data` parameter of 360 in the second `.Beacon 44000` command, represents the north pole.
The `Section` parameter of the first `.Beacon 44000` command can be omitted, because this beacon represents a permanent magnet which is always detectable. This primes the AWS, ready to detect the state of the second `.Beacon 44000` command.
With the second `.Beacon 44000` command, the `Section` parameter of 1, references the next section ahead, and if the signal apsect associated with section 1 is green, an AWS clear indication will be issued when this beacon command is encountered. If the aspect is red or yellow, the beacon is ignored, and and AWS warning will be issued, 1 second after the first beacon was passed.
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.
AWS permanent magnet associated with a temporary or permanent speed restriction:
For an AWS inductor associated with a temporary or permanent speed restriction, use the following `.Beacon 44000` command:
100.0, .Beacon 44000;0;;180, ; AWS permanent magnet (south pole)
The `Data` parameter of 180, represents the magnet's south pole.
The `Section` parameter of the `.Beacon 44000` command can be omitted, because this beacon represents a permanent magnet which is always detectable. This primes the AWS, and as there is no second `.Beacon 44000` command, an AWS warning will be issued, 1 second after this beacon is passed.
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.
A note on opposite direction of travel, as well as bi-directional signalling and AWS suppression:
If a train is driven backwards over an AWS inductor associated with a signal, then an AWS warning will be issued, as the beacon representing an electromagnet is passed first, but as the AWS is not yet primed, the electromagnet beacon is not acted upon. When the AWS is subsequently primed by the permanent magnet, the delay period will elapse, thus issuing an AWS warning, regardless.
openBVE does not presently support bi-directional signalling, however, the UkTrainSys plugin does support AWS suppression, which prevents an AWS permanent magnet from being detected. This would be linked to the signalling system, such that when trains are permitted to travel in the opposite direction, AWS permanent magnets which are only meant to apply to signals in the normal direction of travel, would be suppressed (and vice-versa).
To suppress an AWS permanent magnet, you can do use the follwing `.Beacon 44000` command:
100.0, .Beacon 44000;-1;;270, ; AWS suppression
The `Data` parameter of 270, tells UkTrainSys that this `.Beacon 44000` command represents a suppression magnet.
The `Section` parameter can be omitted, to unconditionally suppress the subsequent AWS permanent magnet (in the direction of travel). In future, UkTrainSys could be expanded to act upon a section which applies to the opposite direction of travel, where the aspect of that section could conditionally suppress the subsequent AWS permanent magnet (remember, openBVE doesn't currently support bi-directional signalling - this is an idea for future use only).
The AWS permanent magnet which is to be suppressed, MUST be located within 2 metres of the suppression beacon (a distance of 0.5 metres is recommended).
For example, to suppress an AWS permanent magnet in the opposite (reverse) direction of travel only:
100.0, .Beacon 44000;-1;;180, ; AWS permanent magnet (south pole)
100.5, .Beacon 44000;-1;;270, ; AWS suppression
101.0, .Beacon 44000;0;1;360, ; AWS electromagnet (north pole)
In the above example, the suppression beacon is encountered before the beacon representing the permanent magnet, ONLY if the train is travelling backwards, and if the train is travelling backwards, the permanent magnet will be ignored by the UkTrainSys plugin. If the train is travelling forwards, the AWS permanent magnet will still be detected, as usual.
To suppress an AWS permanent magnet in the normal (forward) direction of travel only:
99.5, .Beacon 44000;-1;;270, ; AWS suppression
100.0, .Beacon 44000;-1;;180, ; AWS permanent magnet (south pole)
101.0, .Beacon 44000;0;1;360, ; AWS electromagnet (north pole)
In this example, the suppression beacon is encountered before the beacon representing the permanent magnet, ONLY if the train is travelling forwards, and the permanent magnet will be ignored by the UkTrainSys plugin in the forward direction. If the train is travelling backwards, the AWS permanent magnet will still be detected, as usual.
If you want to suppress an AWS permanent magnet in both directions of travel, then you can either remove the beacon representing the permanent magnet altogether, or place a suppression beacon both before and after the beacon representing the permanent magnet.
Beacon types and the Train Protection and Warning System (TPWS)
Beacon 44002:
This beacon represents a TPWS Overspeed Sensor System (OSS) induction loop, associated with a signal. This beacon supports prototypical TPWS operation, where the permissible speed is determined by the spacing between a pair of OSS induction loops, combined with a pair of train-borne timers, and also allowing for induction loop nesting and interleaving, and opposite direction of travel. When the section referenced by the `Section` parameter of a `.Beacon 44002` command has an aspect of 0 (i.e. the section is occupied by a train), the induction loop is energised.
To simulate prototypical TPWS Overspeed Sensor System behaviour, a pair of `.Beacon 44002` commands should be placed in the route file, where the first `.Beacon 44002` command represents the OSS arming induction loop, and the second `.Beacon 44002` command represents the OSS trigger induction loop.
When the plugin registers passing the OSS arming induction loop (identified by one of two frequencies which should be emitted from it), one of two timers associated with either frequency is started within the plugin, which counts to 974 milliseconds on passenger trains, and 1218 milliseconds on freight trains (this timeout period can be set via the UkTrainSys.cfg file - please see below for more information). If the associated timer has not expired by the time a matching OSS trigger induction loop is encountered (which is identified by one of two different frequencies which should be emitted from it), then the TPWS deems that the train is travelling too fast, and will issue an OSS Brake Demand. Thus, the speed at which a TPWS equipped train is permitted to travel on approaching a red signal, is determined by both the timeout period, and the distance between the two `.Beacon 44002` commands which are emitting recognised frequencies.
For prototypical TPWS simulation, the `.Beacon 44002` commands should be used as follows (both of these examples would create an OSS with a permissible speed of around 56 km/h).
For the normal direction of travel, the following beacon should be used (applies to ordinary uses of TPWS in a route):
1004.85, .Beacon 44002;0;1;64250, ; TPWS OSS arming loop
1020.00, .Beacon 44002;0;1;65250, ; TPWS OSS trigger loop
Firstly, note the spacing between the two beacons, which is 15.15 metres (`1020 - 1004.85 = 15.15`). This determines the OSS permissible speed (a very easy and quick formula for calculating the distance for a given speed, can be found below).
The `Section` parameter of 1, references the next section ahead, and if section 1 is occupied, the loops are energised. If the timer which is triggered by the arming loop, has not expired before the trigger loop is reached, then passing the second `.Beacon 44002` command will trigger a TPWS OSS Brake Demand.
The `Data` parameter of 64250 in the first `.Beacon 44002` command, represents the arming frequency of 64250 Hz (64.25 kHz).
The `Data` parameter of 65250 in the second `.Beacon 44002` command, represents the trigger frequency of 65250 Hz (65.25 kHz).
The frequencies must exactly match the values shown in the above example, and they must appear in the order shown. This means that the OSS is only recongnised when travelling in the forward direction, and is ignored if travelling backwards over the beacons. If you inadvertently get the frequencies the wrong way around, then the OSS will only be effective if you are travelling backwards!
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.
TPWS+ (OSS+):
If a TPWS+ (Plus) installation is being simulated, then the same pair of beacons (with the same frequencies specified in the same order), should be used. The first occurance of the pair of `.Beacon 44002` commands (the OSS+), should be located around 750 metres in the rear of the associated signal, and the beacon pair should be spaced further apart, so that they allow a higher permissible speed than the inner pair of `.Beacon 44002` commands.
OSS induction loop spacing: The formula for working out the correct spacing between the `.Beacon 44002` commands, and hence correctly setting the permissible speed, is as follows. You can use either the passenger train OSS timeout, or the freight train OSS timeout, to calculate the beacon spacing. However, I would recommend using the passenger train timeout value.
If using the passenger train OSS timeout period of 974 ms:
`distance[m] = 0.27056 * speed[km/h]`
If using the freight train OSS timeout period of 1218 ms:
`distance[m] = 0.33833 * speed[km/h]`
You can also calculate the beacon spacing with any OSS timeout value, by using the following formula:
`distance[m] = ((permittedspeed[km/h] * 1000) * timeout[s]) / 3600`
For passenger trains, `timeout` is 0.974 seconds;
For freight trains, the `timeout` is 1.218 seconds.
Beacon 44003:
This beacon represents a TPWS Trainstop Sensor System (TSS) induction loop, associated with a signal. When the section referenced by the `Section` parameter of a `.Beacon 44003` command has an aspect of 0 (i.e. the section is occupied by a train), the TSS induction loop is energised.
To simulate prototypical TPWS Trainstop Sensor System behaviour, a pair of `.Beacon 44003` commands should be placed in the route file, where the first `.Beacon 44003` command represents the TSS arming induction loop, and the second `.Beacon 44003` command represents the TSS trigger induction loop.
When the plugin registers passing the TSS arming induction loop (identified by one of two frequencies which should be emitted from it), one of two detection states associated with either frequency is activated within the plugin. If the TSS trigger induction loop (which is identified by one of two different frequencies which should be emitted from it), is detected after the arming loop is detected, but while the trigger loop is still within range of the arming loop, then the plugin will recognise this condition as a valid TSS installation, and will issue a TSS Brake Demand. The use of an arming and trigger loop, together with specific frequencies, allows for prototypical behaviour when travelling backwards over the induction loops, for example.
For prototypical TPWS TSS simulation, the `.Beacon 44003` commands should be used as follows:
100, .Beacon 44003;0;1;66250, ; TPWS TSS arming loop
101, .Beacon 44003;0;1;65250, ; TPWS TSS trigger loop
The `Section` parameter of 1, references the next section ahead, and if section 1 is occupied, the TSS induction loops are energised.
Note the spacing between the two `.Beacon 44003` commands - they are 1 metre apart. They can be spaced up to 2 metres apart, but any more than this, and the TSS trigger loop will be out of range of the TSS arming loop, and the TSS will not work. The TPWS will only act upon the detection of the trigger frequency, if it is close enough to the arming loop at the time.
If you were to switch the above `.Beacon 44003` commands around, such that the trigger loop comes before the arming loop, then the TSS would only be recognised as such, if the train was travelling backwards over the TSS.
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.
Putting it all together:
A typical signal with AWS and standard TPWS, could be declared as follows (the OSS beacon spacing of 15.15 metres, would give around a 56 km/h permissible speed):
1004.85, .Beacon 44002;0;1;64250, ; TPWS OSS arming loop
1020.00, .Beacon 44002;0;1;65250, ; TPWS OSS trigger loop
1036.0, .Beacon 44000;-1;;180, ; AWS permanent magnet (south pole)
1037.0, .Beacon 44000;0;1;360, ; AWS electromagnet (north pole)
1219.00, .Beacon 44003;0;1;66250, ; TPWS TSS arming loop
1220.00, .Beacon 44003;0;1;65250, ; TPWS TSS trigger loop
.SigF 4;1;-2.1;5.85, ; Signal
.Section 0;2;3;4, ; New section
A typical signal with AWS, TPWS and TPWS+, is declared as follows (the OSS+ beacon spacing of 25.97 metres, would give around a 96 km/h permissible speed, while the OSS beacon spacing of 15.15 metres, would give around a 56 km/h permissible speed):
444.03, .Beacon 44002;0;1;64250, ; TPWS OSS+ arming loop
470.00, .Beacon 44002;0;1;65250, ; TPWS OSS+ trigger loop
1004.85, .Beacon 44002;0;1;64250, ; TPWS OSS arming loop
1020.00, .Beacon 44002;0;1;65250, ; TPWS OSS trigger loop
1036.0, .Beacon 44000;-1;;180, ; AWS permanent magnet (south pole)
1037.0, .Beacon 44000;0;1;360, ; AWS electromagnet (north pole)
1219.00, .Beacon 44003;0;1;66250, ; TPWS TSS arming loop
1220.00, .Beacon 44003;0;1;65250, ; TPWS TSS trigger loop
.SigF 4;1;-2.1;5.85, ; Signal
.Section 0;2;3;4, ; New section
Note that in these examples, the TPWS induction loops, AWS magnets, and signal command, are placed before the `.Section` command for the upcoming signal.
Beacon 44004:
This beacon represents a permanently energised TPWS Overspeed Sensor induction loop, not associated with a signal, but rather, for example, a permissible speed indicator board.
This beacon is essentially identical to `.Beacon 44002`, as detailed above, except that `.Beacon 44004` will always arm the relevant TPWS OSS timer, regardless of signal aspects. As such, you can omit the `Section` parameter:
1004.85, .Beacon 44004;0;;64250, ; TPWS OSS arming loop
1020.00, .Beacon 44004;0;;65250, ; TPWS OSS trigger loop
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.
The same notes with regard to the OSS induction loop arming and trigger frequencies, apply to this beacon as well.
For advanced developers - interleaving and nesting TPWS induction loops:
As with the real TPWS, the UkTrainSys plugin allows you to nest or interleave TPWS induction loops. This is done, for example, when an OSS associated with a signal, is located in the same place as an OSS associated with an upcoming permanent speed restriction. It can even allow TPWS to be prototypically simulated on a bi-directionally signalled line (more for future use).
OSS:
The UkTrainSys plugin identifies TPWS induction loops by the beacon type, but also by the frequency being emitted from the beacon, specified via the optional `Data` parameter. UkTrainSys actually simulates two train-borne timers (Timer A and Timer B), and each is independent of the other, and both can be operative simulataneously. Each timer is started or triggered, by a different arming and trigger frequency pair. For example:
OSS Timer A, is armed and triggered by the following frequencies:
1004.85, .Beacon 44002;0;1;64250, ; TPWS OSS arming loop (Timer A)
1020.00, .Beacon 44002;0;1;65250, ; TPWS OSS trigger loop (Timer A)
OSS Timer B, is armed and triggered by the following different frequencies:
1004.85, .Beacon 44002;0;1;64750, ; TPWS OSS arming loop (Timer B)
1020.00, .Beacon 44002;0;1;65750, ; TPWS OSS trigger loop (Timer B)
Note that the trigger frequency intended for Timer B, will not be recognised as a trigger for Timer A, or vice-versa.
What this arrangement means, is that two OSS installations can co-exist in the same location, and not intefere with each other. For example, imagine that a signal has an OSS associated with it (OSS A), and this has a set speed of 56 km/h. Now imagine, that there is a permanent speed restriction just beyond this signal, and this also has an OSS associated with it (OSS B), with a set speed of 96.56 km/h. In this scenario, safety requirements necessitate both of these OSS installations co-existing in the same place. To accomodate this scenario, the TPWS OSS induction loops (four in total), can be interleaved:
1004.85, .Beacon 44002;0;1;64250, ; TPWS OSS A arming loop
1010.88, .Beacon 44004;0;;64750, ; TPWS OSS B arming loop
1020.00, .Beacon 44002;0;1;65250, ; TPWS OSS A trigger loop
1037.00, .Beacon 44004;0;;65750, ; TPWS OSS B trigger loop
In the above example, OSS B is permanently energised (as `.Beacon 44004` commands are used). Whenever a train is travelling above 96.56 km/h while passing through OSS B, the UkTrainSys plugin's Timer B will recognise the OSS B arming frequency, and then the OSS B trigger frequency, and respond accordingly. If the signal associated with OSS A is showing a proceed aspect, then OSS A is not energised, and is never detected.
If however, the signal associated with OSS A, is showing a red aspect, then OSS A is energised as well. As you can imagine, if there were only one timer, and one pair of frequencies, then this would complicate things somewhat, and the spacing between the induction loops would be detected incorrectly. However, as each OSS induction loop emits it's own unique frequency, the UkTrainSys plugin will recognise only the OSS A arming and trigger frequencies as relating to Timer A, and only the OSS B frequencies as relating to Timer B. One does not affect the other.
The TPWS OSS induction loops can also be nested. In the following example, imagine that the permanent speed restriction just beyond this signal, is set at a higher speed, and that it's associated OSS (OSS B), has a set speed of 120.7 km/h:
0916.30, .Beacon 44004;0;;64250, ; TPWS OSS A arming loop
1004.85, .Beacon 44002;0;1;64750, ; TPWS OSS B arming loop
1020.00, .Beacon 44002;0;1;65750, ; TPWS OSS B trigger loop
1037.00, .Beacon 44004;0;;65250, ; TPWS OSS A trigger loop
Note how in this example, one OSS is contained within the other (nested). As with the first example, each OSS induction loop emits it's own unique frequency, so the UkTrainSys plugin will recognise only the OSS A arming and trigger frequencies as relating to Timer A, and only the OSS B frequencies as relating to Timer B. One does not affect the other
TSS:
Lastly, the Trainstop Sensor System (TSS) TSS induction loops, are also identified by two frequency pairs, one pair associated with Detection A, and the other, with Detection B. One does not affect the other.
TSS Detection A, is armed and triggered by the following frequencies:
1004.85, .Beacon 44003;0;1;66250, ; TPWS TSS arming loop (Detection A)
1020.00, .Beacon 44003;0;1;65250, ; TPWS TSS trigger loop (Detection A)
TSS Detection B, is armed and triggered by the following different frequencies:
1004.85, .Beacon 44003;0;1;66750, ; TPWS TSS arming loop (Detection B)
1020.00, .Beacon 44003;0;1;65750, ; TPWS TSS trigger loop (Detection B)
Beacon types and legacy behaviour
The UkTrainSys plugin is also backwards compatible with beacon commands intended for use with Simon Gathercole's previous generation of C++ Windows-only plugins for BVE 4. Developers creating new routes for openBVE are encouraged to use the new functionality and behaviour previously mentioned, rather than using the old, legacy behaviour, which is not as realistic or flexible.
Beacon types and the Automatic Power Control system (legacy behaviour)
Beacon 20 (legacy behaviour - deprecated):
The UkTrainSys plugin supports a legacy behaviour for this beacon. You can use a single `.Beacon 20` command to communicate both the location of the first set of APC magnets, as well as the distance to the second set of APC magnets. This does not, however, allow for the actual neutral section to be simulated, or for driving backwards through a neutral section with the Automatic Power Control system still working. For this, you need to use the new behaviour, which was described earlier on.
To use only the simplified legacy behaviour, take the following example:
.Beacon 20;0;;46
If relying upon the legacy behaviour, this `.Beacon 20` command should be located where the APC magnets are required, before the neutral section only. The `Data` value of 46 tells the UkTrainSys plugin the distance (in metres) to the second pair of APC magnets, and when the train reaches the correct location, the circuit breaker will re-close.
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.
Beacon types and the Automatic Warning System (legacy behaviour)
The UkTrainSys plugin also supports the old AWS behaviour modelled in Simon Gathercole's range of BVE4 plugins, although this legacy behaviour is less flexible and not as realistic, and it's use is not encouraged in new routes designed for openBVE.
Beacon 44000 (legacy behaviour - deprecated):
This beacon represents an AWS magnet associated with a signal. When the section referenced by the `Section` parameter of a `.Beacon 44000` command has an aspect of 0 (i.e. the section is occupied by a train), passing over this beacon will trigger an AWS warning within the cab. Use the beacon as follows:
.Beacon 44000;0;1
The `Section` parameter of 1, references the next section ahead, and if section 1 is occupied, an AWS warning is triggered.
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.
Beacon 44001 (legacy behaviour - deprecated):
This beacon represents a permanently energised AWS magnet not associated with a signal, but rather, for example, a permissible speed advanced warning indicator board. Use the beacon as follows:
.Beacon 44001;0
No section parameter is required here, as `.Beacon 44001` will always trigger an AWS warning, regardless.
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.
Beacon types and the Train Protection and Warning System (legacy behaviour)
The UkTrainSys plugin also supports the old TPWS behaviour modelled in Simon Gathercole's range of BVE4 plugins, although this legacy behaviour is less flexible and not as realistic, and it's use is not encouraged in new routes designed for openBVE.
Beacon 44002 (legacy behaviour - deprecated):
In the case of standard TPWS, this beacon should be located as the final loop amongst the set of two OSS induction loops. In the case of TPWS+ (Plus), this beacon should be located as the last of the first pair of OSS induction loops, and the last of the second pair of OSS induction loops. When the section referenced by the `Section` parameter of this `.Beacon 44002` command has an aspect of 0 (i.e. the section is occupied by a train), passing over this beacon will trigger a TPWS OSS Brake Demand if the train is travelling above the permitted speed when passing over the beacon. Use the beacon as follows:
.Beacon 44002;0;1;56
The `Section` parameter of 1, references the next section ahead, and if section 1 is occupied, passing over this beacon will trigger a TPWS OSS Brake Demand if the train is travelling above the permitted speed when passing over the beacon.
The `Data` parameter of 56 defines the permitted speed in (kilometres per hour) when passing over this TPWS Overspeed Sensor, when the section referenced by the `Section` parameter has an aspect of 0.
If a TPWS+ (Plus) installation is being simulated, then the first occurance of the `.Beacon 44002` command should have a higher speed than the second `.Beacon 44002` command.
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.
Beacon 44003 (legacy behaviour - deprecated):
This beacon represents a TPWS Train Stop Sensor induction loop, associated with a signal. When the section referenced by the `Section` parameter of a `.Beacon 44003` command has an aspect of 0 (i.e. the section is occupied by a train), passing over this beacon will trigger a TPWS TSS Brake Demand. Use the beacon as follows:
.Beacon 44003;0;1
The `Section` parameter of 1, references the next section ahead, and if section 1 is occupied, passing over this beacon will trigger a TPWS TSS Brake Demand.
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.
Beacon 44004 (legacy behaviour - deprecated):
For legacy behaviour, you can use this beacon as follows:
.Beacon 44004;0;;56
No section parameter is required here, as `.Beacon 44004` will always trigger a TPWS OSS Brake Demand if the train is travelling above the permitted speed when passing over the beacon.
The `Data` parameter of 56 defines the permitted speed (in kilometres per hour) when passing over this TPWS Overspeed Sensor.
Note: the `BeaconStructureIndex` value will depend upon what objects you have loaded within your route file; please see the Developing for openBVE section of the official openBVE homepage for more information.

### The UkTrainSys configuration file

The UkTrainSys plugin makes use of a configuration file, which can be used to set various options. If the plugin cannot find it's configuration file, then a new file is created with default values assigned. This will always have a filename which is comprised of the assembly name, with a .cfg extension added (e.g. UkTrainSys.cfg).
Here is a summary of the options which you can set:
The [Options] section
DebugMode =
Whether or not the plugin should create a `Debug.log` file in the same folder where the plugin resides, and display debug information via openBVE's F10 debug screen. This is a boolean value (True or False). The default value is False.
The [AiSupport] section
Enabled =
Whether or not the plugin should support openBVE's AI driver in operating the systems simulated by the UkTrainSys plugin. This is is a boolean value (True or False). The default value is True.
MaximumDraActivationDistance =
The maximum distance in metres from the upcoming signal showing a red aspect, below which the AI Support will activate the DRA. This can be either an integer or a floating point value. The default value is 150 metres.
Options common to all systems
Enabled =
Whether or not a particular system should be enabled. This is a boolean value (True or False). The default value is False for all systems. If a particular train does have a particular system installed, then that system can be enabled by using this option.
Options common to power supplies
MaximumOutputVoltage =
The maximum voltage which the power supply can provide, measured in Volts. This can be either an integer or a floating point value. The default value varies according to the power supply in question.
MaximumOutputCurrent =
The maximum current which the power supply can provide (current rating), measured in Amperes. If the ampere load on the power supply exceeds this value, then the power supply circuit breaker will trip open. This can be either an integer or a floating point value. The default value varies according to the power supply in question.
Options common to electrical systems
RequiredVoltage =
The voltage requirements for a particular system (and maximum voltage rating), measured in Volts. This can be either an integer or a floating point value. The default value varies according to the system in question.
RequiredCurrent =
The current requirements for a particular system (and maximum current rating), measured in Amperes. This can be either an integer or a floating point value. The default value varies according to the system in question.
The [InterlockManager] section
This system has no options to set, apart from the options common to all systems (see above).
The [Battery] section
DischargeRate =
The rate at which the battery will discharge when a load is placed upon it, measured in Amperes per second. This is a floating point value. The default value is 0.001 amperes per second.
The [Overhead] section
MaximumInputVoltage =
The maximum voltage which the overhead supply can handle from the overhead line, measured in Volts. This can be either an integer or a floating point value. The default value is 29000 volts.
MaximumInputCurrent =
The maximum current which can be drawn from the overhead line, measured in Amperes. This can be either an integer or a floating point value. The default value is 17500 volts.
The [Diesel] section
MotorStartDelay =
The delay before the starter motor sound begins looping after the motor has spun up, measured in milliseconds. This is an integer value. The default value is 400 milliseconds.
EngineStartDelay =
The delay before the engine idle sound begins looping, after the engine has successfully started, and after which the starter button integral lamp extinguishes, measured in milliseconds. This is an integer value. The default value is 2500 milliseconds.
EngineRunDownDelay =
The delay before the engine has completely stopped after a normal shutdown, measured in milliseconds. This is an integer value. The default value is 2000 milliseconds.
EngineStallDelay =
The delay before the engine has completely stopped after stalling, measured in milliseconds. This is an integer value. The default value is 2000 milliseconds.
StallProbability =
The probability of the engine stalling during engine startup, as a percentage. This is an integer value ranging from 0 to 100. The default value is 25 percent.
The [Aws] section
CancelTimeout =
The AWS warning horn cancellation timeout period, measured in milliseconds. This is an integer value. The default value is 3000 milliseconds.
The [Vigilance] section
InactivityTimeout =
The Vigilance device driver inactivity timeout period, measured in milliseconds. This is an integer value. The default value is 60000 milliseconds.
CancelTimeout =
The Vigilance device warning beep acknowledgement timeout period, measured in milliseconds. This is an integer value. The default value is 7000 milliseconds.
The [Tpws] section
BrakesAppliedTimeout =
The timeout period which must expire before the brakes can be released after the train has been brought to a halt, following a TPWS Brake Demand. This value is measured in milliseconds. This is an integer value, with the default value being 60000 milliseconds.
TssOverrideTimeout =
The TPWS TSS Override timeout period (used when passing a signal at danger with a signaller's permission), measured in milliseconds. This is an integer value. The default value is 20000 milliseconds.
OssTimeout =
The TPWS OSS timeout period, measured in milliseconds. This is an integer value. The default value is 974 milliseconds, which is suitable for passenger trains. For freight trains, specify a value of 1218 milliseconds instead.
IndicatorBlinkRate =
The TPWS Brake Demand indicator lamp blink rate, measured in milliseconds. This is an integer value. The default value is 300 milliseconds.
The [Dra] section
This system has no options to set, apart from the options common to electrical systems and all systems (see above).
The [Headlights] section
This system has no options to set, apart from the options common to electrical systems and all systems (see above).
The [Taillights] section
This system has no options to set, apart from the options common to electrical systems and all systems (see above).
The [Blower] section
Delay =
The delay before the in-cab blower (fan) loop sound begins, measured in milliseconds. This allows the blower spinning up sound to play before the looping sound begins. This is an integer value. The default value is 1700 milliseconds.
The [Pantograph] section
UpResetTimeout =
The time taken to raise the pantograph from the lowered position, measured in milliseconds. This is an integer value. The default value is 5000 milliseconds.
PantographLocation =
The distance from the front of the train to the pantograph head, measured in metres. This can be either an integer or a floating point value. The default value is 0 metres.
The [Tapchanger] section (unfinished)
This system has no options to set, apart from the options common to electrical systems and all systems (see above).
The [Apc] section
ApcReceiverLocation =
The distance from the front of the train (beacon receiver) to the location of the bogie-mounted Automatic Power Control receiver, measured in metres. APC is a system which automatically cuts power to the on-board traction power equipment while passing a neutral section in the overhead line. This allows the APC receiver to be located nearer to the pantograph. This can be either an integer or a floating point value. The default value is 0 metres.
The [Horn] section
CentreTimeout =
The timeout period before the horn lever returns to the centre position after the horn is blown, measured in milliseconds. This is an integer value. The default value is 1000 milliseconds.

### Information for programmers

Description of how this plugin works:
This plugin features multiple safety/operational system classes, multiple power supply classes, a power supply manager class, an interlock manager class, a startup/self-test manager, and an offset beacon manager class, a cab controls class, a sound manager class, and AI guard class.
General design principle summary:

- Classes representing functional electrical systems have power states, operational states (used as failure modes), and safety systems have a safety state. These classes can be instantiated.
- Systems are continually updated via calls in the Elapse() method, although inner processing is carried out based upon conditions and states.
- Safety state changes are initiated via methods, usually in the form of a command relevant to the system, called either when the host application issues an event, or by other systems. These methods can ensure that certain state changes are conditional and safe.
- A system can read but not modify another system's state(s) directly, so the provided methods must be used, unless the state in question is managed by an outside manager-style class. It is nevertheless good practice to call a suitable method when interacting with a system.
- Manager-style classes are static, and cannot be instantiated. They can alter relevant states of managed systems.

Cab Controls class:
This class stores the state of the "physical" in-cab controls (i.e. buttons, switches, handles, and so-on). The states within this class, are changed via the KeyDown(), KeyUp(), SetPower(), SetBrake(), SetReverser(), and DoorChange() methods, as initiated by the host application. The cab controls class is also responsible for determining the state of panel elements which represent physical controls. Safety system classes for example, can also monitor the states within the cab controls class if required.
Safety System classes:
Each safety system class derives from the abstract ElectricalSystem class. All electrical systems connect directly to the power supply manager, have required voltage and current values, circuit breakers which can be opened or closed, as well as "operative states", which can be used to determine failure modes (in future).
Safety system classes do not directly control the power and brake handle positions. Rather, they issue "Demands" and "Requests" to the interlock manager class, which itself determines when to lock the brakes on, or cut-off traction power, and also when the power and brake interlocks can be released. Hence, a safety system class can demand that the interlock manager apply the brakes or cut-off traction power immediately, but can only request that the brakes be released or traction power be restored.
Each safety system class has states, and an Update() method. The implementation within the Update() method of a safety system class defines its behaviour based upon the current state of the safety system, and is called once during each Elapse() call, as initiated by the host application. Safety system classes also have non-inherited methods which should be called via the the SetReverser(), SetBrake(), SetPower(), SetBeacon(), KeyDown() and KeyUp() methods, to set safety system states when events from the host application are triggered. Safety systems also implement a Reset() method, with the implied action carried out unconditionally, so should be used only where necessary, however the interlock manager will still retain control of the brake and traction interlocks regardless. The inherited Enable() method should be used if a train is to be equipped with a particular safety system, according to the configuration file. Safety system classes can also check the state of any relevant controls in the cab controls class, and update themselves depending upon the states of those relevant controls, if necessary. Each safety system class has a Reinitialise() method, which should be called via the Initialise() method, as initiated by the host application. This sets the safety system to a default state upon loading a route, or jumping to a station.
Safety system classes directly control the state of relevant in-cab indications and playback of sounds (via the panel[] array and sound manager).
If safety systems need to know the state of other safety systems, then this can be accomplished in two ways. Firstly, the state of a safety system is available via internal read-only properties. Secondly, safety systems can communicate with each other using events. For example, the Automatic Warning System class publishes an event which occurs whenever the AWS reset button has been released. The Vigilance Device, along with the Train Protection and Warning System, subscribe to this event, as they are both tied to the Automatic Warning System. If a safety system needs to change the state of another safety system, it should call an appropriate method.
Interlock Manager:
The interlock manager class has direct control over forcing the brakes to be applied, cutting off traction power, and determining when the brakes can be released, and traction power restored. Safety system classes can issue brake demands to the interlock manager via its DemandBrakeApplication() method, or demand that traction power be cutoff via the DemandTractionPowerCutoff() method. The Interlock Manager will always act immediately upon these demands. However, safety systems can only make requests for the brake and power interlocks to be released again, via the RequestBrakeReset() and RequestTractionPowerReset() methods. If such an interlock reset is requested, the interlocks will only be released if certain Interlock Manager rules and behaviours permit it at the time of the request. If the reset is not permitted at the time, then the request remains pending, and will be granted whenever the prerequisite conditions are eventually met. The Interlock Manager also checks the states of safety system classes or the cab controls class where necessary, to determine whether a brake or traction power interlock should be released.
Power supply classes:
Note: This feature is more for future use, if and when openBVE supports clickable 3D cab controls, as such things as circuit breaker panels can be simulated then.
Power supply simulation has three main aspects; the power supply manager, a range of power supplies, and individual electrical systems. Power is primarily handled via the power supply manager class. Electrical systems are first "connected" to the power supply manager, and then a single power supply can be connected to the power supply manager at any given time, too. The power supply manager monitors all connected electrical systems to determine their total voltage and current requirements. It also monitors the connected power supply to check whether it is able to supply enough current. If the power supply becomes overloaded or otherwise has its circuit breaker tripped open, the power supply manager sets the power state of each connected electrical system accordingly, so they no longer function until power is restored.
Each power supply has a maximum voltage and current rating, and monitors the power requirements of the power supply manager. If the power supply manager current demand exceeds the available amperage of the power supply in question, the power supply will trip open its own circuit breaker in the event of an overload condition. If a power supply's circuit breaker trips, it must be manually closed before the power supply will provide power again.
Train developers should configure power supplies to always have a sufficiently high current rating in all circumstances, until it becomes more practical to simulate the ability to open and close individual circuit breakers by using the mouse to interact with a 3D cab.
Sound playback:
The sound manager class provides Play(), Stop() and IsPlaying() methods, and deals with the sound handles passed from the host application. Calling the Play() method with a specified sound index, starts playback of the sound, either once only, or looped continuously, with a specified pitch and volume.
If a sound is played without looping, and a subsequent call using the same sound index is made, but the sound hasn't finished playing and neither the pitch or volume are different, the sound is stopped and then played again from the start. If playback of a non-looping sound index has not finished yet, and another play request is made with the same sound index, but the the pitch or volume is different this time, then the sound continues playing with the new pitch or volume.
If a sound index is looped, subsequent calls to the Play() method allow for the volume and pitch to be changed, without sound playback stopping and starting again.
The IsPlaying() method returns a boolean indicating whether or not a specified sound index is currently playing.
Offset Beacon Receiver Manager class:
This class stores information about certain types of beacon when the SetBeacon() method is called. Specifically handled, are beacons for which in reality, the beacon reciever should not be located at the front of the train, which is where the openBVE "beacon receiver" is located. The offset beacon receiver manager can assume the role of issuing trigger points to systems which respond to these beacons. This allows a train with an offset beacon receiver to travel backwards over beacon locations, with the action associated with the beacon, being triggered at the correct location, as though the actual beacon receiver were not at the front of the train.
A new beacon is added to the offset beacon receiver manager via the AddBeacon() method (which is done via the SetBeacon() method, as initiated by the host application when passing a beacon location). A new beacon is only added if the train is travelling forwards at the time that AddBeacon() is called. Several pieces of information are stored - the actual location of the beacon, the beacon type, the beacon's optional data, and a beacon receiver offset value. These values are used to trigger an action associated with the beacon, at a location which takes the offset beacon reciever location into account, whether travelling forwards, or backwards. When the train is travelling backwards, if the actual beacon receiver passes the location of a stored beacon, then the beacon information is deleted from the stored beacon array, so that it can be registered again, if the train later passes the beacon while travelling forwards.
When the Reinitialise() method is called, i.e. when jumping to a station, any beacons stored by the offset beacon receiver manager are deleted. For a beacon to be registered again, it must be added via the SetBeacon() method, when the train is travelling forwards.
Source Code:
For the source code, please see the "source" folder which was included within the UkTrainSys archive which you downloaded, where you can find the solution and C# files. I recommend using SharpDevelop as your IDE. For the latest version of the plugin, source code, documentation, and configuration files for openBVE trains, please visit http://railsimroutes.net/libraries/uktrainsys/.

###

Anthony Bowden
23rd December, 2010
--
http://railsimroutes.net