Add HackRF support to TSCM RF scan and misc improvements

TSCM RF scan now auto-detects HackRF via SDRFactory and uses
hackrf_sweep as an alternative to rtl_power. Also includes
improvements to listening post, rtlamr, weather satellite,
SubGHz, Meshtastic, SSTV, WeFax, and process monitor modules.

Fixes #154

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

utils/meshtastic.py

@@ -376,63 +376,82 @@ class MeshtasticClient:
             self._error = "Meshtastic SDK not installed. Install with: pip install meshtastic"
             return False
 
+        # Quick check under lock — bail if already running
         with self._lock:
             if self._running:
                 return True
 
-            try:
-                # Subscribe to message events before connecting
-                pub.subscribe(self._on_receive, "meshtastic.receive")
-                pub.subscribe(self._on_connection, "meshtastic.connection.established")
-                pub.subscribe(self._on_disconnect, "meshtastic.connection.lost")
+        # Create interface outside lock (blocking I/O: serial/TCP connect)
+        new_interface = None
+        new_device_path = None
+        new_connection_type = None
+        try:
+            # Subscribe to message events before connecting
+            pub.subscribe(self._on_receive, "meshtastic.receive")
+            pub.subscribe(self._on_connection, "meshtastic.connection.established")
+            pub.subscribe(self._on_disconnect, "meshtastic.connection.lost")
 
-                # Connect based on connection type
-                if connection_type == 'tcp':
-                    if not hostname:
-                        self._error = "Hostname is required for TCP connections"
-                        self._cleanup_subscriptions()
-                        return False
-                    self._interface = meshtastic.tcp_interface.TCPInterface(hostname=hostname)
-                    self._device_path = hostname
-                    self._connection_type = 'tcp'
-                    logger.info(f"Connected to Meshtastic device via TCP: {hostname}")
+            if connection_type == 'tcp':
+                if not hostname:
+                    self._error = "Hostname is required for TCP connections"
+                    self._cleanup_subscriptions()
+                    return False
+                new_interface = meshtastic.tcp_interface.TCPInterface(hostname=hostname)
+                new_device_path = hostname
+                new_connection_type = 'tcp'
+                logger.info(f"Connected to Meshtastic device via TCP: {hostname}")
+            else:
+                if device:
+                    new_interface = meshtastic.serial_interface.SerialInterface(device)
+                    new_device_path = device
                 else:
-                    # Serial connection (default)
-                    if device:
-                        self._interface = meshtastic.serial_interface.SerialInterface(device)
-                        self._device_path = device
-                    else:
-                        # Auto-discover
-                        self._interface = meshtastic.serial_interface.SerialInterface()
-                        self._device_path = "auto"
-                    self._connection_type = 'serial'
-                    logger.info(f"Connected to Meshtastic device via serial: {self._device_path}")
+                    new_interface = meshtastic.serial_interface.SerialInterface()
+                    new_device_path = "auto"
+                new_connection_type = 'serial'
+                logger.info(f"Connected to Meshtastic device via serial: {new_device_path}")
+        except Exception as e:
+            self._error = str(e)
+            logger.error(f"Failed to connect to Meshtastic: {e}")
+            self._cleanup_subscriptions()
+            return False
 
-                self._running = True
-                self._error = None
+        # Install interface under lock
+        with self._lock:
+            if self._running:
+                # Another thread connected while we were connecting — discard ours
+                if new_interface:
+                    try:
+                        new_interface.close()
+                    except Exception:
+                        pass
                 return True
 
-            except Exception as e:
-                self._error = str(e)
-                logger.error(f"Failed to connect to Meshtastic: {e}")
-                self._cleanup_subscriptions()
-                return False
+            self._interface = new_interface
+            self._device_path = new_device_path
+            self._connection_type = new_connection_type
+            self._running = True
+            self._error = None
+            return True
 
     def disconnect(self) -> None:
         """Disconnect from the Meshtastic device."""
+        iface_to_close = None
         with self._lock:
-            if self._interface:
-                try:
-                    self._interface.close()
-                except Exception as e:
-                    logger.warning(f"Error closing Meshtastic interface: {e}")
-                self._interface = None
-
+            iface_to_close = self._interface
+            self._interface = None
             self._cleanup_subscriptions()
             self._running = False
             self._device_path = None
             self._connection_type = None
-            logger.info("Disconnected from Meshtastic device")
+
+        # Close interface outside lock (blocking I/O)
+        if iface_to_close:
+            try:
+                iface_to_close.close()
+            except Exception as e:
+                logger.warning(f"Error closing Meshtastic interface: {e}")
+
+        logger.info("Disconnected from Meshtastic device")
 
     def _cleanup_subscriptions(self) -> None:
         """Unsubscribe from pubsub topics."""

utils/process_monitor.py

@@ -112,6 +112,8 @@ class ProcessMonitor:
 
     def _check_all_processes(self) -> None:
         """Check health of all registered processes."""
+        # Collect crashed processes under lock, handle restarts outside
+        crashed: list[tuple[str, ProcessInfo]] = []
         with self._lock:
             for name, info in list(self.processes.items()):
                 if not info.enabled:
@@ -126,10 +128,14 @@ class ProcessMonitor:
                     logger.warning(
                         f"Process '{name}' terminated with code {return_code}"
                     )
-                    self._handle_crash(name, info)
+                    crashed.append((name, info))
+
+        # Handle restarts outside lock (involves sleeps and callbacks)
+        for name, info in crashed:
+            self._handle_crash(name, info)
 
     def _handle_crash(self, name: str, info: ProcessInfo) -> None:
-        """Handle a crashed process."""
+        """Handle a crashed process. Must be called WITHOUT holding self._lock."""
         if info.restart_callback is None:
             logger.info(f"No restart callback for '{name}', skipping auto-restart")
             return
@@ -139,7 +145,8 @@ class ProcessMonitor:
                 f"Process '{name}' exceeded max restarts ({info.max_restarts}), "
                 "disabling auto-restart"
             )
-            info.enabled = False
+            with self._lock:
+                info.enabled = False
             return
 
         # Calculate backoff with exponential increase
@@ -149,18 +156,20 @@ class ProcessMonitor:
             f"(attempt {info.restart_count + 1}/{info.max_restarts})"
         )
 
-        # Wait for backoff period
+        # Wait for backoff period outside lock
         time.sleep(backoff)
 
         # Attempt restart
         try:
             info.restart_callback()
-            info.restart_count += 1
-            info.last_restart = datetime.now()
+            with self._lock:
+                info.restart_count += 1
+                info.last_restart = datetime.now()
             logger.info(f"Successfully restarted '{name}'")
         except Exception as e:
             logger.error(f"Failed to restart '{name}': {e}")
