Merge pull request #615 from Csantucci/EOT-official

 Management of EOT devices  https://blueprints.launchpad.net/or/+spec/eot

Author: Csantucci

Source/Documentation/Manual/cabs.rst

@@ -507,6 +507,156 @@ Here an example of use of one of the controls::
 		ORTSScreenPage ( "2300-0" )
 	)
 
+.. _cabs-eot:
+
+EOT (End of Train device)
+-------------------------
+
+See :ref:`here <physics-eot>` for full description of EOT features.
+
+Following EOT controls are available for EOT management:
+
+- ORTS_EOT_BRAKE_PIPE : displays the value of the brake pipe pressure at last wagon. 
+  The display is always enabled (even if the EOT is disarmed), because this display 
+  could be available also in other ways; however it is possible to mask the display 
+  using a texture driven by the EOT state.
+- ORTS_EOT_STATE_DISPLAY : may have values from 0 to 5, corresponding to the states listed :ref:`here <physics-eot-states>`  
+- ORTS_EOT_ID : the EOT ID is generated as a 5-digit random number and can be displayed 
+  in the cab using this control; entering the ID by the train driver is not supported, 
+  as the .cvf files don't support as of now digital data entry
+- ORTS_EOT_COMM_TEST : driver command that starts the communication test between locomotive and EOT
+- ORTS_EOT_ARM_TWO_WAY : driver command passes the EOT from ArmNow to ArmedTwoWay
+- ORTS_EOT_DISARM : passes the EOT to disarmed state
+- ORTS_EOT_EMERGENCY_BRAKE (on-off): lets the EOT venting the brake pipe from the last train car.
+  
+These controls are available only using the mouse; only The last one can also be operated by the 
+``<Ctrl+Backspace>`` key combination.
+
+An example of implementation of the above controls can be seen
+:ref:`in this picture <physics-eot-display>`
+
+The ``ORTS_EOT_EMERGENCY_BRAKE`` control can be implemented in the cab by an ON-OFF switch.
+
+An example of implementation of the above controls in a .cvf file follows::
+
+   		TwoState (
+			Type ( ORTS_EOT_COMM_TEST TWO_STATE )
+			Position ( 474 385 16.25 10 )
+			Graphic ( "..\\..\\Common.Cab\\ES44v3\\softkey5trans.ace" )
+			NumFrames ( 2 2 1 )
+			Style ( WHILE_PRESSED )
+			MouseControl ( 1 )
+			ORTSDisplay ( 0 )
+			ORTSScreenPage ( "2100-0" )
+		)
+		TwoState (
+			Type ( ORTS_EOT_DISARM TWO_STATE )
+			Position ( 493 385 16.25 10 )
+			Graphic ( "..\\..\\Common.Cab\\ES44v3\\softkey5trans.ace" )
+			NumFrames ( 2 2 1 )
+			Style ( WHILE_PRESSED )
+			MouseControl ( 1 )
+			ORTSDisplay ( 0 )
+			ORTSScreenPage ( "2100-0" )
+		)
+		TwoState (
+			Type ( ORTS_EOT_ARM_TWO_WAY TWO_STATE )
+			Position ( 511.7 385.7 16.25 10 )
+			Graphic ( "..\\..\\Common.Cab\\ES44v3\\softkey7trans.ace" )
+			NumFrames ( 2 2 1 )
+			Style ( WHILE_PRESSED )
+			MouseControl ( 1 )
+			ORTSDisplay ( 0 )
+			ORTSScreenPage ( "2100-0" )
+		)
+		MultiStateDisplay (
+			Type ( ORTS_EOT_STATE_DISPLAY MULTI_STATE_DISPLAY )
+			Position ( 516 314.5 17 5.15 )
+			Graphic ( "..\\..\\Common.Cab\\ES44v3\\CommTest.ace" )
+			States ( 2 2 1
+				State (
+					Style ( 0 )
+					SwitchVal ( 0 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 2 )
+				)
+			)
+			ORTSDisplay ( 0 )
+			ORTSScreenPage ( "2100-0" )
+		)
+			Digital (
+			Type ( ORTS_EOT_ID DIGITAL )
+			Position ( 421 313 22 8 )
+			ScaleRange ( 0 999999 )
+			Accuracy ( 0 )
+			AccuracySwitch ( 0 )
+			LeadingZeros ( 0 )
+			Justification ( 1 )
+			PositiveColour ( 1
+				ControlColour ( 255 255 255 )
+			)
+			NegativeColour ( 1
+				ControlColour ( 255 255 0 )
+			)
+			DecreaseColour ( 0
+				ControlColour ( 0 0 0 )
+			)
+			Units ( KILO_LBS )
+			ORTSFont ( 6 0 "Arial" )
+			ORTSDisplay ( 0 )
+			ORTSScreenPage ( "2100-0" )
+		)
+		MultiStateDisplay (
+			Type ( ORTS_EOT_STATE_DISPLAY MULTI_STATE_DISPLAY )
+			Position ( 513.5 328 22.66 5.15 )
+			Graphic ( "..\\..\\Common.Cab\\ES44v3\\EOTStatus2.ace" )
+			States ( 4 4 1
+				State (
+					Style ( 0 )
+					SwitchVal ( 0 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 2 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 4 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 5 )
+				)
+			)
+			ORTSDisplay ( 0 )
+			ORTSScreenPage ( "2100-0" )
+		)
+		MultiStateDisplay (
+			Type ( ORTS_EOT_STATE_DISPLAY MULTI_STATE_DISPLAY )
+			Position (  431.4 292.1 9 5  )
+			Graphic ( "..\\..\\Common.Cab\\ES44v3\\MaskEOT.ace" )
+			States ( 2 2 1
+				State (
+					Style ( 0 )
+					SwitchVal ( 0 )
+				)
+				State (
+					Style ( 0 )
+					SwitchVal ( 2 )
+				)
+			)
+		)
+		TwoState (
+			Type ( ORTS_EOT_EMERGENCY_BRAKE TWO_STATE )
+			Position ( 53.5 344.2 21.4 42.8 )
+			Graphic ( ..\\..\\Common.Cab\\ES44v3\\EOTEmergency.ace )
+			NumFrames ( 2 2 1 )
+			Style ( ONOFF )
+			MouseControl ( 1 )
+		)
+
 
 Animated 2D Wipers
 ------------------

