keep the machine connection alive across system standby

A system standby tears down the USB/Bluetooth link to the machine. Machines
watching the communication (like Kaleido) react on that connection loss, on a
laptop typically towards the end of a roast when the user did not touch the
keyboard for a while.

- adds artisanlib/power.py with a SleepInhibitor preventing the idle system
  sleep while Artisan is ON (macOS: NSProcessInfo activity, which also disables
  App Nap and the timer coalescing that delays sampling while the display is
  off, with an IOKit power assertion as fallback; Windows:
  SetThreadExecutionState; Linux: systemd-inhibit). The display is still
  allowed to sleep.
- adds the 'Prevent Sleep' flag (default ON) to the Sampling dialog
- adds a WakeDetector recognizing system suspensions that cannot be inhibited
  (eg. a laptop closing its lid) and reconnects the machine on wake via the new
  AsyncComm.reconnect()/KaleidoPort.reconnect(), both sharing the new
  force_reconnect(), as a connection established before a suspension can be
  dead without the transport ever reporting an error
- reports a lost connection only once instead of on every failing reconnect
- logs the connection lifecycle (connect, connected, connection lost, timeout,
  serial exception) on the default log level to ease the analysis of connection
  issues

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

Author: edwin-truthsearch-io

src/artisanlib/async_comm.py

@@ -86,6 +86,23 @@ def loop(self) -> asyncio.AbstractEventLoop:
         return self.__loop
 
 
+# closes the given connection through the asyncio loop it is running in, to have the connect loop
+# of the corresponding transport re-establish it immediately.
+# Used on system wake as a connection that was established before a system suspension might be dead
+# without the transport ever reporting an error or EOF (thus without ever timing out).
+# Can be called from any thread. Returns True if a reconnect was triggered.
+def force_reconnect(loop_thread:AsyncLoopThread|None, writer:asyncio.StreamWriter|None) -> bool:
+    if loop_thread is None or writer is None:
+        return False
+    _log.info('reconnect requested')
+    try:
+        loop_thread.loop.call_soon_threadsafe(writer.close)
+        return True
+    except Exception as e: # pylint: disable=broad-except
+        _log.error(e)
+        return False
+
+
 class AsyncIterable:
 
     _queue: 'asyncio.Queue[bytes]' # type Queue is not subscriptable in Python <3.9 thus it is quoted
