hint at a stale Bluetooth serial port if the machine does not respond

On macOS a Bluetooth serial port can survive a system suspension as a stale
device: /dev/cu.<machine> still exists and opens successfully, but there is no
serial connection behind it any longer, so nothing is sent or received. The
connect loop then repeats "connection timeout" forever while the user is left
with empty readings and no indication of what to do. The port can only be
re-established by removing the machine in the system Bluetooth settings and
pairing it again (neither toggling Bluetooth nor reconnecting the device
rebuilds it, and the Bluetooth daemon cannot be restarted under SIP).

- counts the connect attempts of the Kaleido serial transport that opened the
  port but received no response from the machine and, after three of them,
  logs a hint and reports it to the user via the new unresponsive_handler
- the hint is raised only once per unresponsive phase and re-armed by a
  successful connect, so a machine that is simply switched off does not repeat
  the message on every reconnect attempt

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: edwin-truthsearch-io

src/artisanlib/canvas.py

@@ -13042,7 +13042,8 @@ def OnMonitor(self) -> None:
                     self.aw.kaleido.start(self.mode, self.aw.kaleidoHost, self.aw.kaleidoPort,
                         serial=kaleido_serial,
                         connected_handler=lambda : self.aw.sendmessageSignal.emit(QApplication.translate('Message', '{} connected').format('Kaleido'),True,None),
-                        disconnected_handler=lambda : self.aw.sendmessageSignal.emit(QApplication.translate('Message', '{} disconnected').format('Kaleido'),True,None))
+                        disconnected_handler=lambda : self.aw.sendmessageSignal.emit(QApplication.translate('Message', '{} disconnected').format('Kaleido'),True,None),
+                        unresponsive_handler=lambda : self.aw.sendmessageSignal.emit(QApplication.translate('Message', '{} does not respond. If connected via Bluetooth, remove the machine in the system Bluetooth settings and pair it again.').format('Kaleido'),True,None))
                 elif self.device == 142:
                     try:
                         from artisanlib.ikawa import IKAWA_BLE

src/artisanlib/kaleido.py

@@ -61,7 +61,7 @@ class KaleidoPort:
 
     __slots__ = [ '_asyncLoopThread', '_write_queue', '_running', '_default_data_stream', '_ping_timeout', '_open_timeout', '_init_timeout',
             '_send_timeout', '_read_timeout', '_ping_retry_delay', '_reconnect_delay', 'send_button_timeout', '_single_await_var_prefix',
-            '_state', '_pending_requests', '_logging' ]
+            '_state', '_pending_requests', '_logging', '_unresponsive_connects', '_unresponsive_hint_after' ]
 
     def __init__(self) -> None:
         # internals
@@ -78,6 +78,15 @@ def __init__(self) -> None:
         self._ping_retry_delay:Final[float] = 1  # in seconds
         self._reconnect_delay:Final[float] = 0.5 # in seconds
 
+        # counts the connect attempts that opened the port, but never received a response from the
+        # machine. On macOS a Bluetooth serial port can be left behind by a system suspension: the
+        # /dev/cu.* device still exists and opens successfully, but there is no serial connection
+        # behind it any longer and thus data is neither sent nor received. As this is
+        # indistinguishable from a machine that is turned off, we hint at it only after a couple of
+        # such attempts (see the unresponsive_handler of serial_connect)
+        self._unresponsive_connects:int = 0
+        self._unresponsive_hint_after:Final[int] = 3
+
         self.send_button_timeout:Final[float] = 1.2  # in seconds
 
         # _state holds the last received data of the corresponding var for known all tags
@@ -439,9 +448,21 @@ async def serial_initialize(self, reader: asyncio.StreamReader, writer: asyncio.
         except TimeoutError:
             _log.debug('SC AR timeout')
 
+    # registers a connect attempt that opened the port, but received no response from the machine.
+    # Returns True exactly once per unresponsive phase, on reaching _unresponsive_hint_after, to
+    # trigger the hint only once and not on every reconnect attempt
+    def register_unresponsive_connect(self) -> bool:
+        self._unresponsive_connects += 1
+        return self._unresponsive_connects == self._unresponsive_hint_after
+
+    # called on a successful connect to re-arm the hint for the next unresponsive phase
+    def reset_unresponsive_connects(self) -> None:
+        self._unresponsive_connects = 0
+
     async def serial_connect(self, mode:str, serial:SerialSettings,
                 connected_handler:Callable[[], None]|None = None,
-                disconnected_handler:Callable[[], None]|None = None) -> None:
+                disconnected_handler:Callable[[], None]|None = None,
+                unresponsive_handler:Callable[[], None]|None = None) -> None:
 
         writer:asyncio.StreamWriter|None = None
         while self._running:
