Merge pull request #532 from Csantucci/distributed-power-official

Distributed power american style. Blueprint https://blueprints.launchpad.net/or/+spec/distributed-power

Author: Csantucci

Source/Documentation/Manual/images/physics-dpu-window.png

@@ -2031,18 +2031,106 @@ Some of the cab monitoring gauges provide visibility of what is happening on the
 the "closest" powered car near the Control car and uses its information.
 
 
-Engines -- Multiple Units in Same Consist or AI Engines
-=======================================================
-
-In an OR player train one locomotive is controlled by the player, while
-the other units are controlled by default by the train's MU (multiple
-unit) signals for braking and throttle position, etc. The
-player-controlled locomotive generates the MU signals which are passed
-along to every unit in the train. For AI trains, the AI software directly
-generates the MU signals, i.e. there is no player-controlled locomotive.
+Multiple Units of Locomotives in Same Consist
+=============================================
+
+In an OR player train one locomotive is controlled by the player, while 
+the other units are controlled by default by the train's MU (multiple 
+unit) signals for braking and throttle position, etc. The 
+player-controlled locomotive generates the MU signals which are passed 
+along to every unit in the train. 
+
+Distributed Power
+-----------------
+
+This is applicable only to trains hauled by diesel locomotives equipped with 
+dynamic brakes.
+
+More locomotive groups may be present in American long freight trains; a 
+locomotive group is defined as a set of locomotives that have no wagons in 
+between. 
+Groups different from the group including the lead locomotive are called 
+remote groups.
+
+Remote groups can be controlled in two modes: *synchronous* or 
+*asynchronous*. Locomotives in the player train can be arranged to be part of 
+one of the two above control groups. So each locomotive group (except the lead one,
+which always belongs to the *sync* control group) 
+can be either part the *sync*  or of the *async* control group. However, if a 
+locomotive group is part of the *async* control group, all locomotive groups behind 
+it must also be part of the *async* control group.
+
+The arrangement can be changed during run, 
+which in real life is performed by using the locomotive's onboard computer 
+(e.g. Locotrol).
+
+This functionality is necessary in American long-train freight 
+operations. An example use case is when a train finished climbing a 
+mountain pass. At this point the lead locomotives have to start dynamic 
+braking driving downhill, while the trailing units still need to keep pushing 
+the train's end uphill. The locomotive driver has the possibility to build 
+the *fence*, i.e. move the last locomotive group to the *async* control group. 
+
+While locomotives in *sync* control group always copy the traction and dynamic 
+brake settings of the lead (man-controlled) locomotive, for locomotives in 
+*async* control group these can be adjusted independently. Other controls, like 
+reverser and air brake are always synchronized throughout the whole train, 
+and changing reverser setting or applying air brakes will force *async* 
+controlled locomotives to fall back to idle. 
+
+The *fence* between *sync* and *async* control groups can be moved back and forth 
+along the train. This is useful when there are one or more middle-train 
+locomotive groups in the consist. However it is not possible to move the 
+fence to separate two directly interconnected locomotives: such locomotives 
+can be rearranged only together.  
+
+If the driver dismantles the *fence*, by moving it after the last locomotive 
+group, all locomotive groups are moved back to *sync* control group, and 
+therefore all locomotives will work in sync with the leading one.
+All-sync operation is also the default, when the game starts. 
+
+Traction and dynamic brake settings for *sync* group can be controlled by the 
+usual keys: ``<A>`` and ``<D>``. The following additional controls are 
+available for controlling the *async* group settings:
+
+- Move To Back -- ``<Ctrl+Shift+O>``: Move one locomotive group to back (*async*) 
+  control group (*fence* is moved towards the front of the train).
+- Move To Front -- ``<Ctrl+O>``: Move one locomotive group to front (*sync*) 
+  control group (*fence* is moved towards the back of the train).
+- Traction -- ``<Ctrl+L>``: Switch *async* group to traction mode.
+- Idle -- ``<Ctrl+Shift+L>``: Switch *async* group to idle state.
+- Brake -- ``<Ctrl+'> (key two positions at the right of L)``: Switch *async* 
+  group to dynamic braking mode.
+- More -- ``<Ctrl+U>``: Increase *async* group traction or dynamic brake by a notch, 
+  depending on its mode setting.
+- Less -- ``<Ctrl+Shift+U>``: Decrease *async* group traction or dynamic brake by a notch, 
+  depending on its mode setting.
+
+HUD shows the sync--async configuration in line *Multiple Units* on main page.
+When it reads e.g. "2--2 | 1", then it means that front and middle-train 
+double-unit locomotives are controlled in *sync* with the leading unit, 
+while the trailing pushing unit is controlled *async* independently. 
+The actual set value of traction or dynamic brake of *async* group is shown in 
+lines *Throttle* and *Dynamic Brake*, respectively, in brackets, e.g.: 
+Throttle: 0% (50%).
+
+The complete distributed power configuration is displayed in the 
+Distributed Power Info extended HUD page, where the state of all locomotives 
+in the train are shown, as well as in the *Train DPU Info* window, which is 
+displayed after pressing ``<Shift+F9>``, and which shows only the state of the first 
+locomotive of each locomotive group, as occurs also in displays of real 
+locomotives.
+
+.. image:: images/physics-dpu-window.png
+
+Engines of AI Trains
+--------------------
+
+For AI trains, the AI software directly generates the remote control
+signals, i.e. there is no player-controlled locomotive. 
 In this way, all engines use the same physics code for power and friction.
 
