ads1x15.py and readme.md: Add the methid raw_to_v()

Provided by @dafvid: This method converts the raw value returned by the
read functions to a voltage according to the gain, set in the constructor.

ads1x15.py

@@ -92,6 +92,15 @@
     _PGA_0_256V  # 16x
 )
 
+_GAINS_V = (
+    6.144,  # 2/3x
+    4.096,  # 1x
+    2.048,  # 2x
+    1.024,  # 4x
+    0.512,  # 8x
+    0.256  # 16x
+)
+
 _CHANNELS = {
     (0, None): _MUX_SINGLE_0,
     (1, None): _MUX_SINGLE_1,
@@ -136,6 +145,10 @@ def _read_register(self, register):
         self.i2c.readfrom_into(self.address, self.temp2)
         return (self.temp2[0] << 8) | self.temp2[1]
 
+    def raw_to_v(self, raw):
+        v_p_b = _GAINS_V[self.gain] / 32767
+        return raw * v_p_b
+
     def set_conv(self, rate, channel1, channel2=None):
         """Set mode for read_rev"""
         self.mode = (_CQUE_NONE | _CLAT_NONLAT |
@@ -183,6 +196,9 @@ class ADS1015(ADS1115):
     def __init__(self, i2c, address=0x48):
         super().__init__(i2c, address)
 
+    def raw_to_v(self, raw):
+        return super().raw_to_v(raw << 4)
+
     def read(self, rate, channel1, channel2 = None):
         return super().read(rate, channel1, channel2) >> 4
 

readme.md

@@ -66,7 +66,7 @@ required for a single conversion is 1/samples\_per\_second plus the time
 needed for communication with the ADC, which is about 1 ms on an esp8266
 at 80 MHz. Slower conversion yields in a less noisy result.
 The data sheet figures of the ads1x15 are given for the slowest sample rate.
-The value returned is a signed integer.
+The value returned is a signed integer of the raw ADC value. That value can be converted to a voltage with the method raw_to_v().
 
 ###  adc.set_conv and adc.read_rev()
 
@@ -84,7 +84,8 @@ communication is shorter than the timer period plus the time needed to process t
 A sample code is shown below. The timing jitter observed on an esp8266 was
 about 1 ms, but the time period is defined by the micro's timer, which has
 it's own issues.
-The value returned by read_rev is a signed integer.
+The value returned by read_rev is a signed integer of the raw ADC value.
+That value can be converted to a voltage with the method raw_to_v().
 
 ###  adc.alert_start() and adc.alert_read()
 
@@ -100,6 +101,8 @@ the range of the ADC, 0..32767 for ADC1115 and
 0..2047 for ADS1015. Rate should be chosen according to the input signal
 change rate and the precision needed. The mode set is the traditional
 comparator mode, with the lower threshold set to 0.
+The value returned by alert_read is a signed integer of the raw ADC value.
+That value can be converted to a voltage with the method raw_to_v().
 
 ###  adc.conversion_start() and adc.alert_read()
 
@@ -113,6 +116,15 @@ The values of channel1, channel2 and rate are the same as for adc.read().
 The timing jitter seen is about 200 ns. However the ADC's timer is not very
 precise. In applications where this is of importance some control and
 calibration of the returned timing pattern has to be done.
+The value returned by alert_read is a signed integer of the raw ADC value.
+That value can be converted to a voltage with the method raw_to_v().
+
+### adc.raw_to_v()
+```
+voltage = adc.raw_to_v(raw)
+```
+Convert the raw ADC result to a voltage that matches the gain setting of the
+constructor. It returns a float value of the voltage.
 
 ###  adc.\_read_register()