# UKSPt.dll.20.05 - release notes

by | Simon Gathercole
issued | 20/05/05

## Contents

1. Contents
2. Summary
3. Starting states
4. Configuration
5. Master Switch
6. AWS/TPWS
7. Vigilance
8. Interlocks
9. Engine
10. Guard
11. Door Release Indicators
12. Rain and Windscreen Wipers
13. Head and Tail Lights
14. Horn Lever Animation

## Summary

UKSpt.dll is an ats plugin for BVE4 designed to represent a variety of modern UK diesel multiple units and specifically the BR 'Sprinter' series, classes 150 to 158.
The plugin has been completely redesigned since the last release (UKMUt.18.01) and includes many new features, which are summarised below and described in detail in the rest of this document:

- the ability to specify simulation starting state in the route file
- configuration of certain features via a configuration file
- simulated 4-position reverser, incorporating Master switch
- DRA is ON in all starting states as required by the Rulebook during crew changes
- revisions to operation of AWS/TPWS to follow the prototype more closely
- safety systems (AWS/TPWS and the Vigilance Device) may be fully isolated
- the type of vigilance device fitted may be specified in the configuration file
- several new and revised interlocks have been included
- an engine feature with realistic startup and shutdown sequences and prototypical interlocks
- door release indicators show the correct side on suitably equipped routes
- a guard gives correct the draw forward/set back buzzer signals on suitably equipped routes
- windscreen wiper and rain simulation
- separately controlled head and tail lights with proving lights
- extensive animation of secondary controls

## Starting states

Two starting states are available:

- OFF

- Master switch off
- Instrument lights off
- Head and tail lights off
- Engine stopped
- Drivers Reminder Appliance automatically switches ON when the Master switch is turned on

- NEUTRAL

- Master switch on, reverser in neutral
- Instrument lights on
- Headlights on (daytime configuration), tail lights off
- Engine idling
- Drivers Reminder Appliance ON

The desired starting state is selected in the route file, where

- `Route.change 0` selects OFF and
- `Route.change 1` selects NEUTRAL

If the driver uses the BVE restart or jump to features, the following starting states are automatically selected:

- on restart or jump to the originating station, the starting state specified in the route file is selected
- on jump to any other station, the train is restarted in NEUTRAL

#### Note for drivers on using jump to

Following a jump to, the driver should ensure that the controls are resynchronised with the plugin by

1. returning the reverser to NEUTRAL
2. returning the power handle to OFF
3. applying full service brakes

#### Note on Beacons

During a jumpto operation, BVE sends all the beacons passed by the train to the plugin, which can result in unexpected behaviour - particularly if the jump is backwards to an earlier station! To avoid this, the plugin currently ignores all beacons received immediately following a start/restart.
In the current version this imposes the following limitations:

- Door release indicators will not be correctly set on starting (they can be adjusted manually);
- Rain beacons must be placed after the initial .stop statement - it is not possible for the route to commence with rain falling.

It may be possible to remove these limitations by more sophisticated processing of beacons and this will be considered for future releases.

## Configuration

The configuration file is named UKSpt.cfg and resides in the same folder as the plugin.
All configuration statements have the form:
`classId.attributeId=value or
classId.attributeId=value1,value2,value3,...
`
where

`classId` | identifies the feature, e.g. "wiper" for rain and windscreen wiper
`attributeId` | identifies a configurable attribute, e.g. "holdPosition" for the wiper parking position

Note that the configuration statements must be entered exactly as shown above, without any whitespace. Details of configuration for individual features are given in the sections below.

## Master Switch

#### Panel variables

ats0 | = 1 when Master switch is OFF
ats1 | = 1 when Master switch is ON

When the starting state is OFF, the master switch must be turned on before the train can be driven - this is done by moving the reverser from 'neutral' to forward and returning it to neutral (this is as close as BVE allows to a four position reverser/master switch). The following should then occur:

- Instrument lights come on
- DRA comes on
- AWS test sequence begins
- Engine startup is enabled

Instrument illumination is faked using masks to represent the unilluminated instruments, controlled as [Pilotlamps] from ats0.

## AWS/TPWS

#### Panel variables

ats6 | = 1 when AWS display is Black
ats7 | = 1 when AWS display is Sunflower
ats8 | = 1 when AWS reset button is pressed
ats9 | = 1 when TPWS Brake Demand lamp is on
ats10 | = 1 when TPWS Isolation lamp is on
ats11 | = 1 when TPWS TSS override lamp is on

#### Sound variables

ats0 | AWS bell
ats1 | AWS startup test bell (reduced sounding time)
ats2 | AWS horn

#### Keys

ats key A1 | [Insert] | AWS reset
ats key C1 | [Page Up] | TPWS TSS override
ats key C2 | [Page Down] | AWS, TPWS, vigilance isolate

