Add documentation around error handling to EvseManager and OCPP modul…

…es (EVerest#819)

Signed-off-by: pietfried <[email protected]>

modules/EvseManager/doc.rst

@@ -219,5 +219,74 @@ If the single phase and three phase intervals do not overlap, there is no hyster
 Note that many cars support 32A on 1ph even if they are limited to 16A on 3ph. Some however are limited to 16A
 in 1ph mode and will hence charge slower then expected in 1ph mode.
 
+Error Handling
+==============
+
+The control flow of this module can be influenced by the error implementation of its requirements. This section documents
+the side effects that can be caused by errors raised by a requirement.
+
+This module subscribes to all errors of the following requirements:
+* evse_board_support
+* connector_lock
+* ac_rcd
+* isolation_monitor
+
+A raised error can cause the EvseManager to become Inoperative. This means that charging is not possible until the error is cleared.
+If no charging session is currently running, it will prevent sessions from being started. If a charging session is currently running and an error is raised
+this will interrupt the charging session.
+
+The following sections provide an overview of errors that cause the EvseManager to become Inoperative until the error is cleared.
+
+evse_board_support
+------------------
+
+evse_board_support/DiodeFault
+evse_board_support/VentilationNotAvailable
+evse_board_support/BrownOut
+evse_board_support/EnergyManagement
+evse_board_support/PermanentFault
+evse_board_support/MREC2GroundFailure
+evse_board_support/MREC4OverCurrentFailure
+evse_board_support/MREC5OverVoltage
+evse_board_support/MREC6UnderVoltage
+evse_board_support/MREC8EmergencyStop
+evse_board_support/MREC10InvalidVehicleMode
+evse_board_support/MREC14PilotFault
+evse_board_support/MREC15PowerLoss
+evse_board_support/MREC17EVSEContactorFault
+evse_board_support/MREC19CableOverTempStop
+evse_board_support/MREC20PartialInsertion
+evse_board_support/MREC23ProximityFault
+evse_board_support/MREC24ConnectorVoltageHigh
+evse_board_support/MREC25BrokenLatch
+evse_board_support/MREC26CutCable
+evse_board_support/VendorError
+evse_board_support/CommunicationFault
+
+connector_lock
+--------------
 
+connector_lock/ConnectorLockCapNotCharged
+connector_lock/ConnectorLockUnexpectedClose
+connector_lock/ConnectorLockUnexpectedOpen
+connector_lock/ConnectorLockFailedLock
+connector_lock/ConnectorLockFailedUnlock
+connector_lock/MREC1ConnectorLockFailure
+connector_lock/VendorError
+
+ac_rcd
+------
+
+ac_rcd/MREC2GroundFailure
+ac_rcd/VendorError
+ac_rcd/Selftest
+ac_rcd/AC
+ac_rcd/DC
+
+isolation_monitor
+-----------------
+
+isolation_monitor/DeviceFault
+isolation_monitor/CommunicationFault
+isolation_monitor/VendorError
 

modules/OCPP/doc.rst

@@ -1,9 +1,36 @@
-Global Errors
-=============
+Global Errors and Error Reporting
+=================================
 
-The `enable_global_errors` flag for this module is true. This module is therefore able to retrieve and process all reported errors
+The `enable_global_errors` flag for this module is enabled. This module is therefore able to retrieve and process all reported errors
 from other modules loaded in the same EVerest configuration.
 
+In OCPP1.6 errors and can be reported using the `StatusNotification.req` message. If this module gets notified about a raised error,
+it initiates a `StatusNotification.req` that contains information about the error that has been raised.
+
+The field `status` of the `StatusNotification.req` will be set to faulted only in case the error is of the special type `evse_manager/Inoperative`.
+The field `connectorId` is set based on the mapping (for evse id and connector id) of the origin of the Error. 
+If no mapping is provided, the error will be reported on connectorId 0. Note that the mapping can be configured per module 
+inside the EVerest config file. 
+The field `errorCode` is set based in the `type` property of the error.
+
+The fields `info`, `vendorId` and `vendorErrorCode` are set based on the error type and the provided error properties. Please see the definiton
+of `get_error_info` to see how the `StatusNotification.req` is constructed based on the given error.
+
+The `StatusNotification.req` message has some limitations with respect to reporting errors:
+* Single errors can not simply be cleared. If multiple errors are raised it is not possible to clear individual errors
+* Some fields of the message have relatively small character limits (e.g. `info` with 50 characters, `vendorErrorCode` with 50 characters)
+
+This module attempts to follow the Minimum Required Error Codes (MRECS): https://inl.gov/chargex/mrec/ . This proposes a unified methodology 
+to define and classify a minimum required set of error codes and how to report them via OCPP1.6.
+
+This module currently deviates from the MREC specification in the following points:
+* Simultaneous errors: MREC requires to report simultaneous errors by reporting them in a single `StatusNotification.req` by separating the 
+information of the fields `vendorId`and `info` by a semicolon. This module sends one `StatusNotifcation.req` per individual errors because
+of the limited maximum characters of the `info` field.
+* MREC requires to always use the value `Faulted` for the `status` field when reporting an error. The OCPP1.6 specification defines the 
+`Faulted` value as follows: "When a Charge Point or connector has reported an error and is not available for energy delivery . (Inoperative).".
+This module therefore only reports `Faulted` when the Charge Point is not available for energy delivery.
+
 Interaction with EVSE Manager
 =============================
 

modules/OCPP201/doc.rst

@@ -1,5 +1,5 @@
 Global Errors
 =============
 
-The `enable_global_errors` flag for this module is true. This module is therefore able to retrieve and process all reported errors
+The `enable_global_errors` flag for this module is enabled. This module is therefore able to retrieve and process all reported errors
 from other modules loaded in the same EVerest configuration.