Add entries for the manual

Author: cesarBLG

Source/Documentation/Manual/cabs.rst

@@ -166,6 +166,24 @@ 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-dieselenginesonoff:
 
 Controls to switch on and off diesel engines

Source/Documentation/Manual/features-rollingstock.rst

@@ -1841,6 +1841,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
 
@@ -1872,6 +1875,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" ) )``
@@ -2054,14 +2066,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
 --------------------------------
 
@@ -2081,6 +2145,7 @@ Use the following .eng parameter to load a power supply script::
 
   Engine (
       ORTSPowerSupply ( "YourEPS.cs" )
+      ORTSPowerSupplyParameters ( "YourEPS.ini" )
       ORTSPowerOnDelay ( 5s )
       ORTSAuxPowerOnDelay ( 10s )
   )
@@ -2089,6 +2154,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.
 
@@ -2470,6 +2541,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:

Source/Documentation/Manual/physics.rst

@@ -947,6 +947,132 @@ for Pantograph 2 (replacing 2 with 3 and 4).
 The third panto is moved with Ctrl-P, while the fourth panto is moved with Ctrl-Shift-P.
 The cabview controls must be named ORTS_PANTOGRAPH3 and ORTS_PANTOGRAPH4.
 
+.. _physics-pantograph-selector:
+
+Pantograph selector
+'''''''''''''''''''
+
+.. index::
+  single: ORTSPantographSelector
+  single: SelectorPositions
+  single: SelectorPosition
+
+When using customized :ref:`power supply scripts:<features-scripting-powersupply>`,
+it is possible to implement a pantograph selector that selects a specific pantograph
+combination direcly, without operating every pantograph control individually.
+
+Example::
+
+Engine (
+  ORTSPowerSupply ( "YourEPSScript.cs" )
+  ORTSPantographSelector ( 
+    Script ( Default )
+    SelectorPositions (
+      SelectorPosition (
+        Name ( "Zero" )
+        Default ()
+      )
+      SelectorPosition (
+        Name ( "Local" )
+      )
+      SelectorPosition (
+        Name ( "Rear" )
+      )
+      SelectorPosition (
+        Name ( "Front" )
+      )
+      SelectorPosition (
+        Name ( "All" )
+      )
+    )
+  )
+)
+
+In combination with a customized power supply script, you can use the pantograph selector
+to achieve different pantograph combinations, for example:
+
+- Position "Zero" would keep all pantographs down
+- Position "Local" would only raise the pantograph from the lead locomotive
+- Position "Rear" would raise the pantograph only of rear-facing locomotives (this is the usually
+the standard position for EMUs, with only the rear pantograph being raised, and the front power head
+is powered through the roof line)
+- Position "Front" would raise the pantograph only of front-facing locomotives
+- Position "All" would raise all pantographs
+
+Please note that this only works with custom scripts.
+
+.. _physics-voltage-selector:
+
+Voltage selector
+''''''''''''''''
+
+.. index::
+  single: ORTSVoltageSelector
+  single: SelectorPositions
+  single: SelectorPosition
+
+When using customized :ref:`power supply scripts:<features-scripting-powersupply>`,
+it is possible to implement a voltage selector that automatically raises the pantograph
+associated to the selected voltage.
+
+Example::
+
+Engine (
+  ORTSPowerSupply ( "YourEPSScript.cs" )
+  ORTSVoltageSelector ( 
+    Script ( Default )
+    SelectorPositions (
+      SelectorPosition (
+        Name ( "AC" )
+        Voltage ( 25000 )
+      )
+      SelectorPosition (
+        Name ( "DC" )
+        Voltage ( 1500 )
+      )
+    )
+  )
+)
+
+Please note that this only works with custom scripts.
+
+.. _physics-power-limitation-selector:
+
+Power limitation selector
+'''''''''''''''''''''''''
+
+.. index::
+  single: ORTSPowerLimitationSelector
+  single: SelectorPositions
+  single: SelectorPosition
+
+The power limitation selector allows limiting the total current drawn from
+the overhead wire.
+
+Example::
+
+Engine (
+  ORTSPowerLimitationSelector ( 
+    Script ( Default )
+    SelectorPositions (
+      SelectorPosition (
+        Name ( "Conventional line" )
+        MaxPower ( 1200kW )
+        Default()
+      )
+      SelectorPosition (
+        Name ( "High speed line" )
+        MaxPower ( 1800kW )
+      )
+    )
+  )
+)
+
+Depending on the controller position, the power consumption of every locomotive will be limited.
+
+In combination with customized :ref:`power supply scripts:<features-scripting-powersupply>`, more
+advanced power limits can be imposed, e.g. depending on the number of locomotives in the trainset.
+
 .. _physics-circuit-breaker:
 
 Circuit breaker