-This software model will ensure that non-player controlled engines will
+This software model will ensure that non-player controlled engines will 
 behave exactly the same way as player controlled ones.
 
 .. _physics-braking:

Source/Documentation/Manual/physics.rst

@@ -43,6 +43,7 @@ public enum UserCommand
         [GetString("Display Station Labels")] DisplayStationLabels,
         [GetString("Display Switch Window")] DisplaySwitchWindow,
         [GetString("Display Train Operations Window")] DisplayTrainOperationsWindow,
+        [GetString("Display Train Dpu Window")] DisplayTrainDpuWindow,
         [GetString("Display Next Station Window")] DisplayNextStationWindow,
         [GetString("Display Compass Window")] DisplayCompassWindow,
         [GetString("Display Train List Window")] DisplayTrainListWindow,
@@ -210,5 +211,14 @@ public enum UserCommand
         [GetString("Control AI Fire On")] ControlAIFireOn,
         [GetString("Control AI Fire Off")] ControlAIFireOff,
         [GetString("Control AI Fire Reset")] ControlAIFireReset,
+
+        //Distributed power
+        [GetString("Control DP Move To Front")] ControlDPMoveToFront,
+        [GetString("Control DP Move To Back")] ControlDPMoveToBack,
+        [GetString("Control DP Traction")] ControlDPTraction,
+        [GetString("Control DP Idle")] ControlDPIdle,
+        [GetString("Control DP Brake")] ControlDPBrake,
+        [GetString("Control DP More")] ControlDPMore,
+        [GetString("Control DP Less")] ControlDPLess,
     }
 }

Source/ORTS.Common/Input/UserCommand.cs

@@ -436,6 +436,14 @@ static void InitializeCommands(UserCommandInput[] Commands)
 
             Commands[(int)UserCommand.ControlWaterScoop] = new UserCommandKeyInput(0x15);
             Commands[(int)UserCommand.ControlWiper] = new UserCommandKeyInput(0x2F);
+            // Distributed power
+            Commands[(int)UserCommand.ControlDPMoveToFront] = new UserCommandKeyInput(0x18, KeyModifiers.Control); //O
+            Commands[(int)UserCommand.ControlDPMoveToBack] = new UserCommandKeyInput(0x18, KeyModifiers.Control | KeyModifiers.Shift); //O
+            Commands[(int)UserCommand.ControlDPTraction] = new UserCommandKeyInput(0x26, KeyModifiers.Control); //L
+            Commands[(int)UserCommand.ControlDPIdle] = new UserCommandKeyInput(0x26, KeyModifiers.Control | KeyModifiers.Shift); //L
+            Commands[(int)UserCommand.ControlDPBrake] = new UserCommandKeyInput(0x28, KeyModifiers.Control); //
+            Commands[(int)UserCommand.ControlDPMore] = new UserCommandKeyInput(0x16, KeyModifiers.Control); //U
+            Commands[(int)UserCommand.ControlDPLess] = new UserCommandKeyInput(0x16, KeyModifiers.Control | KeyModifiers.Shift); //U
 
             Commands[(int)UserCommand.DebugClockBackwards] = new UserCommandKeyInput(0x0C);
             Commands[(int)UserCommand.DebugClockForwards] = new UserCommandKeyInput(0x0D);
@@ -475,6 +483,7 @@ static void InitializeCommands(UserCommandInput[] Commands)
             Commands[(int)UserCommand.DisplaySwitchWindow] = new UserCommandKeyInput(0x42);
             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.GameAutopilotMode] = new UserCommandKeyInput(0x1E, KeyModifiers.Alt);
             Commands[(int)UserCommand.GameChangeCab] = new UserCommandKeyInput(0x12, KeyModifiers.Control);

Source/ORTS.Settings/InputSettings.cs

