Voltage read-out handbook: dividers, Vcc, "internal", LDO, demystified
Adding some sections to the manual in next release:
Appendix A. Voltage Readout Methods
Method 1, Classic divider (Non-OTSM, 1S or series):
Config options: READ_VOLTAGE_FROM_DIVIDER
Traditionally voltage is read across a voltage divider made from the R1 and R2
resistors. The ADC readout is made relative to the internal 1.1V reference.
In other words the ADC result is V_divider/1.1V * 255. This method does not
work for OTSM, because the voltage pin detects power off when voltage is below
about 1.5V. For this method, all divider voltages must be below 1.1, which
won't work for OTSM.
When to use: For any build without OTSM
Advantages: Works in 1S and 2S, 1 point calibration possible.
Disadvantages: Doesn't work with OTSM, requires a divider.
Method 2, inverted (aka "internal") reads (1S OTSM):
Config options: READ_VOLTAGE_FROM_VCC
This has been become known as "internal" voltage reading. It effectively just reads
Vcc, or the voltage on the supply pin of the mcu. However it does this
actually reading the internal 1.1V reference, but reading it referenced to Vcc,
essentially inverting the result. The ADC value procued is 1.1V/Vcc * 255. And
clearly Vcc= 1.1*255/ADC. It works well when Vcc represents the battery
voltage, ie in 1S.
When to use: Can use for any 1S build, but useful for 1S OTSM
Advantages: Should work pretty well with no calibration, and easy to adjust.
Can be used on small boards with no voltage divider.
Disadvantages: 1S only, Calibration theoretically more difficult to get exact.
Method 3 Vcc-referenced divider reads (LDO OTSM method)
Config options: READ_VOLTAGE_FROM_VCC
REFERENCE_DIVIDER_READS_TO_VCC
Like method 1, but references the divider read to Vcc. ADC result is
V_divider/Vcc * 255.
When to use it: This works for any LDO build, ie builds where Vcc is regulated
and can be used as a reference. It is only needed though for OTSM LDO builds,
but is likely to be better than Method 1 for any LDO build, due to the more
stable voltage reference.
Advantages:Most stable voltage reference can mean calibration-free.
Disadvantages: Requires regulated mcu input voltage (won't work in 1S)
Note, this may work on zener builds in theory, but depends on the stability
of the zener (for OTSM it also requires a quality schottkey protection diodes and
depends on the leakage of the zener).
Summary:
For non-OTSM builds with a divider the classic divider method is fine.
For 1S-OTSM or 1S with no divider or 1S for calibration free use, use inverted
reads (Meth 2).
For LDO-OTSM builds, use Vcc-referenced divider reads. (Meth 3)
Any OTSM build must have separate builds for 1S and LDO.