Merge pull request #874 from cesarBLG/blending-enhancement

Dynamic brake controller refactoring

Author: cesarBLG

Source/Documentation/Manual/physics.rst

@@ -2705,6 +2705,12 @@ Brake Token:   ``TrainBrakesControllerSupressionStart``
 - Brake Systems: Air single pipe, Air twin pipe, EP
 - Description:   Cancels effect of penalty brake application by TCS and restores control of brakes to driver.  
 
+Brake Position Labels
+----------------------
+The name of a given brake controller notch can be customized by adding an ORTSLabel
+block to the notch definition::
+
+   Notch ( 0.5  0 TrainBrakesControllerEPFullServiceStart ORTSLabel ( "Regeneration III and EP" ) )
 
 .. _physics-hud-brake:
 
@@ -2967,7 +2973,7 @@ DynamicBrakeForceCurves defined in the ENG file, than one is created
 based on the MSTS parameter values.
 
 It is possible to use dynamic brakes as a replacement for air brakes
-when they are available (dynamic brake blending). During blending operation,
+when they are available ("local" dynamic brake blending). During blending operation,
 the following parameters will adjust the behaviour of air brakes:
 
 .. index::
@@ -2980,7 +2986,38 @@ the following parameters will adjust the behaviour of air brakes:
   air brakes are released while dynamic brakes satisfy the train brake demand.
   If dynamic braking is not sufficient, air brakes will be partially applied
   so the combination air+dynamic provides the required brake demand.
-
+  
+Sometimes the train brake controller is capable to apply the dynamic
+brakes for the whole consist, usually as a first step before air brakes
+are applied. This is usually known as "train blending", as opposed to 
+"local" blending which only affects dynamic braking on the locomotive itself.
+A blending table which looks similar to the DynamicBrakeForceCurves table is
+available. It specifies the amount of dynamic brake that is applied at each
+notch of the train brake controller, where 0 means no dynamic brake and 1 means full dynamic brake::
+  Engine(
+    ORTSTrainDynamicBlendingTable(
+        comment ( Notch 0 of train brake - no dynamic brake applied )
+        0 (
+            0 0 
+            300km/h 0
+        )
+        comment ( 30% of Train brake - apply full dynamic brake )
+        0.3 (
+            0 1 
+            300km/h 1
+        )
+        comment ( 90% of Train brake - still apply full dynamic brake )
+        0.9 (
+            0 1 
+            300km/h 1
+        )
+        comment ( Emergency brake notch - do not command dynamic brake )
+        1 (
+            0 0 
+            300km/h 0
+        )
+    )
+  )
 
 Native Open Rails Braking Parameters
 ------------------------------------

Source/Orts.Simulation/Common/Scripting/BrakeController.cs

@@ -226,8 +226,6 @@ public void SetUpdateValue(float value)
         /// </summary>
         public void SetDynamicBrakeIntervention(float value)
         {
-            if (value > 0 && Host.TrainDynamicBrakeIntervention <= 0)
-                Host.TrainDynamicBrakeCommandStartTime = Host.Simulator.ClockTime;
             if (value <= 0)
                 Host.TrainDynamicBrakeIntervention = -1;
             else Host.TrainDynamicBrakeIntervention = Math.Min(value, 1);
@@ -279,6 +277,10 @@ public void SetDynamicBrakeIntervention(float value)
         /// </summary>
         /// <returns>The nullable state fraction</returns>
         public abstract float? GetStateFraction();
+        public virtual string GetStateName()
+        {
+            return ControllerStateDictionary.Dict[GetState()];
+        }
     }
 
     public enum BrakeControllerEvent

Source/Orts.Simulation/Simulation/Confirmer.cs

@@ -185,7 +185,7 @@ public Confirmer(Simulator simulator, double defaultDurationS)
             ConfirmText = new string[][] {
                 new string [] { GetString("<none>") } 
                 // Power
-                , new string [] { GetParticularString("NonSteam", "Reverser"), GetString("reverse"), GetString("neutral"), GetString("forward"), null, null, GetString("locked. Close throttle, stop train then re-try.") } 
+                , new string [] { GetParticularString("NonSteam", "Reverser"), GetString("reverse"), GetString("neutral"), GetString("forward"), null, null, GetString("locked. Close throttle, release dynamic brake, stop train then re-try.") } 
                 , new string [] { GetString("Throttle"), null, null, null, GetString("close"), GetString("open"), GetString("locked. Release dynamic brake then re-try.") } 
                 , new string [] { GetString("Wheel-slip"), GetString("over"), null, GetString("occurring. Tractive power greatly reduced."), null, null, GetString("warning") } 
                 // Electric power
@@ -230,7 +230,7 @@ public Confirmer(Simulator simulator, double defaultDurationS)
                 , new string [] { GetString("Train Brake"), null, null, null, GetString("release"), GetString("apply") } 
                 , new string [] { GetString("Engine Brake"), null, null, null, GetString("release"), GetString("apply") }
                 , new string [] { GetString("Brakeman Brake"), null, null, null, GetString("release"), GetString("apply") }
-                , new string [] { GetString("Dynamic Brake"), GetString("off"), null, GetString("setup"), GetString("decrease"), GetString("increase") }
+                , new string [] { GetString("Dynamic Brake"), GetString("off"), null, GetString("setup"), GetString("decrease"), GetString("increase"), GetString("locked. Move reverser then retry.") }
                 , new string [] { GetString("Emergency Brake"), GetString("release"), null, GetString("apply") } 
                 , new string [] { GetString("Bail Off"), GetString("disengage"), null, GetString("engage") } 
                 , new string [] { GetString("Brakes"), GetString("initialize"), null, null, null, null, GetString("cannot initialize. Stop train then re-try.") } 

Source/Orts.Simulation/Simulation/RollingStocks/MSTSDieselLocomotive.cs

@@ -766,7 +766,7 @@ protected override void UpdateTractiveForce(float elapsedClockSeconds, float t,
             // Note typically only one of the above will only ever be non-zero at the one time.
             // For flipped locomotives the force is "flipped" elsewhere, whereas dynamic brake force is "flipped" below by the direction of the speed.
 
-            if (DynamicBrakePercent > 0 && DynamicBrakeForceCurves != null && AbsSpeedMpS > 0)
+            if (DynamicBrakePercent > 0 && DynamicBrake && DynamicBrakeForceCurves != null && AbsSpeedMpS > 0)
             {
                 float f = DynamicBrakeForceCurves.Get(.01f * DynamicBrakePercent, AbsTractionSpeedMpS);
                 if (f > 0 && LocomotivePowerSupply.DynamicBrakeAvailable)