@@ -425,6 +425,8 @@ public enum DirectXFeature
         [Default(new[] { 50, 50 })]
         public int[] WindowPosition_TrainOperations { get; set; }
         [Default(new[] { 50, 50 })]
+        public int[] WindowPosition_TrainDpu { get; set; }
+        [Default(new[] { 50, 50 })]
         public int[] WindowPosition_CarOperations { get; set; }
         [Default(new[] { 50, 50 })]
         public int[] WindowPosition_ComposeMessage { get; set; }

Source/ORTS.Settings/UserSettings.cs

@@ -1311,6 +1311,134 @@ public override string ToString()
         }
     }
 
+    // Distributed Power controls
+    [Serializable()]
+    public sealed class DPMoveToFrontCommand : Command
+    {
+        public static MSTSWagon Receiver { get; set; }
+
+        public DPMoveToFrontCommand(CommandLog log)
+            : base(log)
+        {
+            Redo();
+        }
+
+        public override void Redo()
+        {
+            Receiver.Train.DPMoveToFront();
+            // Report();
+        }
+    }
+
+    [Serializable()]
+    public sealed class DPMoveToBackCommand : Command
+    {
+        public static MSTSWagon Receiver { get; set; }
+
+        public DPMoveToBackCommand(CommandLog log)
+            : base(log)
+        {
+            Redo();
+        }
+
+        public override void Redo()
+        {
+            Receiver.Train.DPMoveToBack();
+            // Report();
+        }
+    }
+
+    [Serializable()]
+    public sealed class DPIdleCommand : Command
+    {
+        public static MSTSWagon Receiver { get; set; }
+
+        public DPIdleCommand(CommandLog log)
+            : base(log)
+        {
+            Redo();
+        }
+
+        public override void Redo()
+        {
+            Receiver.Train.DPIdle();
+            // Report();
+        }
+    }
+
+    [Serializable()]
+    public sealed class DPTractionCommand : Command
+    {
+        public static MSTSWagon Receiver { get; set; }
+
+        public DPTractionCommand(CommandLog log)
+            : base(log)
+        {
+            Redo();
+        }
+
+        public override void Redo()
+        {
+            Receiver.Train.DPTraction();
+            // Report();
+        }
+    }
+
+    [Serializable()]
+    public sealed class DPDynamicBrakeCommand : Command
+    {
+        public static MSTSWagon Receiver { get; set; }
+
+        public DPDynamicBrakeCommand(CommandLog log)
+            : base(log)
+        {
+            Redo();
+        }
+
+        public override void Redo()
+        {
+            Receiver.Train.DPDynamicBrake();
+            // Report();
+        }
+    }
+
+    [Serializable()]
+    public sealed class DPMoreCommand : Command
+    {
+        public static MSTSWagon Receiver { get; set; }
+
+        public DPMoreCommand(CommandLog log)
+            : base(log)
+        {
+            Redo();
+        }
+
+        public override void Redo()
+        {
+            Receiver.Train.DPMore();
+            // Report();
+        }
+    }
+
+    [Serializable()]
+    public sealed class DPLessCommand : Command
+    {
+        public static MSTSWagon Receiver { get; set; }
+
+        public DPLessCommand(CommandLog log)
+            : base(log)
+        {
+            Redo();
+        }
+
+        public override void Redo()
+        {
+            Receiver.Train.DPLess();
+            // Report();
+        }
+    }
+
+
     // Steam controls
     [Serializable()]
     public sealed class ContinuousSteamHeatCommand : ContinuousCommand

Source/Orts.Simulation/Common/Commands.cs

@@ -1357,6 +1357,7 @@ public override void HandleMsg() //only client will get message, thus will set s
             train.InitializeBrakes();
             //train.InitializeSignals(false);//client do it won't have impact
             train.CheckFreight();
+            train.SetDPUnitIDs();
             bool canPlace = true;
             Train.TCSubpathRoute tempRoute = train.CalculateInitialTrainPosition(ref canPlace);
 
@@ -1567,6 +1568,7 @@ public override void HandleMsg() //only client will get message, thus will set s
                 train.CalculatePositionOfCars();
                 train.travelled = Travelled;
                 train.CheckFreight();
+                train.SetDPUnitIDs();
                 return;
             }
             train1.TrainType = Train.TRAINTYPE.REMOTE;
@@ -1601,6 +1603,7 @@ public override void HandleMsg() //only client will get message, thus will set s
             train1.InitializeBrakes();
             //train1.InitializeSignals(false);
             train1.CheckFreight();
+            train1.SetDPUnitIDs();
             bool canPlace = true;
             Train.TCSubpathRoute tempRoute = train1.CalculateInitialTrainPosition(ref canPlace);
 
