Merge pull request #961 from cesarBLG/powersupply-scripts

Improvements for Power Supplies

Author: cesarBLG

Source/Documentation/Manual/cabs.rst

@@ -61,23 +61,25 @@ The following DMI size variants are available: FullSize (displays the whole DMI)
 The information displayed in the DMI is controlled via the TCS script. For more details,
 see :ref:`C# engine scripting - Train Control System <features-scripting-tcs>`.
 
-.. _cabs-battery-switch:
+.. _cabs-battery:
 
-Battery switch
---------------
+Battery
+-------
 
 .. index::
    single: ORTS_BATTERY_SWITCH_COMMAND_SWITCH
    single: ORTS_BATTERY_SWITCH_COMMAND_BUTTON_CLOSE
    single: ORTS_BATTERY_SWITCH_ON
+   single: ORTS_BATTERY_VOLTAGE
 
-The :ref:`battery switch <physics-battery-switch>` controls the low voltage power supply of the locomotive.
+The :ref:`battery subsystem <physics-battery>` controls the low voltage power supply of the locomotive.
 
 The following controls are available for the cabview:
 
-- ``ORTS_BATTERY_SWITCH_COMMAND_SWITCH`` can be used if the switch is directly controlled from the cab
+- ``ORTS_BATTERY_SWITCH_COMMAND_SWITCH`` can be used if the battery switch is directly controlled from the cab
 - ``ORTS_BATTERY_SWITCH_COMMAND_BUTTON_CLOSE`` and ``ORTS_BATTERY_SWITCH_COMMAND_BUTTON_OPEN`` can be used if the switch is controlled with two pushbuttons (one to close the switch and the other to open it)
 - ``ORTS_BATTERY_SWITCH_ON`` can be used to control a light on the cab showing the state of the battery switch
+- ``ORTS_BATTERY_VOLTAGE`` monitors the battery voltage
 
 Other controls can be disabled if the low voltage power supply is not available using the following parameter::
 
@@ -166,6 +168,44 @@ The following controls are available for the cabview:
 - ``ORTS_ELECTRIC_TRAIN_SUPPLY_COMMAND_SWITCH`` can be used to control the electric train supply switch
 - ``ORTS_ELECTRIC_TRAIN_SUPPLY_ON`` can be used to indicate that the electric train supply line is powered on
 
+.. _cabs-voltmeters:
+
+Voltmeters
+----------
+
+.. index::
+   single: LINE_VOLTAGE
+   single: ORTS_PANTOGRAPH_VOLTAGE_AC
+   single: ORTS_PANTOGRAPH_VOLTAGE_DC
+   single: ORTS_BATTERY_VOLTAGE
+
+The following voltmeters are available for the cabview:
+
+- ``LINE_VOLTAGE`` indicates the line voltage
+- ``ORTS_PANTOGRAPH_VOLTAGE_AC`` indicates the line voltage when operating on AC lines
+- ``ORTS_PANTOGRAPH_VOLTAGE_DC`` indicates the line voltage when operating on DC lines
+- ``ORTS_BATTERY_VOLTAGE`` indicates the vehicle's battery voltage
+
+.. _cabs-electricselectors:
+
+.. index::
+   single: ORTS_PANTOGRAPH_SELECTOR
+   single: ORTS_POWER_LIMITATION_SELECTOR
+   single: ORTS_VOLTAGE_SELECTOR
+
+There :ref:`pantograph selector <physics-pantograph-selector>`, 
+:ref:`voltage selector <physics-voltage-selector>` and 
+:ref:`power limitation selector <physics-power-limitation-selector>` can be used
+to switch the traction system for locomotives operating at different voltages.
+
+They can be included in the cabview as follows:
+
+- ``ORTS_PANTOGRAPH_SELECTOR`` allows selecting pre-defined pantograph arrangements
+  (requires a custom script).
+- ``ORTS_VOLTAGE_SELECTOR`` configures the power supply for the voltage of the line
+  (requires a custom script to raise the right pantograph).
+- ``ORTS_POWER_LIMITATION_SELECTOR`` limits the maximum power that the locomotive can draw.
+
 .. _cabs-dieselenginesonoff:
 
 Controls to switch on and off diesel engines

Source/Documentation/Manual/features-rollingstock.rst

@@ -149,11 +149,11 @@ block!
 .. index::
    single: Conditions(ORTSBattery
 
-Battery Switch
-''''''''''''''
+Battery
+'''''''
 
 The light condition ``ORTSBattery`` allows a light to respond to the state of
-the :ref:`battery switch subsystem <physics-battery-switch>`. The valid settings
+the :ref:`battery subsystem <physics-battery>`. The valid settings
 and associated conditions for the light to turn *on* are as follows:
 
 - ``ORTSBattery ( 0 )`` Battery state is ignored (default)
@@ -1921,6 +1921,9 @@ Scripts will run if referenced by OR-specific fields in the .eng file.
    single: ORTSEngineBrakeController
    single: ORTSCircuitBreaker
    single: ORTSTractionCutOffRelay
+   single: ORTSPantographSelector
+   single: ORTSVoltageSelector
+   single: ORTSPowerLimitationSelector
    single: ORTSPowerSupply
    single: ORTSTrainControlSystem
 
@@ -1952,6 +1955,15 @@ Scripts will run if referenced by OR-specific fields in the .eng file.
    * - Passenger car power supply
      - ``ORTS.Scripting.Api.PassengerCarPowerSupply``
      - ``Wagon ( ORTSPowerSupply ( "DemoPower.cs" ) )``
+   * - Pantograph selector
+     - ``ORTS.Scripting.Api.PantographSelector``
+     - ``Engine ( ORTSPantographSelector ( Script ( "DemoPantographSelector.cs" ) ) )``
+   * - Voltage selector
+     - ``ORTS.Scripting.Api.VoltageSelector``
+     - ``Engine ( ORTSVoltageSelector ( Script ( "DemoVoltageSelector.cs" ) ) )``
+   * - Power limitation selector
+     - ``ORTS.Scripting.Api.PowerLimitationSelector``
+     - ``Engine ( ORTSPantographSelector ( Script ( "DemoPowerLimitator.cs" ) ) )``
    * - Train Control System
      - ``ORTS.Scripting.Api.TrainControlSystem``
      - ``Engine ( ORTSTrainControlSystem ( "DemoTCS.cs" ) )``
@@ -2134,14 +2146,66 @@ Use the following .eng parameter to load a traction cut-off relay script::
   )
 
 ``ORTSTractionCutOffRelay`` refers to the traction cut-off relay script in the engine's ``Script`` 
