Merge pull request #399 from Sharpe49/power-supply

Power supply package
http://www.elvastower.com/forums/index.php?/topic/35071-version-14/page__view__findpost__p__271864

Author: cjakeman

Source/Documentation/Manual/cabs.rst

@@ -19,6 +19,91 @@ next paragraphs.
 OR adds support for the ETCS circular speed gauge, as described 
 :ref:`here <options-etcs>`.
 
+.. _cabs-battery-switch:
+
+Battery switch
+--------------
+
+.. index::
+   single: ORTS_BATTERY_SWITCH_COMMAND_SWITCH
+   single: ORTS_BATTERY_SWITCH_COMMAND_BUTTON_CLOSE
+   single: ORTS_BATTERY_SWITCH_ON
+
+The :ref:`battery switch <physics-battery-switch>` 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_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
+
+Other controls can be hidden if the low voltage power supply is not available using the following parameter::
+
+      TwoState (
+         Type ( ORTS_CIRCUIT_BREAKER_CLOSED TWO_STATE)
+         ...
+         DisabledIfLowVoltagePowerSupplyOff ( 1 )
+      )
+
+.. _cabs-master-key:
+
+Master key
+----------
+
+.. index::
+   single: ORTS_MASTER_KEY
+   single: ORTS_CURRENT_CAB_IN_USE
+   single: ORTS_OTHER_CAB_IN_USE
+
+The :ref:`master key <physics-master-key>` controls the power supply of the cab.
+
+The following controls are available for the cabview:
+
+- ``ORTS_MASTER_KEY`` can be used in order to control the master key
+- ``ORTS_CURRENT_CAB_IN_USE`` can be used to indicate that the current cab is active
+- ``ORTS_OTHER_CAB_IN_USE`` can be used to indicate that another cab of the train is active
+
+Other controls can be hidden if the cab power supply is not available using the following parameter::
+
+      TwoState (
+         Type ( ORTS_CIRCUIT_BREAKER_CLOSED TWO_STATE)
+         ...
+         DisabledIfCabPowerSupplyOff ( 1 )
+      )
+
+.. _cabs-service-retention:
+
+Service retention
+-----------------
+
+.. index::
+   single: ORTS_SERVICE_RETENTION_BUTTON
+   single: ORTS_SERVICE_RETENTION_CANCELLATION_BUTTON
+
+The :ref:`service retention <physics-service-retention>` can be used to disable a cab without cutting the power on the train.
+It can only be used with a power supply script that uses this functionality.
+
+The following controls are available for the cabview:
+
+- ``ORTS_SERVICE_RETENTION_BUTTON`` can be used in order to enable the service retention
+- ``ORTS_SERVICE_RETENTION_CANCELLATION_BUTTON`` can be used in order to cancel the service retention
+
+.. _cabs-electric-train-supply:
+
+Electric train supply
+---------------------
+
+.. index::
+   single: ORTS_ELECTRIC_TRAIN_SUPPLY_COMMAND_SWITCH
+   single: ORTS_ELECTRIC_TRAIN_SUPPLY_ON
+
+The :ref:`electric train supply <physics-electric-train-supply>` controls the power line that supplies the passenger cars with electricity.
+
+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-dieselenginesonoff:
 
 Controls to switch on and off diesel engines
@@ -329,18 +414,15 @@ Further OR cab controls
 -----------------------
 
 OR supports the cabview control to open/close the left doors, the right doors 
-and the mirrors. Moreover it supports the controls for the battery state and for 
-the key state; these two controls have no effect on the state of the locomotive.
+and the mirrors.
 
 .. index::
    single: ORTS_LEFTDOOR
    single: ORTS_RIGHTDOOR
    single: ORTS_MIRRORS
-   single: ORTS_BATTERY
-   single: ORTS_POWERKEY
 
 The control blocks are like the one shown for the cab light. The Type strings 
-are ORTS_LEFTDOOR, ORTS_RIGHTDOOR, ORTS_MIRRORS, ORTS_BATTERY and ORTS_POWERKEY.
+are ORTS_LEFTDOOR, ORTS_RIGHTDOOR and ORTS_MIRRORS.
 
 
 High-resolution Cab Backgrounds and Controls

Source/Documentation/Manual/features-rollingstock.rst

