Plugin version: 0.3.2.0
Author: Anthony Bowden
Project homepage: https://railsimroutes.net/libraries/uktrainsys/
Target simulator: openBVE v1.5.4.1 upwards
Target CLI: Microsoft .NET 4.0 / Mono 4.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


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


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:


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:


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:


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:

• 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:


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:


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:


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):


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):


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   920dxxxxx 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 920100200 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:


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:


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:


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:


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:


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:


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):


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:


If using the freight train OSS timeout period of 1218 ms:


You can also calculate the beacon spacing with any OSS timeout value, by using the following formula:


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:


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):


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):


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:


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:


OSS Timer B, is armed and triggered by the following different frequencies:


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:


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:


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:


TSS Detection B, is armed and triggered by the following different frequencies:




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:


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:


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:


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:


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:


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:


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/.

Change Log

Recent changes:

[Updated 10th April 2019: v0.3.2.0]

Fixes:

• Fixed an issue with the Train Protection and Warning System (TPWS) simulation where an incorrect variable in the ArmTss() method was reset upon passing an opposite-direction TSS f5 frequency. [Thanks to Chris Lees for spotting the typo in my code!]

Changes:

• Recompiled the plugin with Target .NET Framework of v4.0 and checked functionality with openBVE v1.5.4.1.

Recent changes:

[Updated 9th February 2011: v0.3.1.91]

Fixes:

• If the Driver Reminder Appliance (DRA) is disabled via the UkTrainSys.cfg file, it's no longer possible for the state of the device to be set to SafetyStates.Activated, preventing unwanted Interlock Manager interventions.

[Updated 25th December 2010: v0.3.1.9]

Changes:

• Added initial support for diesel trains which use Simon Gathercole's UKSpt.dll. Much of Simon's complex diesel engine model is reproduced by the UkTrainSys plugin, rather than the simple model, which isn't supported. This means that UkTrainSys includes the requirement to hold the engine starter button down until the engines are running, as well as simulating the starter motor, and a percentage likelihood that the engine will stall on starting (default 25%). The diesel engine class is implemented as another kind of power supply, like the battery, so it can provide electrical power, or be overloaded, for example. I'll model fuel consumption at a later date.
  
  
• Added diesel engine startup and restart procedures to the AI Support feature.
  
  
• Implemented the optional Vigilance Device reduced cycle time of 45 seconds, when the power notch is 6 or 7 (for use with UK Sprinter trains).
  
  
• Changed the conditions under which the vigilance device inactivity timer can be reset. Now, the timer is only reset if the power/brake controller is returned to the Off or 0 position - moving between different power or brake notches without returning the controller to 0, no longer resets the timer. Also, sounding the horn will now reset the vigilance timer, too.
  
  
• Improved the AI Support's handling of the Driver Reminder Appliance (DRA). Now, the AI Support will only activate the DRA if the train is 150 metres in the rear of the upcoming signal showing a red aspect, or nearer. This distance in the rear of the signal, within which the DRA will be operated by the AI Support, can be configured via the UkTrainSys.cfg file.
  
  
• Changed the AI Support related panel indices, to accomodate a solution for the infamous freaky anomalous multiple-arm phenomenon (backwards incompatible change).
  
  
• Changed the default Enabled states, so that if no configuration file is found, all systems are disabled by default. The Interlock Manager is also now disabled by default, under these circumstances. This means that if a new configuration file had to be created, then no systems will be simulated, but the train can still be driven successfully.
  
  
• Made some adjustments regarding the internal reverser position. The Interlock Manager's DemandTractionPowerCutoff() method, now sets the internal reverser to neutral, as well as setting the internal power handle position to zero, so that regenerative braking is also disabled along with traction power.
  
  
• The AI driver now visibly interacts with the reverser handle in many, but not all, cases (backwards incompatible change).
  
  
• Expanded the range of optional Data values which UkTrainSys will reconise, when passed as a parameter of a .Beacon 50 command. A new value of 40 informs the plugin of an upcoming terminal station stop, and a value of 41, instructs the AI Support to lower the pantograph (or stop the diesel engine) the next time the train stops and the doors open. This also resolves the situation where openBVE's AI and the plugin repeatedly override each other at a terminal station. .Beacon 50 can also now instruct the AI Support to return the power handle to the off position, prior to a neutral section. Please see the documentation for more details.
  
  
• The AI Guard has been expanded to accomodate multiple stopping locations at a station, passed via multiple .Beacon 24 commands. UkTrainSys selects the appropriate beacon to act upon, depending upon how many cars the player's train has. Please see the documentation for more details.
  
  
• When a brake demand is issued, emergency brakes are now applied, rather than service brakes.
  
  
• The time taken to lower the pantograph is now half of the specified pantograph rising time.
  
  
• The simulation of the Train Protection and Warning System (TPWS) is now much more realistic. The previous behaviour, emulated the functionality found in Simon Gathercole's range of Windows-only BVE4 plugins. This was adequate in many cases, however it didn't work in the same way that the real TPWS works in all cases, particularly with regard to the Overspeed Sensor System (OSS) and Trainstop Sensor System (TSS). In the case of the OSS, with Simon's plugin, a single beacon was used, which specified a maximum permitted speed. If the train was travelling above this speed when passing the beacon, a TPWS brake demand was issued. This did not, however, take braking or deceleration curves into account. With the TSS, a single beacon was also used; to the user, this worked prototypically, although it's an over-simplification of how the real system works.
  
  The new UkTrainSys implementation of TPWS, works just like the real system. An OSS can now be comprised of a pair of induction loops (beacons), each emitting a unique frequency (specified via the optional Data parameter), and the spacing between the beacons determines the permissible speed. UkTrainSys features a pair of OSS timers; each is independent of the other, and each is armed and triggered by specific frequencies. This means that UkTrainSys also supports the interleaving and nesting of OSS induction loops, as well as realistic behaviour when travelling backwards over the beacons.
  
  UkTrainSys also now supports realistic TSS behaviour. Each TSS can now be comprised of two induction loops, just like in reality, each emitting one of two specific frequencies, as with the OSS induction loops. One frequency arms the TSS, and the other frequency triggers a TSS brake demand, provided that it is detected while still within detection range of the TSS arming induction loop. As with the OSS, the TSS supports a pair of detection processes which operate independently of each other, each armed and triggered by specific frequencies. This also allows for fully realistic behaviour while travelling backwards over TSS installations (more for future use).
  
  It should be noted, that UkTrainSys does still support the old, legacy behaviour in use on existing routes, but developers creating new routes for openBVE, are encouraged to use the new, realistic TPWS simulation instead, not only because it's more realistic, but because it's more flexible, and possibly more future-proof if openBVE supports networked tracks in future. Please see the documentation for more details.
  
  