@@ -463,6 +484,7 @@ async def serial_connect(self, mode:str, serial:SerialSettings,
                     await asyncio.wait_for(self.serial_initialize(reader, writer, mode), timeout=self._init_timeout)
 
                     _log.debug('connected')
+                    self.reset_unresponsive_connects()
                     if connected_handler is not None:
                         try:
                             connected_handler()
@@ -483,6 +505,16 @@ async def serial_connect(self, mode:str, serial:SerialSettings,
                             raise exception
             except TimeoutError:
                 _log.debug('connection timeout')
+                if self.register_unresponsive_connect():
+                    _log.warning('%s opens, but the machine does not respond. If the machine is '
+                            'connected via Bluetooth, the serial port might be stale and has to be '
+                            're-established by removing the machine in the system Bluetooth '
+                            'settings and pairing it again', serial['port'])
+                    if unresponsive_handler is not None:
+                        try:
+                            unresponsive_handler()
+                        except Exception as e: # pylint: disable=broad-except
+                            _log.exception(e)
             except Exception as e: # pylint: disable=broad-except
                 _log.error(e)
             finally:
@@ -613,11 +645,13 @@ def markTP(self) -> None:
     def start(self, mode:str, host:str = '127.0.0.1', port:int = 80, path:str = 'ws',
                 serial:SerialSettings|None = None,
                 connected_handler:Callable[[], None]|None = None,
-                disconnected_handler:Callable[[], None]|None = None) -> None:
+                disconnected_handler:Callable[[], None]|None = None,
+                unresponsive_handler:Callable[[], None]|None = None) -> None:
         try:
             # initialize data structures
             self._state = {}
             self._pending_requests = {}
+            self.reset_unresponsive_connects()
 
             _log.debug('start sampling')
             if self._asyncLoopThread is None:
@@ -630,7 +664,7 @@ def start(self, mode:str, host:str = '127.0.0.1', port:int = 80, path:str = 'ws'
                     connected_handler, disconnected_handler)
             else:
                 coro = self.serial_connect(mode, serial,
-                    connected_handler, disconnected_handler)
+                    connected_handler, disconnected_handler, unresponsive_handler)
             asyncio.run_coroutine_threadsafe(coro, self._asyncLoopThread.loop)
         except Exception as e:  # pylint: disable=broad-except
             _log.exception(e)

src/test/unitary/artisanlib/test_kaleido.py

@@ -726,3 +726,55 @@ def test_kaleido_methods_from_source_inspection(self) -> None:
 #        # Test Heater/Fan retrieval (converts int to float)
 #        result = get_heater_fan_values(75, 50)
 #        assert result == (75.0, 50.0)
+
+
+class TestKaleidoUnresponsiveConnect:
+    """Test the hint raised when the serial port opens but the machine never responds.
+
+    On macOS a Bluetooth serial port survives a system suspension as a stale device: it still
+    opens successfully while no data passes any longer. The hint is raised after a couple of such
+    connect attempts and only once per unresponsive phase.
+    """
+
+    def test_hint_is_raised_after_the_configured_number_of_attempts(self) -> None:
+        from artisanlib.kaleido import KaleidoPort
+
+        kaleido = KaleidoPort()
+        attempts = kaleido._unresponsive_hint_after
+        results = [kaleido.register_unresponsive_connect() for _ in range(attempts)]
+        assert results[:-1] == [False] * (attempts - 1)
+        assert results[-1] is True
+
+    def test_hint_is_raised_only_once(self) -> None:
+        from artisanlib.kaleido import KaleidoPort
+
+        kaleido = KaleidoPort()
+        for _ in range(kaleido._unresponsive_hint_after):
+            kaleido.register_unresponsive_connect()
+        # further failing attempts must not repeat the hint on every reconnect
+        assert not any(kaleido.register_unresponsive_connect() for _ in range(10))
+
+    def test_a_successful_connect_rearms_the_hint(self) -> None:
+        from artisanlib.kaleido import KaleidoPort
+
+        kaleido = KaleidoPort()
+        attempts = kaleido._unresponsive_hint_after
+        for _ in range(attempts):
+            kaleido.register_unresponsive_connect()
+        kaleido.reset_unresponsive_connects()
+        results = [kaleido.register_unresponsive_connect() for _ in range(attempts)]
+        assert results[-1] is True
+
+    def test_start_rearms_the_hint(self) -> None:
+        """start() resets the counter such that a new session reports an unresponsive machine."""
+        from unittest.mock import patch
+
+        from artisanlib.kaleido import KaleidoPort
+
+        kaleido = KaleidoPort()
+        for _ in range(kaleido._unresponsive_hint_after):
+            kaleido.register_unresponsive_connect()
+        with patch('artisanlib.kaleido.AsyncLoopThread'), patch('asyncio.run_coroutine_threadsafe'):
+            kaleido.start('C', serial=None)
+        assert kaleido._unresponsive_connects == 0
+        kaleido.stop()

wiki/ReleaseHistory.md

@@ -22,6 +22,7 @@ v4.2.2
   - faster app start (startup time redued by ~50%)
   - refreshed UI
 * FIXES
+  - reports a hint if the serial port of a Kaleido machine opens, but the machine does not respond, as a Bluetooth serial port can be left behind stale by a system suspension on macOS ([Issue #2226](../../../issues/2226))
   - fixes faulty hash generation on files created using `Save As` causing `modified file` warnings on load ([Issue #2205](../../../issues/2205))
   - fixes regression causing canvas color not being applied correctly ([Issue #2212](../../../issues/2212))