Source/Documentation/Manual/images/physics-eot-display.png

@@ -4684,3 +4684,154 @@ UoM - Angle (deg, radians) - default is rad. Typically this value maybe between
 - ``ORTSWheelFlangeLength`` - Wheel flange length is defined as the length of flange starting from the beginning of the maximum flange angle 
 to the point where flange angle reduces to 26.6 degrees. UoM - Distance (m, in, ft, etc) - default is m
 
+.. _physics-eot:
+
+EOT - End of train device
+=========================
+
+General
+-------
+
+See :ref:`here https://en.wikipedia.org/wiki/End-of-train_device` for basic info about EOTs.
+
+EOTs in Open Rails may be of three different levels (types)::
+
+- No communication: "dumb" EOTs, like flags or flashing lamps 
+- One way: the EOT is capable to transmit to the lead locomotive the brake pipe pressure at the end of the train
+- Two way: the EOT is also capable to receive a command to vent the air brake pipe.
+
+How to define an EOT
+--------------------
+
+EOTs must be defined within subfolders of the ``Trains\ORTS_EOT`` folder. These subfolders contain 
+the same file set present in a subfolder of the ``Trains\Trainset`` folder; the file defining an EOT 
+has the same format as a .wag file, but it must have an .eot extension. To define the level of the EOT 
+the following block must be added at the end of the .eot file (after the closing parenthesis of the 
+Wagon() block)::
+
+  ORTSEOT (
+	Level ( "level" )
+  )
+
+  
+level may assume following values: ``NoComm``, ``OneWay`` and ``TwoWay``.
+
+Usually EOTs were provided as a very short wagon for simulation with MSTS or OR. To upgrade it to 
+a functioning EOT for OR following simple steps are needed::
+
+- Create the ``Trains\ORTS_EOT`` folder
+- copy the EOT subfolder present in the ``Trains\Trainset`` folder into the ``Trains\ORTS_EOT`` folder
+- change the extension of the .wag file(s) to .eot
+- add at the end of the .eot file the ORTSEOT block.
+
+For Open Rails the EOT is a special type (a subclass) of wagon, with specific features. As 
+such it appears at the end of the train in the Train Operations window.
+
+How to attach and detach an EOT at the end of a train
+-----------------------------------------------------
+
+An EOT may be attached at the end of a train (be it player train or AI train) 
+already at game start, 
+by inserting at the end of the .con file a block like the following one::
+                  ORTSEot (
+                        EOTData ( EOT_OR TrainSimulations_EOT )
+                        UiD ( 203 )
+                )
+
+where ``ORTSEot`` and ``EOTData`` are fixed keywords, EOT_OR is the name of the .eot file 
+and TrainSimulations_EOT is the folder where EOT_OR.eot resides. TrainSimulations_EOT is 
+a subfolder of ``Trains\ORTS_EOT``.
+
+If an EOT is present at the end of the train since game start, it will be fully operating 
+from the beginning 
+(in one-way state if it is a one-way EOT, and in two-way state if it is a two-way EOT).
+
+An EOT may also be attached at the end of the actual player train using the EOT list window 
+
+
+.. image:: images/physics-eot.png
+   :scale: 80 %
+   :align: center
+
+which can be recalled by pressing ``<Ctrl+F9>``. Such window lists all .eot files present in 
+the subfolders of ``Trains\ORTS_EOT``. If the train has an EOT at the end of it, the related row 
+in the EOT list window will be red. If the train has no EOT at the end of it (no red row), it can 
+be attached at the end of the train with following sequence:
+
+- within the EOT list window click on the row showing the desired EOT; the row will become red 
+  and the EOT will physically appear at the end of the train
+- if it is an One Way or Two Way EOT type, connect its brake hose with the Car Operations 
+  Window (see :ref:`here <driving-car-operations>`)
+- using the Car Operations Window on the wagon preceding the EOT, open the rear angle cock.
+
+When an EOT is attached to the actual player train, a line indicating its presence will appear 
+in the Train Driving Window (F5). The EOT will be in Disarmed state (that is fully disabled).
+
+To detach an EOT from the end of the actual player train, recall the EOT list window and click 
+on the red row. The EOT will disappear. Always remember to detach the EOT when this 
+would occur in reality (e.g. when rear coupling other wagons, when decoupling the rear of the train 
+and in general before shunting).
+
+How to arm (enable) or disarm a one-way or two-way EOT 
+------------------------------------------------------
+
+The arm and disarm procedure must be performed from the cabview, as the controls are available only 
+through mouse. So it requires an equipped cabview. See :ref:`here <cabs-eot>` for a list of the 
+available controls. 
+
+The procedure for a two-way EOT is explained basing on the picture below, which shows a 
+sample case based on a cab of Borislav Miletic. 
+
+.. _physics-eot-display:
+
+.. image:: images/physics-eot-display.png
+   :scale: 100 %
+   :align: center
+
+.. _physics-eot-states:
+
+The possible states for a two-way EOT are following ones::
+  * Disarmed,
+  * CommTestOn,
+  * Armed,
+  * LocalTestOn,
+  * ArmNow,
+  * ArmedTwoWay
+  
+The EOT state is shown in the Train Driving window using above terminology, 
+while the latter is a bit different in the EOT setup display in the sample cab
+following a real case (but it may be modified).
+
+When the EOT is attached to the train with the EOT List window, the EOT is in 
+``Disarmed`` state. An EOT ID appears as a 5-digit random number. In the cab 
+the Comm Test field shows ``Failed``.
+
+By clicking on the key below the ``Comm Test`` soft button, the state in the 
+Train Driving window passes to the ``CommTestOn`` state. When the ``CommTestOn`` is 
+terminated, the state in the Train Driving window passes to the ``Armed`` state for 
+the one-way EOTs, and to the ``LocalTestOn`` state for the two-way EOTs.
+In the EOT setup display the Comm Test field shows  ``Passed`` and the EOT 
+Status Field shows ``One Way``. Now the ``Rear`` field shows the brake pipe 
+pressure at the end of the train.
+
+The LocalTestOn in two-way EOTs is about 25 seconds long. After such time 
+interval the state shown in the Train Driving window passes to the ``ArmNow`` state, and 
+the EOT status in the display shows ``Arm Now``.
+
+At this point the train driver must click the key below the ``Arm Two-Way`` soft button. 
+The EOT Passes to the ``ArmedTwoWay`` state, that is shown as ``Armed`` in the 
+EOT status within the EOT Status display.
+
+By clicking the key below the ``Request Disarm`` soft button, the EOT returns to 
+the ``Disarmed`` state.
+
+Emergency brake through EOT
+---------------------------
+
+Two-way EOTs, when in the ``ArmedTwoWay`` state, can be requested to vent the brake pipe 
+and therefore to cause an emergency brake. This occurs automatically when an Emergency 
+brake is triggered, and also manually when the ``ORTS_EOT_EMERGENCY_BRAKE`` 
+control is activated. The manual activation may also occur by pressing 
+``<Ctrl+Backspace>`` .
+
+

Source/Documentation/Manual/images/physics-eot.png

@@ -47,6 +47,7 @@ public enum UserCommand
         [GetString("Display Next Station Window")] DisplayNextStationWindow,
         [GetString("Display Compass Window")] DisplayCompassWindow,
         [GetString("Display Train List Window")] DisplayTrainListWindow,
+        [GetString("Display EOT List Window")] DisplayEOTListWindow,
 
         [GetString("Debug Speed Up")] DebugSpeedUp,
         [GetString("Debug Speed Down")] DebugSpeedDown,
@@ -144,6 +145,7 @@ public enum UserCommand
         [GetString("Control Brake Hose Disconnect")] ControlBrakeHoseDisconnect,
         [GetString("Control Alerter")] ControlAlerter,
         [GetString("Control Emergency Push Button")] ControlEmergencyPushButton,
+        [GetString("Control EOT Emergency Brake")] ControlEOTEmergencyBrake,
         [GetString("Control Sander")] ControlSander,
         [GetString("Control Sander Toggle")] ControlSanderToggle,
         [GetString("Control Wiper")] ControlWiper,

Source/Documentation/Manual/physics.rst

@@ -375,6 +375,7 @@ static void InitializeCommands(UserCommandInput[] Commands)
             Commands[(int)UserCommand.ControlDynamicBrakeIncrease] = new UserCommandKeyInput(0x34);
             Commands[(int)UserCommand.ControlElectricTrainSupply] = new UserCommandKeyInput(0x30, KeyModifiers.Alt);
             Commands[(int)UserCommand.ControlEmergencyPushButton] = new UserCommandKeyInput(0x0E);
