Ready for release

Author: siddacious

README.rst

@@ -22,7 +22,6 @@ This driver depends on:
 
 * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
 * `Bus Device <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
-* `Register <https://github.com/adafruit/Adafruit_CircuitPython_Register>`_
 
 Please ensure all dependencies are available on the CircuitPython filesystem.
 This is easily achieved by downloading
@@ -56,7 +55,23 @@ To install in a virtual environment in your current project:
 Usage Example
 =============
 
-.. todo:: Add a quick, simple example. It and other examples should live in the examples folder and be included in docs/examples.rst.
+.. code-block:: python3
+
+    import board
+    import busio
+    import adafruit_mcp4728
+
+    i2c = busio.I2C(board.SCL, board.SDA)
+    mcp4728 =  adafruit_mcp4728.MCP4728(i2c)
+
+    mcp4728.channel_a.value = 65535 # Voltage = VDD
+    mcp4728.channel_b.value = int(65535/2) # VDD/2
+    mcp4728.channel_c.value = int(65535/4) # VDD/4
+
+    mcp4728.channel_d.value = int(65535/4) # Vref.INTERNAL/4 * 2 => 2.048/4 * 2 = 2.048/2 =  ~ 1.024V
+
+
+    mcp4728.save_settings() # save the current values to the eeprom,making them the default on power up
 
 Contributing
 ============

adafruit_mcp4728.py

@@ -48,21 +48,9 @@
 from struct import pack_into
 from time import sleep
 import adafruit_bus_device.i2c_device as i2c_device
-from adafruit_register.i2c_struct import UnaryStruct
-import traceback
 
 _MCP4728_DEFAULT_ADDRESS = 0x60
 
-_MCP4728_CH_A_MULTI_IB = 0x40
-_MCP4728_CH_B_MULTI_IB = 0x42
-_MCP4728_CH_C_MULTI_IB = 0x44
-_MCP4728_CH_D_MULTI_IB = 0x46
-
-_MCP4728_CH_A_SINGLE_EEPROM = 0x58
-_MCP4728_CH_B_SINGLE_EEPROM = 0x5A
-_MCP4728_CH_C_SINGLE_EEPROM = 0x5C
-_MCP4728_CH_D_SINGLE_EEPROM = 0x5E
-
 _MCP4728_CH_A_MULTI_EEPROM = 0x50
 
 class CV:
@@ -101,68 +89,49 @@ class MCP4728:
         :param address: The I2C slave address of the sensor
 
     """
-    _channel_a_single_write_eeprom = UnaryStruct(_MCP4728_CH_A_SINGLE_EEPROM, ">H")
-    _channel_b_single_write_eeprom = UnaryStruct(_MCP4728_CH_B_SINGLE_EEPROM, ">H")
-    _channel_c_single_write_eeprom = UnaryStruct(_MCP4728_CH_C_SINGLE_EEPROM, ">H")
-    _channel_d_single_write_eeprom = UnaryStruct(_MCP4728_CH_D_SINGLE_EEPROM, ">H")
-
-    _channel_a_multi_write = UnaryStruct(_MCP4728_CH_A_MULTI_IB, ">H")
-    _channel_b_multi_write = UnaryStruct(_MCP4728_CH_B_MULTI_IB, ">H")
-    _channel_c_multi_write = UnaryStruct(_MCP4728_CH_C_MULTI_IB, ">H")
-    _channel_d_multi_write = UnaryStruct(_MCP4728_CH_D_MULTI_IB, ">H")
-
-    _multi_write_channel_a_start = UnaryStruct(_MCP4728_CH_A_MULTI_EEPROM, ">HHHH")
 
     def __init__(self, i2c_bus, address=_MCP4728_DEFAULT_ADDRESS):
 
         self.i2c_device = i2c_device.I2CDevice(i2c_bus, address)
-        
+
         raw_registers = self._read_registers()
 
         self.channel_a = Channel(self, self._cache_page(*raw_registers[0]), 0)
         self.channel_b = Channel(self, self._cache_page(*raw_registers[1]), 1)
         self.channel_c = Channel(self, self._cache_page(*raw_registers[2]), 2)
         self.channel_d = Channel(self, self._cache_page(*raw_registers[3]), 3)
 
-    def _get_flags(self, high_byte):
+    @staticmethod
+    def _get_flags(high_byte):
         vref = (high_byte & 1<<7) > 0
         gain = (high_byte & 1<<4) > 0
-        pd = (high_byte & 0b011<<5)>>5
-        return (vref, gain, pd)
+        power_state = (high_byte & 0b011<<5)>>5
+        return (vref, gain, power_state)
 
-    def _cache_page(self, value, vref, gain, pd):
-        return {"value": value, "vref": vref, "gain": gain, "pd": pd}
+    @staticmethod
+    def _cache_page(value, vref, gain, power_state):
+        return {"value": value, "vref": vref, "gain": gain, "power_state": power_state}
 
     def _read_registers(self):
         buf = bytearray(24)
 
         with self.i2c_device as i2c:
             i2c.readinto(buf)
 
-        self._print_buffer(buf)
-
         # stride is 6 because we get 6 bytes for each channel; 3 for the output regs
-        # and 3 for the eeprom. here we only care about the output buffer so we throw out
+        # and 3 for the eeprom. Here we only care about the output regoster so we throw out
         # the eeprom values as 'n/a'
         current_values = []
-        for header, high_byte, low_byte, na_1, na_2, na_3 in self._chunk(buf, 6):
+        for header, high_byte, low_byte, na_1, na_2, na_3 in self._chunk(buf, 6):#pylint:disable=unused-variable
             value = (high_byte & 0b00001111) << 8 | low_byte
-            vref, gain, pd = self._get_flags(high_byte)
-            current_values.append((value, vref, gain, pd))
+            vref, gain, power_state = self._get_flags(high_byte)
+            current_values.append((value, vref, gain, power_state))
 
         return current_values
 
-    def _print_buffer(self, buf):
-        print()
-        for index, value in enumerate(buf):
-            if index %3 == 0:
-                print("\n%4s\t"%index, end="")
-            print("%s %s "%(format(value, '#010b'), hex(value)), end="")
-        print()
-
-
     def save_settings(self):
-        """Saves the currently selected values, Vref, and gain selections for each channel to the EEPROM, setting them as defaults on power up"""
+        """Saves the currently selected values, Vref, and gain selections for each channel
+           to the EEPROM, setting them as defaults on power up"""
         byte_list = []
         byte_list += self._generate_bytes_with_flags(self.channel_a)
         byte_list += self._generate_bytes_with_flags(self.channel_b)
@@ -176,48 +145,36 @@ def _write_multi_eeprom(self, byte_list):
         buffer_list += byte_list
 
         buf = bytearray(buffer_list)
-        self._print_buffer(buf)
+
         with self.i2c_device as i2c:
             i2c.write(buf)
 
         sleep(0.015) # the better to write you with
 
-    def _sync_vrefs(self):
-        base_values = 0b10000000
-        base_values |= (self.channel_a.vref<<3)
-        base_values |= (self.channel_b.vref<<2)
-        base_values |= (self.channel_c.vref<<1)
-        base_values |= (self.channel_d.vref)
-        
-        print("vref values:")
-        print(base_values)
-        print(self._lzb(base_values))
+    def sync_vrefs(self):
+        """Syncs the driver's vref state with the DAC"""
+        gain_setter_command = 0b10000000
+        gain_setter_command |= (self.channel_a.vref<<3)
+        gain_setter_command |= (self.channel_b.vref<<2)
+        gain_setter_command |= (self.channel_c.vref<<1)
+        gain_setter_command |= (self.channel_d.vref)
 
         buf = bytearray(1)
-        pack_into(">B", buf, 0, base_values)        
-        print("buf bytes:")
-        self._print_buffer(buf)
+        pack_into(">B", buf, 0, gain_setter_command)
         with self.i2c_device as i2c:
             i2c.write(buf)
 
