Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/live.py

@@ -0,0 +1,859 @@
+"""Barmaja PyArduino LiveRun support.
+
+LiveRun keeps the student's Arduino-style API but executes the Python program on
+its host (normal Python or PictoBlox) while Telemetrix4Arduino runs on the Uno.
+
+The public entry point is ``LiveRun()``.  The rest of this module is deliberately
+internal so the student surface remains small and consistent with standalone
+Barmaja PyArduino programs.
+"""
+
+from __future__ import annotations
+
+import atexit
+import contextlib
+import io
+import os
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+
+class LiveRunError(RuntimeError):
+    """Raised when Barmaja PyArduino cannot start or use LiveRun."""
+
+
+class LiveStudentError(LiveRunError):
+    """Actionable LiveRun setup error; preserve the original cause for debugging."""
+
+
+class LiveDependencyError(LiveRunError):
+    """Required LiveRun Python support is not installed."""
+
+
+class LiveConnectionError(LiveRunError):
+    """The Uno did not answer as a Telemetrix LiveRun board."""
+
+
+class LivePortBusyError(LiveConnectionError):
+    """Another process has the serial port open; do not attempt to reflash."""
+
+
+class LivePortMissingError(LiveConnectionError):
+    """The selected COM port disappeared or was not present."""
+
+
+EXPECTED_FIRMWARE = "5.4.4"
+
+
+def _port_is_busy(exc: BaseException) -> bool:
+    """Identify a locked COM port in the underlying pyserial/Windows error.
+
+    A failed firmware identity check is expected after a standalone upload.
+    Access denied, on the other hand, is *not* evidence that the firmware is
+    wrong; trying avrdude in this case just gives a second misleading error.
+    """
+    seen: set[int] = set()
+    current: Optional[BaseException] = exc
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        message = str(current).lower()
+        if any(word in message for word in (
+            "access is denied", "permissionerror(13", "port is busy",
+            "port busy", "resource busy", "device or resource busy",
+            "permission denied",
+        )):
+            return True
+        if isinstance(current, PermissionError):
+            return True
+        if isinstance(current, OSError) and getattr(current, "winerror", None) in (5, 32):
+            return True
+        current = current.__cause__ or current.__context__
+    return False
+
+
+def _port_is_missing(exc: BaseException) -> bool:
+    seen: set[int] = set()
+    current: Optional[BaseException] = exc
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        message = str(current).lower()
+        if (isinstance(current, FileNotFoundError) or
+                isinstance(current, OSError) and getattr(current, "winerror", None) in (2, 3) or
+                "file not found" in message or
+                "the system cannot find the file specified" in message):
+            return True
+        current = current.__cause__ or current.__context__
+    return False
+
+
+def _patch_pinned_telemetrix_identity_wait() -> None:
+    """Give Telemetrix 1.43 enough time to dispatch the Uno identity reply.
+
+    The pinned client waits only 0.5 seconds after sending ARE_U_THERE.  On
+    Windows, its background receiver/reporter threads can dispatch the valid
+    three-byte response just after that deadline.  Keep the pinned protocol and
+    extend only this internal wait; future client versions are left untouched.
+    """
+    try:
+        from telemetrix import telemetrix as client
+        from telemetrix.private_constants import PrivateConstants
+    except Exception:
+        return
+    cls = client.Telemetrix
+    if getattr(cls, "_barmaja_identity_wait_patch", False):
+        return
+    if str(getattr(PrivateConstants, "TELEMETRIX_VERSION", "")) != "1.43":
+        return
+
+    def _get_arduino_id(self) -> None:
+        self._send_command([PrivateConstants.ARE_U_THERE])
+        deadline = time.monotonic() + 3.0
+        while self.reported_arduino_id is None and time.monotonic() < deadline:
+            time.sleep(0.05)
+
+    cls._get_arduino_id = _get_arduino_id
+    cls._barmaja_identity_wait_patch = True
+
+
+def _port_was_lost(exc: BaseException) -> bool:
+    """True for errors that mean the USB serial link is closed or gone.
+
+    Covers pyserial ``PortNotOpenError`` ("Attempting to use a port that is not
+    open"), write/read failures after unplugging, and Windows ClearCommError.
+    """
+    seen: set[int] = set()
+    current: Optional[BaseException] = exc
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        name = type(current).__name__.lower()
+        message = str(current).lower()
+        if ("portnotopen" in name or "not open" in message or "port is not open" in message
+                or "write fail in _send_command" in message or "shutdown failed" in message
+                or "clearcommerror" in message or "device not configured" in message
+                or "input/output error" in message or "device disconnected" in message
+                or "device attached to the system is not functioning" in message
+                or "writefile failed" in message or "readfile failed" in message
+                or "handle is invalid" in message):
+            return True
+        if _port_is_missing(current):
+            return True
+        current = current.__cause__ or current.__context__
+    return False
+
+
+class _GuardedSync:
+    """Wrap Telemetrix calls so a lost USB port is reported ONCE and cleanly.
+
+    Without this the upstream client (``shutdown_on_exception=True``) keeps
+    calling into a closed serial handle and a student sees a long chain of
+    repeated ``PortNotOpenError`` tracebacks.  Any error that proves the port
+    is gone stops LiveRun, releases everything and raises one short message.
+    """
+
+    def __init__(self, target: Any, owner: "_TelemetrixBackend") -> None:
+        object.__setattr__(self, "_target", target)
+        object.__setattr__(self, "_owner", owner)
+
+    def __getattr__(self, name: str) -> Any:
+        value = getattr(self._target, name)
+        if name in ("_context", "board"):
+            return _GuardedSync(value, self._owner)
+        if callable(value):
+            owner = self._owner
+
+            def guarded(*args: Any, **kwargs: Any) -> Any:
+                try:
+                    return value(*args, **kwargs)
+                except LiveRunError:
+                    raise
+                except BaseException as exc:
+                    if isinstance(exc, (KeyboardInterrupt, SystemExit, GeneratorExit)):
+                        raise
+                    if owner._closed or _port_was_lost(exc):
+                        owner._port_lost(exc)
+                    raise
+            return guarded
+        return value
+
+
+@dataclass(frozen=True)
+class LiveSession:
+    """Small status object returned by ``LiveRun()``.
+
+    Students do not need to store this object; it is useful for diagnostics and
+    advanced code that wants to display the selected COM port or firmware.
+    """
+
+    port: str
+    firmware_version: str
+
+    def shutdown(self) -> None:
+        LiveStop()
+
+
+class _TelemetrixBackend:
+    def __init__(self, port: str) -> None:
+        try:
+            import telemetrix_Barmaja as tb
+        except Exception as exc:
+            raise LiveDependencyError(
+                "LiveRun needs the Barmaja Telemetrix support package. "
+                "Install the Barmaja PyArduino LiveRun/Offline pack and run again."
+            ) from exc
+
+        _patch_pinned_telemetrix_identity_wait()
+        self.tb = tb
+        capture = io.StringIO()
+        try:
+            # The upstream client prints a long banner and connection transcript.
+            # Keep the beginner-facing console clean; Barmaja prints a short status
+            # after a successful connection instead.
+            with contextlib.redirect_stdout(capture), contextlib.redirect_stderr(capture):
+                self.sync = tb.TelemetrixSync(
+                    com_port=port,
+                    arduino_wait=float(os.environ.get("BARMAJA_LIVE_ARDUINO_WAIT", "3.0")),
+                    shutdown_on_exception=True,
+                )
+        except Exception as exc:
+            if _port_is_busy(exc):
+                raise LivePortBusyError(
+                    f"Arduino Uno found on {port}, but its port is busy. "
+                    "Close other programs using this Arduino and try again."
+                ) from exc
+            if _port_is_missing(exc):
+                raise LivePortMissingError(
+                    f"Arduino Uno is no longer available on {port}. "
+                    "Reconnect USB and try again."
+                ) from exc
+            # The long upstream transcript belongs only in debugging tools;
+            # it is not helpful to students when a standalone sketch is running.
+            raise LiveConnectionError(
+                "Arduino is not running LiveRun firmware yet."
+            ) from exc
+
+        self.port = port
+        try:
+            self._raw_board = self.sync._context.board
+        except Exception:
+            self._raw_board = None
+        # Telemetrix 1.43 with shutdown_on_exception=True recurses on a dead port:
+        # _send_command -> shutdown() -> _send_command ...  Once connected, let
+        # BARMAJA own cleanup instead (see _release_port / _port_lost).
+        if self._raw_board is not None:
+            try:
+                self._raw_board.shutdown_on_exception = False
+            except Exception:
+                pass
+        self._link_broken = False
+        self.sync = _GuardedSync(self.sync, self)
+        _install_thread_hook()
+        self._wire_address: Optional[int] = None
+        self._wire_tx: list[int] = []
+        self._wire_rx: list[int] = []
+        self._dht_started: set[tuple[int, int]] = set()
+        self._sonars: set[tuple[int, int]] = set()
+        self._closed = False
+
+    @property
+    def firmware_version(self) -> str:
+        try:
+            values = self.sync._context.board.firmware_version
+            if values and len(values) >= 3:
+                return ".".join(str(int(v)) for v in values[:3])
+        except Exception:
+            pass
+        return "unknown"
+
+    @staticmethod
+    def _analog_channel(pin: int) -> int:
+        """Translate Barmaja's Arduino aliases A0..A5 (14..19) for Telemetrix."""
+        pin = int(pin)
+        if 14 <= pin <= 19:
+            return pin - 14
+        if 0 <= pin <= 5:
+            return pin
+        raise ValueError("analogRead() on Arduino Uno expects A0..A5.")
+
+    def _link_ok(self) -> bool:
+        """Cheap health check: port open and the Telemetrix receiver thread alive.
+
+        Without this, cached readings (e.g. analogRead) silently repeat the last
+        value forever after the USB cable is pulled.
+        """
+        if getattr(self, "_link_broken", False):
+            return False
+        board = getattr(self, "_raw_board", None)
+        if board is None:
+            return True
+        try:
+            port = getattr(board, "serial_port", None)
+            if port is not None and not getattr(port, "is_open", True):
+                return False
+            receiver = getattr(board, "the_data_receive_thread", None)
+            if receiver is not None and receiver.ident is not None and not receiver.is_alive():
+                return False
+            # Active probe (rate-limited). Telemetrix 1.43's receiver thread
+            # swallows OSError -- and pyserial's SerialException IS an OSError --
+            # so after a USB unplug it spins forever and the cached readings go
+            # stale silently.  On Windows ``in_waiting`` raises
+            # "ClearCommError failed" for a removed device.
+            if port is not None:
+                now = time.monotonic()
+                if now - getattr(self, "_last_probe", 0.0) >= 0.1:
+                    self._last_probe = now
+                    try:
+                        port.in_waiting
+                    except Exception as exc:
+                        if _port_was_lost(exc) or isinstance(exc, OSError):
+                            return False
+        except Exception:
+            return False
+        return True
+
+    def _check(self) -> None:
+        if self._closed:
+            raise LiveRunError("LiveRun has already been stopped. Call LiveRun() again.")
+        if not self._link_ok():
+            self._port_lost(LivePortMissingError(f"USB link lost on {self.port}"))
+
+    def _release_port(self) -> None:
+        """Stop Telemetrix threads and ALWAYS close the COM handle, quietly.
+
+        Upstream shutdown() first sends STOP_ALL_REPORTS; on a dead port that
+        raises before serial_port.close(), leaving the COM port held open inside
+        IDLE/PictoBlox so the next LiveRun() reports "port busy".
+        """
+        quiet = io.StringIO()
+        board = getattr(self, "_raw_board", None)
+        with contextlib.redirect_stdout(quiet), contextlib.redirect_stderr(quiet):
+            if board is None or self._link_ok():
+                try:
+                    self.sync._target.shutdown()
+                except BaseException as exc:
+                    if isinstance(exc, (KeyboardInterrupt, SystemExit)):
+                        raise
+            if board is not None:
+                try:
+                    board.shutdown_flag = True
+                    board._stop_threads()
+                except Exception:
+                    pass
+                port = getattr(board, "serial_port", None)
+                if port is not None:
+                    try:
+                        port.close()
+                    except Exception:
+                        pass
+            try:
+                self.sync._target._context._closed = True
+            except Exception:
+                pass
+
+    def _port_lost(self, exc: BaseException) -> None:
+        """Stop LiveRun after USB loss: release once, raise one actionable error."""
+        global _active_backend, _active_session
+        already = self._closed
+        self._closed = True
+        if _active_backend is self:
+            _active_backend = None
+            _active_session = None
+        if not already:
+            self._link_broken = True
+            try:
+                self._release_port()
+            except BaseException:
+                pass
+        _enable_student_error_display()
+        error = LiveStudentError(
+            f"Arduino connection lost on {self.port}.\n"
+            "Reconnect the USB cable, close other programs using the Arduino, "
+            "and run the program again."
+        )
+        error._barmaja_student_message = True
+        raise error from None
+
+    # ---------- core Arduino-style API ----------
+    def pin_mode(self, pin: int, mode: int) -> None:
+        self._check()
+        self.sync.pinMode(int(pin), int(mode))
+
+    def digital_write(self, pin: int, value: int) -> None:
+        self._check()
+        self.sync.digitalWrite(int(pin), int(value))
+
+    def digital_read(self, pin: int) -> int:
+        self._check()
+        return int(self.sync.digitalRead(int(pin)))
+
+    def analog_read(self, pin: int) -> int:
+        self._check()
+        return int(self.sync.analogRead(self._analog_channel(pin)))
+
+    def analog_write(self, pin: int, value: int) -> None:
+        self._check()
+        self.sync.analogWrite(int(pin), int(value))
+
+    def delay(self, milliseconds: int) -> None:
+        self._check()
+        self.sync.delay(int(milliseconds))
+
+    def millis(self) -> int:
+        self._check()
+        return int(self.sync.millis())
+
+    # ---------- servo ----------
+    def servo_attach(self, pin: int, min_us: Optional[int] = None, max_us: Optional[int] = None) -> None:
+        self._check()
+        ctx = self.sync._context
+        pin = int(pin)
+        if ctx._set_servo is None:
+            raise LiveRunError("Servo is not supported by this Telemetrix firmware.")
+        if min_us is None:
+            try:
+                ctx._set_servo(pin)
+            except TypeError:
+                ctx._set_servo(pin, 544, 2400)
+        else:
+            try:
+                ctx._set_servo(pin, int(min_us), int(max_us))
+            except TypeError:
+                ctx._set_servo(pin)
+        ctx._servos.add(pin)
+
+    def servo_write(self, pin: int, angle: int) -> None:
+        self._check()
+        self.sync.servoWrite(int(pin), int(angle))
+
+    def servo_write_microseconds(self, pin: int, microseconds: int) -> None:
+        self._check()
+        pin = int(pin)
+        us = int(microseconds)
+        board = self.sync._context.board
+        method = getattr(board, "servo_write_microseconds", None)
+        if method is None:
+            # Official Telemetrix exposes degrees, not Servo.writeMicroseconds().
+            # Convert the standard 544..2400 us Arduino range to 0..180 degrees.
+            us = max(544, min(2400, us))
+            angle = round((us - 544) * 180 / (2400 - 544))
+            self.sync.servoWrite(pin, angle)
+        else:
+            method(pin, us)
+
+    def servo_detach(self, pin: int) -> None:
+        self._check()
+        pin = int(pin)
+        ctx = self.sync._context
+        method = getattr(ctx.board, "servo_detach", None)
+        if method is None:
+            raise LiveRunError("Servo detach is not supported by this Telemetrix build.")
+        method(pin)
+        ctx._servos.discard(pin)
+
+    def servo_attached(self, pin: int) -> bool:
+        self._check()
+        return int(pin) in self.sync._context._servos
+
+    # ---------- HC-SR04 ----------
+    def ultrasonic_begin(self, trigger_pin: int, echo_pin: int) -> None:
+        self._check()
+        key = (int(trigger_pin), int(echo_pin))
+        if key not in self._sonars:
+            self.sync.sonarBegin(*key)
+            self._sonars.add(key)
+
+    def ultrasonic_read(self, trigger_pin: int, echo_pin: int) -> float:
+        self.ultrasonic_begin(trigger_pin, echo_pin)
+        return float(self.sync.sonarReadCM(int(trigger_pin), int(echo_pin)))
+
+    # ---------- DHT ----------
+    def dht_begin(self, pin: int, sensor_type: int) -> None:
+        self._check()
+        key = (int(pin), int(sensor_type))
+        if key not in self._dht_started:
+            self.sync.dhtBegin(*key)
+            self._dht_started.add(key)
+
+    def dht_last(self, pin: int, sensor_type: int) -> tuple[Optional[float], Optional[float]]:
+        self.dht_begin(pin, sensor_type)
+        temperature, humidity = self.sync.dhtLast(int(pin))
+        return temperature, humidity
+
+    # ---------- I2C / Wire ----------
+    def wire_begin(self) -> None:
+        self._check()
+        self.sync.i2cBegin(0)
+
+    def wire_begin_transmission(self, address: int) -> None:
+        self.wire_begin()
+        self._wire_address = int(address)
+        self._wire_tx = []
+
+    def wire_write(self, value: int) -> int:
+        if self._wire_address is None:
+            raise LiveRunError("Call Wire.beginTransmission(address) before Wire.write().")
+        self._wire_tx.append(int(value) & 0xFF)
+        return 1
+
+    def wire_end_transmission(self) -> int:
+        if self._wire_address is None:
+            raise LiveRunError("Call Wire.beginTransmission(address) before Wire.endTransmission().")
+        self.sync.i2cWrite(self._wire_address, self._wire_tx, i2c_port=0)
+        self._wire_address = None
+        self._wire_tx = []
+        return 0
+
+    def wire_request_from(self, address: int, count: int) -> int:
+        self.wire_begin()
+        data = self.sync.i2cRead(
+            int(address), None, int(count), i2c_port=0, write_register=False
+        )
+        self._wire_rx = list(data)
+        return len(self._wire_rx)
+
+    def wire_available(self) -> int:
+        return len(self._wire_rx)
+
+    def wire_read(self) -> int:
+        if not self._wire_rx:
+            return -1
+        return int(self._wire_rx.pop(0))
+
+    # ---------- LCD ----------
+    def lcd_create(self, address: int, columns: int, rows: int):
+        self._check()
+        try:
+            lcd_cls = self.tb.LCD1602
+        except AttributeError as exc:
+            raise LiveRunError("LCD support is missing from telemetrix_Barmaja.") from exc
+        return lcd_cls(self.sync._context, address=int(address), columns=int(columns), rows=int(rows))
+
+    # ---------- lifecycle ----------
+    def shutdown(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        # A port that is already gone must not produce a second traceback.
+        self._release_port()
+
+
+_active_backend: Optional[_TelemetrixBackend] = None
+_active_session: Optional[LiveSession] = None
+_atexit_registered = False
+_thread_hook_installed = False
+
+
+def _install_thread_hook() -> None:
+    """Silence Telemetrix background-thread tracebacks caused by a lost port.
+
+    When USB is unplugged the upstream receiver thread dies with a
+    SerialException/PortNotOpenError traceback printed by ``threading``.  That
+    noise is replaced by ONE clean message from the next LiveRun call.  Any
+    other thread error is passed to the previous hook unchanged.
+    """
+    global _thread_hook_installed
+    if _thread_hook_installed:
+        return
+    import threading
+    previous = threading.excepthook
+
+    def hook(args) -> None:
+        backend_ = _active_backend
+        exc = args.exc_value
+        board = getattr(backend_, "_raw_board", None) if backend_ is not None else None
+        owned = board is not None and args.thread in (
+            getattr(board, "the_data_receive_thread", None),
+            getattr(board, "the_reporter_thread", None),
+        )
+        if exc is not None and (owned or "serial" in type(exc).__module__.lower()) and (
+                _port_was_lost(exc) or "serialexception" in type(exc).__name__.lower()):
+            if backend_ is not None:
+                backend_._link_broken = True
+            return
+        previous(args)
+
+    threading.excepthook = hook
+    _thread_hook_installed = True
+
+
+def _say(text: str, *, error: bool = False, style: Optional[str] = None) -> None:
+    try:
+        from .console import write_styled
+        import sys
+        stream = sys.stderr if error else sys.stdout
+        write_styled(stream, text, style=style)
+        stream.flush()
+    except Exception:
+        import builtins
+        builtins.print(text)
+
+
+def _select_port(port: Optional[str]) -> str:
+    from .toolchain import board_for_port, detect_board
+    if port:
+        return board_for_port(port).port
+    return detect_board().port
+
+
+def _telemetrix_sketch() -> Optional[Path]:
+    from .environment import private_arduino_library_roots
+    for library_root in private_arduino_library_roots():
+        sketch = (
+            library_root
+            / "Telemetrix4Arduino"
+            / "examples"
+            / "Telemetrix4Arduino"
+            / "Telemetrix4Arduino.ino"
+        )
+        if sketch.is_file():
+            return sketch
+    return None
+
+
+def _upload_live_firmware(port: str) -> None:
+    sketch = _telemetrix_sketch()
+    if sketch is None:
+        raise LiveRunError(
+            "Telemetrix4Arduino firmware is not installed in Barmaja's offline libraries. "
+            "Install/reinstall the Barmaja PyArduino Full or Light Offline pack."
+        )
+
+    from .toolchain import board_for_port, compile_existing_sketch, upload_compiled
+
+    _say("Preparing Arduino Uno for LiveRun...")
+    artifact = compile_existing_sketch(sketch.parent)
+    board = board_for_port(port)
+    # After a failed client identity check Windows can take a short moment to
+    # release the serial handle.  Retry only a *busy-port upload*, never a
+    # compile failure or another type of avrdude failure.
+    for attempt in range(2):
+        try:
+            upload_compiled(artifact, board)
+            break
+        except Exception as exc:
+            if attempt != 0 or not _port_is_busy(exc):
+                raise
+            time.sleep(1.0)
+    # Give the Uno a short moment after avrdude closes the port.  The Telemetrix
+    # client performs its own reset wait when it opens the connection.
+    time.sleep(0.5)
+
+
+def _try_connect(port: str) -> _TelemetrixBackend:
+    return _TelemetrixBackend(port)
+
+
+def _connect_after_firmware_upload(port: str) -> _TelemetrixBackend:
+    """Let Uno USB reset / Telemetrix handshake settle after an AVR flash.
+
+    Do not compile or reflash again on these retries.  A locked port must be
+    reported as locked instead of retried as if the firmware were missing.
+    """
+    last_error: Optional[Exception] = None
+    for attempt in range(3):
+        if attempt:
+            time.sleep(1.0)
+        try:
+            return _try_connect(port)
+        except LivePortBusyError:
+            raise
+        except LiveConnectionError as exc:
+            last_error = exc
+    raise LiveRunError(
+        "Arduino firmware was uploaded, but the LiveRun connection did not start. "
+        "Unplug/reconnect USB, close other Arduino programs, and try again."
+    ) from last_error
+
+
+def _LiveRun_core(port: Optional[str] = None, *, auto_firmware: bool = True) -> LiveSession:
+    """Start live PC/PictoBlox control of the connected Arduino Uno.
+
+    The first call connects to Telemetrix4Arduino.  If the Uno is running a
+    normal standalone sketch and ``auto_firmware`` is true, Barmaja uploads the
+    pinned Telemetrix4Arduino firmware and reconnects automatically.
+
+    After this call, the usual Barmaja API (``pinMode``, ``analogRead``,
+    ``digitalWrite``, ``Servo``, etc.) executes live instead of raising the
+    desktop guard.  Normal ``print()`` remains ordinary Python output, so in
+    PictoBlox it appears in the Python console.
+    """
+    global _active_backend, _active_session, _atexit_registered
+
+    if _active_backend is not None and not _active_backend._closed:
+        if port and str(port).strip().upper() != _active_backend.port.upper():
+            raise LiveRunError(
+                f"LiveRun is already connected on {_active_backend.port}. "
+                "Call LiveStop() before selecting another port."
+            )
+        return _active_session  # type: ignore[return-value]
+
+    chosen_port = _select_port(port)
+    firmware_changed = False
+    try:
+        backend = _try_connect(chosen_port)
+    except LiveDependencyError:
+        raise
+    except LivePortBusyError:
+        # Do not flash a busy port.  A locked COM3 is not evidence of missing
+        # firmware, and attempting upload only masks the actionable problem.
+        raise
+    except LivePortMissingError:
+        raise
+    except LiveConnectionError:
+        if not auto_firmware:
+            raise
+        _upload_live_firmware(chosen_port)
+        firmware_changed = True
+        backend = _connect_after_firmware_upload(chosen_port)
+
+    # A Telemetrix board may answer successfully while running an older server.
+    # LiveRun is validated against one pinned firmware version, so update it
+    # automatically instead of silently accepting an untested protocol.
+    if backend.firmware_version != EXPECTED_FIRMWARE:
+        if not auto_firmware:
+            backend.shutdown()
+            raise LiveRunError(
+                f"LiveRun requires Telemetrix4Arduino {EXPECTED_FIRMWARE}; "
+                f"the board reported {backend.firmware_version}."
+            )
+        backend.shutdown()
+        _upload_live_firmware(chosen_port)
+        firmware_changed = True
+        backend = _connect_after_firmware_upload(chosen_port)
+        if backend.firmware_version != EXPECTED_FIRMWARE:
+            backend.shutdown()
+            raise LiveRunError(
+                f"Arduino reported Telemetrix firmware {backend.firmware_version} after update; "
+                f"expected {EXPECTED_FIRMWARE}."
+            )
+
+    _active_backend = backend
+    _active_session = LiveSession(chosen_port, backend.firmware_version)
+    if not _atexit_registered:
+        atexit.register(LiveStop)
+        _atexit_registered = True
+
+    _say("Barmaja PyArduino LiveRun ready.", style="success")
+    _say(f"Arduino Uno: {chosen_port}")
+    if firmware_changed:
+        _say("LiveRun firmware was installed automatically.", style="success")
+    return _active_session
+
+
+
+def _clean_liverun_error(exc: Exception, selected_port: Optional[str], auto_firmware: bool) -> str:
+    """Map known connection/firmware failures to approved student help text.
+
+    Keep other error families out of this function so genuine programming bugs
+    are still surfaced by Python with their real tracebacks.
+    """
+    from .errors import BoardDetectionError, ToolchainError
+
+    port = (selected_port or "").strip().upper()
+    if isinstance(exc, BoardDetectionError):
+        if exc.reason == "not-found":
+            return "Arduino Uno not detected.\nConnect the Arduino by USB and try again."
+        if exc.reason == "multiple":
+            options = ", ".join(exc.ports)
+            return (
+                "More than one Arduino Uno or possible board was detected.\n"
+                "Disconnect extra boards or choose a port with LiveRun(port='COM3')."
+                + (" Available ports: " + options if options else "")
+            )
+        return "Could not scan for the Arduino Uno.\nCheck the USB connection and Barmaja offline installation."
+    if isinstance(exc, LivePortBusyError) or _port_is_busy(exc):
+        return (
+            "Arduino Uno found on {}, but the port is busy.\n"
+            "Close any program using {} and try again."
+        ).format(port or "the selected port", port or "that port")
+    if isinstance(exc, LivePortMissingError) or _port_is_missing(exc):
+        return "Arduino connection lost.\nReconnect the Arduino and run the program again."
+    if isinstance(exc, LiveDependencyError):
+        return "LiveRun support is missing.\nReinstall the Barmaja PyArduino offline package."
+    if isinstance(exc, LiveConnectionError) and not auto_firmware:
+        return "Could not connect to the Arduino for LiveRun.\nCheck the firmware or enable automatic firmware preparation."
+    if isinstance(exc, (LiveRunError, ToolchainError)):
+        return "Could not prepare the Arduino for LiveRun.\nReconnect the board and try again."
+    raise TypeError("This is not a recognized LiveRun setup error")
+
+
+def _enable_student_error_display() -> None:
+    """Quiet only expected student errors in standard Python.
+
+    Other exception classes are delegated unchanged to the existing hook.
+    Some IDEs (notably embedded PictoBlox) own exception rendering, so a
+    physical PictoBlox check is still necessary.
+    """
+    previous = sys.excepthook
+    if getattr(previous, "_barmaja_liverun_clean_hook", False):
+        return
+
+    def display(exc_type, exc, traceback):
+        if isinstance(exc, LiveStudentError) or getattr(exc, "_barmaja_student_message", False):
+            sys.stderr.write(str(exc).rstrip() + "\n")
+            sys.stderr.flush()
+            return
+        previous(exc_type, exc, traceback)
+
+    display._barmaja_liverun_clean_hook = True
+    sys.excepthook = display
+
+
+def LiveRun(port: Optional[str] = None, *, auto_firmware: bool = True,
+            debug: bool = False) -> LiveSession:
+    """Start LiveRun. ``debug=True`` preserves original technical exceptions.
+
+    Normal startup failures use concise explanations. Technical causes remain
+    accessible through exception chaining and in debug mode.
+    """
+    if debug:
+        return _LiveRun_core(port, auto_firmware=auto_firmware)
+    try:
+        return _LiveRun_core(port, auto_firmware=auto_firmware)
+    except LiveStudentError:
+        raise
+    except Exception as exc:
+        from .errors import BoardDetectionError, ToolchainError
+        if not isinstance(exc, (LiveRunError, BoardDetectionError, ToolchainError)):
+            raise
+        selected_port = port
+        # The selected port is known after detection in most cases, but do not
+        # trigger a second hardware scan just to improve an error message.
+        if not selected_port:
+            # LiveConnectionError / port errors sometimes carry a port name.
+            # Never guess COM3 if the user's board actually has another port.
+            import re
+            match = re.search(r"\bCOM[0-9]+\b", str(exc), re.IGNORECASE)
+            if match:
+                selected_port = match.group(0)
+        _enable_student_error_display()
+        message = _clean_liverun_error(exc, selected_port, auto_firmware)
+        # Preserve exception subclasses used by the recovery protocol and
+        # existing callers/tests. Only the displayed message is rewritten.
+        shown = type(exc)(message) if isinstance(exc, (LivePortBusyError, LivePortMissingError)) else LiveStudentError(message)
+        shown._barmaja_student_message = True
+        raise shown from None
+
+def LiveStop() -> None:
+    """Stop the current LiveRun connection, if one is active."""
+    global _active_backend, _active_session
+    backend = _active_backend
+    _active_backend = None
+    _active_session = None
+    if backend is not None:
+        try:
+            backend.shutdown()
+        except Exception:
+            pass
+
+
+def is_live() -> bool:
+    return _active_backend is not None and not _active_backend._closed
+
+
+def backend() -> _TelemetrixBackend:
+    if _active_backend is None or _active_backend._closed:
+        raise LiveRunError("LiveRun is not active. Add LiveRun() near the top of the program.")
+    return _active_backend