Add extracted tools: CitrineOS, OpenOCPP, ShapeShifter

- CitrineOS core extracted (CSMS OCPP 2.0.1)
- OpenOCPP extracted (firmware OCPP 1.6J/2.0.1)
- ShapeShifter library installed (pip install -e)
- ShapeShifter specification extracted
- EVerest extracted

TODO updated with progress

tools/EVerest-main/docs/source/how-to-guides/bringup/ac.rst

@@ -0,0 +1,181 @@
+.. _htg_bring_up_ac:
+
+###########
+AC BringUp
+###########
+
+Make sure to have completed the bring up of the CP signaling as
+described in :ref:`htg_basic_bringup`.
+
+It may be a good idea to verify the powermeter functionality now as
+well - even though it is not strictly necessary for charging.
+Please refer to :ref:`htg_bring_up_powermeter` for the bring-up of
+the powermeter.
+
+Once the CP signaling has been verified, most of the work for AC is
+done. Let's verify the AC-specific components:
+
+- RCD
+- Connector Lock
+
+You can continue to use your bringup config you used for the bring up
+of CP, PP and relays, which includes the 
+:ref:`BSP BringUp module <everest_modules_BUEvseBoardSupport>`.
+
+RCD
+===
+
+Residual current monitoring is mandatory in most countries, but the
+exact regulations differ in different regions. Typically, both AC and DC
+residual current faults need to be detected. If the RCD is part of your
+charger setup (it may also be in the installation instead) it is a good
+idea to test it now.
+
+Connect an RCD test device, and verify it triggers both on AC and DC
+faults within the correct timings and levels according to your region.
+
+Connector Lock
+==============
+
+A connector lock is required for AC charging in case your charging station
+has a socket outlet. Verify that the lock is working correctly by
+commanding it to lock and unlock via your BSP driver.
+
+Milestone: First Charging of a Real Car
+=======================================
+
+Now that all individual components have been verified, it is time to
+assemble all pieces and charge a real car.
+
+Start by creating a simple AC basic charging configuration file for
+EVerest with a minimum amount of components - e.g. with one ModBus
+power meter and your board support driver for CP/PP/Relays. You can set
+“disable_authentication: true” in the configuration of EvseManager, then
+no Auth manager is needed.
+
+.. image:: images/basic-ac-charging-config.png
+   :alt: AC Basic Charging Configuration
+   :width: 550px
+
+Copy the config file to your charger prototype. Make sure EVerest is
+not running as a *systemd* service as we will start it manually in the
+beginning. So in case of doubt, try to shutdown the *everest* system
+service:
+
+.. code-block:: bash
+
+   systemctl stop everest
+
+Then start EVerest with the following command:
+
+.. code-block:: bash
+
+   manager /path/to/simple_ac_config.yaml
+
+It should look similar to the following:
+
+.. image:: images/everest-manager-start.png
+   :alt: EVerest Manager start
+
+Watch out for the log line “Ready to start charging”. Once that appears,
+you can plug in the EV simulator.
+
+Simulate a simple charging session by going to state B. Wait for PWM to
+appear, then switch to state C. The relay should click and charging
+should work.
+
+Now, switch back to state B to pause charging. The relay should open and
+EVerest will wait in state “ChargingPausedByEV”. Go back to state C to
+close relay again.
+
+Now, stop charging by first switching to state B followed by state A
+(unplug). PWM should stop and the relay should open.
+
+**Congratulations, you now simulated a full AC charging session on your
+prototype!**
+
+Two more things that should be tested before trying a real car:
+
+Stop EVerest with ``Ctrl+C``. Switch the EV simulator to state B and
+start EVerest again. Ideally, the plug-in should be detected right
+after “Ready for charging” and PWM should be enabled. Switch to state C
+after PWM is on and the relay should close.
+
+.. tip::
+
+   If this does not work, your BSP driver needs to publish the current state
+   when the “enable” command is called.
+
+This test is important as it simulates the behavior of a power
+loss while a charging session is running. Especially in a home
+environment, it is expected that the charging continues once the grid is
+back.
+
+Now you are ready to connect your first real EV. Here are a few things
+you should also try with real EVs:
+
+-  Try pause/resume from EVSE side if you have some sort of human
+   interface (you will need to call the pause/resume charging commands
+   on EvseManager). If the EV supports it, also triggered by EV side.
+
+-  Unplug power input to the charger while a charging session is active
+   and replug it to verify it starts charging again (simulate grid black
+   out).
+
+-  Try different amperage limits.
+
+Here is a (non-complete) list of things you should test as well in the
+full setup:
+
+-  Try over-current shutdown (draw more amperage than the PWM allows,
+   e.g. set PWM to 6 A / 10% but connect a heater to the output of the
+   EV tester that draws much more than 6A).
+
+-  Test under-/over-voltage behavior (different countries have different
+   requirements).
+
+-  Test over-/under-temperature scenarios.
+
+
+EVerest BringUp for AC ISO 15118-2
+==================================
+
+If basic AC charging is fully working, it is time for the ISO 15118-2
+charging bring-up. You can use a simulator for this, but unlike for
+basic charging, ISO 15118 simulators are quite complex and expensive.
+You could use a real car for this.
+
+.. note::
+
+   At the time of writing, most cars do not support ISO 15118 for AC - they do
+   so only on DC. Refer to https://github.com/EVerest/logfiles
+   to get a better idea which car brands / models can be used for testing.
+
+As with basic charging, we first create a new configuration file by
+extending the one we just used for basic charging.
+
+We add an :ref:`ISO 15118 stack <everest_modules_EvseV2G>` as well as a
+:ref:`SLAC module <everest_modules_EvseSlac>`:
+
+.. image:: images/iso-15118-stack.png
+   :alt: ISO 15118 Stack
+
+Start EVerest the same as we did for the basic charging test.
+
+Now connect a real car and watch the output. Explaining the actual ISO
+15118 protocol is beyond the scope of this document.
+
+For more information on how to debug ISO communication, refer to
+:doc:`Debugging ISO15118 </how-to-guides/debug-iso15118>`.
+
+Now we have the charging functionality up and running for the most
+important paths.
+
+.. tip::
+
+   A lot of error cases should be tested now as well as we mostly covered the
+   happy paths - but this goes beyond the scope of this how-to-guide.
+
+----
+
+**Authors**: Cornelius Claussen

