fix: broken blink implementation and documentation

Author: JnyJny

busylight/lights/muteme/muteme.py

@@ -44,9 +44,37 @@ def blink(self, color: ColorTuple, blink: Speed = Speed.Slow) -> None:
         super().blink(color, blink)
         with self.batch_update():
             self.command.color = color
-            self.command.blink = blink.value & 0x2
+            if blink in [Speed.Slow, Speed.Medium]:
+                self.command.blink = 2
+            if blink in [Speed.Fast]:
+                self.command.blink = 1
 
-    @property
-    def touch(self) -> int:
-        """ """
-        raise NotImplementedError("touch")
+    def touch(self, timeout: int = 100) -> bool:
+        """Returns the current state of the touch surface."""
+
+        # EJO this is a hack constructed from observing that
+        #     consecutive reads from the device while touched can be:
+        #
+        #     a = [0, 0, 0, 1]
+        #     b = [0, 0, 0, 0]
+        #
+        #     Sometimes the order is reversed where b contains the
+        #     actual touch status in the final byte. If we sum each of
+        #     the items in both arrays we should arrive at a valid
+        #     touch status in the final byte regardless of how the
+        #     device was polled. This behavior will probably need to
+        #     be controlled, hopefully the device release_number will
+        #     provide the necessary information to differentiate
+        #     devices that might need different polling strategies.
+        #
+
+        first = self.read_strategy(4, timeout)
+        second = self.read_strategy(4, timeout)
+
+        result = [f + s for f, s in zip(first, second)]
+
+        try:
+            return result[-1] == 1
+        except IndexError:
+            pass
+        return False

busylight/lights/muteme/muteme_impl.py

@@ -61,9 +61,10 @@ def __init__(self):
         self.default = self.value
 
     header = Header(8, 8)
+    # bit 7 unused?
 
-    sleep = SleepField(7, 1)
-    blink = BlinkField(5, 2)
+    sleep = SleepField(6, 1)
+    _blink = BlinkField(5, 1)
     dim = DimField(4, 1)
 
     reserved = ReservedField(3, 1)
@@ -95,3 +96,19 @@ def firmware_update(self) -> bool:
     def firmware_update(self, value: bool) -> None:
         self.reserved = int(bool(value))
         self.red = int(bool(value))
+
+    @property
+    def blink(self) -> int:
+        if self._blink:
+            return self._blink + self.dim
+        return 0
+
+    @blink.setter
+    def blink(self, value: int) -> None:
+        if value == 0:
+            self._blink = 0
+        if value == 1:
+            self._blink = 1
+        if value == 2:
+            self._blink = 1
+            self.dim = 1

docs/devices/muteme.md

@@ -58,7 +58,8 @@ typedef struct {
   unsigned int header:8;   /* 08:15 Constant: 0x00 */
 
   unsigned int sleep:1;    /* 07:07 Initiates a ten second sleep mode */
-  unsigned int blink:2;	   /* 05:06 Blink: off=00 slow=01, fast=10 */
+  unsgined int pad0:1;
+  unsigned int blink:1;	   /* 05:05 Blink */
   unsigned int dim:1;	   /* 04:04 Set is dim, cleared is bright*/
   unsigned int reserved:1; /* 03:03 Reserved for future use. */
   unsigned int blue:1;	   /* 02:02 Set is full value blue */
@@ -107,13 +108,9 @@ bright operation when `dim` is cleared.
 
 ### Blink Mode
 
-The light can be made to blink at two different speeds by setting the
-`blink` field. Valid blink values are:
-
-- 0b00 off
-- 0b01 slow
-- 0b10 unused state
-- 0b11 fast
+The light can blink at two different speeds: slow and fast.
+Fast blink is indicated by setting blink and clearing dim.
+Slow blink is indicated by setting blink and setting dim.
 
 ## Observations