make config file clearer

etc/dbus-serialbattery/config.default.ini

@@ -2,35 +2,45 @@
 
 ; Choose the mode for voltage / current limitations (True / False)
 ; False is a step mode. This is the default with limitations on hard boundary steps
-; True is a linear mode. The values between the steps are calculated for smoother values (by WaldemarFech)
+; True is a linear mode. For CCL and DCL the values between the steps are calculated for smoother values (by WaldemarFech)
+; For CVL the penalties are only applied, if the cell voltage reaches the penalty voltage
 LINEAR_LIMITATION_ENABLE = False
 
 ; Battery Current limits
 MAX_BATTERY_CHARGE_CURRENT = 70.0
 MAX_BATTERY_DISCHARGE_CURRENT = 90.0
 
 
-; --------- Charge Voltage limitation (CVL) ---------
-; Description: Limit maximal charging voltage dynamically
-; Example: The battery is full and was for 900 seconds on max voltage, switch to float voltage to don't stress the batteries
+; --------- Charge Voltage limitation (affecting CVL) ---------
+; Description: Limit max charging voltage (MAX_CELL_VOLTAGE * cell count) and switch from max voltage to float voltage (FLOAT_CELL_VOLTAGE * cell count)
+; after max voltage is reached for MAX_VOLTAGE_TIME_SEC. It switches back to max voltage after SoC is below SOC_LEVEL_TO_RESET_VOLTAGE_LIMIT
+; If LINEAR_LIMITATION_ENABLE is set to True then penalty voltages are applied
+; Example: The battery reached max voltage of 55.2V and hold it for 900 seconds, the the CVL is switched to float voltage of 53.6V to don't stress the batteries.
+; Allow max voltage of 55.2V again, if SoC is once below 90%
 ; Charge voltage control management enable (True/False).
 CVCM_ENABLE = False
 
-; Example: 16 cells * 3.45V/cell = 55.2V max charge voltage. 16*2.9V = 46.4V min discharge voltage
-; Cell min/max voltages - used with the cell count to get the min/max battery voltage
+; -- Cell Voltages
+; Description: Cell min/max voltages which are used to calculate the min/max battery voltage
+; Example: 16 cells * 3.45V/cell = 55.2V max charge voltage. 16 cells * 2.90V = 46.4V min discharge voltage
 MIN_CELL_VOLTAGE = 2.90
-; max voltage is can seen as absorption voltage
+; Max voltage can seen as absorption voltage
 MAX_CELL_VOLTAGE = 3.45
 FLOAT_CELL_VOLTAGE = 3.35
 
-; -- works only when LINEAR_LIMITATION_ENABLE = True
-; if the cell voltage reaches 3.55V, then reduce current battery-voltage by 0.01V
-; if the cell voltage goes over 3.6V, then the maximum penalty will not be exceeded
-; there will be a sum of all penalties for each cell, which exceeds the limits
-PENALTY_AT_CELL_VOLTAGE = 3.45, 3.55, 3.6
+; -- Penalty Voltages
+; NOTE: works only when LINEAR_LIMITATION_ENABLE = True
+; More details can be found here: https://github.com/Louisvdw/dbus-serialbattery/issues/297#issuecomment-1327142635
+; If the cell voltage reaches 3.48V, then reduce actual battery-voltage by 0.01V
+; If the cell voltage goes over 3.6V, then the maximum penalty will not be exceeded
+; There will be a sum of all penalties for each cell, which exceeds the limits
+; NOTE: The first value of PENALTY_AT_CELL_VOLTAGE has to be at least MAX_CELL_VOLTAGE + the first value of PENALTY_BATTERY_VOLTAGE,
+; else the FLOAT_CELL_VOLTAGE is never set. Additionally the battery voltage has to reach max voltage and all cells has to be below penalty voltage to switch to float voltage.
+PENALTY_AT_CELL_VOLTAGE = 3.48, 3.55, 3.6
 ; this voltage will be subtracted
 PENALTY_BATTERY_VOLTAGE = 0.01, 1.0, 2.0
 
+; -- CVL Reset based on SoC option
 ; Reset max voltage after
 MAX_VOLTAGE_TIME_SEC = 900
 ; Specify SoC where CVL limit is reset to max voltage
@@ -49,7 +59,7 @@ CCCM_CV_ENABLE = True
 ; Discharge current control management referring to cell-voltage enable (True/False).
 DCCM_CV_ENABLE = True
 
-; Set Steps to reduce battery current
+; Set steps to reduce battery current
 ; The current will be changed linear between those steps if LINEAR_LIMITATION_ENABLE is set to True
 CELL_VOLTAGES_WHILE_CHARGING = 3.55, 3.50, 3.45, 3.30
 MAX_CHARGE_CURRENT_CV_FRACTION = 0, 0.05, 0.5, 1
@@ -77,30 +87,30 @@ MAX_DISCHARGE_CURRENT_T_FRACTION = 0, 0.2, 0.3, 0.4, 1, 1, 0
 
 
 ; --------- SOC limitation (affecting CCL/DCL) ---------
-; Description: Maximal charge / discharge current will be increased / decreased depending on State of Charge, see CC_SOC_LIMIT1 etc.
-; The State of Charge (SoC) charge / discharge current will be in-/decreased depending on SOC.
+; Description: Maximal charge / discharge current will be increased / decreased depending on State of Charge,
+;  see CC_SOC_LIMIT1 etc.
 ; Example: The SoC limit will be monitored to control the currents.
 ; Charge current control management enable (True/False).
 CCCM_SOC_ENABLE = True
 ; Discharge current control management enable (True/False).
 DCCM_SOC_ENABLE = True
 
-; charge current soc limits
+; Charge current soc limits
 CC_SOC_LIMIT1 = 98
 CC_SOC_LIMIT2 = 95
 CC_SOC_LIMIT3 = 91
 
-; charge current limits
+; Charge current limits
 CC_CURRENT_LIMIT1_FRACTION = 0.1
 CC_CURRENT_LIMIT2_FRACTION = 0.3
 CC_CURRENT_LIMIT3_FRACTION = 0.5
 
-; discharge current soc limits
+; Discharge current soc limits
 DC_SOC_LIMIT1 = 10
 DC_SOC_LIMIT2 = 20
 DC_SOC_LIMIT3 = 30
 
-; discharge current limits
+; Discharge current limits
 DC_CURRENT_LIMIT1_FRACTION = 0.1
 DC_CURRENT_LIMIT2_FRACTION = 0.3
 DC_CURRENT_LIMIT3_FRACTION = 0.5
@@ -141,7 +151,7 @@ PUBLISH_CONFIG_VALUES = 1
 
 ; Select the format of cell data presented on dbus [Valid values 0,1,2,3]
 ; 0 Do not publish all the cells (only the min/max cell data as used by the default GX)
-; 1 Format: /Voltages/Cell; (also available for display on Remote Console)
+; 1 Format: /Voltages/Cell (also available for display on Remote Console)
 ; 2 Format: /Cell/#/Volts
 ; 3 Both formats 1 and 2
 BATTERY_CELL_DATA_FORMAT = 1