-subfolder. For this field, the .cs extension is optional. "Automatic" and "Manual" load the generic OR 
-traction cut-off relay implementation, so do `not` use these names for your own script.
+subfolder. For this field, the .cs extension is optional. Alternatively, there are several
+built-in OR traction cut-off relay implementations:
+
+- "Automatic": no driver intervention required, circuit breaker is closed when conditions are met.
+- "Manual": a traction cut-off switch with open and closed positions.
+- "PushButtons": a traction cut-off relay with dedicated open and close buttons.
+
+Please do `not` use these names for your own script, since the generic implementation will
+be loaded instead.
 
 ``ORTSTractionCutOffRelayClosingDelay`` refers to the delay between the closing command of the traction cut-off relay
 and the effective closing of the relay.
 
+.. _features-scripting-powerselectors
+
+Pantograph, voltage and power limitation selectors
+--------------------------------------------------
+
+Available for electric locomotives only. The scripts control 
+the behavior of the locomotive's 
+:ref:`pantograph selector <physics-pantograph-selector>`, 
+:ref:`voltage selector <physics-voltage-selector>` and 
+:ref:`power limitation selector <physics-power-limitation-selector>` respectively.
+
+.. index::
+   single: ORTSPantographSelector
+   single: ORTSVoltageSelector
+   single: ORTSPowerLimitationSelector
+
+Use the following .eng parameters to load power selector scripts::
+
+  Engine (
+      ORTSPantographSelector ( 
+        Script ( "YourPSScript.cs" )
+        SelectorPositions ( ... )
+      )
+      ORTSVoltageSelector ( 
+        Script ( "YourVSScript.cs" )
+        SelectorPositions ( ... )
+      )
+      ORTSPowerLimitationSelector ( 
+        Script ( "YourPLSScript.cs" )
+        SelectorPositions ( ... )
+      )
+  )
+
+``Script`` refers to the circuit breaker script in the engine's ``Script`` 
+subfolder. For this field, the .cs extension is optional. Alternatively, there are several
+built-in OR selector implementations which can be used if custom features such as interlocking
+with other devices are not required:
+
+- "Default": a selector with sequential positions.
+- "Circular": same as above, but the first position follows again after the last one.
+
+Please do `not` use these names for your own script, since the generic implementation will
+be loaded instead.
+
 .. _features-scripting-powersupply:
 
+
 Diesel and electric power supply
 --------------------------------
 
@@ -2161,6 +2225,7 @@ Use the following .eng parameter to load a power supply script::
 
   Engine (
       ORTSPowerSupply ( "YourEPS.cs" )
+      ORTSPowerSupplyParameters ( "YourEPS.ini" )
       ORTSPowerOnDelay ( 5s )
       ORTSAuxPowerOnDelay ( 10s )
   )
@@ -2169,6 +2234,12 @@ Use the following .eng parameter to load a power supply script::
 subfolder. For this field, the .cs extension is optional. "Default" will load the generic OR power supply 
 implementation, so do `not` use this name for your own script.
 
+``ORTSPowerSupplyParameters``, an optional field, refers to an .ini file, 
+also in the ``Script`` subfolder, whose parameters will be made available to the 
+power supply script through the ``GetBoolParameter()``, ``GetIntParameter()``, 
+``GetFloatParameter()``, and ``GetStringParameter()`` methods. This .ini file provides for easy customization of 
+the behavior of the power supply script by end users.
+
 ``ORTSPowerOnDelay`` refers to the delay between the closing of the circuit breaker or the traction cut-off relay
 and the availability of the power for traction.
 
@@ -2550,6 +2621,23 @@ which may be used this way within the script:
 
 so that, instead of ORTS_TCSnn the related mnemonic string is displayed.
 
+Generic cabview controls are also available for the Power Supply subsystem. They are named ORTS_POWER_SUPPLY1, ORTS_POWER_SUPPLY2
+and so on in the cabview file. Their usage is the same as for the TCS controls.
+
+Events related to power supply controls are made available to power supply scripts via ``TCSEvent.GenericTCSButtonPressed``, 
+``TCSEvent.GenericTCSButtonReleased``, ``TCSEvent.GenericTCSSwitchOff`` and ``TCSEvent.GenericTCSSwitchOn`` events, 
+received asynchronously by script through the method:
+
+.. code-block:: csharp
+
+    public override void HandleEvent(PowerSupplyEvent evt, string message)
+
+As for the TCS buttons, message is a string representing the control number with zero-base indexing
+(e.g. "5" corresponds to ORTS_POWER_SUPPLY6).
+
+SetCabDisplayControl and SetCustomizedCabviewControlName methods, which work in the same
+way as their TCS counterparts, are accessible from all power supply scripts.
+
 Helper classes
 --------------
 3 helper classes are available in the ``Orts.Scripting.Api`` namespace: