updated/shuffled examples

Author: siddacious

README.rst

@@ -63,17 +63,40 @@ Usage Example
 
 .. code-block:: python3
 
-import board
-import adafruit_pcf8591
-import time
-
-i2c = board.I2C()
-pcf = adafruit_pcf8591.PCF8591(i2c)
-
-while True:
-  read_value = pcf.analog_read(0)
-  print("Read value:", read_value, "scaled value: %0.2f V"%((read_value/255)*3.3))
-  time.sleep(.1)
+    import time
+    import board
+
+    import adafruit_pcf8591.pcf8591 as PCF
+    from adafruit_pcf8591.analog_in import AnalogIn
+    from adafruit_pcf8591.analog_out import AnalogOut
+
+    ############# AnalogOut & AnalogIn Example ##########################
+    #
+    # This example shows how to use the included AnalogIn and AnalogOut
+    # classes to set the internal DAC to output a voltage and then measure
+    # it with the first ADC channel.
+    #
+    # Wiring:
+    # Connect the DAC output to the first ADC channel, in addition to the
+    # normal power and I2C connections
+    #
+    #####################################################################
+    i2c = board.I2C()
+    pcf = PCF.PCF8591(i2c)
+
+    pcf_in_0 = AnalogIn(pcf, PCF.A0)
+    pcf_out = AnalogOut(pcf, PCF.OUT)
+
+    while True:
+
+        print("Setting out to ", 65535)
+        pcf_out.value = 65535
+        raw_value = pcf_in_0.value
+        scaled_value = (raw_value / 65535) * pcf_in_0.reference_voltage
+
+        print("Pin 0: %0.2fV" % (scaled_value))
+        print("")
+        time.sleep(1)
 
 
 

adafruit_pcf8591/analog_in.py

@@ -35,22 +35,34 @@ def __init__(self, pcf, pin):
         """AnalogIn
 
         :param ads: The PCF8591 object.
-        :param ~digitalio.DigitalInOut pin: Required pin for single-ended.
+        :param ~digitalio.DigitalInOut pin: Required ADC channel pin.
 
         """
         self._pcf = pcf
         self._channel_number = pin
 
+    @property
+    def voltage(self):
+        """Returns the value of an ADC channel in volts as compared to the reference voltage."""
+
+        if not self._pcf:
+            raise RuntimeError(
+                "Underlying ADC does not exist, likely due to callint `deinit`"
+            )
+        raw_reading = self._pcf.read(self._channel_number)
+        return ((raw_reading << 8) / 65535) * self._pcf.reference_voltage
+
     @property
     def value(self):
-        """Returns the value of an ADC pin scaled to a 16-bit integer from the native value."""
+        """Returns the value of an ADC channel.
+        The value is scaled to a 16-bit integer from the native 8-bit value."""
 
         if not self._pcf:
             raise RuntimeError(
                 "Underlying ADC does not exist, likely due to callint `deinit`"
             )
 
-        return self._pcf.analog_read(self._channel_number) << 8
+        return self._pcf.read(self._channel_number) << 8
 
     @property
     def reference_voltage(self):

adafruit_pcf8591/analog_out.py

@@ -59,7 +59,7 @@ def value(self, new_value):  # this may have to scale from 16-bit
                 "Underlying DAC is disabled, likely due to callint `deinit`"
             )
         # underlying sensor is 8-bit, so scale accordingly
-        self._pcf.analog_write(new_value >> 8)
+        self._pcf.write(new_value >> 8)
         self._value = new_value
 
     def deinit(self):

adafruit_pcf8591/pcf8591.py

@@ -73,7 +73,7 @@ def reference_voltage(self):
         An ADC value of 65535 will equal `reference_voltage`"""
         return self._reference_voltage
 
-    def analog_read(self, channel):
+    def read(self, channel):
         """Read an analog value from one of the four ADC inputs
 
           param: :adcnum The single-ended ADC to read from, 0 thru 3
@@ -103,9 +103,9 @@ def dac_enabled(self):
     def dac_enabled(self, enable_dac):
 
         self._dac_enabled = enable_dac
-        self.analog_write(self._dacval)
+        self.write(self._dacval)
 