@@ -619,7 +619,9 @@ Scripts will run if referenced by OR-specific fields in the .eng file.
 
 .. index::
    single: ORTSTrainBrakeController
+   single: ORTSEngineBrakeController
    single: ORTSCircuitBreaker
+   single: ORTSTractionCutOffRelay
    single: ORTSPowerSupply
    single: ORTSTrainControlSystem
 
@@ -630,15 +632,27 @@ Scripts will run if referenced by OR-specific fields in the .eng file.
    * - System
      - C# class
      - .eng block
-   * - Brakes
+   * - Train brake controller
      - ``ORTS.Scripting.Api.BrakeController``
      - ``Engine ( ORTSTrainBrakeController ( "DemoBrakes.cs" ) )``
+   * - Engine brake controller
+     - ``ORTS.Scripting.Api.BrakeController``
+     - ``Engine ( ORTSEngineBrakeController ( "DemoBrakes.cs" ) )``
    * - Circuit breaker
      - ``ORTS.Scripting.Api.CircuitBreaker``
      - ``Engine ( ORTSCircuitBreaker ( "DemoBreaker.cs" ) )``
+   * - Traction cut-off relay
+     - ``ORTS.Scripting.Api.TractionCutOffRelay``
+     - ``Engine ( ORTSTractionCutOffRelay ( "DemoRelay.cs" ) )``
+   * - Diesel power supply
+     - ``ORTS.Scripting.Api.DieselPowerSupply``
+     - ``Engine ( ORTSPowerSupply ( "DemoPower.cs" ) )``
    * - Electric power supply
      - ``ORTS.Scripting.Api.ElectricPowerSupply``
      - ``Engine ( ORTSPowerSupply ( "DemoPower.cs" ) )``
+   * - Passenger car power supply
+     - ``ORTS.Scripting.Api.PassengerCarPowerSupply``
+     - ``Wagon ( ORTSPowerSupply ( "DemoPower.cs" ) )``
    * - Train Control System
      - ``ORTS.Scripting.Api.TrainControlSystem``
      - ``Engine ( ORTSTrainControlSystem ( "DemoTCS.cs" ) )``
@@ -738,8 +752,6 @@ script, which will be caught by RunActivity.exe if run inside Visual Studio.
 Note that Visual Studio uses relative paths, so if you ever move any folders, 
 you'll need to fix the references by hand.
 
-.. _features-scripting-cb:
-
 Brake controller
 ----------------
 
@@ -750,6 +762,7 @@ of the brake controls and set the air pressures of the brake reservoirs.
 
 .. index::
    single: ORTSTrainBrakeController
+   single: ORTSEngineBrakeController
 
 Use the following .eng parameter to load a brake controller script::
 
@@ -766,6 +779,8 @@ or::
 The .cs extension is optional. "MSTS" loads the default MSTS-compatible 
 implementation, so do `not` use this name for your own script.
 
+.. _features-scripting-cb:
+
 Circuit breaker
 ---------------
 
@@ -780,32 +795,127 @@ Use the following .eng parameter to load a circuit breaker script::
 
   Engine (
       ORTSCircuitBreaker ( "YourCB.cs" )
+      ORTSCircuitBreakerClosingDelay ( 2s )
   )
 
-The .cs extension is optional. "Automatic" and "Manual" load the generic OR 
+``ORTSCircuitBreaker`` refers to the circuit breaker script in the engine's ``Script`` 
+subfolder. For this field, the .cs extension is optional. "Automatic" and "Manual" load the generic OR 
 circuit breaker implementation, so do `not` use these names for your own script.
 
-.. _features-scripting-eps:
+``ORTSCircuitBreakerClosingDelay`` refers to the delay between the closing command of the circuit breaker
+and the effective closing of the circuit breaker.
 
-Electric power supply
----------------------
+.. _features-scripting-tcor:
+
+Traction cut-off relay
+----------------------
+
+Available for diesel locomotives only. The traction cut-off relay script controls 
+the behavior of the locomotive's 
+:ref:`traction cut-off relay <physics-traction-cut-off-relay>`.
+
+.. index::
+   single: ORTSTractionCutOffRelay
 
