Merge pull request #732 from cesarBLG/braking-enhancement

Improvements for air brakes

Author: cesarBLG

Source/Documentation/Manual/cabs.rst

@@ -343,7 +343,7 @@ Dedicated buttons for brake controllers
 .. index::
     single: ORTS_BAILOFF
 
-In addition to the BailOff keyboard command, a cabview control named
+In addition to the BailOff keyboard command ``</>``, a cabview control named
 ORTS_BAILOFF is available. It is used to release the brakes of the engine
 while keeping the train brakes applied.
 
@@ -352,13 +352,14 @@ while keeping the train brakes applied.
 
 In some brake controllers, there is a button that provides a full and quick
 release of the train brake when pressed. OR supports this via the
-ORTS_QUICKRELEASE cabview control.
+ORTS_QUICKRELEASE cabview control, or alternatively, pressing ``<Ctrl+/>``.
 
 .. index::
     single: ORTS_OVERCHARGE
 
 Some brake controllers have a dedicated button to overcharge the brake pipe.
-The ORTS_OVERCHARGE cabview control can be used for this purpose.
+The ORTS_OVERCHARGE cabview control can be used for this purpose. Alternatively
+the keyboard command ``<Ctrl+Shift+/>`` is available.
 
 Here is an example of one of this controls within the .cvf file::
 

Source/Documentation/Manual/physics.rst

@@ -2300,6 +2300,10 @@ pressure rises above the auxiliary reservoir pressure, the brake
 cylinder pressure is released completely at a rate determined by the
 retainer setting.
 
+BrakeEquipmentType() can also contain a "Distributing_Valve" instead of a
+"triple_valve" or a "distributor", for locomotives fitted with the
+Westinghouse ET-6 distributing valve or similar equipment.
+
 Selecting :ref:`Graduated Release Air Brakes <options-general>` in *Menu >
 Options* will force self-lapping notches in the brake controller to have
 graduated release. It will also force graduated release of brakes in triple
@@ -2337,6 +2341,21 @@ brake features.
 Brake system charging time depends on the train length as it should, but
 at the moment there is no modeling of main reservoirs and compressors.
 