@@ -2621,6 +2624,7 @@ public override void HandleMsg()
                         t.MUDirection = (Direction)mDirection1;
                         train.ControlMode = Train.TRAIN_CONTROL.EXPLORER;
                         train.CheckFreight();
+                        train.SetDPUnitIDs();
                         train.InitializeBrakes();
                         canPlace = true;
                         tempRoute = train.CalculateInitialTrainPosition(ref canPlace);
@@ -2671,6 +2675,7 @@ public override void HandleMsg()
                 train2.LeadLocomotive = null;
                 train2.LeadNextLocomotive();
                 train2.CheckFreight();
+                train2.SetDPUnitIDs();
 
                 //train2 may contain myself, and no other players, thus will make myself controlling this train
                 /*if (train2.Cars.Contains(MPManager.Simulator.PlayerLocomotive))
@@ -2693,6 +2698,7 @@ public override void HandleMsg()
                 train2.MUDirection = (Direction)mDirection2;
                 train2.ControlMode = Train.TRAIN_CONTROL.EXPLORER;
                 train2.CheckFreight();
+                train2.SetDPUnitIDs();
                 train2.InitializeBrakes();
                 canPlace = true;
                 tempRoute = train2.CalculateInitialTrainPosition(ref canPlace);
@@ -2967,6 +2973,7 @@ public override void HandleMsg()
             train.MUDirection = (Direction)mDirection;
             train.RearTDBTraveller = new Traveller(MPManager.Simulator.TSectionDat, MPManager.Simulator.TDB.TrackDB.TrackNodes, TileX, TileZ, X, Z, direction == 0 ? Traveller.TravellerDirection.Forward : Traveller.TravellerDirection.Backward);
             train.CheckFreight();
+            train.SetDPUnitIDs();
             train.CalculatePositionOfCars();
             train.LeadLocomotive = null; train2.LeadLocomotive = null;
             if (Lead != -1 && Lead < train.Cars.Count) train.LeadLocomotive = train.Cars[Lead];

Source/Orts.Simulation/MultiPlayer/Message.cs

@@ -961,6 +961,7 @@ public AITrain CreateAITrainDetail(Service_Definition sd, Traffic_Service_Defini
 #endif
             train.CreateRoute(false);  // create route without use of FrontTDBtraveller
             train.CheckFreight(); // check if train is freight or passenger
+            train.SetDPUnitIDs(); // distributed power
             if (!isInitialPlayerTrain || train.InitialSpeed != 0) train.AITrainDirectionForward = true;
             train.BrakeLine3PressurePSI = 0;
 

Source/Orts.Simulation/Simulation/AIs/AI.cs

@@ -4434,6 +4434,7 @@ public void CoupleAI(Train attachTrain, bool thisTrainFront, bool attachTrainFro
                 attachTrain.PresentPosition[1].SetTCPosition(tn.TCCrossReference, offset, direction);
                 // set various items
                 attachTrain.CheckFreight();
+                attachTrain.SetDPUnitIDs();
                 attachTrain.activityClearingDistanceM = attachTrain.Cars.Count < standardTrainMinCarNo ? shortClearingDistanceM : standardClearingDistanceM;
                 attachCar.SignalEvent(Event.Couple);
 
@@ -4549,6 +4550,7 @@ public void CoupleAIToStatic(Train attachTrain, bool thisTrainFront, bool attach
             PresentPosition[1].SetTCPosition(tn.TCCrossReference, offset, direction);
             // set various items
             CheckFreight();
+            SetDPUnitIDs();
             activityClearingDistanceM = Cars.Count < standardTrainMinCarNo ? shortClearingDistanceM : standardClearingDistanceM;
             attachCar.SignalEvent(Event.Couple);
 
@@ -4789,8 +4791,10 @@ public void TerminateCoupling(Train attachTrain, bool thisTrainFront, bool attac
             attachTrain.PresentPosition[1].SetTCPosition(tn.TCCrossReference, offset, direction);
             // set various items
             CheckFreight();
+            SetDPUnitIDs();
             activityClearingDistanceM = Cars.Count < standardTrainMinCarNo ? shortClearingDistanceM : standardClearingDistanceM;
             attachTrain.CheckFreight();
+            attachTrain.SetDPUnitIDs();
             attachTrain.activityClearingDistanceM = attachTrain.Cars.Count < standardTrainMinCarNo ? shortClearingDistanceM : standardClearingDistanceM;
             // anticipate reversal point and remove active action
             TCRoute.ReversalInfo[TCRoute.activeSubpath].ReverseReversalOffset = Math.Max(PresentPosition[0].TCOffset - 10f, 0.3f);