tools/EVerest-main/docs/source/how-to-guides/bringup/basic.rst

@@ -0,0 +1,396 @@
+.. _htg_basic_bringup:
+
+################
+Basic BringUp
+################
+
+This chapter guides you through the basic bring-up of the control pilot (CP),
+proximity pilot (PP), and relays for both AC and DC chargers. It is a 
+prerequisite to the more specific bring-up guides for AC and DC charging.
+
+Control Pilot
+=============
+
+The first step - both for AC and DC - is to verify the control pilot
+(CP) signal functionality and stability. A lot of problems we have seen
+in the field are related to unstable CP signals. So, this step is key
+for a stable product.
+
+The normative requirements are described in IEC 61815-1. This section
+will guide you through the most important requirements specified in the
+norm to be tested at bring-up. It is not complete, IEC gives more
+requirements that should be followed at design time.
+
+.. warning::
+
+   For all parameters: Ensure that the limits are guaranteed over the complete
+   temperature and input voltage ranges as well as all other environmental
+   factors over the complete lifetime of the product.
+
+Being on the edge of the range during bring-up already, will most likely
+result in out-of-spec performance in production due to part tolerance,
+component aging etc.
+
+First, verify PWM output with no car / nothing connected to it.
+
+You should have an EVSE board support driver for your hardware already.
+
+In this how-to-guide, we will use the BringUp & Qualification tool from
+EVerest to select the different CP states manually. This ensures that
+(a) the CP signal is correct and (b) the wiring up to the EVerest HW
+driver is also correct.
+
+You can find an example configuration file in EVerest for the BelayBox
+that you can modify to use the correct BSP driver for your hardware:
+
+.. code-block:: bash
+
+   config/bringup/config-bringup-yetidriver.yaml
+
+Before you start the bring-up, make sure there is no other EVerest
+instance running (e.g. do a ``systemctl stop everest``).
+
+On the target, start it the following way:
+
+.. code-block:: bash
+
+   /etc/everest/run_tmux_helper.sh /etc/everest/bringup/config-bringup-yetidriver.yaml /usr
+
+Now, connect an EV simulator where you can set the states A/B/C/E and
+simulate a diode failure / loss of PE connection between EV and EVSE
+failure.
+
+State D is not really used anymore nowadays; it dates back to the times
+when lead-acid batteries were used that leak hydrogen gas during
+charging.
+
+Connect your EVSE, the simulator and a scope similar to this:
+
+.. image:: images/cp-scope.png
+   :alt: CP Scope
+   :width: 600px
+
+Now go through the following checklist step by step:
+
+.. tip::
+
+   Select PWM off / X1, switch EV simulator to state A.
+   This should output constant +12 V on the CP line.
+
+- Select AC coupling on the scope and verify the ripple noise. There
+  is no hard limit, but we recommend keeping it below 100 mV VPP.
+   
+  .. image:: images/constant-cp-line.png
+     :alt: Constant CP Line
+     :width: 560px
+
+- Switch to DC coupling, measure DC voltage range. It must be +12 V
+  +/- 5% (11.4 V to 12.6 V). Use a multimeter if your scope does not
+  provide sufficient DC accuracy.
+
+Now select PWM State F. This outputs constant -12 V on the CP line.
+
+- Select AC coupling on the scope and verify the ripple noise. There
+  is no hard limit, but we recommend keeping it below 100 mV.
+
+- Switch back to DC coupling, measure DC voltage range. It must be
+  -12 V +/- 5% (-12.6 V to -11.4 V). Use a multimeter if your scope
+  does not provide sufficient DC accuracy.
+
+Select *PWM on* with a duty cycle of 5%, and connect the EV on the
+simulator (State B). Note that the images below were done in state A,
+but you should use state B.
+
+- PWM frequency: Must be in the range 980 Hz - 1020 Hz. It should be
+  1000 Hz.
+   
+  .. image:: images/pwm-freq-1.png
+     :alt: PWM Frequency
+     :width: 560px
+
+- Measure the (high) pulse length for the 5% duty cycle. Measure the
+  time between the zero crossings. It should be 50 µs.
+   
+  .. image:: images/pwm-freq-2.png
+     :alt: PWM Frequency
+     :width: 560px
+
+- Equivalent source resistance: 970 - 1030 Ohm. Using a 1% 1-kOhm
+  resistor should be sufficient to fulfill this requirement if the
+  output of the PWM generator is low impedance.
+
+- Set state B and verify that the PWM duty cycle can be set to any
+  value between 5% (HLC) and the maximum current value your EVSE
+  supports (e.g. 53.3% for 32 A for AC). For AC, the maximum PWM for
+  your application can be calculated with:
+   
+  .. math::
+
+     dutycyclePercent = maxAmpere / (0.6 * 100)
+   
+  For DC, it is always 5%. The range from 5% to
+  10% is not used and it is ok to not support PWM in that range.
+
+- Set state B, which will have a PWM voltage range from +9 V to -12
+  V. Verify rise time is below 10 µs from 10% (-9.9 V) to 90% (6.9 V)
+  of the signal. The example has a rise time of 4.3 µs.
+   
+  .. image:: images/pwm-freq-3.png
+     :alt: PWM Frequency
+     :width: 560px
+
+- State B: Verify fall time is less than 13 µs. As you can see in the
+  screenshot, the fall time is 10.68 µs, which is longer than the open
+  circuit time due to the diode in the EV simulator.
+   
+  .. image:: images/pwm-freq-4.png
+     :alt: PWM Frequency
+     :width: 560px
+
+- Set state C. Verify rise time is below 7 µs from 10% (-10.2 V) to
+  90% (4.2 V) of the signal. The example has a rise time of 3.08 µs.
+   
+  .. image:: images/pwm-freq-5.png
+     :alt: PWM Frequency
+     :width: 560px
+
+- State C: Fall time must be less than 13 µs from 90% (4.2 V) to 10%
+  (-10.2 V) of the signal. The example has a fall time of 12 µs which
+  is in range.
+   
+  .. image:: images/pwm-freq-6.png
+     :alt: PWM Frequency
+     :width: 560px
+
+- Set State E (sometimes called *CP Error* or so). The CP signal
+  should be at 0 V constantly according to the norm. Some EV simulators
+  only short after the diode as seen in the screenshot. Make sure that
+  your CP detection circuitry also treats that as state E.
+   
+  .. image:: images/pwm-freq-7.png
+     :alt: PWM Frequency
+     :width: 560px
+
+- Test diode failure detection: Short the diode on the EV side. Many
+  off-the-shelf EV simulators can be easily modified with an extra push
+  button if it is not included already. Verify that the BSP throws an
+  error (DiodeFault)
+
+- Test short state changes: Toggle between states B, C, B quickly to
+  produce a short time in state C (about 200 ms or less). The short
+  state C should be reliably reported to EVerest. It is a common issue
+  that the safety MCU filters out state durations that are too short.
+  This will cause issues with the BCB toggle wakeup sequence detection
+  of ISO 15118-3.
+
+- Disconnect PE between EV and EVSE. This should be detected as an
+  error or state A.
+
+Now that the basic functionality is working, test stability of the state
+detection. Most cheap EV simulators only use the nominal resistor values
+to test the states, but ideally you have a simulator that can use the
+minimum and maximum values for each state.
+
+Ensure that the following states are detected correctly over the
+complete range:
+
++-----------------+-----------------+-----------------+-----------------+
+| State           | Minimum R       | Nominal R       | Maximum R       |
+|                 | applied by EV   |                 | applied by EV   |
++=================+=================+=================+=================+
+| B               | 1870 Ω          | 2740 Ω          | 4610 Ω          |
++-----------------+-----------------+-----------------+-----------------+
+| C               | 909 Ω           | 1300 Ω          | 1723 Ω          |
++-----------------+-----------------+-----------------+-----------------+
+
+If possible, use a debug GPIO, that shows the exact timing of the ADC
+sampling and connect it to the second channel of your scope like this:
+
+.. image:: images/pwm-freq-8.png
+   :alt: PWM Frequency
+   :width: 560px
+
+In the screenshot, two PWM signals are shown. The cyan one is 5% duty
+cycle and the yellow one is 95% duty cycle. The magenta signal shows the
+time the ADC reads the signal. As you can see, the first magenta pulse
+is nicely aligned with the end of the low part of the PWM, so it will
+read the -12 V reliably even at 95% duty cycle.
+
+The second magenta pulse is nicely aligned with the high part of the PWM
+providing stable readings even at just 5% PWM. The 5% case is the more
+critical one, as very high duty cycles are not typically used.
+
+The most common problem for unstable CP detection (which results in
+charging sessions breaking and potentially leads to relays opening under
+full load) is that the ADC sampling time starts too early or ends too
+late. In both cases it will capture part of the edge of the high part of
+the signal, resulting in a lower measured value. This can lead to e.g. a
+state C detection while it is state B in reality.
+
+Make sure to observe the correct timing under real conditions with a car
+attached. With an open circuit and the 2 µs rise time, timing may be
+perfect, but with a car attached and a 10 µs rise time it may not work
+correctly.
+
+This is especially critical at the 5% duty cycle as the high part is
+only 50 µs long. Never sample in the first 10 µs. When using the MCU to
+synchronize ADC and PWM, make sure that interrupt priorities are set
+correctly so that additional (interrupt) load on the MCU does not lead
+to delayed ADC triggers *sometimes*.
+
+This needs to be 100% stable over long periods of time (hours/days !).
+Some MCU (especially those made for motor control) can trigger the ADC
+synchronously with the PWM generation without involving an interrupt
+routine.
+
+Apply some filtering and averaging in software (e.g. average over 10
+pulses, filter out the highest and the lowest value or similar). It
+should not detect a wrong state, not even a single time.
+
+Do not filter too much though. This is another common flaw that should
+be tested at this stage: IEC 61851-1 requires switching off power when
+the EV transitions from C2 to B2 within 100 ms. As the relays also take
+some time to open, do not delay the detection of the state change by
+more than 50 ms due to filtering. Report all state changes to EVerest,
+also those that are short-lived. Otherwise, some features will not work
+correctly, e.g. ISO 15118 resume after pause.
+
+Now test with several different real cars as well, as the implementation
+on the EV side differs a bit across vendors and models.
+
+Relays
+======
+
+The AC output contactor bring-up is the same as for the DC output relay.
+
+Verify the correct function of the relay. Command the MCU to close the
+relay (use the BringUp tool’s *Allow power on* button) and verify it
+closes the relay in a timely manner (given that there is no RCD error
+etc).
+
+EVerest will issue the *allow_power_on/force_power_off* commands to the
+BSP driver just like you can do it in the BringUp module. It is
+important to understand the logic:
+
+If the safety MCU receives an *“Allow power on”*, it may switch on the
+relay if all other requirements are met (e.g. CP in state C, RCD current
+ok, temperature in range etc). The MCU may decide to not switch on the
+relay if some other local requirements are not met. It is just important
+to always report the actual relay state with the PowerOn/PowerOff
+events.
+
+The following checklist tests if the safety MCU behaves correctly in
+regard to the CP state C2. It does not test for other requirements such
+as over-temperature etc.
+
+If the safety MCU receives a force power off from EVerest, it shall
+open the relay immediately.
+
+Complete the following checklist:
+
+- State A, PWM off, force power off. Set State B then enable PWM 5%
+  and then C.
+  Then allow power on. Relays should switch on within a short period
+  of time after sending allow power on. You should see a “Power On”
+  event (the time between “Allow power on” and the “Power On”
+  feedback event should be short, e.g. less than 300 ms or so, no
+  hard limit here). Click on “Force power off”. You should see a
+  “Power Off” (same timings as above). These timings should be short
+  - see below. You can click “Power On/Off” a couple of times and
+  verify the timing of the feedback.
+
+- Toggle the relay on and off a couple of times and observe the
+  PowerOn/PowerOff events. There should be exactly one event for each
+  on or off switching of the relay. Make sure that there are not
+  multiple PowerOn/PowerOff/PowerOn events being generated because the
+  relay is bouncing.
+
+- State A, PWM off, state State B. Then enable PWM 5%, allow *power on*.
+  Relay should not close. Wait a few seconds, then set state C.
+  Relay should close immediately after entering state C. Ignore the
+  time shown on the “Power On” event. It measures the time from the
+  last “Allow power on” command to feedback.
+
+- State C, PWM 5%, Relay closed. Then set state B. Relay should open
+  immediately (max 100 ms). Go back to state C. Relay should close
+  again. (IEC 61851-1:2017 Table A.6: Sequence 8.1)
+
+- State C, PWM 5%, Relay closed. Then stop PWM but stay in state C.
+  Relay should open after a minimum of 6 seconds. (IEC 61851-1:2017
+  Table A.6: Sequence 10.2)
+
+Timing on closing relays is quite relaxed, but ISO 15118 has a limit of
+one second from the ISO command to switch on to the ISO feedback that it
+was done. As most of the time is spent in the ISO communication stacks,
+the MCU should ensure that the time from commanding the relays to close
+to receiving the feedback that it was closed correctly should be in the
+order of 100 ms in the MCU.
+
+Timing on opening the relays is more critical and a good value is
+opening within 50 ms after the command arrives at the latest. IEC
+61851-1 requires the relay to be open after a maximum of 100 ms after
+state C->B (or A etc) transition.
+
+Verify that the feedback is reported correctly. A typical error during
+bring-up with EVerest is missing relay feedback. Make sure they are
+always reported to represent the relay state correctly. Send the events
+on any change, regardless of the cause of switch on or off in the MCU.
+
+Proximity Pilot
+===============
+
+This section is for Type 2 CCS Chargers. PP works a little different for
+Type 1 Chargers.
+
+For AC chargers with a type 2 socket, PP needs to be verified as well.
+AC Chargers with a permanently attached cable do not use the PP signal.
+DC chargers normally do not use PP as they have an attached cable,
+however it may be used in some configurations to e.g. detect a cut
+cable.
+
+Most of the EV simulators can only switch the nominal resistor values
+for 13 A/20 A/32 A. To test the PP functionality, you could e.g. use
+small wired resistors and connect them manually between PP and PE or
+build yourself a small tester that can do the minimum/nominal and
+maximum resistor values.
+
+Verify that the BSP reports the correct cable ampacity for all values in
+this table:
+
+================= ========= ========= =========
+Cable ampacity    Minimal R Nominal R Maximal R
+================= ========= ========= =========
+13 A              1100 Ω    1500 Ω    2460 Ω
+20 A              400 Ω     680 Ω     936 Ω
+32 A              164 Ω     220 Ω     308 Ω
+63 A 3ph/70 A 1ph 80 Ω      100 Ω     140 Ω
+================= ========= ========= =========
+
+Values below 60 Ω above 4500 Ω should be treated as errors and the BSP
+should report “None” as PP ampacity. Resistor values in between the
+defined ranges in the table should be treated as the lower ampacity
+value.
+
+Ensure that PP is measured quickly after plug-in of the vehicle. The MCU
+should also monitor PP throughout the complete charging session and
+report an error if PP connection breaks.
+
+With CP/PP and relays, the minimal setup for AC charging has already
+been verified.
+
+.. tip::
+
+   In addition, you may want to verify a few more components before charging a
+   real car.
+   But you can also do this later on.
+
+Once the CP signaling has been verified you can continue with the bring up of 
+the powermeter and the bringup for AC or DC, depending on your use case.
+
+- :doc:`AC BringUp </how-to-guides/bringup/ac>`
+- :doc:`DC BringUp </how-to-guides/bringup/dc>`
+- :doc:`BringUp Powermeter </how-to-guides/bringup/powermeter>`
+
+----
+
+**Authors**: Cornelius Claussen

tools/EVerest-main/docs/source/how-to-guides/bringup/dc.rst

@@ -0,0 +1,386 @@
+.. _htg_bring_up_dc:
+
+##########
+DC BringUp
+##########
+
+Make sure to have completed the bring up of the CP signaling as
+described in :ref:`htg_basic_bringup`.
+
+For a DC charger, CP is essential. Several other pieces of hardware need
+to be brought to life as well, though. This gives you a minimal setup
+before testing the complete setup:
+
+- The DC power supply that delivers the charging current to the car
+- Isolation monitoring device
+- Optional: Proximity pilot
+
+Let's start with the DC power supply as this is the most important one.
+
+DC Power Supply
+===============
+
+Make sure the high voltage output of the DC power supply is isolated and
+nothing is attached to it that could draw current or get destroyed by
+high voltages. Make sure it is safe to set the maximum voltage.
+
+.. warning::
+
+   Follow all relevant safety precautions.
+   Only trained personnel may execute this step.
+   High voltages may cause severe injury including death.
+
+We will only check the most important features required for a minimal
+CCS charger setup. Check IEC 61851-23 for a full set of requirements.
+
+We will manually set voltages up to the maximum voltage and verify the
+driver functionality and the performance of the power supply under
+no-load conditions.
+
+Create a simple BringUp configuration file that contains only the
+BUPowerSupplyDC module and the actual driver module / bridge module to
+your external driver. There are a couple of examples that you can
+modify: ``config-bringup-huawei.yaml``, ``config-bringup-uugreen.yaml``,
+``config-bringup-api-powersupply.yaml``.
+
+Start the BringUp & Qualification session with the following command in
+the build folder:
+
+.. code-block:: bash
+
+   /etc/everest/run_tmux_helper.sh /etc/everest/bringup/config-bringup-mypowersupply.yaml /usr
+
+Now make sure to complete the checklist:
+
+Start with the power supply being switched off. Set the maximum output
+voltage (e.g. 1000 V) and then switch the power supply to export mode
+(rectifier mode, power supply outputs power to the car). Make sure to do
+it in exactly this order:
+
+- Verify that the reported capabilities are matching the
+  manufacturer's specifications for the power supply.
+
+- Verify that the output voltage is reached within 6 seconds. If it
+  stays on a lower voltage, the power supply driver may “forget” the
+  voltage setting when being switched on or off. This needs to be
+  fixed. The driver should work independently of the order of setting
+  output voltage and switching on/off.
+
+- Verify the output voltage and current is measured accurately.
+  Compare against an external voltage meter and a current meter (IEC
+  61851-1:2023 CC.6.3 requires +- 10 V for voltage and +-1.5% for
+  current or 0.5 A - whichever is more).
+
+- Verify that there is no overshoot when changing voltage from lowest
+  to highest output voltage. This may cause problems in CableCheck
+  phase on some EVs.
+
+- Verify the measured output voltage is correctly reported back to
+  EVerest (see measured output voltage in the BringUp module).
+
+- Verify the measured voltage is reported frequently (e.g. every
+  second or more often).
+
+- Optional: Measure the power factor. Some power supplies have
+  problems with power factor correction under no / light load
+  conditions. When charging a real car, no load happens during
+  *CableCheck* and *PreCharge* phases.
+
+Now, set the minimum output voltage that the power supply supports
+(e.g. 150 V). On power supplies that have high/low mode switching,
+choose the minimum voltage that the high mode supports. Otherwise, it
+will take quite long to switch from highest to lowest voltage, since the
+power supply will need to change its mode configuration.
+
+- Switch the power supply off and verify that the output voltage
+  drops to 0 V more or less immediately.
+
+- On power supplies with automatic high/low voltage mode switching:
+  Switch manually between the highest and lowest voltage setting to
+  trigger mode switches. They should be reasonably fast, e.g. < 5
+  seconds. Should switching between the modes be necessary during
+  charging, it is ok to have a small pause in *CurrentDemand*.
+
+- Switch on the power supply at e.g. 500 V and exit the bring up
+  setup, so EVerest is no longer communicating with the power supply.
+  It should switch off after a timeout. (Most power supplies switch off
+  within 10-20 seconds after communication loss.)
+
+Isolation monitor device
+========================
+
+The isolation monitor needs to comply with IEC 61557-8 or equivalent.
+EVerest will use the isolation resistance values as reported by the
+driver module and decide whether to stop the charging session or not. It
+is a good idea to have a redundant switch-off by e.g. using the IMD’s
+built in relay to directly switch the emergency off input of the PSU.
+
+To test the correct functionality within EVerest, use the
+BUIsolationMonitor BringUp module and connect it to the driver module.
+An example can be found here:
+
+.. code-block:: bash
+
+   config/config-bringup-isolation-monitor-sil.yaml
+
+.. image:: images/bring-up-split-screen.png
+   :alt: BUIsolationMonitor Bring-Up
+
+Ideally, the BringUp configuration loads both the isolation monitor and
+DC Power supply modules as both are needed to run all tests.
+
+- Switch on the “Power supply” at 500 V. Click on “Start
+  measurements”. Verify the isolation monitor sees the 500 V output
+  voltage. This is to ensure it is actually connected to the correct
+  wires. Verify that new measurements are coming in regularly
+  (e.g. every second).
+
+- Verify that the measured resistance is very high (e.g. 1 MOhm or
+  so).
+
+- Connect a 100 kOhm (or other value) resistor from the minus wire to
+  protective earth. Check how long it takes until the value changes on
+  the screen. This should be inline with the specs from the datasheet
+  (e.g. <10 seconds for Bender).
+
+- Test the same with the plus wire.
+
+- Stop the measurements and verify no more measurements are coming
+  in.
+
+- Start the self-test of the IMD and wait for the result (with the
+  power supply still being on). It should take no more than 10 s or so
+  to do the self-testing. Many isolation monitors take a long time to
+  complete the self-testing. This may cause time-out problems in
+  *CableCheck* with some cars.
+
+The time it takes until the IMD detects the isolation fault will need to
+be set in the final configuration file.
+
+Over-voltage monitor device
+===========================
+
+IEC 61851-23:2023 requires a fast over-voltage protection (OVM)
+(6.3.1.106.2). For a minimal proof-of-concept setup in a lab
+environment, you may want to skip this as it is not functionally needed
+for charging. It will be required for certification though.
+
+The OVM shall switch off if the DC voltage is above the required limit
+for 9 ms. For bring-up purposes, we want to test if limit is transported
+correctly and if the start and stop commands from EVerest are
+implemented correctly in the driver.
+
+An example bring-up configuration using APIs can be found here:
+
+.. code-block:: bash
+
+   config/config-bringup-api-over-voltage-monitor.yaml
+
+Add two things to this bring-up configuration:
+
+1) A power supply driver connected to a BringUp module
+2) An evse_board_support driver connected to a BringUp module
+
+Test setup:
+
+- Connect a CP tester to the control pilot and set state C.
+- Set “Allow power on” in the evse_board_support BringUp. The relays
+  should close now.
+- Connect a scope with one channel to the high voltage (use a 1000 V
+  probe!) and one channel to coil voltage of the relays. Instead of the
+  coil voltage, any other signal that triggers when the emergency
+  shutdown starts can be used.
+
+To test the basic functionality, use the check list below. Start each
+test with a fresh test setup (relays closed).
+
+.. note::
+
+   There are more requirements in the standard - especially regarding timing.
+
+- Switch on power supply at 500 V. Set the OVM limit to 550 V and
+  start the monitoring. Then, set the power supply to 565 V. The relays
+  should open immediately. The point in time when the voltage rises
+  above 550 V is t_1 - the time where the coil voltage indicates a
+  start of emergency shutdown. Verify with the scope that the time
+  between t_1 and t_2 is a maximum of 10 ms (9 ms for detection of
+  over-voltage and 1 ms to initate the shutdown.)
+- Repeat for 825 V (limit) and 840 V (DC output voltage).
+- Repeat for 935 V (limit) and 950 V (DC output voltage).
+- Repeat for 1100 V (limit) and 1115 V (DC output voltage). This
+  measurement is probably not possible as the power supply is limited
+  to 1000 V. It is a test case in table 103 of IEC 61851-23:2023.
+- Set a limit of 550 V. Switch on the power supply at 500 V. Start
+  monitoring. Stop monitoring. Set the DC output voltage to 565 V. The
+  relays shall remain closed as the over-voltage monitoring is not
+  active.
+
+More IEC 61851-23 test cases for DC
+===================================
+
+For a minimum proof-of-concept setup, it should be enough already.
+
+IEC 61851-23 has several more requirements (check the norm for a
+complete list) that need to be fulfilled for a real product. Here is the
+list of mandatory functions from IEC 61851-23:2023 6.3.1.1 that should
+be tested early on as they may influence the final design:
+
+- Verify the timing of the CableCheck phase. EVerest will print some
+  timing hints on the console. Several cars will timeout and not charge
+  if the Cable check takes more than 30 s. Recommendation is to stay
+  below 25 s for the complete phase. This may not be achievable with
+  off-the-shelf components. It is however crucial to be compatible with
+  all EVs. Use e.g. BYD EVs to test for the 30 s timeout in
+  *CableCheck*.
+
+- Continuous continuity checking of the protective conductor
+  according to 6.3.1.2: This can be usually fulfilled by opening the
+  relays (potentially under load), but you should consider ramping down
+  the DC power supply before opening the relays to protect them.
+
+- Verification that the EV is properly connected to the EV supply
+  equipment according to 6.3.1.3: This should be compliant
+  automatically if the *evse_board_support* and the safety MCU passed
+  the BringUp checks.
+
+- Energization of the power supply to the EV according to 6.3.1.4:
+  This should be compliant if the BringUp checks are passed.
+
+- De-energization of the power supply to the EV according to 6.3.1.5:
+  Similar to “Continuous continuity checking of the protective
+  conductor”.
+
+- Maximum allowable current according to 6.3.1.6: This should be
+  compliant if the BringUp checks are passed.
+
+- DC supply for EV according to 6.3.1.101: This should be compliant
+  if the BringUp checks are passed.
+
+- Measuring current and voltage according to 6.3.1.102: For charging,
+  EVerest uses the voltage and current measurements as reported by the
+  power supply (not the power meter). This should be compliant if the
+  BringUp checks passed for the DC power supply.
+
+- Latching of the vehicle coupler according to 6.3.1.103: This should
+  be compliant if the BringUp checks are passed.
+
+- Compatibility check according to 6.3.1.104: This should be
+  compliant if the BringUp checks are passed.
+
+- Insulation resistance check before energy transfer according to
+  6.3.1.105: This should be compliant if the BringUp checks are passed.
+
+- Protection against over-voltage between DC+ and DC– according to
+  6.3.1.106: This is a quite hard requirement (trigger shut-down in 1
+  ms after voltage is above limits for 9 ms). It requires both an
+  accurate and fast measurement. This needs to be implemented in the
+  safety MCU independently of EVerest.
+
+- Verification of vehicle connector latching according to 6.3.1.107:
+  Not applicable for CCS.
+
+- Control circuit supply integrity according to 6.3.1.108: Hardware
+  requirement.
+
+- Short-circuit check before energy transfer according to 6.3.1.109:
+  Test with a 100 Ohm load resistor connected in *CableCheck* as per
+  the norm.
+
+- User initiated shutdown according to 6.3.1.110: This can be
+  implemented either in the BSP (publish var *request_stop_transaction*
+  in interface *evse_board_support*) or use *stop_transaction* command
+  in *evse_manager* interface. Both are available via the EVerest API
+  modules.
+
+- Overload protection for parallel conductors (conditional function)
+  according to 6.3.1.111: Pure hardware requirement.
+
+- Voltage limitation between side B live parts (DC+ and DC–) and
+  protective conductor according to 6.3.1.112: Hardware requirement -
+  choose especially the IMD wisely.
+
+- Shutdown of EV supply equipment according to 6.3.1.113: This should
+  be compliant if the BringUp checks are passed.
+
+First milestone: Connect a real car, zero power charging
+========================================================
+
+Now that all individual components are verified, start EVerest with the
+full configuration that you created earlier.
+
+Disconnect the plus wire between your prototype and the cable to the EV.
+On the first tests, no power should be flowing.
+
+Start EVerest and wait for the message “Ready for charging”. Then plug
+in the vehicle. Watch the ISO traffic. It should be successful until the
+*PreCharge* phase. Then the EV should stop as it cannot see the voltage.
+
+During the start up of the session, monitor the voltage of the DC power
+supply. It should be 500 V in *CableCheck* (or whatever you set in the
+config) and then switch to the EV batteries voltage.
+
+Verify that in precharge the output voltage is within +/-20 V of the
+EV's battery voltage.
+
+Second milestone: Connect a real car, limited power charging
+============================================================
+
+Connect a 5 kOhm resistor in the plus wire between EVSE output and
+connector to EV. This will limit the current flow into the EV, but
+allows voltages to be seen by the EV. Plug in a vehicle. You should now
+get all the way to the *CurrentDemand* phase.
+
+Some EVs will stop after some seconds as no current is flowing.
+
+Verify all communications are correct. Use Wireshark to verify each step
+of the ISO communication (see Debug chapter).
+
+Third milestone: Connect a real car, full power charging
+========================================================
+
+If everything was correct in the previous step, remove the resistor and
+connect the plug normally to the EVSE. Start a charging session.
+
+Power should now be delivered to the EV in *CurrentDemand*.
+
+Verify that the current delivered is what the EV requested and that it
+is also reported correctly in the *CurrentDemandRes* messages. Verify it
+is shown correctly on the in-vehicle display.
+
+Verify the AC side is not getting overloaded.
+
+.. tip::
+
+   A good habit is to monitor your prototype with a small thermal camera to
+   see if any component overheats.
+
+If that works: **Congratulations!** You have successfully charged an EV
+with DC for the first time.
+
+Error cases
+===========
+
+There are many error cases that should be tested now. Listing all goes
+beyond the scope of this manual. A few examples that should be tested:
+
+- Place a 100 kOhm resistor from minus wire to PE. Start a charging
+  session. It should also fail in *CableCheck* state.
+
+- Test short circuit under full load.
+
+- Test load dump: Charge at maximum power and open the relays to zero
+  load. Watch the voltage overshoot. The power supplies need to survive
+  that multiple times. This does happen in the field with some EVs that
+  open their contactors during charging when the onboard controller
+  firmware resets.
+
+- AC under-/over-voltage input
+
+- Over-temperature shutdown
+
+- On three-phase AC/DC converters, switch off one phase on the input
+  at full load.
+
+----
+
+**Authors**: Cornelius Claussen