-            info.restart_count += 1
+            with self._lock:
+                info.restart_count += 1
 
     def get_status(self) -> Dict[str, Any]:
         """

utils/sstv/sstv_decoder.py

@@ -552,15 +552,20 @@ class SSTVDecoder:
         # Clean up if the thread exits while we thought we were running.
         # This prevents a "ghost running" state where is_running is True
         # but the thread has already died (e.g. rtl_fm exited).
+        orphan_proc = None
         with self._lock:
             was_running = self._running
             self._running = False
             if was_running and self._rtl_process:
-                with contextlib.suppress(Exception):
-                    self._rtl_process.terminate()
-                    self._rtl_process.wait(timeout=2)
+                orphan_proc = self._rtl_process
                 self._rtl_process = None
 
+        # Terminate outside lock to avoid blocking other operations
+        if orphan_proc:
+            with contextlib.suppress(Exception):
+                orphan_proc.terminate()
+                orphan_proc.wait(timeout=2)
+
         if was_running:
             logger.warning("Audio decode thread stopped unexpectedly")
             err_detail = rtl_fm_error.split('\n')[-1] if rtl_fm_error else ''
@@ -661,38 +666,52 @@ class SSTVDecoder:
 
     def _retune_rtl_fm(self, new_freq_hz: int) -> None:
         """Retune rtl_fm to a new frequency by restarting the process."""
+        old_proc = None
         with self._lock:
             if not self._running:
                 return
+            old_proc = self._rtl_process
+            self._rtl_process = None
 
-            if self._rtl_process:
-                try:
-                    self._rtl_process.terminate()
-                    self._rtl_process.wait(timeout=2)
-                except Exception:
-                    with contextlib.suppress(Exception):
-                        self._rtl_process.kill()
+        # Terminate old process outside lock
+        if old_proc:
+            try:
+                old_proc.terminate()
+                old_proc.wait(timeout=2)
+            except Exception:
+                with contextlib.suppress(Exception):
+                    old_proc.kill()
 
-            rtl_cmd = [
-                'rtl_fm',
-                '-d', str(self._device_index),
-                '-f', str(new_freq_hz),
-                '-M', self._modulation,
-                '-s', str(SAMPLE_RATE),
-                '-r', str(SAMPLE_RATE),
-                '-l', '0',
-                '-'
-            ]
+        # Build and start new process outside lock
+        rtl_cmd = [
+            'rtl_fm',
+            '-d', str(self._device_index),
+            '-f', str(new_freq_hz),
+            '-M', self._modulation,
+            '-s', str(SAMPLE_RATE),
+            '-r', str(SAMPLE_RATE),
+            '-l', '0',
+            '-'
+        ]
 
-            logger.debug(f"Restarting rtl_fm: {' '.join(rtl_cmd)}")
+        logger.debug(f"Restarting rtl_fm: {' '.join(rtl_cmd)}")
 
-            self._rtl_process = subprocess.Popen(
-                rtl_cmd,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE
-            )
+        new_proc = subprocess.Popen(
+            rtl_cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE
+        )
 
-            self._current_tuned_freq_hz = new_freq_hz
+        # Re-acquire lock to install new process
+        with self._lock:
+            if self._running:
+                self._rtl_process = new_proc
+                self._current_tuned_freq_hz = new_freq_hz
+            else:
+                # stop() was called during retune — clean up new process
+                with contextlib.suppress(Exception):
+                    new_proc.terminate()
+                    new_proc.wait(timeout=2)
 
     @property
     def last_doppler_info(self) -> DopplerInfo | None:
@@ -706,19 +725,22 @@ class SSTVDecoder:
 
     def stop(self) -> None:
         """Stop SSTV decoder."""
+        proc_to_terminate = None
         with self._lock:
             self._running = False
+            proc_to_terminate = self._rtl_process
+            self._rtl_process = None
 
-            if self._rtl_process:
-                try:
-                    self._rtl_process.terminate()
-                    self._rtl_process.wait(timeout=5)
-                except Exception:
-                    with contextlib.suppress(Exception):
-                        self._rtl_process.kill()
-                self._rtl_process = None
+        # Terminate outside lock to avoid blocking other operations
+        if proc_to_terminate:
+            try:
+                proc_to_terminate.terminate()
+                proc_to_terminate.wait(timeout=5)
+            except Exception:
+                with contextlib.suppress(Exception):
+                    proc_to_terminate.kill()
 
-            logger.info("SSTV decoder stopped")
+        logger.info("SSTV decoder stopped")
 
     def get_images(self) -> list[SSTVImage]:
         """Get list of decoded images."""

utils/weather_sat.py

@@ -173,7 +173,7 @@ class WeatherSatDecoder:
         self._current_frequency: float = 0.0
         self._current_mode: str = ''
         self._capture_start_time: float = 0
-        self._device_index: int = -1
+        self._device_index: int = -1
         self._capture_output_dir: Path | None = None
         self._on_complete_callback: Callable[[], None] | None = None
         self._capture_phase: str = 'idle'
@@ -303,13 +303,13 @@ class WeatherSatDecoder:
                 ))
                 return False
 
-            self._current_satellite = satellite
-            self._current_frequency = sat_info['frequency']
-            self._current_mode = sat_info['mode']
-            self._device_index = -1  # Offline decode does not claim an SDR device
-            self._capture_start_time = time.time()
-            self._capture_phase = 'decoding'
-            self._stop_event.clear()
+            self._current_satellite = satellite
+            self._current_frequency = sat_info['frequency']
+            self._current_mode = sat_info['mode']
+            self._device_index = -1  # Offline decode does not claim an SDR device
+            self._capture_start_time = time.time()
+            self._capture_phase = 'decoding'
+            self._stop_event.clear()
 
             try:
                 self._running = True
@@ -363,6 +363,20 @@ class WeatherSatDecoder:
         Returns:
             True if started successfully
         """
+        # Validate satellite BEFORE acquiring the lock
+        sat_info = WEATHER_SATELLITES.get(satellite)
+        if not sat_info:
+            logger.error(f"Unknown satellite: {satellite}")
+            self._emit_progress(CaptureProgress(
+                status='error',
+                message=f'Unknown satellite: {satellite}'
+            ))
+            return False
+
+        # Resolve device ID BEFORE lock — this runs rtl_test which can
+        # take up to 5s and has no side effects on instance state.
+        source_id = self._resolve_device_id(device_index)
+
         with self._lock:
             if self._running:
                 return True