#### New Features for TPWS fitted trains:

#### Self Test

A more detailed representation of the AWS/TPWS self test is included. It is initiated by turning the Master switch on and proceeds as follows:

1. AWS display turns from black to sunflower and back to black
2. The TPWS lamps are illuminated
3. The brakes are applied
4. The AWS horn sounds
5. Pressing the AWS reset button cancels the AWS horn, sounds the AWS bell briefly, turns off the TPWS lamps and allows the brakes to be released.

Note: the reduced AWS bell sound at the end of the test is deliberate, suggested by prototype notes.

#### AWS Brake Demand

- If the AWS horn is not acknowledged within 2-3 seconds

- the brakes are applied;
- the TPWS brake demand lamp flashes;

- On acknowledgement by pressing and releasing the AWS reset button:

- the TPWS brake demand lamp becomes steady
- the AWS sunflower is displayed
- the AWS horn stops sounding

- The brake demand is maintained for the same period as a TPWS brake demand - approximately 1 minute - after which:

- the brakes are released
- the TPWS brake demand lamp goes out

(Thanks to Paul Cooper for information on this feature.)

#### Safety System Isolation

Pressing [Page Down] fully isolates the safety system (AWS/TPWS and VIGILANCE device) and illuminates the TPWS isolation lamp. This feature is not completely prototypical but is provided as a route development/learning aid.

## Vigilance

#### Configurable features (classId =`"vigilance"`)

type | 0, 1, 2 (default 2) | as below

The type of vigilance device fittted to the train is configurable using the `type` attribute, with values:

0 | no vigilance device
1 | standard vigilance device with 60 second cycle time
2 (default) | Sprinter-type vigilance device with cycle time reduced to 45 seconds in notches 6 and 7

## Interlocks

#### New Features:

#### Reverser Interlocks

Brakes are now held on

- when the reverser is OFF
- if the reverser is moved to NEUTRAL while the train is in motion.

#### Door Interlocks

Brakes are held on when the doors are released, unless the reverser is in NEUTRAL.

#### BVE Interlocks

The following non-prototypical interlocks have been added to conform with the behaviour of BVE:

- power is held off whenever the brakes are applied
- power is held off whenever the reverser is in NEUTRAL

## Engine

#### Panel variables

ats3 | = 1 when the engine is running
ats4 | engine start pushbutton with integral indicator lamp (display using [DigitalNumber])
| starter inactive | starter active
button unpressed | 0 | 2
button pressed | 1 | 3
ats5 | engine stop pushbutton with integral indicator lamp (display using [DigitalNumber])
| engine stopped | engine running
button unpressed | 0 | 2
button pressed | 1 | 3

#### Sound variables

Engine start sounds
ats7 | starter motor switching on
ats8 | starter motor loop
ats9 | starter motor running down
ats10 | engine start
ats11 | engine stall on start
ats12 | engine idle
ats13 | engine revving up
ats14 | engine revving down
ats15 | engine stopping

#### Keys

ats key D | [2] | Start engine
ats key E | [3] | Stop engine

#### Configurable features (classId =`"engine"`)

##### General

starterType | 0, 1 (default 0) | 0=simple start model; 1=complex start model
runDownDelay | >0 (default 4000) | length in ms of the revving down sound (ats14)

##### Simple start model

startDelay | >0 (default 4000) | length in ms of the engine start sound (ats10)

##### Complex start model

startDelay | >0 (default 4000) | length in ms of the engine start sound (ats10)
motorStartDelay | >0 (default 250) | length in ms of motor switch on sound (ats7)
stallDelay | >0 (default 1000) | length in ms of engine stall sound (ats11)
fireProbability | 0-1000 | simulation features - see below
stallProbability | 0-1000 |
minFireProbability | 0-1000 (default 10) |
maxStallProbability | 0-1000 (default 400) |

#### New Features:

#### Interlocks

- Before starting the engine:

- the Master Switch must be ON
- the train must be stationary
- the reverser must be in NEUTRAL
- the power handle must be OFF

- Power cannot be applied if the engine is not running!

#### Starting

Two models of engine starting are available:

#### Simple start model

A single sound file is required, covering the entire startup procedure. It must be aliased to `ats10` in `sound.cfg`.
On pressing the engine start button:

- the engine start (`ats10`) sound is played once;
- the engine start button is illuminated;
- after `startDelay` milliseconds:

- the engine idle loop is played;
- illumination of the start button ceases;
- the power interlock is released.

#### Complex start model

Five sound files are required, as listed above. To start the engine, the start button must be pressed and held until the engine fires after a random number of BVE frames. To add even more excitement, the engine randomly stalls after firing. The ease of starting and likelihood of stalling can both be configured.
On pressing the starting button:
If interlocks prevent starting (see above):

- the engine start button is animated, but does not illuminate;
- the engine does not start.