tools/EVerest-main/docs/source/how-to-guides/bringup/index.rst

@@ -0,0 +1,147 @@
+.. _htg_bring_up:
+
+########################
+BringUp & Qualification
+########################
+
+This chapter introduces the EVerest BringUp & Qualification process.
+
+This process is all about bringing up the individual hardware components
+step by step by verifying their functionality and performance in
+isolated test cases. In the end, the whole charger will be brought to
+life and we'll hit the most important milestone: A first complete
+charging session of a real car.
+
+.. tip::
+
+   EVerest HW Drivers should be available for all required hardware
+   components and a prototype hardware should be in place.
+
+Many sections are written like a checklist that you can follow step by step.
+
+Before we start, we recommend to set up the following development
+environment:
+
+- Working cross compiler on your PC to do fast updates of your code
+  (e.g. with *rsync* to the target). On Yocto, use ``bitbake -c
+  populate_sdk my-image`` to generate the SDK.
+- SSH to the target
+- Ensure the hardware interfaces to all components are up and running
+- Include “tmux” in your image
+- Recommended: Unicode support should work on the target terminal
+
+BringUp modules
+================
+
+The following chapters use EVerest's BringUp helper modules.
+
+These modules allow manual control of one or several hardware drivers.
+We will use them to verify correct functionality and timing of all
+components individually before assembling the complete configuration
+file.
+
+The BringUp modules should be included in the system image initially,
+but later in production they should not be installed.
+
+To get familiar with this method, you can use a pure SIL version on your
+development PC. This step is optional. From the *build* folder, start
+the following run script:
+
+.. code-block:: bash
+
+   ./dist/etc/everest/run_tmux_helper.sh ../config/bringup/config-bringup-isolation-monitor-sil.yaml ./dist
+
+The first parameter specifies the config file to load, the second
+parameter points to the EVerest installation to use.
+
+Later, on the embedded target, it can be used like this:
+
+.. code-block:: bash
+
+   /etc/everest/run_tmux_helper.sh /etc/everest/bringup/myconf.yaml /usr
+
+The second argument now points to the EVerest version installed in the
+base Yocto system. If you use a cross-compiled development version
+installed under ``/var/everest``, simply set the second argument to
+``/var/everest``.
+
+You should see a split-screen setup (using tmux) similar to this:
+
+.. image:: images/bring-up-split-screen.png
+   :alt: Bring-Up Split-Screen
+
+In the left pane, EVerest is running all modules except for the two
+BringUp modules. They are running in their own shell. Mouse support
+should be working and you can click on the buttons.
+
+E.g., click on “Start Measurements” and check that new isolation
+measurements are coming in roughly every second.
+
+To exit the tmux session, press ``Ctrl+B`` and then ``d``. Normally with
+tmux, this puts the session running into the background but it keeps
+running. The ``run_tmux_helper.sh`` script will take care of ending the
+session properly here and cleaning up.
+
+Have a look at the config file that it is using
+(``config/bringup/config-bringup-isolation-monitor-sil.yaml``):
+
+.. code-block:: yaml
+
+   active_modules:  
+    bsp_ui:  
+      standalone: true  
+      module: BUIsolationMonitor  
+      connections:  
+        imd:  
+          - implementation_id: main  
+            module_id: iso_monitor  
+    powersupply_ui:  
+      connections:  
+        psu:  
+          - implementation_id: main  
+            module_id: powersupply  
+      module: BUPowerSupplyDC  
+      standalone: true  
+    iso_monitor:  
+      module: IMDSimulator  
+    powersupply:  
+      module: DCSupplySimulator
+
+The configuration file loads the two BringUp modules you saw on the
+right as well as the two driver modules for isolation monitor and DC
+power supply. Since it is a SIL config, both hardware drivers are
+simulated only.
+
+.. tip::
+
+   Have a look at the attribute “standalone: true” in both BringUp modules.
+   This tells the manager and the tmux script that these two modules should be
+   run in a separate tmux window.  
+
+For your hardware, you will need to create configuration files that use
+the real hardware instead of the simulated ones. There are example files
+for each of the following steps - just adapt them to your needs.
+
+Now, let’s use this on real hardware.
+
+.. warning::
+
+   During the hardware bring-up, you will switch on high voltages that can
+   cause severe injury including death.
+   It must only be done by trained personnel.
+   Make sure to follow all necessary safety procedures.
+
+The following chapters will guide you through the individual steps of
+bringing up the hardware components one by one.
+
+.. toctree::
+    :maxdepth: 1
+
+    basic
+    powermeter
+    ac
+    dc
+
+----
+
+**Authors**: Cornelius Claussen

tools/EVerest-main/docs/source/how-to-guides/bringup/powermeter.rst

@@ -0,0 +1,44 @@
+.. _htg_bring_up_powermeter:
+
+##################
+BringUp Powermeter
+##################
+
+In case your charger prototype has a power meter, it may be a good time
+to verify its functionality as well now - even though it is not strictly
+necessary for charging.
+
+Write a bring-up config for your power meter and start it the same way
+as described in :ref:`htg_bring_up`. There are a few examples you can copy
+and modify, e.g. ``config-bringup-DZG.yaml`` or ``config-bringup-LEM.yaml``.
+
+.. code-block:: bash
+
+   /etc/everest/run_tmux_helper.sh /etc/everest/bringup/config-bringup-mypowermeter.yaml /usr
+
+Your setup should look like this:
+
+.. image:: images/bring-up-powermeter.png
+   :alt: Bring-Up Powermeter
+
+Complete the following steps:
+
+- Verify that the measurements come in regularly (e.g. every second).
+- Imported energy in Wh and timestamp are the only required values.
+  Verify they are correct. For bidirectional metering, also verify the
+  exported energy values.
+- Validate the other reported measurements.
+- If supported by the power meter (e.g. for
+  :doc:`German Eichrecht </how-to-guides/eichrecht>`), click
+  on “Start Transaction”. Verify that it replies correctly, and verify
+  the time to reply is less than a few seconds.
+- Click on “Stop Transaction” and verify the reply. The reply should
+  not take more than a few seconds.
+- Apply some test load if possible, and verify that the flow
+  direction of energy is correct. A common mistake is to swap input and
+  output of the meter. If you don’t have a test load, you can also test
+  this when doing the first charging tests with a real car.
+
+----
+
+**Authors**: Cornelius Claussen