@@ -375,15 +389,6 @@ class WeatherSatDecoder:
                 ))
                 return False
 
-            sat_info = WEATHER_SATELLITES.get(satellite)
-            if not sat_info:
-                logger.error(f"Unknown satellite: {satellite}")
-                self._emit_progress(CaptureProgress(
-                    status='error',
-                    message=f'Unknown satellite: {satellite}'
-                ))
-                return False
-
             self._current_satellite = satellite
             self._current_frequency = sat_info['frequency']
             self._current_mode = sat_info['mode']
@@ -394,7 +399,7 @@ class WeatherSatDecoder:
 
             try:
                 self._running = True
-                self._start_satdump(sat_info, device_index, gain, sample_rate, bias_t)
+                self._start_satdump(sat_info, device_index, gain, sample_rate, bias_t, source_id)
 
                 logger.info(
                     f"Weather satellite capture started: {satellite} "
@@ -429,6 +434,7 @@ class WeatherSatDecoder:
         gain: float,
         sample_rate: int,
         bias_t: bool,
+        source_id: str | None = None,
     ) -> None:
         """Start SatDump live capture and decode."""
         # Create timestamped output directory for this capture
@@ -439,9 +445,9 @@ class WeatherSatDecoder:
 
         freq_hz = int(sat_info['frequency'] * 1_000_000)
 