-Available for electric locomotives only. The power supply script determines 
-whether or not the locomotive :ref:`is serviceable <physics-power-supply>` given 
+Use the following .eng parameter to load a traction cut-off relay script::
+
+  Engine (
+      ORTSTractionCutOffRelay ( "YourTCOR.cs" )
+      ORTSTractionCutOffRelayClosingDelay ( 2s )
+  )
+
+``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.
+
+``ORTSTractionCutOffRelayClosingDelay`` refers to the delay between the closing command of the traction cut-off relay
+and the effective closing of the relay.
+
+.. _features-scripting-powersupply:
+
+Diesel and electric power supply
+--------------------------------
+
+Available for diesel and electric locomotives only. The power supply script determines 
+whether or not the locomotive is serviceable (see also the description of :ref:`the diesel power supply <physics-diesel-power-supply>`
+and :ref:`the electric power supply <physics-electric-power-supply>`) given 
 the current line voltage, pantograph position, circuit breaker state, etc.
+It is also capable of forbidding some operations related to the power supply if some conditions
+are not met.
 
 .. index::
    single: ORTSPowerSupply
+   single: ORTSPowerOnDelay
+   single: ORTSAuxPowerOnDelay
 
-Use the following .eng paramater to load an electric power supply script::
+Use the following .eng parameter to load a power supply script::
 
   Engine (
       ORTSPowerSupply ( "YourEPS.cs" )
+      ORTSPowerOnDelay ( 5s )
+      ORTSAuxPowerOnDelay ( 10s )
   )
 
-The .cs extension is optional. "Default" will load the generic OR power supply 
+``ORTSPowerSupply`` refers to the power supply script in the engine's ``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.
 
+``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.
+
+``ORTSAuxPowerOnDelay`` refers to the delay between the closing of the circuit breaker or the traction cut-off relay
+and the availability of the power for auxiliary systems.
+
+.. _features-scripting-passenger-car-power-supply:
+
+Passenger car power supply
+--------------------------
+
+Available for passenger cars using electric heating. The power supply script determines
+whether or not the systems of the cars have power and calculates the power consumption
+on the :ref:`Electric Train Supply <physics-electric-train-supply>`.
+
+.. index::
+   single: ORTSPowerSupply
+   single: ORTSPowerOnDelay
+   single: ORTSPowerSupplyContinuousPower
+   single: ORTSPowerSupplyHeatingPower
+   single: ORTSPowerSupplyAirConditioningPower
+   single: ORTSPowerSupplyAirConditioningYield
+   single: ORTSHeatingCompartmentTemperatureSet
+
+If the locomotive is a diesel locomotive, the power consumed by the cars is no longer available for traction.
+
+Use the following .wag parameter to load a power supply script::
+
+  Wagon (
+      ORTSPowerSupply ( "YourEPS.cs" )
+      ORTSPowerOnDelay ( 5s )
+      ORTSPowerSupplyContinuousPower ( 500W )
+      ORTSPowerSupplyHeatingPower ( 2kW )
+      ORTSPowerSupplyAirConditioningPower ( 3kW )
+      ORTSPowerSupplyAirConditioningYield ( 0.9 )
+      ORTSHeatingCompartmentTemperatureSet ( 20degC )
+  )
+
+``ORTSPowerSupply`` refers to the power supply script in the wagon's ``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.
+
+``ORTSPowerOnDelay`` refers to the delay between the availability of the power on the Electric Train Supply
+cable and the availability of the power for the systems (for example, start-up of the static power converter).
+
+``ORTSPowerSupplyContinuousPower`` refers to the power which is consumed continuously (for example, battery chargers, lights, etc.).
+
+``ORTSPowerSupplyHeatingPower`` refers to the power which is consumed when the heating is active.
+
+``ORTSPowerSupplyAirConditioningPower`` refers to the power which is consumed when the air conditioning (cooling) is active.
+
+``ORTSPowerSupplyAirConditioningYield`` refers to the yield of the air conditioning (ratio of the heat flow rate
+by the electric power of the air conditioning system).
+
+``ORTSHeatingCompartmentTemperatureSet`` refers to the desired temperature inside the car.
+
 
 .. _features-scripting-tcs:
 
@@ -1216,7 +1326,7 @@ The blinker ``On`` property will alternate between ``true`` and ``false`` at the
 
 .. code-block:: csharp
 
-    SetCabDisplayControl(0, RSOBlinker.On ? 1 : 0);
+    SetCabDisplayControl(0, MyBlinker.On ? 1 : 0);
 
 Please note that, when the blinker is stopped, the ``On`` property is ``false``.