Add section regarding phase count switching support

Signed-off-by: Michael Heimpold <michael.heimpold@chargebyte.com>

docs/source/conf.py

@@ -18,6 +18,8 @@
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+numfig = True
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

docs/source/everest_charging_stack.rst

@@ -121,6 +121,114 @@ This module implements and integrates OCPP 1.6 support within EVerest.
 
 This module implements and integrates OCPP 2.0.1 support within EVerest.
 
+Energy Management: 3 phase / 1 phase switching
+==============================================
+
+During AC charging, it is sometimes desired to charge with less than 4.2 kW (= 6 A * 230 V * 3 phases),
+e.g. for solar charging setups. EVerest comes with built-in support for such setups and can dynamically
+switch the count of phases provided to the car. It only requires a corresponding hardware setup and
+support in the used hardware abstractation layer.
+
+The Charge Control C is equipped with two independent onboard relays. This makes this hardware platform
+ideal for setting up such a phase count switching setup.
+Also the BSP driver `CbTarragonDriver <https://github.com/chargebyte/everest-chargebyte/tree/main/modules/CbTarragonDriver>`_
+(aka HAL) for this platform gained support for this.
+
+A phase count switching setup always consists of two contactors which are controlled by the charging
+stack more or less independently. There exists two different kinds of hardware setups which are
+different in the physical wiring:
+
+* **serial** setup type: In this setup type both contactors are wired in 'series'. This means, that
+  the primary contactor always switches all phases (directly or indirectly) while the secondary contactor
+  only switches the phases 2 and 3. The point is here, that if all phases are to be visible to the car,
+  they should appear simultaneously, not one after the other.
+  To achieve this, the primary contactor either switches all phases or, in addition to the neutral line
+  and one phase, also switches the control path from the secondary contactor.
+  From the software perspective, the secondary contactor is switched on first, but switched off last.
+  In contrast to the primary contactor: this one is switched on last, but switched off first.
+  This ensures that - in combination with the physical setup - a homogeneous view of the grid to
+  the car. Thus the charger appears to be a single-phase only or a three-phase charger.
+
+.. _switch-3ph1ph-serial-1:
+.. figure:: _static/images/switch-3ph1ph-serial-4p-contactor.drawio.svg
+    :width: 80%
+
+    Example wiring with two contactors 'in series', both with auxiliary contacts for feedback generation.
+    Both contactors must be rated for 400 V in this setup.
+
+.. _switch-3ph1ph-serial-2:
+.. figure:: _static/images/switch-3ph1ph-serial-3p-contactor.drawio.svg
+    :width: 80%
+
+    Another example wiring with two contactors 'in series'. Here too, both contactors must be
+    rated for 400 V. In this example, the primary contactor only needs to switch 3 wires.
+
+* **mutual** setup type: In this setup type, two different contactors are used 'in parallel'. However,
+  it is important that only one contactor can be active at a time, i.e. they exclude each other *mutually*.
+  This is supported by software configuration, but should already be enforced in hardware,
+  e.g. by using the auxiliary contacts as shown in :numref:`switch-3ph1ph-mutual`.
+  This setup allow to use a single 400 V-rated contactor in combination with a (cheaper) 230 V-rated one.
+
+.. _switch-3ph1ph-mutual:
+.. figure:: _static/images/switch-3ph1ph-mutual.drawio.svg
+    :width: 80%
+
+    Example wiring with two contactors in 'mutual' setup. The primary contactor must be
+    rated for 400 V, the secondary contactor can be rated for 230 V only.
+
+As mentioned, the **CbTarragonDriver** module is the relevant hardware abstraction layer for EVerest
+for the Charge Control C platform. The module must know which wiring type is used in the charger
+and offers the configuration parameter **switch_3ph1ph_wiring** for this which can take the following strings:
+
+*  **none** (default): No phase-count switching is supported - only R1/S1 is used to switch on/off a single contactor.
+* **serial**: Phase-count switching support is enabled using the serial wiring as described above: R1/S1 switches
+  the primary contactor, R2/S2 is attached to the secondary contactor.
+* **mutual**: Phase-count switching support is enabled using the mutual wiring as described above. R1/S1 is wired to
+  the three-phase contactor, R2/S2 is wired to the single-phase contactor.
+
+Snippet of an EVerest configuration file which fits the configuration for :numref:`switch-3ph1ph-mutual`:
+
+.. code-block:: yaml
+
+   ...
+   tarragon_bsp:
+     module: CbTarragonDriver
+     config_module:
+       contactor_1_feedback_type: no
+       contactor_2_feedback_type: no
+       switch_3ph1ph_wiring: mutual
+       connector_type: IEC62196Type2Socket
+   ...
+
+However, enabling support for phase-count switching in the BSP module is not sufficient. The EVerest configuration
+must include a module of type 'EnergyManager' which must be properly linked to 'EvseManager' module et al.
+This 'EnergyManger' has also a configuration switch **switch_3ph1ph_while_charging_mode** which controls the
+phase-count switching in general:
+
+* **Never**: Do not use 1 phase / 3 phase switching even if supported by the BSP.
+* **Oneway**: Only switch from 3 phase to 1 phase if power is not enough, but never switch back to 3 phase for a session.
+* **Both**: Switch in both directions, i.e. from 3 phase to 1 phase and back to 3 phase if available power changes.
+
+The EnergyManager module has also additional configuration options to allow fine-tuning of the behavior, but
+all ship with reasonable default values and thus are not explained in detail here.
+A description of all these parameter can be found in the
+`EnergyManager manifest <https://github.com/EVerest/everest-core/blob/main/modules/EnergyManager/manifest.yaml>`_.
+
+And also the 'EvseManager' module allows fine-tuning the switching process with two configuration parameters:
+
+* **switch_3ph1ph_delay_s**: This takes an integer and defines, how many seconds the charging stacks waits between
+  the switching process. In combination with Charge Control C, this value should be at least 11 seconds since the
+  onboard relays are enforced to only switch on every 10 seconds, using this exact value or less generates a warning
+  but does not result in faster switching.
+* **switch_3ph1ph_cp_state**: Allows to configure the CP state used during phase count switching. The default value
+  of 'X1' should work with all cars and thus it's recommended to leave it on this default value.
+
+The full description of all these parameters can be found in the
+`EvseManager manifest <https://github.com/EVerest/everest-core/blob/main/modules/EvseManager/manifest.yaml>`_.
+
+.. note::
+   Phase count switching is only possible in basic charging mode.
+
 Further reading
 ===============