-        # SatDump v1.2+ uses string source_id (device serial) not numeric index.
-        # Auto-detect serial by querying rtl_eeprom, fall back to string index.
-        source_id = self._resolve_device_id(device_index)
+        # Use pre-resolved source_id, or fall back to resolving now
+        if source_id is None:
+            source_id = self._resolve_device_id(device_index)
 
         cmd = [
             'satdump', 'live',
@@ -465,18 +471,18 @@ class WeatherSatDecoder:
         master_fd, slave_fd = pty.openpty()
         self._pty_master_fd = master_fd
 
-        self._process = subprocess.Popen(
-            cmd,
-            stdout=slave_fd,
-            stderr=slave_fd,
-            stdin=subprocess.DEVNULL,
-            close_fds=True,
-        )
-        register_process(self._process)
-        try:
-            os.close(slave_fd)  # parent doesn't need the slave side
-        except OSError:
-            pass
+        self._process = subprocess.Popen(
+            cmd,
+            stdout=slave_fd,
+            stderr=slave_fd,
+            stdin=subprocess.DEVNULL,
+            close_fds=True,
+        )
+        register_process(self._process)
+        try:
+            os.close(slave_fd)  # parent doesn't need the slave side
+        except OSError:
+            pass
 
         # Check for early exit asynchronously (avoid blocking /start for 3s)
         def _check_early_exit():
@@ -568,18 +574,18 @@ class WeatherSatDecoder:
         master_fd, slave_fd = pty.openpty()
         self._pty_master_fd = master_fd
 
-        self._process = subprocess.Popen(
-            cmd,
-            stdout=slave_fd,
-            stderr=slave_fd,
-            stdin=subprocess.DEVNULL,
-            close_fds=True,
-        )
-        register_process(self._process)
-        try:
-            os.close(slave_fd)  # parent doesn't need the slave side
-        except OSError:
-            pass
+        self._process = subprocess.Popen(
+            cmd,
+            stdout=slave_fd,
+            stderr=slave_fd,
+            stdin=subprocess.DEVNULL,
+            close_fds=True,
+        )
+        register_process(self._process)
+        try:
+            os.close(slave_fd)  # parent doesn't need the slave side
+        except OSError:
+            pass
 
         # For offline mode, don't check for early exit — file decoding
         # may complete very quickly and exit code 0 is normal success.
@@ -812,20 +818,23 @@ class WeatherSatDecoder:
             # Signal watcher thread to do final scan and exit
             self._stop_event.set()
 
-            # Process ended — release resources
-            was_running = self._running
-            self._running = False
+            # Acquire lock when modifying shared state to avoid racing
+            # with stop() which may have already cleaned up.
+            with self._lock:
+                was_running = self._running
+                self._running = False
+                process = self._process
             elapsed = int(time.time() - self._capture_start_time) if self._capture_start_time else 0
 
             if was_running:
                 # Collect exit status (returncode is only set after poll/wait)
-                if self._process and self._process.returncode is None:
+                if process and process.returncode is None:
                     try:
-                        self._process.wait(timeout=5)
+                        process.wait(timeout=5)
                     except subprocess.TimeoutExpired:
-                        self._process.kill()
-                        self._process.wait()
-                retcode = self._process.returncode if self._process else None
+                        process.kill()
+                        process.wait()
+                retcode = process.returncode if process else None
                 if retcode and retcode != 0:
                     self._capture_phase = 'error'
                     self._emit_progress(CaptureProgress(
@@ -899,24 +908,24 @@ class WeatherSatDecoder:
                     except OSError:
                         continue
 
-                    # Determine product type from filename/path
-                    product = self._parse_product_name(filepath)
-
-                    # Copy image to main output dir for serving
-                    safe_sat = re.sub(r'[^A-Za-z0-9_-]+', '_', self._current_satellite).strip('_') or 'satellite'
-                    safe_stem = re.sub(r'[^A-Za-z0-9_-]+', '_', filepath.stem).strip('_') or 'image'
-                    suffix = filepath.suffix.lower()
-                    if suffix not in ('.png', '.jpg', '.jpeg'):
-                        suffix = '.png'
-                    serve_name = (
-                        f"{safe_sat}_{safe_stem}_{datetime.now().strftime('%Y%m%d_%H%M%S_%f')}"
-                        f"{suffix}"
-                    )
-                    serve_path = self._output_dir / serve_name
-                    try:
-                        shutil.copy2(filepath, serve_path)
-                    except OSError:
-                        # Copy failed — don't mark as known so it can be retried
+                    # Determine product type from filename/path
+                    product = self._parse_product_name(filepath)
+
+                    # Copy image to main output dir for serving
+                    safe_sat = re.sub(r'[^A-Za-z0-9_-]+', '_', self._current_satellite).strip('_') or 'satellite'
+                    safe_stem = re.sub(r'[^A-Za-z0-9_-]+', '_', filepath.stem).strip('_') or 'image'
+                    suffix = filepath.suffix.lower()
+                    if suffix not in ('.png', '.jpg', '.jpeg'):
+                        suffix = '.png'
+                    serve_name = (
+                        f"{safe_sat}_{safe_stem}_{datetime.now().strftime('%Y%m%d_%H%M%S_%f')}"
+                        f"{suffix}"
+                    )
+                    serve_path = self._output_dir / serve_name
+                    try:
+                        shutil.copy2(filepath, serve_path)
+                    except OSError:
+                        # Copy failed — don't mark as known so it can be retried
                         continue
 
                     # Only mark as known after successful copy
@@ -960,12 +969,12 @@ class WeatherSatDecoder:
             return 'Multispectral Analysis'
         if 'thermal' in name or 'temp' in name:
             return 'Thermal'
-        if 'ndvi' in name:
-            return 'NDVI Vegetation'
-        if 'channel' in name or 'ch' in name:
-            match = re.search(r'(?:channel|ch)[\s_-]*(\d+)', name)
-            if match:
-                return f'Channel {match.group(1)}'
+        if 'ndvi' in name:
+            return 'NDVI Vegetation'
+        if 'channel' in name or 'ch' in name:
+            match = re.search(r'(?:channel|ch)[\s_-]*(\d+)', name)
+            if match:
+                return f'Channel {match.group(1)}'
         if 'avhrr' in name:
             return 'AVHRR'
         if 'msu' in name or 'mtvza' in name:
@@ -986,14 +995,16 @@ class WeatherSatDecoder:
             self._running = False
             self._stop_event.set()
             self._close_pty()
+            process = self._process
+            self._process = None
+            elapsed = int(time.time() - self._capture_start_time) if self._capture_start_time else 0
+            logger.info(f"Weather satellite capture stopped after {elapsed}s")
+            self._device_index = -1
 
-            if self._process:
-                safe_terminate(self._process)
-                self._process = None
-
-            elapsed = int(time.time() - self._capture_start_time) if self._capture_start_time else 0
-            logger.info(f"Weather satellite capture stopped after {elapsed}s")
-            self._device_index = -1
+        # Terminate outside the lock so stop() returns quickly
+        # and doesn't block start() or other lock acquisitions
+        if process:
+            safe_terminate(process)
 
     def get_images(self) -> list[WeatherSatImage]:
         """Get list of decoded images."""
@@ -1029,18 +1040,18 @@ class WeatherSatDecoder:
 
                 sat_info = WEATHER_SATELLITES.get(satellite, {})
 
-                image = WeatherSatImage(
-                    filename=filepath.name,
-                    path=filepath,
-                    satellite=satellite,
-                    mode=sat_info.get('mode', 'Unknown'),
+                image = WeatherSatImage(
+                    filename=filepath.name,
+                    path=filepath,
+                    satellite=satellite,
+                    mode=sat_info.get('mode', 'Unknown'),
                     timestamp=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc),
                     frequency=sat_info.get('frequency', 0.0),
-                    size_bytes=stat.st_size,
-                    product=self._parse_product_name(filepath),
-                )
-                self._images.append(image)
-                known_filenames.add(filepath.name)
+                    size_bytes=stat.st_size,
+                    product=self._parse_product_name(filepath),
+                )
+                self._images.append(image)
+                known_filenames.add(filepath.name)
 
     def delete_image(self, filename: str) -> bool:
         """Delete a decoded image."""

utils/wefax.py

@@ -299,14 +299,7 @@ class WeFaxDecoder:
             try:
                 self._running = True
                 self._last_error = ''
-                self._start_pipeline()
-
-                logger.info(
-                    f"WeFax decoder started: {frequency_khz} kHz, "
-                    f"station={station}, IOC={ioc}, LPM={lpm}"
-                )
-                return True
-
+                self._start_pipeline_spawn()
             except Exception as e:
                 self._running = False
                 self._last_error = str(e)
@@ -317,8 +310,32 @@ class WeFaxDecoder:
                 ))
                 return False
 