@@ -263,7 +280,7 @@ async def create_serial_connection(
 
 class AsyncComm:
 
-    __slots__ = [ '_asyncLoopThread', '_write_queue', '_running', '_serialize_write_lock', '_ACK_received', '_write_errors_without_disconnect', 'write_error_sem',
+    __slots__ = [ '_asyncLoopThread', '_write_queue', '_running', '_writer', '_serialize_write_lock', '_ACK_received', '_write_errors_without_disconnect', 'write_error_sem',
                     '_host', '_port', '_serial', '_connected_handler', '_disconnected_handler',
                     '_verify_crc', '_logging', '_send_timeout' ]
 
@@ -275,6 +292,7 @@ def __init__(self, host:str = '127.0.0.1', port:int = 8080, serial:'SerialSettin
         self._asyncLoopThread: AsyncLoopThread|None       = None # the asyncio AsyncLoopThread object
         self._write_queue:  asyncio.Queue[bytes]|None     = None # noqa: UP037 # quotes for Python3.8 # the write_queue
         self._running:bool                                = False              # while true we keep running the thread
+        self._writer: asyncio.StreamWriter|None           = None  # the writer of the currently established connection (if any)
 
         # lock to serialize write_await calls to realize request/response patterns in send_await/write_await
         self._serialize_write_lock:asyncio.Lock = asyncio.Lock()
@@ -406,7 +424,7 @@ async def connect(self, connect_timeout:float=5) -> None:
         while self._running:
             try:
                 if self._serial is not None:
-                    _log.debug('connecting to serial port: %s ...', self._serial['port'])
+                    _log.info('connecting to serial port: %s ...', self._serial['port'])
                     connect = self.open_serial_connection(
                         url = self._serial['port'],
                         baudrate = self._serial['baudrate'],
@@ -416,24 +434,25 @@ async def connect(self, connect_timeout:float=5) -> None:
                         timeout = self._serial['timeout'],
                         clear_HUPCL = self._serial['clear_HUPCL'])
                 else:
-                    _log.debug('connecting to %s:%s ...', self._host, self._port)
+                    _log.info('connecting to %s:%s ...', self._host, self._port)
                     connect = asyncio.open_connection(self._host, self._port)
                 # Wait for 2 seconds, then raise TimeoutError
                 reader, writer = await asyncio.wait_for(connect, timeout=connect_timeout)
                 if writer is not None: # pyright:ignore[reportUnnecessaryComparison] # reader is of type asyncio.streams.StreamReader and thus never None
                     self._write_queue = asyncio.Queue()
+                    self._writer = writer # registered to allow a forced reconnect (see reconnect())
                     write_handler = asyncio.create_task(self.handle_writes(writer, self._write_queue))
                     read_handler = asyncio.create_task(self.handle_reads(reader))
                     self._ACK_received = asyncio.Event()
-                    _log.debug('connected')
+                    _log.info('connected to %s', self._serial['port'] if self._serial is not None else f'{self._host}:{self._port}')
                     was_connected = True
                     if self._connected_handler is not None:
                         try:
                             self._connected_handler()
                         except Exception as e: # pylint: disable=broad-except
                             _log.exception(e)
                     done, pending = await asyncio.wait([read_handler, write_handler], return_when=asyncio.FIRST_COMPLETED)
-                    _log.debug('disconnected')
+                    _log.warning('connection lost')
 
                     for task in pending:
                         task.cancel()
@@ -452,20 +471,24 @@ async def connect(self, connect_timeout:float=5) -> None:
                     self._ACK_received = None
 
             except TimeoutError:
-                _log.debug('connection timeout')
-            except SerialException:
-                #_log.debug('serial exception: %s',e)
-                pass
+                _log.warning('connection timeout')
+            except SerialException as e:
+                _log.warning('serial exception: %s', e)
             except Exception as e: # pylint: disable=broad-except
                 _log.error('exception 1: %s', e)
             finally:
                 self._ACK_received = None
+                self._writer = None
                 self.reset_readings()
-                if was_connected and self._disconnected_handler is not None:
-                    try:
-                        self._disconnected_handler()
-                    except Exception as e: # pylint: disable=broad-except
-                        _log.error('exception 2: %s', e)
+                if was_connected:
+                    # only report a disconnect if a connection was established before to not
+                    # repeat the disconnect message on every failing reconnect attempt
+                    was_connected = False
+                    if self._disconnected_handler is not None:
+                        try:
+                            self._disconnected_handler()
+                        except Exception as e: # pylint: disable=broad-except
+                            _log.error('exception 2: %s', e)
                 if writer is not None:
                     try:
                         writer.close()
@@ -476,6 +499,11 @@ async def connect(self, connect_timeout:float=5) -> None:
                         _log.error('exception 3: %s', e)
             await asyncio.sleep(1)
 
+    # closes the current connection to have the connect loop re-establish it immediately
+    # (see force_reconnect())
+    def reconnect(self) -> bool:
+        return self._running and force_reconnect(self._asyncLoopThread, self._writer)
+
     def send(self, message:bytes) -> None:
         if self._asyncLoopThread is not None and self._write_queue is not None:
             asyncio.run_coroutine_threadsafe(self._write_queue.put(message), self._asyncLoopThread.loop)

src/artisanlib/canvas.py

@@ -54,6 +54,9 @@
 
 if TYPE_CHECKING:
     from artisanlib.comm import serialport # pylint: disable=unused-import
+    from artisanlib.power import SleepInhibitor, WakeDetector # pylint: disable=unused-import
+    from artisanlib.async_comm import AsyncComm # pylint: disable=unused-import
+    from artisanlib.kaleido import KaleidoPort # pylint: disable=unused-import
     from artisanlib.atypes import ProfileData, BTU # pylint: disable=unused-import
     from artisanlib.main import ApplicationWindow # pylint: disable=unused-import
     from plus.stock import Blend # pylint: disable=unused-import
@@ -126,6 +129,9 @@
 
 _log: Final[logging.Logger] = logging.getLogger(__name__)
 
+# interval in milliseconds in which Artisan checks for a system suspension while sampling
+_wake_check_interval: Final[int] = 5000
+
 
 
 type Interp1dKind = Literal['linear', 'nearest', 'nearest-up', 'zero', 'slinear', 'quadratic', 'cubic', 'previous', 'next']
@@ -287,7 +293,7 @@ class tgraphcanvas(QObject):
         'extraname1', 'extraname2', 'extramathexpression1', 'extramathexpression2', 'extralinestyles1', 'extralinestyles2', 'extradrawstyles1', 'extradrawstyles2',
         'extralinewidths1', 'extralinewidths2', 'extramarkers1', 'extramarkers2', 'extramarkersizes1', 'extramarkersizes2', 'devicetablecolumnwidths', 'energytablecolumnwidths', 'extraNoneTempHint1',
         'extraNoneTempHint2', 'plotcurves', 'plotcurvecolor', 'overlapList', 'tight_layout_params', 'cupping_tight_layout_params', 'fig', 'ax', 'delta_ax', 'legendloc', 'legendloc_pos', 'onclick_cid',
-        'oncpick_cid', 'ondraw_cid', 'onmove_cid', 'rateofchange1', 'rateofchange2', 'flagon', 'flagstart', 'flagKeepON', 'flagOpenCompleted', 'flagsampling', 'flagsamplingthreadrunning',
+        'oncpick_cid', 'ondraw_cid', 'onmove_cid', 'rateofchange1', 'rateofchange2', 'flagon', 'flagstart', 'flagKeepON', 'flagOpenCompleted', 'flagKeepAwake', 'sleep_inhibitor', 'wake_detector', 'wake_timer', 'flagsampling', 'flagsamplingthreadrunning',
         'manuallogETflag', 'zoom_follow', 'zoom_follow_onET', 'alignEvent', 'compareAlignEvent', 'compareEvents', 'compareET', 'compareBT', 'compareDeltaET', 'compareDeltaBT', 'compareMainEvents', 'compareBBP', 'compareRoast', 'compareExtraCurves1', 'compareExtraCurves2',
         'replayType', 'replayDropType', 'replayedBackgroundEvents', 'beepedBackgroundEvents', 'roastpropertiesflag', 'roastpropertiesAutoOpenFlag', 'roastpropertiesAutoOpenDropFlag',
         'title', 'title_show_always', 'ambientTemp', 'ambientTempSource', 'ambientHumiditySource', 'ambientPressureSource', 'ambient_temperature_device', 'ambient_pressure', 'ambient_pressure_device', 'ambient_humidity',
@@ -923,6 +929,10 @@ def __init__(self, parent:QWidget, dpi:int, locale:str, aw:'ApplicationWindow')
         self.flagstart:bool = False # Artisan logging/recording
         self.flagKeepON:bool = False # turn Artisan ON again after pressing OFF during recording
         self.flagOpenCompleted:bool = False # after completing a recording with OFF, send the saved profile to be opened in the ArtisanViewer
+        self.flagKeepAwake:bool = True # if True the computer is prevented from entering standby (idle system sleep) while Artisan is ON
+        self.sleep_inhibitor:SleepInhibitor|None = None # holds the system sleep inhibition while Artisan is ON (see flagKeepAwake)
+        self.wake_detector:WakeDetector|None = None # detects system suspensions while Artisan is ON to reconnect the machine on wake
+        self.wake_timer:QTimer|None = None # drives the wake_detector while Artisan is ON
         self.flagsampling:bool = False # if True, Artisan is still in the sampling phase and one has to wait for its end to turn OFF
         self.flagsamplingthreadrunning:bool = False
         #log flag that tells to log ET when using device 18 (manual mode)
@@ -12929,6 +12939,88 @@ def resetTimer(self) -> None:
             if self.samplingSemaphore.available() < 1:
                 self.samplingSemaphore.release(1)
 
+    # prevents the computer from entering standby (idle system sleep) while Artisan is sampling.
+    # A system sleep tears down the USB/Bluetooth link to the machine and machines watching the
+    # communication (like Kaleido) react on such a connection loss (eg. by starting to cool).
+    # NOTE: the display is still allowed to sleep, only the system has to stay awake. A laptop
+    #  closing its lid still sleeps (clamshell sleep) as this cannot be inhibited by an application.
+    def preventSleep(self) -> None:
+        if not self.flagKeepAwake:
+            return
+        try:
+            if self.sleep_inhibitor is None:
+                from artisanlib.power import SleepInhibitor
+                self.sleep_inhibitor = SleepInhibitor()
+            self.sleep_inhibitor.inhibit()
+        except Exception as e: # pylint: disable=broad-except
+            _log.exception(e)
+
+    # releases the system sleep inhibition acquired by preventSleep()
+    def allowSleep(self) -> None:
+        try:
+            if self.sleep_inhibitor is not None:
+                self.sleep_inhibitor.release()
+        except Exception as e: # pylint: disable=broad-except
+            _log.exception(e)
+
+    # a system suspension cannot be prevented in all cases (a laptop closing its lid or a user
+    # explicitly sending the machine to sleep). As a machine connection established before a
+    # suspension is dead afterwards, without the transport necessarily reporting an error or
+    # running into a timeout, we watch out for suspensions while sampling to reconnect on wake.
+    def startWakeDetection(self) -> None:
+        try:
+            if self.wake_detector is None:
+                from artisanlib.power import WakeDetector
+                self.wake_detector = WakeDetector()
+            self.wake_detector.start()
+            if self.wake_timer is None:
+                self.wake_timer = QTimer()
+                self.wake_timer.timeout.connect(self.checkWake)
+            self.wake_timer.start(_wake_check_interval)
+        except Exception as e: # pylint: disable=broad-except
+            _log.exception(e)
+
+    def stopWakeDetection(self) -> None:
+        try:
+            if self.wake_timer is not None:
+                self.wake_timer.stop()
+            if self.wake_detector is not None:
+                self.wake_detector.stop()
+        except Exception as e: # pylint: disable=broad-except
+            _log.exception(e)
+
+    @pyqtSlot()
+    def checkWake(self) -> None:
+        try:
+            if self.wake_detector is None:
+                return
+            suspension:float = self.wake_detector.check()
+            if suspension > 0:
+                _log.warning('system resumed after a suspension of %.0fs; reconnecting the machine '
+                        '(NOTE: the roast timer does not advance while the system is suspended)', suspension)
+                self.reconnectMachine()
+                self.aw.sendmessage(QApplication.translate('Message','System resumed. Reconnecting...'))
+        except Exception as e: # pylint: disable=broad-except
+            _log.exception(e)
+
+    # forces a reconnect of those machine connections which offer this operation and returns the
+    # number of connections that were asked to reconnect.
+    # NOTE: the classic serial devices re-open their port automatically on the next failing read
+    #  and the BLE devices are reconnected by their disconnect callbacks, thus both are not
+    #  handled here
+    def reconnectMachine(self) -> int:
+        reconnects:int = 0
+        machines:list[AsyncComm|KaleidoPort|None] = [self.aw.hottop, self.aw.santoker, self.aw.mugma,
+                self.aw.orbiter, self.aw.kaleido]
+        for machine in machines:
+            if machine is not None:
+                try:
+                    if machine.reconnect():
+                        reconnects += 1
+                except Exception as e: # pylint: disable=broad-except
+                    _log.exception(e)
+        return reconnects
+
     @pyqtSlot()
     def OnMonitor(self) -> None:
         try:
@@ -13102,6 +13194,8 @@ def OnMonitor(self) -> None:
             self.TPalarmtimeindex = None
 
             self.flagon = True
+            self.preventSleep() # keep the computer awake to not lose the connection to the machine
+            self.startWakeDetection() # reconnect the machine if the system was suspended nevertheless
             self.redraw(True,re_smooth_foreground=False, re_smooth_background=True) # there is now foreground at this point; we need to re-smooth background with no curve-smoothing and standard instead of optimal-smoothing on ON
 
             if self.designerflag:
@@ -13279,6 +13373,8 @@ def OffMonitorCloseDown(self, respectAlwaysON:bool, wasRecording:bool) -> None:
             except Exception as e: # pylint: disable=broad-except
                 _log.exception(e)
             QTimer.singleShot(5,self.disconnectProbes)
+            self.stopWakeDetection()
+            self.allowSleep() # the machine is disconnected, the computer may sleep again
             # reset the canvas color when it was set by an alarm but never reset
             if 'canvas_alt' in self.palette:
                 self.palette['canvas'] = self.palette['canvas_alt']