Merge pull request #7 from rpavlik/slim-lut

Slim lut

Author: caternuson

adafruit_emc2101/__init__.py

@@ -21,9 +21,8 @@
 
 * Adafruit CircuitPython firmware for the supported boards:
   https://github.com/adafruit/circuitpython/releases
-
-# * Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
-# * Adafruit's Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register
+* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
+* Adafruit's Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register
 """
 
 from micropython import const
@@ -64,7 +63,7 @@ class CV:
 
     @classmethod
     def add_values(cls, value_tuples):
-        "creates CV entires"
+        "creates CV entries"
         cls.string = {}
         cls.lsb = {}
 
@@ -133,20 +132,28 @@ class SpinupTime(CV):
 
 
 class EMC2101:  # pylint: disable=too-many-instance-attributes
-    """Driver for the EMC2101 Fan Controller.
+    """Basic driver for the EMC2101 Fan Controller.
+
     :param ~busio.I2C i2c_bus: The I2C bus the EMC is connected to.
+
+    If you need control over PWM frequency and the controller's built in temperature/speed
+    look-up table (LUT), you will need :class:`emc2101_lut.EMC2101_LUT` which extends this
+    class to add those features, at the cost of increased memory usage.
     """
 
     _part_id = ROUnaryStruct(_REG_PARTID, "<B")
     _mfg_id = ROUnaryStruct(_REG_MFGID, "<B")
     _int_temp = ROUnaryStruct(_INTERNAL_TEMP, "<b")
 
+    # Some of these registers are defined as two halves because
+    # the chip does not support multi-byte reads or writes, and there
+    # is currently no way to tell Struct to do a transaction for each byte.
+
     # IMPORTANT! the sign bit for the external temp is in the msbyte so mark it as signed
     # and lsb as unsigned
     _ext_temp_msb = ROUnaryStruct(_EXTERNAL_TEMP_MSB, "<b")
     _ext_temp_lsb = ROUnaryStruct(_EXTERNAL_TEMP_LSB, "<B")
 
-    # _tach_read = ROUnaryStruct(_TACH_LSB, "<H")
     _tach_read_lsb = ROUnaryStruct(_TACH_LSB, "<B")
     _tach_read_msb = ROUnaryStruct(_TACH_MSB, "<B")
     _tach_mode_enable = RWBit(_REG_CONFIG, 2)
@@ -225,7 +232,7 @@ def manual_fan_speed(self):
     @manual_fan_speed.setter
     def manual_fan_speed(self, fan_speed):
         if fan_speed not in range(0, 101):
-            raise AttributeError("manual_fan_speed must be from 0-100 ")
+            raise AttributeError("manual_fan_speed must be from 0-100")
 
         # convert from a percentage to an lsb value
         percentage = fan_speed / 100.0
@@ -238,7 +245,12 @@ def manual_fan_speed(self, fan_speed):
     @property
     def lut_enabled(self):
         """Enable or disable the internal look up table used to map a given temperature
-        to a fan speed. When the LUT is disabled fan speed can be changed with `manual_fan_speed`"""
+        to a fan speed.
+
+        When the LUT is disabled (the default), fan speed can be changed with `manual_fan_speed`.
+        To actually set this to True and modify the LUT, you need to use the extended version of
+        this driver, :class:`emc2101_lut.EMC2101_LUT`
+        """
         return not self._fan_lut_prog
 
     @property

adafruit_emc2101/emc2101_lut.py

@@ -8,7 +8,7 @@
 Brushless fan controller: extended functionality
 
 
-* Author(s): Bryan Siepert
+* Author(s): Bryan Siepert, Ryan Pavlik
 
 Implementation Notes
 --------------------
@@ -22,15 +22,16 @@
 * Adafruit CircuitPython firmware for the supported boards:
   https://github.com/adafruit/circuitpython/releases
 
-# * Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
-# * Adafruit's Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register
+* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
+* Adafruit's Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register
 
-The class defined here may be used instead of adafruit_emc2101.EMC2101,
+The class defined here may be used instead of :class:`adafruit_emc2101.EMC2101`,
 if your device has enough RAM to support it. This class adds LUT control
 and PWM frequency control to the base feature set.
 """
 
 from micropython import const
+from adafruit_register.i2c_struct_array import StructArray
 from adafruit_register.i2c_struct import UnaryStruct
 from adafruit_register.i2c_bit import RWBit
 from adafruit_register.i2c_bits import RWBits
@@ -43,6 +44,7 @@
 _PWM_FREQ = const(0x4D)
 _PWM_DIV = const(0x4E)
 _LUT_HYSTERESIS = const(0x4F)
+_LUT_BASE = const(0x50)
 
 MAX_LUT_SPEED = 0x3F  # 6-bit value
 MAX_LUT_TEMP = 0x7F  # 7-bit
@@ -54,32 +56,16 @@ def _speed_to_lsb(percentage):
 
 class FanSpeedLUT:
     """A class used to provide a dict-like interface to the EMC2101's Temperature to Fan speed
-    Look Up Table"""
+    Look Up Table.
 
-    # seems like a pain but ¯\_(ツ)_/¯
-    _fan_lut_t1 = UnaryStruct(0x50, "<B")
-    _fan_lut_s1 = UnaryStruct(0x51, "<B")
+    Keys are integer temperatures, values are fan duty cycles between 0 and 100.
+    A max of 8 values may be stored.
 