-    def _sync_gains(self):
-        # [S] 1 1 0 0 A2 A1 A0 0 
-        # [A] 1 1 0 X GXA GXB GXC GXD [A] [P]
-        base_values = 0b11000000
-        base_values |= (self.channel_a.gain<<3)
-        base_values |= (self.channel_b.gain<<2)
-        base_values |= (self.channel_c.gain<<1)
-        base_values |= (self.channel_d.gain)
-
+    def sync_gains(self):
+        """Syncs the driver's gain state with the DAC"""
 
-        print("gain values:")
-        print(base_values)
-        print(self._lzb(base_values))
+        sync_setter_command = 0b11000000
+        sync_setter_command |= (self.channel_a.gain<<3)
+        sync_setter_command |= (self.channel_b.gain<<2)
+        sync_setter_command |= (self.channel_c.gain<<1)
+        sync_setter_command |= (self.channel_d.gain)
 
         buf = bytearray(1)
-        pack_into(">B", buf, 0, base_values)        
-        print("buf bytes:")
-        self._print_buffer(buf)
+        pack_into(">B", buf, 0, sync_setter_command)
 
         with self.i2c_device as i2c:
             i2c.write(buf)
@@ -227,14 +184,15 @@ def _set_value(self, channel):
         channel_bytes = self._generate_bytes_with_flags(channel)
 
         write_command_byte = 0b01000000 # 0 1 0 0 0 DAC1 DAC0 UDAC
-        write_command_byte |= (channel._channel_index<<1)
+        write_command_byte |= (channel.channel_index<<1)
 
         channel_bytes.insert(0, write_command_byte)
 
         with self.i2c_device as i2c:
             i2c.write(bytearray(channel_bytes))
 
-    def _generate_bytes_with_flags(self, channel):
+    @staticmethod
+    def _generate_bytes_with_flags(channel):
         buf = bytearray(2)
         pack_into(">H", buf, 0, channel.raw_value)
 
@@ -243,25 +201,22 @@ def _generate_bytes_with_flags(self, channel):
 
         return buf
 
-    def _chunk(self, l, n):
-        # For item i in a range that is a length of l,
-        for i in range(0, len(l), n):
-            # Create an index range for l of n items:
-            yield l[i:i+n]
-
-    def _lzb(self, byte_val): # leading zero bin
-        return format(byte_val, '#010b')
-    def _bt(self):
-        for line in traceback.format_stack():
-            print(line.strip())
+    @staticmethod
+    def _chunk(big_list, chunk_size):
+        """Divides a given list into `chunk_size` sized chunks"""
+        for i in range(0, len(big_list), chunk_size):
+            yield big_list[i:i+chunk_size]
+
 class Channel:
-    """An instance of a single channel for a multi-channel DAC"""
+    """An instance of a single channel for a multi-channel DAC.
+
+    **All available channels are created automatically and should not be created by the user**"""
     def __init__(self, dac_instance, cache_page, index):
         self._vref = cache_page['vref']
         self._gain = cache_page['gain']
         self._raw_value = cache_page['value']
         self._dac = dac_instance
-        self._channel_index = index
+        self.channel_index = index
 
     @property
     def normalized_value(self):
@@ -299,19 +254,25 @@ def raw_value(self, value):
         if value < 0 or value > (2**12-1):
             raise AttributeError("`raw_value` must be a 12-bit integer between 0 and %s"%(2**12-1))
         self._raw_value = value
-        self._dac._set_value(self)
+        # disabling the protected access warning here because making it public would be
+        # more confusing
+        self._dac._set_value(self) #pylint:disable=protected-access
 
     @property
     def gain(self):