• The simulation of the Automatic Warning System (AWS) has been enhanced, and now works just like the real AWS. UkTrainSys now supports the detection of the permanent magnet, and the electromagnet, allowing for a fully realistic AWS implementation, using only a single beacon type.
  
  The new AWS simulation includes the 1000 ms delay timer for detection of the electromagnet. Upon passing the permanent magnet, the AWS is set and the sunflower instrument goes black, and only if the electromagnet is detected, is the AWS reset (i.e. the bell/bing sound is heard). If no electromagnet is detected within the delay period, then an AWS warning is issued, and the sunflower is displayed.
  
  As with the real AWS, travelling at a very low speed over an AWS inductor associated with a signal showing a clear (green) aspect, will initially trigger an AWS warning (because the electromagnet isn't detected in time), and then, if the warning isn't cancelled, the AWS is reset automatically as the electromagnet is detected (and the bell/bing is then heard).
  
  The new UkTrainSys AWS simulation also supports AWS suppression, via the insertion of beacons either immediately before or after the permament magnet beacon. This can be used to suppress the AWS in one or both directions of travel, although this feature is more for future use, should openBVE support bi-directionally signalled lines in future.
  
  As with the TPWS simulation, UkTrainSys does still support the old, legacy AWS implementation in use on existing routes, but again, developers creating new routes for openBVE, are encouraged to use the new AWS simulation instead, for the same reasons as the new TPWS simulation is preferred. Please see the documentation for more details.

Fixes:

• Fixed a crash which would occur, if there was no power supply enabled.
• Fixed an issue, where the Vigliance Device inactivity timer could have an excessively large value assigned, when jumping to a previous station.

[28th November 2010: v0.3.1.3]

Changes:

• Updated the plugin for compatibility with openBVE v1.2.9.20; changed the SetSignal() method implementation.

[26th November 2010: v0.3.1.2]

Changes:

• Support for TPWS+ (Plus) installations is now approved. Please see the documentation for beacon details.
• The AI support now sets and resets the DRA upon stopping the train, depending upon the state of the upcoming aspect.
  Known issue: There's currently a minor problem I've noticed, where at Birmingham New Street on the Cross-City South route for example, the AI arm reaches out to operate the DRA switch, but waits for 10 seconds before actually doing it. It seems that openBVE isn't calling the PerformAI() method for that time period, for some reason.
• Added an "Offset Beacon Receiver Manager", which 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. 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.
• Neutral section, pantograph and air-blast/vacuum circuit breaker (ACB/VCB) simulation has been enhanced. Beacon 20 now allows for both the APC magnets and the neutral section itself to be simulated seperately. If the train passes a pair of APC magnets which causes the Automatic Power Control system to command open the ACB/VCB, and the train's speed is insufficient, such that the train stops, then the pantograph up/reset button can be pressed to re-close the ACB/VCB. If the train's pantograph/APC receiver location is not within the 4 metre long neutral section of overhead line, then overhead power is still available, which will allow the driver to move the train forwards or backwards, depending upon which side of the neutral section the train is stranded on. The driver can then accelerate to a sufficient speed in order to coast through the neutral section successfully this time. If the train's pantograph stops within the 4 metre long neutral section, then there is no overhead power, no matter whether the ACB/VCB is re-closed or not.
  Note: This works whether the train is travelling forwards or backwards, even if the APC receiver is located at the back of the train (as would be the case with an electric loco pushing a rake of coaches and a Driving Van Trailer, from the rear).

Fixed:

• The plugin no longer crashes if AI support is enabled on a route with no sections defined.

[21st November 2010: v0.3.1.1]

Changes:

• Added a timer for checking whether or not the PerformAI() method has been called by the host application within the last 10 seconds. If not, the plugin assumes that the AI driver is no longer enabled in the host application, and the AI arms and hands are no longer shown. [Thanks to Michelle for the suggestion]
• Fixed some issues with the TPWS Isolation feature not working correctly (it hadn't been tested properly - my apologies).
• Added a delay after the AI driver has responded to the guard's ready-to-start buzzer signal, to prevent the AI from taking power, so the left hand has enough time to transition from the buzzer signal button to the traction/brake controller, before the latter is moved on departure.
• Updated the Interlock Manager brake release and traction power conditions.

[20th November 2010: v0.3.1.0]

Changes:

• Added plugin variables in the 50-52 range, to support visible driver's arms and hands interacting with cab controls when openBVE's AI human driver is enabled.
• Debug mode is now disabled by default, if no existing configuration file is found.
• Added support for a guard's buzzer indicator light (plugin variable 25) [Thanks to Steve Green for the suggestion]
• Added plugin variables (15 and 16) to support individual left and right door indicators.
• Added an IsPlaying() method to the SoundManager class, which returns a boolean indicating whether or not a specified sound index is currently playing.
• Guard's buzzer signals are now handled by repeatedly playing a single buzzer sound as many times as is necessary, making the dedicated "set back", "draw forward" and "ready to start" buzzer sounds obsolete. These audio files and associated sound variables are no longer supported by the UkTrainSys plugin. This change has been made, to enable the guard's buzzer indicator light to illuminate whenever a buzzer sound is being played, and to extinguish between each playback of an individual buzzer sound.
• Added the guard's "ready to start" buzzer signal.
• Expanded the AI Support feature to automatically respond to the guard's buzzer signals with the driver's own buzzer response.
• Added support for a new beacon (50), which can instruct the AI driver to perform an action within the cab, depending upon the optional Data parameter. Currently, this beacon can be used to instruct the AI driver to sound the horn, either with a low tone followed by a high tone on the horn, or vice-versa.
• Added support for the Automatic Power Control system and beacon 20, which represents the APC magnets. Both new and legacy beacon 20 behaviour is implemented; if the Data parameter is greater than zero, legacy behaviour is used, which is compatible with existing routes which use this beacon. If the Data parameter is zero or om itted entirely, the new behaviour is used, which requires a .Beacon 20 command both before and after the neutral section.
• Optimised the way in which strings are handled, and reorganised the files within the solution. [Many thanks to Mustafa Selcuk Oral or the feedback]

[11th November 2010: v0.3.0.2]

Changes:

• Discarded the Plugin.TrainSpecifications class in favour of using OpenBveApi.Runtime.VehicleSpecs; altered debug message handling to make use of the StringBuilder class instead, and put an end to apostrophe abuse. [Thanks to Michelle for the feedback ;-)]
• Altered TPWS Overspeed Sensor behaviour, such that the speed of the train only matters at the instant the final OSS loop is passed over. [Thanks to Steve Green for the feedback]
• The plugin now ignores all beacons when jumping to a new station.
• Minor improvements to the horn lever automatic return-to-centre feature.

[8th November 2010: v0.3.0.0]

• Initial release for evaluation and testing.

Anthony Bowden
28th March, 2019
--
http://railsimroutes.net