First implementation of DPU brake sync

SteelFill · SteelFill · commit e466e275dcc6 · 2024-02-03T16:19:07.000-06:00
diff --git a/Source/Documentation/Manual/cabs.rst b/Source/Documentation/Manual/cabs.rst
@@ -684,14 +684,16 @@ Air Flow Meter
 
 .. index::
    single:  ORTS_AIR_FLOW_METER
+   single:  ORTS_TRAIN_AIR_FLOW_METER
 
 This cabview control is used on some locomotives, particularly in North America, to show the
 volumetric flow rate of air moving from the main res to the brake pipe during release/recharge.
 Such an indication can be used to determine when brake pipe charging is complete,
 measure the amount of brake pipe leakage, and so on.
 The control will only function on locomotives with air brakes.
 
-Here is an example implementation of ORTS_AIR_FLOW_METER as an analog dial::
+Here is an example implementation of ORTS_AIR_FLOW_METER as an analog dial (display types other
+than analog dials can be used)::
 
 
 		Dial (
@@ -706,8 +708,10 @@ Here is an example implementation of ORTS_AIR_FLOW_METER as an analog dial::
 			DirIncrease ( 0 )
 		)
 
-Applicable user-defined units are CUBIC_FT_MIN, LITERS_S, LITERS_MIN, and CUBIC_M_S. Cubic meters per
-second will be used if no units are specified.
+Alternately, a control type of ORTS_TRAIN_AIR_FLOW_METER can be used to display the total
+air flow rate of all locomotives, useful for distributed power where multiple locomotives can
+charge the brake pipe simultaneously. Applicable user-defined units are CUBIC_FT_MIN, LITERS_S,
+LITERS_MIN, and CUBIC_M_S. Cubic meters per second will be used if no units are specified.
 
 
 Animated 2D Wipers
diff --git a/Source/Documentation/Manual/physics.rst b/Source/Documentation/Manual/physics.rst
@@ -2272,6 +2272,52 @@ 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%).
 