-    _fan_lut_t2 = UnaryStruct(0x52, "<B")
-    _fan_lut_s2 = UnaryStruct(0x53, "<B")
-
-    _fan_lut_t3 = UnaryStruct(0x54, "<B")
-    _fan_lut_s3 = UnaryStruct(0x55, "<B")
-
-    _fan_lut_t4 = UnaryStruct(0x56, "<B")
-    _fan_lut_s4 = UnaryStruct(0x57, "<B")
-
-    _fan_lut_t5 = UnaryStruct(0x58, "<B")
-    _fan_lut_s5 = UnaryStruct(0x59, "<B")
-
-    _fan_lut_t6 = UnaryStruct(0x5A, "<B")
-    _fan_lut_s6 = UnaryStruct(0x5B, "<B")
-
-    _fan_lut_t7 = UnaryStruct(0x5C, "<B")
-    _fan_lut_s7 = UnaryStruct(0x5D, "<B")
+    To remove a single stored point in the LUT, assign it as `None`.
+    """
 
-    _fan_lut_t8 = UnaryStruct(0x5E, "<B")
-    _fan_lut_s8 = UnaryStruct(0x5F, "<B")
+    # 8 (Temperature, Speed) pairs in increasing order
+    _fan_lut = StructArray(_LUT_BASE, "<B", 16)
 
     def __init__(self, fan_obj):
         self.emc_fan = fan_obj
@@ -96,9 +82,14 @@ def __getitem__(self, index):
     def __setitem__(self, index, value):
         if not isinstance(index, int):
             raise IndexError
-        if value > 100.0 or value < 0:
+        if value is None:
+            # Assign None to remove this entry
+            del self.lut_values[index]
+        elif value > 100.0 or value < 0:
+            # Range check
             raise AttributeError("LUT values must be a fan speed from 0-100%")
-        self.lut_values[index] = value
+        else:
+            self.lut_values[index] = value
         self._update_lut()
 
     def __repr__(self):
@@ -108,7 +99,7 @@ def __repr__(self):
     def __str__(self):
         """return the official string representation of the LUT"""
         value_strs = []
-        lut_keys = list(sorted(self.lut_values.keys()))
+        lut_keys = tuple(sorted(self.lut_values.keys()))
         for temp in lut_keys:
             fan_drive = self.lut_values[temp]
             value_strs.append("%d deg C => %.1f%% duty cycle" % (temp, fan_drive))
@@ -137,18 +128,23 @@ def _update_lut(self):
         # get and sort the new lut keys so that we can assign them in order
         for idx, current_temp in enumerate(sorted(self.lut_values.keys())):
             current_speed = _speed_to_lsb(self.lut_values[current_temp])
-            setattr(self, "_fan_lut_t%d" % (idx + 1), current_temp)
-            setattr(self, "_fan_lut_s%d" % (idx + 1), current_speed)
+            self._set_lut_entry(idx, current_temp, current_speed)
 
         # Set the remaining LUT entries to the default (Temp/Speed = max value)
-        for idx in range(8)[len(self.lut_values) :]:
-            setattr(self, "_fan_lut_t%d" % (idx + 1), MAX_LUT_TEMP)
-            setattr(self, "_fan_lut_s%d" % (idx + 1), MAX_LUT_SPEED)
+        for idx in range(len(self.lut_values), 8):
+            self._set_lut_entry(idx, MAX_LUT_TEMP, MAX_LUT_SPEED)
         self.emc_fan.lut_enabled = current_mode
 
+    def _set_lut_entry(self, idx, temp, speed):
+        self._fan_lut[idx * 2] = bytearray((temp,))
+        self._fan_lut[idx * 2 + 1] = bytearray((speed,))
+
 
 class EMC2101_LUT(EMC2101):  # pylint: disable=too-many-instance-attributes
-    """Driver for the EMC2101 Fan Controller.
+    """Driver for the EMC2101 Fan Controller, with PWM frequency and LUT control.
+
+    See :class:`adafruit_emc2101.EMC2101` for the base/common functionality.
+
     :param ~busio.I2C i2c_bus: The I2C bus the EMC is connected to.
     """
 
@@ -234,5 +230,5 @@ def lut_enabled(self, enable_lut):
 
     @property
     def lut(self):
-        """The dict-like representation of the LUT"""
+        """The dict-like representation of the LUT, actually of type :class:`FanSpeedLUT`"""
         return self._lut

docs/examples.rst

@@ -11,6 +11,8 @@ LUT Usage Example
 -----------------
 
 Use the temperature to fan speed Look Up Table to automatically control the fan speed.
+This example requires more memory than the first one because it needs to use the extended
+:class:`adafruit_emc2101.emc2101_lut.EMC2101_LUT` driver to access LUT functionality.
 
 .. literalinclude:: ../examples/emc2101_lut_example.py
     :caption: examples/emc2101_lut_example.py
@@ -21,6 +23,8 @@ PWM Tuning
 -----------------
 
 Adjust the EMC2101s PWM settings to fit your application.
+This example requires more memory than the first one because it needs to use the extended
+:class:`adafruit_emc2101.emc2101_lut.EMC2101_LUT` driver to access LUT functionality.
 
 .. literalinclude:: ../examples/set_pwm_freq.py
     :caption: examples/set_pwm_freq.py

examples/emc2101_lut_example.py

@@ -27,6 +27,6 @@
 time.sleep(3)
 print("50%% duty cycle is %f RPM:" % emc.fan_speed)
 
-emc.forced_ext_temp = 43  # over 30, should be 50%
+emc.forced_ext_temp = 43  # over 42, should be 75%
 time.sleep(3)
 print("75%% duty cycle is %f RPM:" % emc.fan_speed)