+        # Health check sleep outside lock
+        try:
+            self._start_pipeline_health_check()
+            logger.info(
+                f"WeFax decoder started: {frequency_khz} kHz, "
+                f"station={station}, IOC={ioc}, LPM={lpm}"
+            )
+            return True
+        except Exception as e:
+            with self._lock:
+                self._running = False
+                self._last_error = str(e)
+            logger.error(f"Failed to start WeFax decoder: {e}")
+            self._emit_progress(WeFaxProgress(
+                status='error',
+                message=str(e),
+            ))
+            return False
+
     def _start_pipeline(self) -> None:
         """Start SDR FM demod subprocess in USB mode for WeFax."""
+        self._start_pipeline_spawn()
+        self._start_pipeline_health_check()
+
+    def _start_pipeline_spawn(self) -> None:
+        """Spawn the SDR FM demod subprocess. Must hold self._lock."""
         try:
             sdr_type_enum = SDRType(self._sdr_type)
         except ValueError:
@@ -361,21 +378,24 @@ class WeFaxDecoder:
             stderr=subprocess.PIPE,
         )
 
-        # Post-spawn health check — catch immediate failures
+    def _start_pipeline_health_check(self) -> None:
+        """Post-spawn health check and decode thread start. Called outside lock."""
         time.sleep(0.3)
-        if self._sdr_process.poll() is not None:
-            stderr_detail = ''
-            if self._sdr_process.stderr:
-                stderr_detail = self._sdr_process.stderr.read().decode(
-                    errors='replace').strip()
-            rc = self._sdr_process.returncode
-            self._sdr_process = None
-            detail = stderr_detail.split('\n')[-1] if stderr_detail else f'exit code {rc}'
-            raise RuntimeError(f'{self._sdr_tool_name} failed: {detail}')
 
-        self._decode_thread = threading.Thread(
-            target=self._decode_audio_stream, daemon=True)
-        self._decode_thread.start()
+        with self._lock:
+            if self._sdr_process and self._sdr_process.poll() is not None:
+                stderr_detail = ''
+                if self._sdr_process.stderr:
+                    stderr_detail = self._sdr_process.stderr.read().decode(
+                        errors='replace').strip()
+                rc = self._sdr_process.returncode
+                self._sdr_process = None
+                detail = stderr_detail.split('\n')[-1] if stderr_detail else f'exit code {rc}'
+                raise RuntimeError(f'{self._sdr_tool_name} failed: {detail}')
+
+            self._decode_thread = threading.Thread(
+                target=self._decode_audio_stream, daemon=True)
+            self._decode_thread.start()
 
     def _decode_audio_stream(self) -> None:
         """Read audio from SDR FM demod and decode WeFax images.