+In addition to applying power and dynamic brake, remote units can also manage the
+train brake, independent brake, and emergency brake in sync with the lead locomotive.
+This can dramatically speed up brake application and release on long trains, which has
+allowed trains to increase in length substantially without major decreases in brake
+performance. Only one locomotive in each group, the 'lead' DP unit, will have brakes
+cut-in. Usually this is the same locomotive recieving throttle data from the lead
+locomotive. In Open Rails, these locomotives are designated automatically. To determine
+which units are the 'lead' in each group, check the ID row on the DPU Info window.
+
+As described earlier, operation in *sync* mode or *async* mode has no effect on air
+brake behavior. In reality, additional remote modes such as *set-out*, *bv out*,
+and *isolate* would disable air brakes on remote units, but these modes are not
+present for simplicity.
+
+.. index::
+   single: ORTSDPBrakeSynchronization
+
+By default, Open Rails will treat remote groups as manned helpers who typically
+would not assist in train brake operations, so only independent brakes will synchronize.
+To enable train brake synchronization, the token ``engine(ORTSDPBrakeSynchronization(``
+should be used. The valid settings for ``ORTSDPBrakeSynchronization`` are as follows:
+
+- ``"Apply"``: DP units will reduce the brake pipe pressure locally to match the
+  equalizing reservoir pressure of the controlling locomotive. (The controlling
+  locomotive must also have the ``"Apply"`` setting.)
+- ``"Release"``: DP units will increase the brake pipe pressure locally to match
+  the equalizing reservoir pressure of the controlling locomotive. (The controlling
+  locomotive must also have the ``"Release"`` setting.)
+- ``"Emergency"``: DP units will vent the brake pipe to 0 if an emergency application
+  is triggered by the controlling locomotive. (The controlling locomotive must also
+  have the ``"Emergency"`` setting.)
+- ``"Independent"``: DP units will match the brake cylinder pressure of the
+  controlling locomotive, and will automatically bail-off automatic brake
+  applications if needed. (The controlling locomotive must also have the
+  ``"Independent"`` setting.)
+                - NOTE: Although ``"Independent"`` is enabled by default,
+                  if ``ORTSDPBrakeSynchronization`` is present in the .eng
+                  file but ``"Independent"`` is not specified as an option,
+                  independent brakes will NOT be synchronized.
+
+All settings can be combined as needed, simply place a comma between each setting
+in the string: ``ORTSDPBrakeSynchronization("Apply, Release, Emergency, Independent")``
+will simulate the configuration of most modern locomotives. Unlike other distributed power
+features, brake synchronization can be applied to any locomotive type to simulate a wide
+variety of braking systems.
+
 Distributed power info and commands can also be displayed and operated through 
 cabview controls, as explained :ref:`here <cabs-distributed-power>`
 
diff --git a/Source/Orts.Formats.Msts/CabViewFile.cs b/Source/Orts.Formats.Msts/CabViewFile.cs
@@ -198,6 +198,7 @@ public enum CABViewControlTypes
         ORTS_QUICKRELEASE,
         ORTS_OVERCHARGE,
         ORTS_AIR_FLOW_METER,
+        ORTS_TRAIN_AIR_FLOW_METER,
         ORTS_BATTERY_SWITCH_COMMAND_SWITCH,
         ORTS_BATTERY_SWITCH_COMMAND_BUTTON_CLOSE,
         ORTS_BATTERY_SWITCH_COMMAND_BUTTON_OPEN,
diff --git a/Source/Orts.Simulation/Simulation/Physics/Train.cs b/Source/Orts.Simulation/Simulation/Physics/Train.cs
@@ -76,6 +76,9 @@ namespace Orts.Simulation.Physics
     public class Train
     {
         public List<TrainCar> Cars = new List<TrainCar>();           // listed front to back
+        public List<TrainCar> DPLeadUnits = new List<TrainCar>();    // list of all DP lead locomotives
+        // list of connected locomotives, each element is a list of the connected locomotives themselves
+        public List<List<TrainCar>> LocoGroups = new List<List<TrainCar>>();
         public int Number;
         public string Name;
         public string TcsParametersFileName;
@@ -138,6 +141,7 @@ public TrainCar LastCar
         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 TotalBrakePipeFlowM3pS; // Total flow rate of air from all MR to BP
         public float TotalTrainBrakePipeVolumeM3; // Total volume of train brake pipe
         public float TotalTrainBrakeCylinderVolumeM3; // Total volume of train brake cylinders
         public float TotalTrainBrakeSystemVolumeM3; // Total volume of train brake system
@@ -689,6 +693,7 @@ public Train(Simulator simulator, BinaryReader inf)
             BrakeLine2PressurePSI = inf.ReadSingle();
             BrakeLine3PressurePSI = inf.ReadSingle();
             BrakeLine4 = inf.ReadSingle();
+            TotalBrakePipeFlowM3pS = inf.ReadSingle();
             aiBrakePercent = inf.ReadSingle();
             LeadLocomotiveIndex = inf.ReadInt32();
             RetainerSetting = (RetainerSetting)inf.ReadInt32();
@@ -1037,6 +1042,7 @@ public virtual void Save(BinaryWriter outf)
             outf.Write(BrakeLine2PressurePSI);
             outf.Write(BrakeLine3PressurePSI);
             outf.Write(BrakeLine4);
+            outf.Write(TotalBrakePipeFlowM3pS);
             outf.Write(aiBrakePercent);
             outf.Write(LeadLocomotiveIndex);
             outf.Write((int)RetainerSetting);
@@ -1312,6 +1318,7 @@ public TrainCar GetNextCab()
             LeadLocomotiveIndex = Math.Abs(nextCabIndex) - 1;
             Trace.Assert(LeadLocomotive != null, "Tried to switch to non-existent loco");
             TrainCar newLead = LeadLocomotive;  // Changing LeadLocomotiveIndex also changed LeadLocomotive
+            SetDPUnitIDs(true); // DP IDs must be reprocessed when lead locomotive changes
             ((MSTSLocomotive)newLead).UsingRearCab = nextCabIndex < 0;
 
             if (oldLead != null && newLead != null && oldLead != newLead)
@@ -1370,6 +1377,7 @@ public void LeadNextLocomotive()
             else if (coud > 1)
                 LeadLocomotiveIndex = firstLead;
             TrainCar newLead = LeadLocomotive;
+            SetDPUnitIDs(true); // DP IDs must be reprocessed when lead locomotive changes
             if (prevLead != null && newLead != null && prevLead != newLead)
                 newLead.CopyControllerSettings(prevLead);
         }
@@ -1525,19 +1533,59 @@ public void ReverseCars()
         /// </summary>
         public void SetDPUnitIDs(bool keepRemoteGroups = false)
         {
+            // List to keep track of new 'lead' DP units
+            // 'Lead' DP units follow the air brake commands of the master loco, 'trail' DP units do not
+            List<TrainCar> tempDPLead = new List<TrainCar>();
+
+            // List of each DP group's locomotives
+            List<List<TrainCar>> tempLocoGroups = new List<List<TrainCar>>();
+
+            var prevId = -1;
+
             var id = 0;
             foreach (var car in Cars)
             {
                 //Console.WriteLine("___{0} {1}", car.CarID, id);
-                if (car is MSTSLocomotive)
+                if (car is MSTSLocomotive loco)
                 {
-                    (car as MSTSLocomotive).DPUnitID = id;
+                    loco.DPUnitID = id;
+
+                    if (id != prevId && !tempDPLead.Contains(car)) // If this is a new ID, that means we found a 'lead' unit
+                    {
+                        tempDPLead.Add(car);
+
+                        prevId = id;
+                    }
+
                     if (car.RemoteControlGroup == 1 && !keepRemoteGroups)
                         car.RemoteControlGroup = 0;
                 }
                 else
                     id++;
             }
+
+            foreach (TrainCar locoCar in tempDPLead)
+            {
+                // The train's lead unit should always be a DP lead unit, even if not at the front
+                // If a different locomotive in the lead loco's group has been declared DP lead, replace that loco with the lead loco
+                if (LeadLocomotive is MSTSLocomotive lead && locoCar is MSTSLocomotive loco)
+                    if (loco.DPUnitID == lead.DPUnitID && locoCar != LeadLocomotive)
+                    {
+                        tempDPLead.Insert(tempDPLead.IndexOf(locoCar), LeadLocomotive);
+                        tempDPLead.Remove(locoCar);
+                        break; // foreach doesn't like it when the collection is modified during the loop, break to mitigate error
+                    }
+            }
+
+            DPLeadUnits = tempDPLead;
+
+            foreach (TrainCar loco in DPLeadUnits)
+            {
+                // Find all locomotives connected to each DP unit
+                tempLocoGroups.Add(DetermineLocomotiveGroup(loco));
+            }
+
+            LocoGroups = tempLocoGroups;
         }
 
         /// <summary>
@@ -4217,6 +4265,76 @@ public TrainCar FindLeadLocomotive()
             return null;
         }
 
+        //================================================================================================//
+        /// <summary>
+        /// Find connected locomotives
+        /// <\summary>
+
+        // Finds all locomotives connected to the TrainCar reference provided as input,
+        // returning the connected locomotives* as a list of TrainCars.
+        // Returns null if there are no locomotives in the given group.
+        // *If the input is a steam locomotive, the output will instead be the steam locomotive and any tenders connected.
+        // Useful for determining locomotive brake propagation on groups of locomotives other than the lead group.
+
+        public List<TrainCar> DetermineLocomotiveGroup(TrainCar loco)
+        {
+            if (loco is MSTSLocomotive)
+            {
+                List<TrainCar> tempGroup = new List<TrainCar>();
+                int first;
+                int last;
+
+                first = last = Cars.IndexOf(loco);
+
+                // If locomotive is a steam locomotive, check for tenders only
+                if (first >= 0 && loco is MSTSSteamLocomotive)
+                {
+                    if (first > 0 && Cars[first - 1].WagonType == TrainCar.WagonTypes.Tender)
+                        first--;
+                    if (last < Cars.Count - 1 && Cars[last + 1].WagonType == TrainCar.WagonTypes.Tender)
+                        last++;
+                }
+                else // Other locomotive types
+                {
+                    for (int i = last; i < Cars.Count && (Cars[i] is MSTSLocomotive && !(Cars[i] is MSTSSteamLocomotive)); i++)
+                        last = i;
+                    for (int i = first; i >= 0 && (Cars[i] is MSTSLocomotive && !(Cars[i] is MSTSSteamLocomotive)); i--)
+                        first = i;
+                }
+
+                if (first < 0 || last < 0)
+                    return null;
+                else
+                {
+                    for (int i = first; i <= last; i++)
+                        tempGroup.Add(Cars[i]);
+                    return tempGroup;
+                }
+            }
+            else
+                return null;
+        }
+
+        //================================================================================================//
+        /// <summary>
+        /// Find connected DP lead locomotive
+        /// <\summary>
+
+        // Finds the DP lead locomotive to the TrainCar reference provided as input,
+        // returning the TrainCar reference to the DP lead unit.
+        // Returns null if there are no DP lead units controlling the given train car.
+
+        public TrainCar DetermineDPLeadLocomotive(TrainCar locoCar)
+        {
+            if (Cars.Contains(locoCar) && locoCar is MSTSLocomotive loco)
+                foreach (TrainCar dpLead in DPLeadUnits)
+                    if (dpLead is MSTSLocomotive dpLeadLoco)
+                        if (dpLeadLoco.DPUnitID == loco.DPUnitID)
+                            return dpLead;
+
+            return null;
+        }
+
         //================================================================================================//
         /// <summary>
         /// Propagate brake pressure
diff --git a/Source/Orts.Simulation/Simulation/RollingStocks/MSTSDieselLocomotive.cs b/Source/Orts.Simulation/Simulation/RollingStocks/MSTSDieselLocomotive.cs
@@ -1171,8 +1171,7 @@ public string GetDpuStatus(bool dataDpu, CABViewControlUnits loadUnits = CABView
             var brakeInfoValue = brakeValue(Simulator.Catalog.GetString("BP"), Simulator.Catalog.GetString("Flow"));
             status.AppendFormat("{0:F0}\t", brakeInfoValue);
             // Air flow meter
-            brakeInfoValue = brakeValue(Simulator.Catalog.GetString("Flow"), Simulator.Catalog.GetString("EOT"));
-            status.AppendFormat("{0:F0}\t", brakeInfoValue);
+            status.AppendFormat("{0:F0}\t", FormatStrings.FormatAirFlow(FilteredBrakePipeFlowM3pS, IsMetric));
 
             // Remote
             if (dataDpu)
diff --git a/Source/Orts.Simulation/Simulation/RollingStocks/MSTSLocomotive.cs b/Source/Orts.Simulation/Simulation/RollingStocks/MSTSLocomotive.cs
@@ -428,6 +428,10 @@ public float OdometerM
         public bool DoesBrakeCutPower { get; private set; }
         public float BrakeCutsPowerAtBrakeCylinderPressurePSI { get; private set; }
         public bool DoesHornTriggerBell { get; private set; }
+        public bool DPSyncTrainApplication { get; private set; }
+        public bool DPSyncTrainRelease { get; private set; }
+        public bool DPSyncEmergency { get; private set; }
+        public bool DPSyncIndependent { get; private set; } = true;
 
         protected const float DefaultCompressorRestartToMaxSysPressureDiff = 35;    // Used to check if difference between these two .eng parameters is correct, and to correct it
         protected const float DefaultMaxMainResToCompressorRestartPressureDiff = 10; // Used to check if difference between these two .eng parameters is correct, and to correct it
@@ -1110,6 +1114,19 @@ public override void Parse(string lowercasetoken, STFReader stf)
                         }
                     }
                     break;