-    def analog_write(self, value):
+    def write(self, value):
         """Writes a uint8_t value to the DAC output
 
       param: :output The value to write: 0 is GND and 65535 is VCC

examples/pcf8591_adc_example.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: Copyright (c) 2020 Bryan Siepert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+import time
+import board
+from adafruit_pcf8591.pcf8591 import PCF8591
+
+################ Read/ADC Example #####################
+#
+# This example shows how to use a PCF8591 instance to read one of the ADC channels.
+#
+# Wiring:
+# Connect a voltage source to the first ADC channel, in addition to the
+# normal power and I2C connections. The voltage level should be between 0V/GND and VCC
+#
+########################################
+i2c = board.I2C()
+pcf = PCF8591(i2c)
+
+channel_a = 0
+channel_b = 1
+
+while True:
+
+    read_value = pcf.read(channel_a)
+    scaled_value = (read_value / 255) * pcf.reference_voltage
+
+    print("Channel: %d %0.2fV" % (channel_a, scaled_value))
+    print("")
+    time.sleep(0.1)
+
+    read_value = pcf.read(channel_b)
+    scaled_value = (read_value / 255) * pcf.reference_voltage
+
+    print("Channel: %d %0.2fV" % (channel_b, scaled_value))
+    print("")
+    print("*" * 20)
+    time.sleep(1)

examples/pcf8591_analog_in.py

@@ -6,7 +6,18 @@
 import adafruit_pcf8591.pcf8591 as PCF
 from adafruit_pcf8591.analog_in import AnalogIn
 
-VOLTAGE_LEVEL = 3.3
+################ AnalogIn Example #####################
+#
+# This example shows how to use the AnalogIn class provided
+# by the library by creating an AnalogIn instance and using
+# it to measure the voltage at the first ADC channel input
+#
+# Wiring:
+# Connect a voltage source to the first ADC channel, in addition to the
+# normal power and I2C connections. The voltage level should be between 0V/GND and VCC
+#
+########################################
+
 i2c = board.I2C()
 pcf = PCF.PCF8591(i2c)
 

examples/pcf8591_analog_out.py

@@ -0,0 +1,43 @@
+# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
+# SPDX-FileCopyrightText: Copyright (c) 2020 Bryan Siepert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+import time
+import board
+from adafruit_pcf8591.pcf8591 import PCF8591
+
+################ read/DAC Example #####################
+#
+# This example shows how to use a PCF8591 instance to set the voltage output by the included DAC.
+#
+# Wiring:
+# Connect the DAC output to the first ADC channel, in addition to the
+# normal power and I2C connections
+#
+########################################
+i2c = board.I2C()
+
+pcf = PCF8591(i2c)
+print("enabling DAC")
+pcf.dac_enabled = True
+while True:
+    print("Setting DAC to", 255)
+    pcf.write(255)
+    print("Reading channel 0")
+    read_value = pcf.read(0)
+    scaled_value = (read_value / 255) * pcf.reference_voltage
+
+    print("Channel 0: %0.2fV" % (scaled_value))
+    print("")
+    time.sleep(0.5)
+    print("Setting DAC to", 0)
+    pcf.write(0)
+
+    print("Reading channel 0")
+    read_value = pcf.read(0)
+    scaled_value = (read_value / 255) * pcf.reference_voltage
+
+    print("Channel 3: %0.2fV" % (scaled_value))
+    print("")
+
+    time.sleep(1.0)

examples/pcf8591_dac_example.py

@@ -1,30 +1,54 @@
 # SPDX-FileCopyrightText: Copyright (c) 2020 Bryan Siepert for Adafruit Industries
-#
 # SPDX-License-Identifier: MIT
 import time
 import board
-from adafruit_pcf8591.pcf8591 import PCF8591
 
-VOLTAGE_LEVEL = 3.3
+import adafruit_pcf8591.pcf8591 as PCF
+from adafruit_pcf8591.analog_in import AnalogIn
+from adafruit_pcf8591.analog_out import AnalogOut
+
+############# AnalogOut & AnalogIn Example ##########################
+#
+# This example shows how to use the included AnalogIn and AnalogOut
+# classes to set the internal DAC to output a voltage and then measure
+# it with the first ADC channel.
+#
+# Wiring:
+# Connect the DAC output to the first ADC channel, in addition to the
+# normal power and I2C connections
+#
+#####################################################################
 i2c = board.I2C()
-pcf = PCF8591(i2c)
+pcf = PCF.PCF8591(i2c)
 
-channel_a = 0
-channel_b = 1
+pcf_in_0 = AnalogIn(pcf, PCF.A0)
+pcf_out = AnalogOut(pcf, PCF.OUT)
 
 while True:
 
-    read_value = pcf.analog_read(channel_a)
-    scaled_value = (read_value / 255) * VOLTAGE_LEVEL
+    print("Setting out to ", 65535)
+    pcf_out.value = 65535
+    raw_value = pcf_in_0.value
+    scaled_value = (raw_value / 65535) * pcf_in_0.reference_voltage
 
-    print("Channel: %d %0.2fV" % (channel_a, scaled_value))
+    print("Pin 0: %0.2fV" % (scaled_value))
     print("")
-    time.sleep(0.1)
+    time.sleep(1)
+
+    print("Setting out to ", 32767)
+    pcf_out.value = 32767
+    raw_value = pcf_in_0.value
+    scaled_value = (raw_value / 65535) * pcf_in_0.reference_voltage
+
+    print("Pin 0: %0.2fV" % (scaled_value))
+    print("")
+    time.sleep(1)
 
-    read_value = pcf.analog_read(channel_b)
-    scaled_value = (read_value / 255) * VOLTAGE_LEVEL
+    print("Setting out to ", 0)
+    pcf_out.value = 0
+    raw_value = pcf_in_0.value
+    scaled_value = (raw_value / 65535) * pcf_in_0.reference_voltage
 
-    print("Channel: %d %0.2fV" % (channel_b, scaled_value))
+    print("Pin 0: %0.2fV" % (scaled_value))
     print("")
-    print("*" * 20)
     time.sleep(1)