+            Commands[(int)UserCommand.ControlEOTEmergencyBrake] = new UserCommandKeyInput(0x0E, KeyModifiers.Control);
             Commands[(int)UserCommand.ControlEngineBrakeDecrease] = new UserCommandKeyInput(0x1A);
             Commands[(int)UserCommand.ControlEngineBrakeIncrease] = new UserCommandKeyInput(0x1B);
             Commands[(int)UserCommand.ControlBrakemanBrakeDecrease] = new UserCommandKeyInput(0x1A, KeyModifiers.Alt);
@@ -486,6 +487,7 @@ static void InitializeCommands(UserCommandInput[] Commands)
             Commands[(int)UserCommand.DisplayTrackMonitorWindow] = new UserCommandModifiableKeyInput(0x3E, Commands[(int)UserCommand.DisplayNextWindowTab]);
             Commands[(int)UserCommand.DisplayTrainOperationsWindow] = new UserCommandKeyInput(0x43);
             Commands[(int)UserCommand.DisplayTrainDpuWindow] = new UserCommandKeyInput(0x43, KeyModifiers.Shift);
+            Commands[(int)UserCommand.DisplayEOTListWindow] = new UserCommandKeyInput(0x43, KeyModifiers.Control);
 
             Commands[(int)UserCommand.GameAutopilotMode] = new UserCommandKeyInput(0x1E, KeyModifiers.Alt);
             Commands[(int)UserCommand.GameChangeCab] = new UserCommandKeyInput(0x12, KeyModifiers.Control);

Source/ORTS.Common/Input/UserCommand.cs

@@ -1300,6 +1300,7 @@ public TrainCfg(STFReader stf) {
                 new STFReader.TokenProcessor("durability", ()=>{ Durability = stf.ReadFloatBlock(STFReader.UNITS.None, null); }),
                 new STFReader.TokenProcessor("wagon", ()=>{ WagonList.Add(new Wagon(stf)); }),
                 new STFReader.TokenProcessor("engine", ()=>{ WagonList.Add(new Wagon(stf)); }),
+                new STFReader.TokenProcessor("ortseot", ()=>{ WagonList.Add(new Wagon(stf)); }),
                 new STFReader.TokenProcessor("ortstraincontrolsystemparameters", () => TcsParametersFileName = stf.ReadStringBlock(null)),
             });
         }
@@ -1310,6 +1311,7 @@ public class Wagon {
         public string Name;
         public int UiD;
         public bool IsEngine;
+        public bool IsEOT;
         public bool Flip;
 
         public Wagon(STFReader stf) {
@@ -1319,6 +1321,7 @@ public Wagon(STFReader stf) {
                 new STFReader.TokenProcessor("flip", ()=>{ stf.MustMatch("("); stf.MustMatch(")"); Flip = true; }),
                 new STFReader.TokenProcessor("enginedata", ()=>{ stf.MustMatch("("); Name = stf.ReadString(); Folder = stf.ReadString(); stf.MustMatch(")"); IsEngine = true; }),
                 new STFReader.TokenProcessor("wagondata", ()=>{ stf.MustMatch("("); Name = stf.ReadString(); Folder = stf.ReadString(); stf.MustMatch(")"); }),
+                new STFReader.TokenProcessor("eotdata", ()=>{ stf.MustMatch("("); Name = stf.ReadString(); Folder = stf.ReadString(); stf.MustMatch(")"); IsEOT = true;  }),
             });
         }
 

Source/ORTS.Settings/InputSettings.cs

@@ -206,6 +206,13 @@ public enum CABViewControlTypes
         ORTS_GENERIC_ITEM2,
         ORTS_SCREEN_SELECT,
         ORTS_STATIC_DISPLAY,
+        ORTS_EOT_BRAKE_PIPE,
+        ORTS_EOT_STATE_DISPLAY,
+        ORTS_EOT_ID,
+        ORTS_EOT_COMM_TEST,
+        ORTS_EOT_DISARM,
+        ORTS_EOT_ARM_TWO_WAY,
+        ORTS_EOT_EMERGENCY_BRAKE,
 
         // TCS Controls
         ORTS_TCS1,