+                case "engine(ortsdpbrakesynchronization":
+                    var dpSyncModes = stf.ReadStringBlock("").ToLower().Replace(" ", "").Split(',');
+                    if (dpSyncModes.Contains("apply"))
+                        DPSyncTrainApplication = true;
+                    if (dpSyncModes.Contains("release"))
+                        DPSyncTrainRelease = true;
+                    if (dpSyncModes.Contains("emergency"))
+                        DPSyncEmergency = true;
+                    if (dpSyncModes.Contains("independent"))
+                        DPSyncIndependent = true;
+                    else // Independent synchronization is assumed to be enabled unless explicitly not enabled
+                        DPSyncIndependent = false;
+                    break;
                 case "engine(ortsdynamicblendingoverride": DynamicBrakeBlendingOverride = stf.ReadBoolBlock(false); break;
                 case "engine(ortsdynamicblendingforcematch": DynamicBrakeBlendingForceMatch = stf.ReadBoolBlock(false); break;
                 case "engine(vacuumbrakeshasvacuumpump": VacuumPumpFitted = stf.ReadBoolBlock(false); break;
@@ -2681,11 +2698,20 @@ protected virtual void UpdateCompressor(float elapsedClockSeconds)
             if (MainResPressurePSI < CompressorRestartPressurePSI && LocomotivePowerSupply.AuxiliaryPowerSupplyState == PowerSupplyState.PowerOn && !CompressorIsOn)
             {
                 SignalEvent(Event.CompressorOn);
-                foreach (var car in Train.Cars)
+                foreach (List<TrainCar> locoGroup in Train.LocoGroups)
                 {
-                    if (car is MSTSLocomotive loco && loco.RemoteControlGroup == 0 && loco.LocomotivePowerSupply.AuxiliaryPowerSupplyOn && !loco.CompressorIsOn && loco.CompressorIsMUControlled)
+                    // Synchronize compressor between coupled locomotives
+                    if (locoGroup.Contains(this as TrainCar))
+                    {
+                        foreach (TrainCar locoCar in locoGroup)
+                            if (locoCar is MSTSLocomotive loco && loco.LocomotivePowerSupply.AuxiliaryPowerSupplyOn && !loco.CompressorIsOn)
+                                loco.SignalEvent(Event.CompressorOn);
+                    }
+                    else if (CompressorIsMUControlled) // Synchronize compressor between remote groups if configured to do so
                     {
-                        loco.SignalEvent(Event.CompressorOn);
+                        foreach (TrainCar remoteLocoCar in locoGroup)
+                            if (remoteLocoCar is MSTSLocomotive remoteLoco && remoteLoco.LocomotivePowerSupply.AuxiliaryPowerSupplyOn && !remoteLoco.CompressorIsOn && remoteLoco.CompressorIsMUControlled)
+                                remoteLoco.SignalEvent(Event.CompressorOn);
                     }
                 }
             }