If starting is allowed:

- the starter motor switching on sound (`ats7`) is played once;
- the engine start button is illuminated;
- after `motorStartDelay` milliseconds:

- the starter motor loop (`ats8`) is played;
- the engine start loop begins.

During the engine start loop

<>the probability of the engine firing in any one BVE frame is as configured by the attribute `fireProbability` (a value between 0 and 1000)
- if the start button is released during this period

- the starter motor loop ends
- illumination of the start button ceases
- the starter motor running down sound (`ats9`) is played
- the engine returns to the stopped state.

On engine firing:

- the probability of the engine stalling is as configured by the attribute `stallProbability` `` (a value between 0 and 1000);

- if the engine stalls:

- the engine stalled sound (`ats11`) is played once;
- after stallDelay milliseconds:

- illumination of the start button ceases
- the engine returns to the stopped state.

- Note that the start button must be released before another starting attempt can be made.

- if the engine does not stall

- the engine start (`ats10`) sound is played once
- after `startDelay` milliseconds:

- the engine idle loop is played
- illumination of the start button ceases
- the power interlock is released

#### Randomising Start Performance

With the complex start model, performance can be further randomised by specifying:

`fireProbability` | = 0
`stallProbability` | = 1000

In this case random values are assigned as follows:

`fireProbability` | a value between `minFireProbability` and 1000
`stallProbability` | a value between 0 and `maxStallProbability`

#### Revving up/down sounds

These sounds are played whenever the power handle is moved away from/to the OFF position. In addition, the revving down sound is correctly played if the power is tripped by an interlock.

#### Notes

1. There is a slight but noticeable delay on shutting off power before the revving down sound is played, due to the way BVE handles plugin sound variables. If this is unacceptable, increase the power down delay in the `train.dat` file.
2. Because it is not possible with BVE 4.1 to fade plugin sounds out, stopping the idle loop when the power handle is opened produces an unrealistic sudden change in the engine sound. To avoid this, the idle loop is played continuously, regardless of power setting.

#### Engine shutdown

On pressing the engine shutdown button:

- the engine stopping sound (`ats15`) is played once
- the power interlock is reapplied

Note that there are no interlocks preventing the engine stop button being active while the train is in motion.

## Guard

#### Sound variables

ats5 | Draw forward signal
ats6 | Set back signal

#### Beacons

23 | Door release side
24 | Station limits

#### New Features:

In a suitably beaconed route, the Guard will play the correct buzzer signal if the train stops outside the permitted zone at a station. The route must be equipped as follows:

- `.beacon 23;0;0;s` must precede the station with s not equal to 0. If s is 0, the Guard will ignore the following station limits beacons - this enables non-stopping routes to be created with minimal recoding.

- `.beacon 24;0;0;ddduuoo` defines the start of station limits, with:

- ddd = distance from this beacon to the `.stop` statement in metres
- uu = permitted underrun in metres, as in the `.stop` statement (must be two digits - pad left with 0 if less than 10m)
- oo = permitted overrun in metres, as in the `.stop` statement (must be two digits - pad left with 0 if less than 10m)

- `.beacon 24;0;0;0` defines the end of station limits

- if this beacon is omitted, station limits end if the overrun exceeds 500m

The Guard will not play a buzzer signal if the train stops outside station limits, so that signal stops will not be affected.

## Door Release Indicators

#### Panel variables

ats14 | = 1 when the doors are closed
ats15 | = 1 when the left hand doors are released
ats16 | = 1 when the right hand doors are released

#### Keys

ats key J | [8] | release doors (left)
ats key K | [9] | close doors
ats key L | [0] | release doors (right)

#### New Features:

This is a stub which controls door interlocks and allows for more detailed models of specific door types in future. It is, however, able to drive door release indicators on routes correctly equipped with .beacon 23. The keys allow the correct indication to be selected manually on startup or after a restart.

## Rain and Windscreen Wipers

#### Panel variables

ats198 | wiper switch position, =0 (OFF), 1, 2... up to the number of wiper settings
ats199 | wiper position
ats200-255 | raindrop animation = 1 when raindrop is visible

#### Sound variables

ats16 | switch sound
ats17 | single sweep of wipers on wet windscreen
ats18 | single sweep of wipers on dry windscreen
ats19-23 | raindrop sounds

#### Keys

ats key B1 | [Home] | wiper on/speed up
ats key B2 | [End] | wiper off/speed down

#### Configurable features (classId =`"wiper"`)

holdPosition | 0 or 100 (values >0 are treated as 100; default 0) | parking position of wiper
sweepTimes | time1,time2..., values >0 (default single value of 1000) | time in ms for a single sweep of the wiper
holdTimes | time1,time2..., values >250 (default single value of 250) | corresponding hold times in ms
nDrops | 0-50 (default 50) | number of raindrops to use
nDropSounds | 0-5 (default 5) | number of drop sounds to use
vFactor | Rain simulation features - see below |
lockout |  |
wipeFactor |  |
dryLimit |  |