-        """Sets the gain of the channel if the Vref for the channel is ``Vref.INTERNAL``. *The gain setting has no effect if the Vref for the channel is `Vref.VDD`*. With gain set to 1, the output voltage goes from 0v to 2.048V. If a channe's gain is set to 2, the voltage goes from 0v to 4.096V. `gain` Must be 1 or 2"""
+        """Sets the gain of the channel if the Vref for the channel is ``Vref.INTERNAL``.
+        **The gain setting has no effect if the Vref for the channel is `Vref.VDD`**.
+
+        With gain set to 1, the output voltage goes from 0v to 2.048V. If a channe's gain is set
+        to 2, the voltage goes from 0v to 4.096V. `gain` Must be 1 or 2"""
         return self._gain
 
     @gain.setter
     def gain(self, value):
-        if value != 1 and value != 2:
+        if not value in (1, 2):
             raise AttributeError("`gain` must be 1 or 2")
         self._gain = value-1
-        self._dac._sync_gains()
+        self._dac.sync_gains()
 
     @property
     def vref(self):
@@ -323,4 +284,4 @@ def vref(self, value):
         if not Vref.is_valid(value):
             raise AttributeError("range must be a `Vref`")
         self._vref = value
-        self._dac._sync_vrefs()
+        self._dac.sync_vrefs()

docs/conf.py

@@ -20,7 +20,7 @@
 # Uncomment the below if you use native CircuitPython modules such as
 # digitalio, micropython and busio. List the modules you use. Without it, the
 # autodoc module docs will fail to generate with a warning.
-autodoc_mock_imports = ["adafruit_register", "adafruit_bus_device"]
+autodoc_mock_imports = ["adafruit_bus_device"]
 
 
 

docs/index.rst

@@ -23,14 +23,11 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
-.. todo:: Add any Learn guide links here. If there are none, then simply delete this todo and leave
-    the toctree above for use later.
-
 .. toctree::
     :caption: Related Products
 
-.. todo:: Add any product links here. If there are none, then simply delete this todo and leave
-    the toctree above for use later.
+    Adafruit MCP4728 Breakout <https://www.adafruit.com/product/44xx>
+
 
 .. toctree::
     :caption: Other Links

examples/mcp4728_full_test.py

@@ -0,0 +1,45 @@
+import board
+import busio
+import adafruit_mcp4728
+
+i2c = busio.I2C(board.SCL, board.SDA)
+mcp4728 =  adafruit_mcp4728.MCP4728(i2c)
+
+#pylint:disable=no-member
+mcp4728.channel_a.vref = adafruit_mcp4728.Vref.VDD # sets the channel to scale between 0v and VDD
+mcp4728.channel_b.vref = adafruit_mcp4728.Vref.VDD
+mcp4728.channel_c.vref = adafruit_mcp4728.Vref.VDD
+mcp4728.channel_d.vref = adafruit_mcp4728.Vref.INTERNAL # scales between 0v and 2.048v
+
+mcp4728.channel_a.gain = 1
+mcp4728.channel_b.gain = 1
+mcp4728.channel_c.gain = 1
+
+# changes the gain to 2 so the channel now scales between 0v and 4.098V (2 x Internal Vref)
+mcp4728.channel_d.gain = 2
+
+
+mcp4728.channel_a.value = 65535 # Voltage = VDD
+mcp4728.channel_b.value = int(65535/2) # VDD/2
+mcp4728.channel_c.value = int(65535/4) # VDD/4
+
+mcp4728.channel_d.value = int(65535/4) # Vref.INTERNAL/4 * 2 => 2.048/4 * 2 = 2.048/2 =  ~ 1.024V
+
+print("cha value:", mcp4728.channel_a.value)
+print("chb value:", mcp4728.channel_b.value)
+print("chc value:", mcp4728.channel_c.value)
+print("chd value:", mcp4728.channel_d.value)
+print()
+
+print("cha gain:", mcp4728.channel_a.gain)
+print("chb gain:", mcp4728.channel_b.gain)
+print("chc gain:", mcp4728.channel_c.gain)
+print("chd gain:", mcp4728.channel_d.gain)
+print()
+print("cha vref:", mcp4728.channel_a.vref)
+print("chb vref:", mcp4728.channel_b.vref)
+print("chc vref:", mcp4728.channel_c.vref)
+print("chd vref:", mcp4728.channel_d.vref)
+
+
+mcp4728.save_settings()