@@ -5456,6 +5482,32 @@ public virtual float GetDataOf(CabViewControl cvc)
                                 data = this.FilteredBrakePipeFlowM3pS;
                                 break;
 
+                        }
+                        break;
+                    }
+                case CABViewControlTypes.ORTS_TRAIN_AIR_FLOW_METER:
+                    {
+                        switch (cvc.Units)
+                        {
+                            case CABViewControlUnits.CUBIC_FT_MIN:
+                                data = this.Train.TotalBrakePipeFlowM3pS * 35.3147f * 60.0f;
+                                break;
+
+                            case CABViewControlUnits.LITRES_S:
+                            case CABViewControlUnits.LITERS_S:
+                                data = this.Train.TotalBrakePipeFlowM3pS * 1000.0f;
+                                break;
+
+                            case CABViewControlUnits.LITRES_MIN:
+                            case CABViewControlUnits.LITERS_MIN:
+                                data = this.Train.TotalBrakePipeFlowM3pS * 1000.0f * 60.0f;
+                                break;
+
+                            case CABViewControlUnits.CUBIC_M_S:
+                            default:
+                                data = this.Train.TotalBrakePipeFlowM3pS;
+                                break;
+
                         }
                         break;
                     }
diff --git a/Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/Brakes/MSTS/AirSinglePipe.cs b/Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/Brakes/MSTS/AirSinglePipe.cs
diff --git a/Source/RunActivity/Viewer3D/Popups/TrainDPUWindow.cs b/Source/RunActivity/Viewer3D/Popups/TrainDPUWindow.cs