+For EP brakes, two variants are available:
+
+- If ``Wagon(ORTSEPBrakeControlsBrakePipe`` is set to 0 (default situation),
+an electrical wire (application wire) provides simultaneous fast brake application
+along the train. Release time will be fast if standard air brake haven't been applied,
+otherwise air brakes will determine release time. Typically this system is present
+with Train Brake Controllers having an EP-only application section, followed by an
+air application portion which serves as a fallback system.
+- If ``Wagon(ORTSEPBrakeControlsBrakePipe`` is set to 1, brake pipe is charged and discharged
+simultaneously at each car in the train, providing fast and uniform brake application and release.
+The locomotive instructs the cars to "charge" or "discharge" the brake pipe to reach
+a reference pressure. Standard triple valves or distributors will follow brake pipe variations
+actuating the cylinders. This system is sometimes called "UIC EP brake". It is typically the system
+used in high speed trains.
+
 .. _physics-brake-controller:
 
 Train Brake Controller Positions
@@ -2352,6 +2371,7 @@ The following notch positions can be defined for the train brake at ``Engine(Eng
    single: TrainBrakesControllerSlowServiceStart
    single: TrainBrakesControllerFullServiceStart
    single: TrainBrakesControllerHoldStart
+   single: TrainBrakesControllerHoldEngineStart
    single: TrainBrakesControllerEPHoldStart
    single: TrainBrakesControllerSelfLapStart
    single: TrainBrakesControllerRunningStart
@@ -2371,6 +2391,7 @@ The following notch positions can be defined for the train brake at ``Engine(Eng
    single: ORTSTrainBrakesControllerMaxOverchargePressure
    single: ORTSTrainBrakesControllerOverchargeEliminationRate
    single: ORTSTrainBrakesControllerSlowApplicationRate
+   single: EngineBrakesControllerBailOffStart
 
 **RELEASE and RUNNING tokens**
 
@@ -2430,6 +2451,15 @@ Brake Token:   ``TrainBrakesControllerReleaseStart``
 
                     - Connects brake pipe to ejector(s) and/or vacuum pump. Brakes may be released by operating large or small ejector.  
 
+Brake Token:   ``EngineBrakesControllerBailOffStart``
+
+- Operation:     Air, EP, Vacuum
+- Brake Systems: Air single pipe, Air twin pipe, EP, Vacuum single pipe
+- Description:   
+   
+                - Engine brake: bail off engine brakes
+                - Train brake: no change
+
 **LAP, HOLDING and NEUTRAL tokens**
 
 Brake Token:   ``TrainBrakesControllerRunningStart``
@@ -2504,6 +2534,15 @@ Brake Token:   ``TrainBrakesControllerNeutralHandleOffStart``
                 - Air brakes: Train pipe pressure is held without compensation for leakage.
                 - EP brakes: Brake application is held at any value.
                 - Vacuum brakes: Train pipe vacuum is held without compensation for leakage.  
+                
+Brake Token:   ``TrainBrakesControllerHoldEngineStart``
+
+- Operation:     Air, EP, Vacuum
+- Brake Systems: Air single pipe, Air twin pipe, EP, Vacuum single pipe
+- Description:   HOLD ENGINE
+
+                - Engine brakes: engine brake cylinder pressure is held at current value.
+                - Train brakes: same as RELEASE/RUNNING
 
 
 **SELF LAPPING APPLY tokens**
@@ -2875,6 +2914,22 @@ defined in a DynamicBrakeForceCurves table that works like the
 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,
+the following parameters will adjust the behaviour of air brakes:
+
+.. index::
+   single: DynamicBrakeHasAutoBailOff
+   single: ORTSDynamicBrakesHasPartialBailOff
+   
+- ``Engine(DynamicBrakeHasAutoBailOff`` -- Set to 1 if brake cylinders are
+  emptied while dynamic brake is active
+- ``Engine(ORTSDynamicBrakesHasPartialBailOff`` -- If this parameter is set to 1,
+  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.
+
+
 Native Open Rails Braking Parameters
 ------------------------------------
 
@@ -2898,6 +2953,8 @@ MaxAuxilaryChargingRate and EmergencyResChargingRate.
    single: ORTSBrakeServiceTimeFactor
    single: ORTSBrakeEmergencyTimeFactor
    single: ORTSBrakePipeTimeFactor
+   single: ORTSEPBrakeControlsBrakePipe
+   single: ORTSCompressorIsMuControlled
 
 - ``Wagon(BrakePipeVolume`` -- Volume of car's brake pipe in cubic feet
   (default .5).
@@ -2919,6 +2976,8 @@ MaxAuxilaryChargingRate and EmergencyResChargingRate.
   for twin pipe systems, if the main reservoir pipe is used for charging the auxiliary
   reservoirs. If set to false, the main reservoir pipe will not be used
   by the brake system.
+- ``Wagon(ORTSEPBrakeControlsBrakePipe`` -- Set to 1 for UIC EP brake: brake pipe
+  pressure is electrically controlled at every fitted car.
 - ``Engine(ORTSMainResChargingRate`` -- Rate of main reservoir pressure change
   in psi per second when the compressor is on (default .4).
 - ``Engine(ORTSEngineBrakeReleaseRate`` -- Rate of engine brake pressure
@@ -2942,6 +3001,8 @@ MaxAuxilaryChargingRate and EmergencyResChargingRate.
   (default .003).
 - ``Engine(AirBrakeMaxMainResPipePressure`` -- Pressure in Main Reservoir 
   Pipe for twin pipe braking systems (default = Main Reservoir Pressure).
+- ``Engine(ORTSCompressorIsMuControlled`` -- Set to 1 if compressors from
+  all locomotives are synchronized.
 
 .. _physics-retainers:
 

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

@@ -226,11 +226,11 @@ public void SetUpdateValue(float value)
         /// </summary>
         public void SetDynamicBrakeIntervention(float value)
         {
-            // TODO: Set dynamic brake intervention instead of controller position
-            // There are some issues that need to be identified and fixed before setting the intervention directly
-            if (Locomotive.DynamicBrakeController == null) return;
-            Locomotive.DynamicBrakeChangeActiveState(value > 0);
-            Locomotive.DynamicBrakeController.SetValue(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);
         }
 
         /// <summary>
@@ -363,6 +363,8 @@ public enum ControllerState
         SMEFullServ,        // TrainBrakesControllerSMEFullServiceStart
         SMESelfLap,         // TrainBrakesControllerSMEHoldStart
         SMEReleaseStart,    // TrainBrakesControllerSMEReleaseStart
+        HoldEngine,        // TrainBrakesControllerHoldEngineStart
+        BailOff,            // EngineBrakesControllerBailOffStart
     };
 
     public static class ControllerStateDictionary
@@ -409,7 +411,9 @@ public static class ControllerStateDictionary
             {ControllerState.SMEOnly, Catalog.GetString("SME Service")},
             {ControllerState.SMEFullServ, Catalog.GetString("SME Full Service")},
             {ControllerState.SMESelfLap, Catalog.GetString("SME Self Lap")},
-            {ControllerState.SMEReleaseStart, Catalog.GetString("SME Release Start")}
+            {ControllerState.SMEReleaseStart, Catalog.GetString("SME Release Start")},
+            {ControllerState.HoldEngine, Catalog.GetString("Hold Engine")},
+            {ControllerState.BailOff, Catalog.GetString("Bail Off")}
         };
     }
 }

Source/Orts.Simulation/Simulation/AIs/AITrain.cs

@@ -4089,7 +4089,8 @@ public override void InitializeBrakes()
             float fullServReductionPSI = -5;
             float max = maxPressurePSI;
             float fullServ = fullServPressurePSI;
-            BrakeLine3PressurePSI = BrakeLine4 = 0;
+            BrakeLine3PressurePSI = 0;
+            BrakeLine4 = -1;
             if (FirstCar != null && FirstCar.BrakeSystem is VacuumSinglePipe)
             {
                 max = maxPressurePSIVacuum;

Source/Orts.Simulation/Simulation/Physics/Train.cs

@@ -134,7 +134,7 @@ public TrainCar LastCar
         // but Class VacuumSinglePipe uses it for vacuum in InHg.
         public float BrakeLine2PressurePSI;              // extra line for dual line systems, main reservoir
         public float BrakeLine3PressurePSI;              // extra line just in case, engine brake pressure
-        public float BrakeLine4 = -1;                    // extra line just in case, ep brake control line. -1: release/inactive, 0: hold, 0 < value <=1: apply
+        public float BrakeLine4 = -1;                    // extra line just in case, ep brake control line. -2: hold, -1: inactive, 0: release, 0 < value <=1: apply
         public RetainerSetting RetainerSetting = RetainerSetting.Exhaust;
         public int RetainerPercent = 100;
         public float TotalTrainBrakePipeVolumeM3; // Total volume of train brake pipe
@@ -4017,6 +4017,8 @@ public void UnconditionalInitializeBrakes()
                     fullServPressurePSI = lead.BrakeSystem is VacuumSinglePipe ? 16 : maxPressurePSI - lead.TrainBrakeController.FullServReductionPSI;
                     EqualReservoirPressurePSIorInHg = Math.Min(maxPressurePSI, EqualReservoirPressurePSIorInHg);
                     lead.TrainBrakeController.UpdatePressure(ref EqualReservoirPressurePSIorInHg, 1000, ref BrakeLine4);
+                    if (!(lead.BrakeSystem is EPBrakeSystem))
+                        BrakeLine4 = -1;
                     EqualReservoirPressurePSIorInHg =
                             MathHelper.Max(EqualReservoirPressurePSIorInHg, fullServPressurePSI);
                 }
@@ -4223,7 +4225,11 @@ public void PropagateBrakePressure(float elapsedClockSeconds)
             if (LeadLocomotive is MSTSLocomotive lead)
             {
                 if (lead.TrainBrakeController != null)
+                {
                     lead.TrainBrakeController.UpdatePressure(ref EqualReservoirPressurePSIorInHg, elapsedClockSeconds, ref BrakeLine4);
+                    if (!(lead.BrakeSystem is EPBrakeSystem))
+                        BrakeLine4 = -1;
+                }
                 if (lead.EngineBrakeController != null)
                     lead.EngineBrakeController.UpdateEngineBrakePressure(ref BrakeLine3PressurePSI, elapsedClockSeconds);
                 lead.BrakeSystem.PropagateBrakePressure(elapsedClockSeconds);

Source/Orts.Simulation/Simulation/RollingStocks/MSTSLocomotive.cs

@@ -370,6 +370,7 @@ public float OdometerM
         public float DynamicBrakeMaxCurrentA;
         public float DynamicBrakeDelayS;
         public bool DynamicBrakeAutoBailOff;
+        public bool DynamicBrakePartialBailOff;
         public bool UsingRearCab;
         public bool BrakeOverchargeSoundOn = false;
 
@@ -1020,6 +1021,7 @@ public override void Parse(string lowercasetoken, STFReader stf)
                 case "engine(dynamicbrakesmaximumforce": MaxDynamicBrakeForceN = stf.ReadFloatBlock(STFReader.UNITS.Force, null); break;
                 case "engine(dynamicbrakehasautobailoff":
                 case "engine(ortsdynamicbrakeshasautobailoff": DynamicBrakeAutoBailOff = stf.ReadBoolBlock(true); break;
+                case "engine(ortsdynamicbrakeshaspartialbailoff": DynamicBrakePartialBailOff = stf.ReadBoolBlock(false); break;
                 case "engine(dynamicbrakesdelaytimebeforeengaging": DynamicBrakeDelayS = stf.ReadFloatBlock(STFReader.UNITS.Time, null); break;
                 case "engine(dynamicbrakesresistorcurrentlimit": DynamicBrakeMaxCurrentA = stf.ReadFloatBlock(STFReader.UNITS.Current, null); break;
                 case "engine(numwheels": MSTSLocoNumDrvWheels = stf.ReadFloatBlock(STFReader.UNITS.None, 4.0f); if (MSTSLocoNumDrvWheels < 1) STFException.TraceWarning(stf, "Engine:NumWheels is less than 1, parts of the simulation may not function correctly"); break;
@@ -1139,6 +1141,7 @@ public override void Copy(MSTSWagon copy)
             ContinuousForceTimeFactor = locoCopy.ContinuousForceTimeFactor;
             DynamicBrakeForceCurves = locoCopy.DynamicBrakeForceCurves;
             DynamicBrakeAutoBailOff = locoCopy.DynamicBrakeAutoBailOff;
+            DynamicBrakePartialBailOff = locoCopy.DynamicBrakePartialBailOff;
             DynamicBrakeMaxCurrentA = locoCopy.DynamicBrakeMaxCurrentA;
             CombinedControlType = locoCopy.CombinedControlType;
             CombinedControlSplitPosition = locoCopy.CombinedControlSplitPosition;
@@ -1811,14 +1814,12 @@ protected void CorrectBrakingParams()
         /// </summary>
         public void DynamicBrakeBlending(float elapsedClockSeconds)
         {
-            if (Math.Abs(SpeedMpS) > DynamicBrakeSpeed1MpS && airPipeSystem != null && ((airPipeSystem is EPBrakeSystem && Train.BrakeLine4 > 0f) || airPipeSystem.BrakeLine1PressurePSI < TrainBrakeController.MaxPressurePSI - 1f)
-                && ThrottleController.CurrentValue == 0f && !(DynamicBrakeController != null && DynamicBrakeBlendingOverride && DynamicBrakeController.CurrentValue > 0f)
-                /* && (!DynamicBrakeBlendingLeverOverride && DynamicBrakeController != null && DynamicBrakeIntervention < DynamicBrakeController.CurrentValue)*/)
+            // Local blending
+            if (Math.Abs(SpeedMpS) > DynamicBrakeSpeed1MpS && airPipeSystem != null && airPipeSystem.AutoCylPressurePSI > 0.1f
+                && ThrottlePercent == 0 && !(DynamicBrakeController != null && DynamicBrakeBlendingOverride && DynamicBrakeController.CurrentValue > 0))
             {
-                float threshold = DynamicBrakeBlendingForceMatch ? 100f : 0.01f;
                 float maxCylPressurePSI = airPipeSystem.GetMaxCylPressurePSI();
-                float targetDynamicBrakePercent = airPipeSystem is EPBrakeSystem ? Train.BrakeLine4 : Math.Min(((TrainBrakeController.MaxPressurePSI - airPipeSystem.BrakeLine1PressurePSI) * airPipeSystem.GetAuxCylVolumeRatio()) / maxCylPressurePSI, 1f);
-                //DynamicBrakeIntervention = Math.Min(((TrainBrakeController.CurrentValue - DynamicBrakeBlendingStart) / (DynamicBrakeBlendingStop - DynamicBrakeBlendingStart)), 1f);
+                float target = airPipeSystem.AutoCylPressurePSI / maxCylPressurePSI;
 
                 if (!DynamicBrakeBlended)
                 {
@@ -1831,11 +1832,19 @@ public void DynamicBrakeBlending(float elapsedClockSeconds)
                 }
                 if (DynamicBrake)
                 {
-                    float diff = DynamicBrakeBlendingForceMatch ? targetDynamicBrakePercent * MaxBrakeForceN - DynamicBrakeForceN : targetDynamicBrakePercent - DynamicBrakeIntervention;
-                    if (diff > threshold && DynamicBrakeIntervention <= 1)
-                        DynamicBrakeIntervention = Math.Min( DynamicBrakeIntervention + elapsedClockSeconds * (airPipeSystem.GetMaxApplicationRatePSIpS() / maxCylPressurePSI), 1.0f);
-                    else if (diff < -threshold)
-                        DynamicBrakeIntervention -= elapsedClockSeconds * (airPipeSystem.GetMaxReleaseRatePSIpS() / maxCylPressurePSI);
+                    if (DynamicBrakeBlendingForceMatch)
+                    {
+                        float diff = target * MaxBrakeForceN - DynamicBrakeForceN;
+                        float threshold = 100;
+                        if (diff > threshold && DynamicBrakeIntervention < 1)
+                            DynamicBrakeIntervention = Math.Min(DynamicBrakeIntervention + elapsedClockSeconds, 1);
+                        else if (diff < -threshold && DynamicBrakeIntervention > 0.01f)
+                            DynamicBrakeIntervention = Math.Max(DynamicBrakeIntervention - elapsedClockSeconds, 0.01f);
+                    }
+                    else
+                    {
+                        DynamicBrakeIntervention = target;
+                    }
                 }
                 if (DynamicBrakeController != null)
                     DynamicBrakeIntervention = Math.Max(DynamicBrakeIntervention, DynamicBrakeController.CurrentValue);
@@ -1845,6 +1854,17 @@ public void DynamicBrakeBlending(float elapsedClockSeconds)
                 DynamicBrakeIntervention = -1;
                 DynamicBrakeBlended = false;
             }
+            // Train blending
+            if (IsLeadLocomotive())
+            {
+                if (TrainBrakeController.TrainDynamicBrakeIntervention > DynamicBrakeIntervention)
+                {
+                    DynamicBrakeBlended = true;
+                    DynamicBrakeIntervention = TrainBrakeController.TrainDynamicBrakeIntervention;
+                }
+                if (TrainBrakeController.TrainDynamicBrakeCommandStartTime > DynamicBrakeCommandStartTime)
+                    DynamicBrakeCommandStartTime = TrainBrakeController.TrainDynamicBrakeCommandStartTime;
+            }
         }
 
         /// <summary>
@@ -2246,6 +2266,7 @@ protected virtual void UpdateControllers(float elapsedClockSeconds)
             }
 
             DynamicBrakeBlending(elapsedClockSeconds);
+
             if (DynamicBrakeController != null && DynamicBrakeController.CommandStartTime > DynamicBrakeCommandStartTime) // use the latest command time
                 DynamicBrakeCommandStartTime = DynamicBrakeController.CommandStartTime;
 

Source/Orts.Simulation/Simulation/RollingStocks/MSTSWagon.cs

@@ -227,6 +227,7 @@ public enum BrakeValveType
             None,
             TripleValve, // Plain triple valve
             Distributor, // Triple valve with graduated release
+            DistributingValve, // Triple valve + driver brake valve control. Only for locomotives
         }
         /// <summary>
         /// Type of brake valve in the car
@@ -1190,6 +1191,7 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                             case "triple_valve": BrakeValve = BrakeValveType.TripleValve; break;
                             case "distributor":
                             case "graduated_release_triple_valve": BrakeValve = BrakeValveType.Distributor; break;
+                            case "distributing_valve": BrakeValve = BrakeValveType.DistributingValve; break;
                             case "emergency_brake_reservoir": EmergencyReservoirPresent = true; break;
                             case "handbrake": HandBrakePresent = true; break;
                             case "auxilary_reservoir": // MSTS legacy parameter - use is discouraged