#### Beacons

21 | optional data from 0-100 gives rain intensity

#### Features:

Modelling of rain and windscreen wipers is based on code designed and written by O.Saarekas and is used with permission. However, a number of enhancements and new features have been added:

#### Wiper speeds and hold times

Wiper speed is configurable up to a maximum of four settings, plus OFF. Speeds are entered in the configuration file under the attribute `sweepTimes` as a list of values, each representing the time in milliseconds for a single sweep of the wiper across the screen. The default is a single setting with a sweep time of 1000ms.
For each speed, a hold time is configurable using the attribute `holdTimes` to create intermittent wiper modes. Note that even in continuous modes, the minimum hold time is 250ms (see Wiper Animation below). If more hold times are entered than sweep times, superfluous hold times are ignored; if there are fewer hold times than sweep times, the default hold time of 250ms is used.

#### Wiper Animation

For better visual effect a minimum pause of 250ms at each end of the wiper's sweep has been introduced: this ensures that the wiper appears to reach the end of its travel on every sweep. Previously, the wiper could sometimes reverse direction within a BVE frame and appear to miss out the end of its sweep.

#### Wiper Sounds

Two wiper sounds are supported, one representing the wiper on a wet windscreen, the other the scrape of a wiper on a dry windscreen. Changeover is controlled by rain simulation variables (see below).

#### Raindrops

From 0 to 50 (the default) raindrops can be configured using the attribute `nDrops`: the same drop placement algorithm is used as in OS_ATS_1.3.
Up to five (the default) drop sound channels can be configured using the attribute `nDropSounds`- they can be aliased to the same or different sound files in the `sound.cfg` file. It is strongly recommended that the full five channels be used, otherwise sound may not play correctly at higher rain intensities.

### New Rain Simulation Features

A number of the variables used in simulating rain are configurable in this release, to allow us to find the most effective values for them. It is likely that they will be fixed in future releases.

#### Speed Dependence

Rain intensity i now increases with speed as:
i = i0 × (1 + vFactor × speed)
where `vFactor` is a configurable attribute The default value is 0.05

#### Raindrop 'lockout'

At high rain intensities, the rain algorithm could reuse a raindrop almost immediately after it had been removed by the wiper, with two undesirable results:

1. It looked as though the wiper had missed the drop;
2. The difference in effectiveness between different wiper speeds did not show up well.

To avoid this phenomenon, drops are now locked out of use for a configurable time after being wiped. The time can be entered in milliseconds under the attribute `lockout` (default value 1000).

#### Wiper Sounds

To decide which wiper sound to use, the 'wetness' of the windscreen is modelled, increasing by 1.0 for each drop that falls and being reduced for every sweep of the wiper as
wetnessn+1 = wetnessn × 1/wipeFactor
where `wipeFactor` is a configurable attribute (default value 2.5).
The value of wetness at which the sound changes from 'wet' to 'dry' is configurable using the attribute `dryLimit` (default value 2.0).
The intention is that at low rates of rain, the driver will be forced to switch between wiper modes in order to avoid annoying wiper-scrape, introducing an extra level of distraction into the simulation :-)
To help with configuring this feature, an Excel spreadsheet Rain.xls is supplied. Given a starting value of wetness and the number of drops falling on each sweep of the wipers (a measure of rain intensity and approximately 1 at an intensity of 5), this calculates and displays on a graph:

- How the wetness varies for each sweep of the wipers
- The minimum value it will eventually reach (the asymptote)

It can also show the value of `dryLimit` for easy comparison.

## Head and Tail Lights

#### Panel variables

ats20 | Headlights [ = 0 (off), 1 (day), 2 (marker only), 3 (night) ]
ats21 | Taillights [ = 1 when on]

#### Sound variables

ats24 | Generic panel switch sound

#### Keys

ats key F | [4] | Toggle taillights
ats key G | [5] | Cycle headlights (works as a rotary switch)

#### Starting states for the Head and Tail lights:

#### Starting state OFF

- Headlights OFF
- Tail lights OFF

#### Starting State NEUTRAL

- Headlights ON (DAY)
- Tail lights OFF

## Horn Lever Animation

#### Panel variables

ats24 | = 0 (forward), 1 (off, centred), 2 (back)

#### Configurable features (classId =`"horn"`)

tForward | (default 1500) | time lever remains forward before automatically recentering
tBack | (default 1500) | time lever remains back before automatically recentering

#### Features:

The horn lever moves when either of the BVE horn keys is pressed and returns to its off position automatically after a time which can be separately configured to suit the horn sounds used with the train.

This document © Simon Gathercole 2005
Date of issue 20/05/05