discstation 0.1.40 → 0.1.42

package/README.md

@@ -16,6 +16,31 @@ use every mode.
   (greyed out, auto-collapsing) the moment one appears.
 - **Drive:** ATAPI DVD writer (e.g. iHAS124) over USB
 
+### Updating the remote's firmware (over the air)
+
+No cable needed once a remote runs this firmware: every host release ships the
+matching firmware image (built by `npm publish` via `scripts/build-firmware.sh`).
+When the attached remote is older, the web page and the phone app show
+**"Remote firmware X — Y is available" + UPDATE REMOTE**. The remote downloads the
+image from the host over Wi-Fi, checks its MD5, writes it to its spare firmware
+slot and reboots (about 10 s; the OLED shows progress). It works whether the
+remote is linked by USB or Wi-Fi, as long as it has joined your network, and it
+is refused while a burn/rip/play is running.
+
+- **One cable flash first:** remotes flashed before this feature can't update
+  themselves; the page says so. Flash once with
+  `arduino-cli compile --upload -b esp32:esp32:esp32 -p <port> arduino/DiscStation`
+  and every later update is one click.
+- **Safety:** a corrupt or wrong-checksum image is rejected and the running
+  firmware keeps working. There is no automatic rollback for a firmware that
+  boots but misbehaves - recover with a cable flash. Over Wi-Fi the remote only
+  accepts an image from the host that is already driving it.
+- **Manual fallback (per remote, from any computer):** set `OTA_PASSWORD` in
+  `secrets.h`, then
+  `arduino-cli upload -b esp32:esp32:esp32 -p discstation-xxxx.local --protocol network --upload-field password=<pw> arduino/DiscStation`.
+- **Headroom:** the image uses ~96% of the 1.31 MB app slot; if it grows past
+  that, updates will be refused until the partition scheme is changed (cable flash).
+
 ### Wi-Fi remote (optional)
 
 The firmware also serves the same line protocol over TCP 2323, so the

package/arduino/DiscStation/DiscStation.ino

@@ -8,6 +8,8 @@
 #include <ESPmDNS.h>
 #include <Preferences.h>
 #include <ArduinoOTA.h>
+#include <HTTPClient.h>
+#include <Update.h>
 #include "qrcode_lite.h"
 
 // Optional build-time Wi-Fi override for power users: copy secrets.h.example
@@ -17,6 +19,16 @@
   #include "secrets.h"
 #endif
 
+// Injected by scripts/build-firmware.sh as -DFW_VERSION=x.y.z (an unquoted pp-number,
+// which survives the build system's shell quoting); ad-hoc builds are "dev".
+#define FW_STR_(x) #x
+#define FW_STR(x) FW_STR_(x)
+#ifdef FW_VERSION
+  #define FW_VERSION_STR FW_STR(FW_VERSION)
+#else
+  #define FW_VERSION_STR "dev"
+#endif
+
 #define SCREEN_WIDTH 128
 #define SCREEN_HEIGHT 64
 #define OLED_RESET    -1
@@ -66,6 +78,7 @@ bool wifiConnected = false;
 bool wifiInitDone = false;
 bool portalActive = false;
 bool otaEnabled = false;
+bool msgViaTcp = false;   // which link the message being parsed arrived on (set by drainAndDispatch)
 bool credsJustSaved = false;
 bool wifiResetArmed = false;
 unsigned long wifiDropAt = 0;
@@ -716,6 +729,81 @@ void drawPlay() {
   display.display();
 }
 
+void drawOtaProgress(int pct) {
+  if (!displayOk) return;
+  display.clearDisplay();
+  drawHeader();
+  display.setCursor(2, 18);
+  display.print("UPDATING FIRMWARE");
+  display.drawRect(4, 32, 120, 10, SSD1306_WHITE);
+  display.fillRect(6, 34, (116 * pct) / 100, 6, SSD1306_WHITE);
+  display.setCursor(2, 50);
+  display.print("DO NOT POWER OFF");
+  display.display();
+}
+
+// Host-driven update: "OTA_URL:<http url>|<size>|<md5>". Streams the image into the
+// inactive app slot; Update verifies the MD5 and image header before switching, so a
+// bad download never boots and the running firmware stays.
+void runOta(const String& arg) {
+  int b = arg.lastIndexOf('|');
+  int a = b > 0 ? arg.lastIndexOf('|', b - 1) : -1;
+  if (a <= 0) { Out.println("OTA:ERR bad request"); return; }
+  String url = arg.substring(0, a);
+  size_t size = arg.substring(a + 1, b).toInt();
+  String md5 = arg.substring(b + 1);
+  if (size == 0 || md5.length() != 32) { Out.println("OTA:ERR bad request"); return; }
+  if (!wifiConnected) { Out.println("OTA:ERR remote not on Wi-Fi"); return; }
+  if (msgViaTcp) {
+    // Over Wi-Fi only take an image from the host that is already driving us.
+    String host = url.substring(url.indexOf("//") + 2);
+    host = host.substring(0, host.indexOf('/'));
+    if (host.indexOf(':') > 0) host = host.substring(0, host.indexOf(':'));
+    if (host != tcpClient.remoteIP().toString()) { Out.println("OTA:ERR host mismatch"); return; }
+  }
+  HTTPClient http;
+  http.begin(url);
+  if (http.GET() != 200 || (size_t)http.getSize() != size) {
+    http.end();
+    Out.println("OTA:ERR download");
+    return;
+  }
+  if (!Update.begin(size)) { http.end(); Out.println("OTA:ERR no space"); return; }
+  Update.setMD5(md5.c_str());
+  WiFiClient* stream = http.getStreamPtr();
+  uint8_t buf[1024];
+  size_t done = 0;
+  int lastPct = -1;
+  unsigned long lastData = millis();
+  drawOtaProgress(0);
+  while (done < size) {
+    int n = stream->readBytes(buf, min(sizeof(buf), size - done));
+    if (n <= 0) {
+      if (millis() - lastData > 15000 || !http.connected()) break;
+      continue;
+    }
+    lastData = millis();
+    if (Update.write(buf, n) != (size_t)n) break;
+    done += n;
+    esp_task_wdt_reset();
+    int pct = done * 100 / size;
+    if (pct != lastPct && pct % 5 == 0) {
+      lastPct = pct;
+      Out.print("OTA:"); Out.println(pct);
+      drawOtaProgress(pct);
+    }
+  }
+  http.end();
+  if (done == size && Update.end(true)) {
+    Out.println("OTA:DONE");
+    delay(500);
+    ESP.restart();
+  }
+  Update.abort();
+  Out.println("OTA:ERR verify failed");
+  drawStandby();
+}
+
 void parseMessage(String msg) {
   msg.trim();
 
@@ -726,6 +814,17 @@ void parseMessage(String msg) {
     return;
   }
 
+  if (msg == "VERSION") {
+    Out.print("VERSION:"); Out.println(FW_VERSION_STR);
+    return;
+  }
+
+  if (msg.startsWith("OTA_URL:")) {
+    lastMsgTime = millis();
+    runOta(msg.substring(8));
+    return;
+  }
+
   if (msg.startsWith("VU:")) {
     // No wakeDisplay()/RCV echo here - this arrives ~15x/sec while playing,
     // wakeDisplay() would draw stale bars a frame early, and echoing it
@@ -1201,6 +1300,7 @@ void handlePlayPauseButton(bool longPress) {
 // instead of working through a backlog. Every other message type still gets
 // parsed in order; only VU: is collapsible like this.
 void drainAndDispatch(Stream &s) {
+  msgViaTcp = (&s == (Stream*)&tcpClient);
   String pendingVu = "";
   while (s.available()) {
     String msg = s.readStringUntil('\n');

package/arduino/firmware/firmware.json

@@ -0,0 +1 @@
+{"version":"0.1.42","size":1260592,"md5":"fc62c97a1f9e0bedc579426771789964"}

package/install-macos.sh

@@ -31,6 +31,8 @@ brew install python ffmpeg cdrdao dvdauthor node yt-dlp xorriso mpv libdiscid ha
   libdvdcss dvdbackup libcdio-paranoia
 mkdir -p "$APP_DIR" "$VENV_DIR" "$CONFIG_DIR"
 cp -R "$ROOT_DIR/src/." "$APP_DIR/"
+# remote firmware image for over-the-air updates (built by scripts/build-firmware.sh)
+if [[ -d "$ROOT_DIR/arduino/firmware" ]]; then cp -R "$ROOT_DIR/arduino/firmware" "$APP_DIR/firmware"; fi
 python3 -m venv "$VENV_DIR"
 "$VENV_DIR/bin/python" -m pip install --upgrade pip
 if [[ -f "$ROOT_DIR/requirements.txt" ]]; then

package/install-windows.ps1

@@ -98,6 +98,7 @@ if ($winget -and -not $IsWin7) {
 # --- 3. App files + venv ------------------------------------------------------
 New-Item -ItemType Directory -Force -Path $Base, $App | Out-Null
 Copy-Item -Recurse -Force (Join-Path $Root "src\*") $App
+if (Test-Path (Join-Path $Root "arduino\firmware")) { Copy-Item -Recurse -Force (Join-Path $Root "arduino\firmware") $App }
 & $PyExe @PyArgs -m venv $Venv
 $Py = Join-Path $Venv "Scripts\python.exe"
 & $Py -m pip install --upgrade pip

package/install.sh

@@ -26,6 +26,8 @@ fi
 
 mkdir -p "$APP_DIR" "$CONFIG_DIR" "$VENV_DIR"
 cp -R "$ROOT_DIR/src/." "$APP_DIR/"
+# remote firmware image for over-the-air updates (built by scripts/build-firmware.sh)
+if [[ -d "$ROOT_DIR/arduino/firmware" ]]; then cp -R "$ROOT_DIR/arduino/firmware" "$APP_DIR/firmware"; fi
 if [[ ! -f "$CONFIG_DIR/discstation.env" && -f "$ROOT_DIR/discstation.env.example" ]]; then
   cp "$ROOT_DIR/discstation.env.example" "$CONFIG_DIR/discstation.env"
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discstation",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "DiscStation optical-media appliance host — one cross-OS installer",
   "bin": {
     "discstation-setup": "scripts/setup.mjs",
@@ -8,7 +8,8 @@
   },
   "scripts": {
     "setup": "node scripts/setup.mjs",
-    "postinstall": "node scripts/postinstall.mjs"
+    "postinstall": "node scripts/postinstall.mjs",
+    "prepack": "bash scripts/build-firmware.sh"
   },
   "engines": {
     "node": ">=16"

package/scripts/build-firmware.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Build the release firmware image the host serves to remotes for over-the-air
+# updates (arduino/firmware/discstation.bin + firmware.json). Runs on `npm pack`
+# / `npm publish` (prepack) so a published package always carries an image that
+# matches its version. Needs arduino-cli with the esp32 core.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+command -v arduino-cli >/dev/null || { echo "arduino-cli is required to build the firmware image" >&2; exit 1; }
+
+VERSION=$(node -p "require('./package.json').version")
+OUT=arduino/firmware
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+# Build from a copy without secrets.h so Wi-Fi credentials can never end up in a published image.
+cp -R arduino/DiscStation "$TMP/DiscStation"
+rm -f "$TMP/DiscStation/secrets.h"
+
+rm -rf "$OUT" && mkdir -p "$OUT"
+arduino-cli compile -b esp32:esp32:esp32 \
+  --build-property "compiler.cpp.extra_flags=-DFW_VERSION=$VERSION" \
+  --output-dir "$TMP/out" "$TMP/DiscStation" >/dev/null
+cp "$TMP/out/DiscStation.ino.bin" "$OUT/discstation.bin"
+
+SIZE=$(wc -c <"$OUT/discstation.bin" | tr -d ' ')
+MD5=$( (md5sum "$OUT/discstation.bin" 2>/dev/null || md5 -r "$OUT/discstation.bin") | cut -d' ' -f1)
+printf '{"version":"%s","size":%s,"md5":"%s"}\n' "$VERSION" "$SIZE" "$MD5" >"$OUT/firmware.json"
+echo "firmware $VERSION: $SIZE bytes, md5 $MD5"

package/scripts/check.sh

@@ -55,6 +55,35 @@ try:
     raise SystemExit("cancel not raised")
 except d.CancelError:
     pass
+
+# Remote OTA state: available only for a real, older release; dev builds never nag.
+d._appliance_mode = "hardware"
+d._firmware_image = lambda: (None, {"version": "0.2.0", "size": 1, "md5": "x"})
+for fw, want in (("0.1.0", "available"), ("dev", "current"), ("0.2.0", "current"), ("0.3.0", "current")):
+    d._remote_fw = fw
+    assert d._remote_update_state() == want, (fw, d._remote_update_state())
+d._remote_fw, d._remote_fw_asked = None, 0.0
+assert d._remote_update_state() == "unknown"
+d._appliance_mode = "software"
+assert d._remote_update_state() == ""
+
+# HybridSerial: web side when no remote, replay keeps the current screen, an unplug detaches quietly.
+d._replay.clear()
+for m in ("DISC:Audio CD", "HOME:Select mode", "PLAY_MODE:AUDIO_CD", "PLAY:PLAYING", "VU:1,2", "PING"):
+    d._remember(m)
+assert list(d._replay.values()) == ["DISC:Audio CD", "PLAY_MODE:AUDIO_CD", "PLAY:PLAYING"]
+d._remember("HOME:Select mode")
+assert list(d._replay.values()) == ["DISC:Audio CD", "HOME:Select mode"]
+h = d.HybridSerial()
+h.virtual.push_line("PLAY_BUTTON")
+assert h.in_waiting and h.readline() == b"PLAY_BUTTON\n" and h.write(b"x") == 1
+class Unplugged:
+    @property
+    def in_waiting(self): raise OSError("gone")
+    def close(self): pass
+d._appliance_mode = "hardware"
+h.hw = Unplugged()
+assert h.in_waiting == 0 and h.hw is None and d._appliance_mode == "software"
 print("smoke ok")
 EOF
 )

package/scripts/postinstall.mjs

@@ -75,6 +75,8 @@ if (!existsSync(appDir) || !alreadyInstalled()) {
 
 try {
   cpSync(join(ROOT, 'src'), appDir, { recursive: true, force: true });
+  const fw = join(ROOT, 'arduino', 'firmware');
+  if (existsSync(fw)) cpSync(fw, join(appDir, 'firmware'), { recursive: true, force: true });
   restartService();
   console.log('\ndiscstation: redeployed the updated host and restarted the service.\n');
 } catch (e) {

package/src/discstation.py

@@ -5,6 +5,7 @@ import collections
 import concurrent.futures
 import contextlib
 import errno
+import functools
 try:
     import fcntl  # POSIX-only; used only in drive_status()'s Linux branch
 except ImportError:
@@ -61,6 +62,10 @@ _web_op_verb = "BURNING"  # progress-bar verb for the current PROGRESS: stream
 _operation_active = False  # a burn/rip/play flow is holding the drive
 _last_disc_info = {"disc_present": False, "capacity_bytes": 0, "capacity_gb": 0, "type": "none"}
 _active_ser = None
+_remote_fw = None         # firmware version the attached remote reported (None = old firmware / not asked yet)
+_remote_fw_asked = 0.0    # when VERSION was requested; a silent remote later than this = pre-OTA firmware
+_ota_msg = ""             # last over-the-air update error, shown next to the Update button
+_HTTP_PORT = 0            # plain-HTTP listener port; the remote pulls its firmware image from it
 _appliance_mode = "hardware"  # "hardware" (real ESP32) or "software" (web remote only)
 STATIC_DIR = Path(__file__).resolve().parent / "static"
 
@@ -146,9 +151,14 @@ class TcpSerial:
         self._buf = b""
         self._lock = threading.Lock()
         self._alive = True
+        self.last_rx = time.monotonic()   # link monitor: silent this long = the remote is gone
         self._reader = threading.Thread(target=self._pump, daemon=True)
         self._reader.start()
 
+    def local_addr(self):
+        """This machine's address on the connection to the remote."""
+        return self._sock.getsockname()[0]
+
     def _pump(self):
         while self._alive:
             try:
@@ -159,6 +169,7 @@ class TcpSerial:
                 break
             if not chunk:
                 break
+            self.last_rx = time.monotonic()
             with self._lock:
                 self._buf += chunk
         self._alive = False
@@ -205,10 +216,199 @@ class TcpSerial:
         pass
 
 
-class _HardwareAttached(Exception):
-    """Raised out of station_loop when a real link (USB serial or the Wi-Fi
-    remote) appears while running on a VirtualSerial, so main() can hand
-    control over to it."""
+# What the remote's screen needs to be told again when it is plugged in mid-run:
+# the last message per prefix, so a remote attached during PLAY lands on the PLAY
+# screen instead of "Starting...". Activity messages belong to one operation and are
+# forgotten when a terminal message (back to a menu/standby, done, error) arrives.
+_REPLAY_ACTIVITY = ("PLAY_MODE", "PLAY_STATUS", "PLAY", "STATUS", "PROGRESS", "WAITING",
+                    "INFO", "TITLE", "META", "FIT", "WARNING")
+_REPLAY_TERMINAL = ("HOME", "STANDBY", "DONE", "ERROR", "CANCELLED")
+_REPLAY_STICKY = ("DISC", "DISC_NAME", "MENU_ITEMS", "IP")
+_replay = collections.OrderedDict()
+_replay_lock = threading.Lock()
+
+
+def _remember(msg):
+    prefix = msg.split(":", 1)[0]
+    if prefix in _REPLAY_TERMINAL:
+        drop = _REPLAY_ACTIVITY + _REPLAY_TERMINAL
+    elif prefix in _REPLAY_ACTIVITY:
+        drop = _REPLAY_TERMINAL   # the screen left the menu
+    elif prefix in _REPLAY_STICKY:
+        drop = ()
+    else:
+        return                    # VU frames, PING, VERSION, ...
+    with _replay_lock:
+        for k in drop:
+            _replay.pop(k, None)
+        _replay.pop(prefix, None)  # re-insert so dict order is send order
+        _replay[prefix] = msg
+
+
+class HybridSerial:
+    """The one link object station_loop and every flow hold for the life of the
+    process. It routes to the physical remote (USB serial or Wi-Fi) when one is
+    attached and to the web/app remote otherwise, and the link monitor swaps the
+    remote in and out underneath running flows - so plugging or unplugging it never
+    interrupts a burn/rip/play and never needs station_loop to restart."""
+
+    def __init__(self):
+        self.virtual = VirtualSerial()
+        self.hw = None
+
+    def detach(self, hw):
+        global _appliance_mode, _line_buf
+        if self.hw is not hw:
+            return
+        self.hw = None
+        _appliance_mode = "software"
+        _line_buf = b""
+        discstation_burn.reset_serial_state()
+        try:
+            hw.close()
+        except Exception:
+            pass
+        print("Remote disconnected - the web/app remote is active again.")
+        _sse_publish(_status_snapshot())
+
+    def _through(self, method, *args, default=b""):
+        hw = self.hw
+        if hw is None:
+            return getattr(self.virtual, method)(*args)
+        try:
+            return getattr(hw, method)(*args)
+        except (serial.SerialException, OSError):
+            self.detach(hw)
+            return default
+
+    @property
+    def in_waiting(self):
+        hw = self.hw
+        if hw is None:
+            return self.virtual.in_waiting
+        try:
+            return hw.in_waiting
+        except (serial.SerialException, OSError):
+            self.detach(hw)
+            return 0
+
+    def read(self, n=1):
+        return self._through("read", n)
+
+    def readline(self):
+        return self._through("readline")
+
+    def write(self, data):
+        if self.hw is None:
+            return len(data) if data else 0
+        return self._through("write", data, default=len(data) if data else 0)
+
+    def close(self):
+        hw = self.hw
+        if hw is not None:
+            try:
+                hw.close()
+            except Exception:
+                pass
+
+
+def _open_remote_link(look_for_wifi):
+    """Open the physical remote (USB serial wins, else the Wi-Fi remote) and wait for
+    its boot to finish. Returns the link or None. Runs on the monitor thread only."""
+    port = discstation_host.serial_port()
+    if port:
+        print(f"Using ESP32 serial port: {port}")
+        ser = serial.Serial(port, discstation_burn.BAUD, timeout=1, write_timeout=2)
+        if discstation_host.system_name() == "linux":
+            ser.setDTR(False)
+            time.sleep(0.1)
+            ser.setDTR(True)
+        deadline = time.monotonic() + 6
+        while time.monotonic() < deadline:
+            line = ser.readline().decode(errors="ignore").strip()
+            if line:
+                print(f"ESP32: {line}")
+            if "DISCSTATION_READY" in line:
+                break
+        return ser
+    if look_for_wifi:
+        remote = discstation_host.remote_host()
+        if remote:
+            try:
+                print(f"Connecting to Wi-Fi remote at {remote}:2323 ...")
+                link = TcpSerial(remote)
+                print(f"Wi-Fi remote link up ({remote}).")
+                return link
+            except OSError as e:
+                print(f"Wi-Fi remote {remote} unreachable ({e}); using web remote.")
+    return None
+
+
+def _attach_remote(hybrid, hw):
+    """Bring a freshly opened remote up to date and make it the active link."""
+    global _appliance_mode, _line_buf, _remote_fw, _remote_fw_asked
+    with discstation_burn.SERIAL_WRITE_LOCK:   # flows' sends wait, so none is lost mid-attach
+        with _replay_lock:
+            lines = list(_replay.values())
+        try:
+            for msg in lines + ["VERSION"]:
+                hw.write((msg + "\n").encode())
+        except (serial.SerialException, OSError):
+            try:
+                hw.close()
+            except Exception:
+                pass
+            return
+        _remote_fw, _remote_fw_asked = None, time.time()
+        discstation_burn.reset_serial_state()
+        _line_buf = b""
+        hybrid.hw = hw
+        hybrid.attached_at = time.monotonic()
+        _appliance_mode = "hardware"
+    print("Remote attached - control handed to the hardware remote.")
+    _sse_publish(_status_snapshot())
+
+
+def _link_monitor(hybrid, first_pass=False):
+    """Watches for the remote being plugged in / removed while flows run.
+    Not attached: look for USB every second, the Wi-Fi remote (mDNS) every 5 s.
+    Attached: keep it alive with PINGs and notice a dead link within seconds
+    (USB unplug shows up as an ioctl error at once; a Wi-Fi remote that goes
+    silent for 15 s is treated as gone)."""
+    last_wifi = last_ping = 0.0
+    logged_error = False
+    while True:
+        try:
+            hw = hybrid.hw
+            now = time.monotonic()
+            if hw is None:
+                wifi_due = now - last_wifi >= 5
+                if wifi_due:
+                    last_wifi = now
+                link = _open_remote_link(wifi_due)
+                logged_error = False
+                if link is not None:
+                    _attach_remote(hybrid, link)
+            else:
+                hw.in_waiting   # raises once the device is gone; does not consume bytes
+                silent = now - getattr(hw, "last_rx", now)
+                if silent > 15 and now - getattr(hybrid, "attached_at", now) > 15:
+                    raise serial.SerialException("remote stopped answering")
+                if now - last_ping >= 3:
+                    last_ping = now
+                    with discstation_burn.SERIAL_WRITE_LOCK:
+                        hw.write(b"PING\n")
+        except (serial.SerialException, OSError):
+            if hybrid.hw is not None:
+                hybrid.detach(hybrid.hw)
+            elif not logged_error:
+                logged_error = True
+                print("Remote found but could not be opened yet; retrying.")
+        except Exception as e:
+            print(f"Link monitor error: {e}")
+        if first_pass:
+            return
+        time.sleep(1)
 
 
 class _WebHandler(http.server.BaseHTTPRequestHandler):
@@ -225,6 +425,8 @@ class _WebHandler(http.server.BaseHTTPRequestHandler):
             self._serve_disc_info()
         elif path == '/events':
             self._serve_sse()
+        elif path == '/firmware.bin':
+            self._serve_firmware()
         elif path == '/sw.js':
             self._serve_sw()
         elif path == '/manifest.json':
@@ -246,6 +448,8 @@ class _WebHandler(http.server.BaseHTTPRequestHandler):
             self._handle_set_label()
         elif path == '/remote/button':
             self._handle_remote_button()
+        elif path == '/remote/update':
+            self._handle_remote_update()
         else:
             self.send_error(404)
 
@@ -324,12 +528,47 @@ class _WebHandler(http.server.BaseHTTPRequestHandler):
         if not cmd:
             self._respond(400, 'Missing cmd')
             return
-        if isinstance(_active_ser, VirtualSerial):
-            _active_ser.push_line(cmd)
+        if _active_ser is not None and _active_ser.hw is None:
+            _active_ser.virtual.push_line(cmd)
             self._respond(200, 'OK')
         else:
             self._respond(409, 'A hardware remote is attached')
 
+    def _serve_firmware(self):
+        image, _ = _firmware_image()
+        if not image:
+            self.send_error(404)
+            return
+        data = image.read_bytes()
+        self.send_response(200)
+        self.send_header('Content-Type', 'application/octet-stream')
+        self.send_header('Content-Length', str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def _handle_remote_update(self):
+        """Tell the attached remote to download the firmware image this host ships
+        (OTA_URL:<url>|<size>|<md5>). The remote verifies the MD5 before switching."""
+        global _ota_msg
+        ser = _active_ser
+        image, meta = _firmware_image()
+        if ser is None or ser.hw is None:
+            self._respond(409, 'No hardware remote attached')
+        elif _operation_active:
+            self._respond(409, 'Wait until the current operation finishes')
+        elif not image or not _HTTP_PORT:
+            self._respond(409, 'This host has no firmware image to send')
+        elif _remote_update_state() != "available":
+            self._respond(409, 'The remote is already up to date' if _remote_fw else 'This remote needs one cable flash first')
+        else:
+            # the address the remote reaches us on: for the Wi-Fi link that is the
+            # socket's own local address (also what the firmware checks it against)
+            host = ser.hw.local_addr() if hasattr(ser.hw, "local_addr") else local_ip()
+            _ota_msg = ""
+            discstation_burn.safe_send(ser, f"OTA_URL:http://{host}:{_HTTP_PORT}/firmware.bin|{meta['size']}|{meta['md5']}")
+            _record_ota("0")
+            self._respond(200, 'OK')
+
     def _serve_disc_info(self):
         if _operation_active:
             # a burn/rip/play holds the drive — don't probe it, serve last-known.
@@ -406,7 +645,7 @@ class _WebHandler(http.server.BaseHTTPRequestHandler):
     def _serve_sw(self):
         sw = '''self.addEventListener('install', e => {
   self.skipWaiting();
-  caches.open('discstation-v17').then(c => c.addAll(['/','/static/style.css?v=17','/static/app.js?v=17']));
+  caches.open('discstation-v18').then(c => c.addAll(['/','/static/style.css?v=18','/static/app.js?v=18']));
 });
 self.addEventListener('activate', e => e.waitUntil(clients.claim()));
 self.addEventListener('fetch', e => {
@@ -415,7 +654,7 @@ self.addEventListener('fetch', e => {
   if (path === '/' || path.startsWith('/static/')) {
     e.respondWith(fetch(e.request).then(r => {
       const copy = r.clone();
-      caches.open('discstation-v17').then(c => c.put(e.request, copy));
+      caches.open('discstation-v18').then(c => c.put(e.request, copy));
       return r;
     }).catch(() => caches.match(e.request)));
   } else {
@@ -523,6 +762,7 @@ self.addEventListener('fetch', e => {
 
 
 def start_web_server(port=8080):
+    global _HTTP_PORT
     global _web_server, _web_port
     if _web_server:
         return _web_server
@@ -569,6 +809,7 @@ def start_web_server(port=8080):
             threading.Thread(target=plain.serve_forever, daemon=True).start()
             print(f"Plain HTTP (mobile app) on http://0.0.0.0:{http_port}")
             plain_http_up = True
+            _HTTP_PORT = http_port
         except OSError as e:
             print(f"Plain HTTP listener not started on {http_port}: {e}")
 
@@ -730,10 +971,65 @@ _sse_subs = set()          # of Queue
 _sse_lock = threading.Lock()
 
 
+@functools.lru_cache(maxsize=1)
+def _firmware_image():
+    """(image path, {version,size,md5}) for the remote firmware shipped with this
+    host (scripts/build-firmware.sh), or (None, None)."""
+    here = Path(__file__).resolve().parent
+    for d in (here / "firmware", here.parent / "arduino" / "firmware"):
+        try:
+            meta = json.loads((d / "firmware.json").read_text())
+            if (d / "discstation.bin").is_file():
+                return d / "discstation.bin", meta
+        except (OSError, ValueError):
+            pass
+    return None, None
+
+
+def _remote_update_state():
+    """'' no hardware remote / still asking, 'unknown' the remote never answered
+    VERSION (pre-OTA firmware: needs one cable flash), 'current', 'available'."""
+    if _appliance_mode != "hardware":
+        return ""
+    _, meta = _firmware_image()
+    if _remote_fw is None:
+        return "unknown" if meta and time.time() - _remote_fw_asked > 14 else ""
+    try:
+        newer = tuple(map(int, meta["version"].split("."))) > tuple(map(int, _remote_fw.split(".")))
+    except (TypeError, ValueError):  # "dev" builds (or an unparsable version) never nag
+        newer = False
+    return "available" if newer else "current"
+
+
 def _status_snapshot():
+    _, meta = _firmware_image()
     return {"status": _web_status or "READY", "progress": _web_progress,
             "active": _web_progress_active, "appliance": _appliance_mode,
-            "playing": _web_playing, "tray_open": _tray_open}
+            "playing": _web_playing, "tray_open": _tray_open,
+            "remote_fw": _remote_fw, "remote_fw_latest": meta["version"] if meta else None,
+            "remote_update": _remote_update_state(), "remote_update_msg": _ota_msg}
+
+
+def _set_remote_fw(version):
+    global _remote_fw, _web_status, _web_progress
+    _remote_fw = version
+    if (_web_status or "").startswith("REMOTE UPDATED"):
+        _web_status, _web_progress = "READY", -1
+    _sse_publish(_status_snapshot())
+
+
+def _record_ota(msg):
+    """OTA:<pct> | OTA:DONE | OTA:ERR <why> lines from the remote while it updates."""
+    global _web_status, _web_progress, _web_progress_active, _ota_msg, _remote_fw, _remote_fw_asked
+    if msg.isdigit():
+        _web_status, _web_progress, _web_progress_active = f"UPDATING REMOTE {msg}%", int(msg), True
+    elif msg == "DONE":
+        _web_status, _web_progress, _web_progress_active = "REMOTE UPDATED - RESTARTING", 100, False
+        _remote_fw, _remote_fw_asked = None, time.time()  # the USB link survives the reboot: ask again
+    else:
+        _web_status, _web_progress, _web_progress_active = "REMOTE UPDATE FAILED", -1, False
+        _ota_msg = msg.removeprefix("ERR").strip()
+    _sse_publish(_status_snapshot())
 
 
 def _sse_publish(event):
@@ -760,6 +1056,7 @@ def _set_web_progress(phase, percent=-1):
 
 def _record_web_status(msg):
     global _web_status, _web_progress, _web_progress_active, _web_playing
+    _remember(msg)
     if msg.startswith("DISC:"):
         _sse_publish({"type": "disc-changed"})
         return
@@ -939,23 +1236,9 @@ discstation_burn.line_reader = read_serial_line
 
 
 def check_serial_alive(ser=None):
-    """Raise serial.SerialException if the ESP32 link looks dead, so main()'s
-    reconnect loop can re-scan for the (possibly renumbered) serial port.
-    Call this inside any long poll loop that would otherwise spin forever on a
-    stale handle (writes to a re-enumerated /dev/ttyUSBN fail silently).
-
-    Meaningless (and actively harmful) in pure web/software mode - there's no
-    ESP32 to go quiet, and serial_activity_age() only advances on real
-    incoming bytes, so a user just reading the screen for >35s before
-    clicking the next button on the web remote looked identical to a dead
-    link and killed the burn ("ESP32 not responding") with no ESP32 in the
-    picture at all."""
-    if isinstance(ser, VirtualSerial):
-        return
-    if discstation_burn.serial_write_failed():
-        raise serial.SerialException("serial write failed (ESP32 link lost)")
-    if discstation_burn.serial_activity_age() >= 35:
-        raise serial.SerialException("ESP32 not responding")
+    """Kept for the flows that call it inside long poll loops. The link monitor
+    (_link_monitor) now owns liveness and swaps a dead remote for the web remote
+    without raising, so a lost remote no longer aborts a burn/rip/play."""
 
 
 def send_disc_info(ser, device, status_line=None):
@@ -2944,7 +3227,7 @@ def _vu_loop(ser, stop_event, pause_event):
                 if proc.poll() is not None:
                     break
                 continue
-            if pause_event.is_set():
+            if pause_event.is_set() or ser.hw is None:   # nobody to draw bars for
                 continue
             samples = _np.frombuffer(raw, dtype=_np.int16).astype(_np.float32) / 32768.0
             spectrum = _np.abs(_np.fft.rfft(samples * window))
@@ -2976,9 +3259,9 @@ def _vu_loop(ser, stop_event, pause_event):
 
 def start_vu_visualizer(ser):
     """Best-effort: returns (stop_event, pause_event), or (None, None) if the
-    visualizer can't run here (no numpy, no PulseAudio, or a web-only link).
+    visualizer can't run here (no numpy, no PulseAudio).
     Linux only."""
-    if _np is None or isinstance(ser, VirtualSerial) or discstation_host.system_name() != "linux":
+    if _np is None or discstation_host.system_name() != "linux":
         return None, None
     stop_event = threading.Event()
     pause_event = threading.Event()
@@ -3979,14 +4262,6 @@ def station_loop(ser):
     except Exception:
         device = None  # empty drive (e.g. macOS after an eject) — keep the loop alive
 
-    for _ in range(50):
-        line = read_serial_line(ser, timeout=0.2)
-        if not line:
-            break
-        print(f"ESP32: {line}")
-        if "DISCSTATION_READY" in line:
-            break
-
     safe_send(ser, "STANDBY:Starting...")
 
     last_disc_line = None
@@ -4102,18 +4377,8 @@ def station_loop(ser):
         if now - last_ping >= 5:
             last_ping = now
             safe_send(ser, "PING")
-            if isinstance(ser, VirtualSerial):
-                # Safe point (no flow active) to check whether a real link -
-                # USB serial or the Wi-Fi remote - has appeared, and hand off
-                # to it instead of the web remote.
-                try:
-                    link = discstation_host.serial_port() or discstation_host.remote_host()
-                except Exception:
-                    link = None
-                if link:
-                    raise _HardwareAttached(link)
-            else:
-                check_serial_alive(ser)
+            if _remote_fw is None and ser.hw is not None:
+                safe_send(ser, "VERSION")  # the first ask can land while the remote is still booting
 
             # Slow full classify as a backstop (type changes, stuck "reading...").
             if (not _tray_open and _disc_poll_future is None
@@ -4147,6 +4412,14 @@ def station_loop(ser):
         if line == "PONG":
             continue
 
+        if line.startswith("VERSION:"):
+            _set_remote_fw(line[8:].strip())
+            continue
+
+        if line.startswith("OTA:"):
+            _record_ota(line[4:].strip())
+            continue
+
         if line.startswith("MENU:"):
             print(f"Menu: {line.split(':', 1)[1]}")
             continue
@@ -4209,8 +4482,7 @@ def station_loop(ser):
         # before its own START got consumed (e.g. never uploaded/confirmed a
         # URL), that stale START would otherwise sit buffered and fire this
         # new, different selection instead. Drop anything unconsumed first.
-        if isinstance(ser, VirtualSerial):
-            ser.clear()
+        ser.virtual.clear()
 
         # The user picked a mode — they want to act on a disc, so the drive is
         # fair game again even if it was ejected from the OLED earlier.
@@ -4297,7 +4569,7 @@ def parse_args():
 
 
 def main():
-    global _active_ser, _line_buf, _appliance_mode
+    global _active_ser, _appliance_mode
     signal.signal(signal.SIGTERM, signal.SIG_IGN)
     check_pidfile()
 
@@ -4308,71 +4580,35 @@ def main():
     try:
         start_web_server(args.port)
 
+        # One link object for the life of the process; the monitor thread swaps the
+        # physical remote (USB serial / Wi-Fi) in and out underneath running flows.
+        ser = HybridSerial()
+        _active_ser = ser
+        _appliance_mode = "software"
+        _link_monitor(ser, first_pass=True)   # a remote already plugged in is up before the menu starts
+        if ser.hw is None:
+            print("No ESP32 found - running in software-only mode (web remote).")
+        _sse_publish(_status_snapshot())
+        threading.Thread(target=_link_monitor, args=(ser,), daemon=True).start()
+
         while True:
             try:
-                _line_buf = b""
-                ser = None
-
-                # 1. USB serial wins whenever it's present (no mDNS scan then).
-                port = discstation_host.serial_port()
-                if port:
-                    print(f"Using ESP32 serial port: {port}")
-                    ser = serial.Serial(port, discstation_burn.BAUD, timeout=1, write_timeout=2)
-                    if discstation_host.system_name() == "linux":
-                        ser.setDTR(False)
-                        time.sleep(0.1)
-                        ser.setDTR(True)
-                    time.sleep(2)
-                    discstation_burn.reset_serial_state()
-                    _appliance_mode = "hardware"
-
-                # 2. Else look for a Wi-Fi remote (DISC_REMOTE_HOST, default auto/mDNS).
-                if ser is None:
-                    remote = discstation_host.remote_host()
-                    if remote:
-                        try:
-                            print(f"Connecting to Wi-Fi remote at {remote}:2323 ...")
-                            ser = TcpSerial(remote)
-                            discstation_burn.reset_serial_state()
-                            _appliance_mode = "hardware"
-                            print(f"Wi-Fi remote link up ({remote}).")
-                        except OSError as e:
-                            print(f"Wi-Fi remote {remote} unreachable ({e}); using web remote.")
-                            ser = None
-
-                # 3. Else the on-screen web/app remote is the control surface.
-                if ser is None:
-                    print("No ESP32 found - running in software-only mode (web remote).")
-                    ser = VirtualSerial()
-                    _appliance_mode = "software"
-                _active_ser = ser
-                # Nothing else publishes an SSE update purely for an appliance-
-                # mode flip (STATUS/PROGRESS/etc. events do, this doesn't) - push
-                # one now so a connected web remote learns about a newly-attached
-                # ESP32 immediately instead of only on its next reload.
-                _sse_publish(_status_snapshot())
                 station_loop(ser)
-            except _HardwareAttached:
-                print("ESP32 detected - handing off from the web remote to hardware.")
-            except (serial.SerialException, OSError, termios.error) as e:
-                print(f"Disconnected ({e}), reconnecting in 3s...")
-                time.sleep(3)
             except KeyboardInterrupt:
                 raise
-            finally:
-                _active_ser = None
-                if ser:
-                    try:
-                        ser.close()
-                    except Exception:
-                        pass
-                    ser = None
+            except (serial.SerialException, OSError, termios.error) as e:
+                print(f"Station loop error ({e}), restarting...")
+                time.sleep(1)
     except KeyboardInterrupt:
         print("\nStopped.")
         exit_code = 130
     except Exception as e:
         print(f"Error: {e}")
         exit_code = 1
+    finally:
+        _active_ser = None
+        if ser:
+            ser.close()
 
     if exit_code:
         sys.exit(exit_code)

package/src/static/app.js

@@ -90,6 +90,7 @@
   }
 
   function applyRemoteState(progress) {
+    applyFirmwareState(progress);
     const hardware = progress.appliance === "hardware";
     if (hardware && !$("remote-panel").hidden) setRemoteVisible(false, true);
     // Software mode has no other control surface at all - don't make it
@@ -107,6 +108,32 @@
     ejectBtn.dataset.cmd = open ? "CONFIRM" : "EJECT";
   }
 
+  // Firmware row: outside the remote panel on purpose - a hardware remote hides
+  // that panel, and hardware is exactly when there is a remote to update.
+  function applyFirmwareState(progress) {
+    const state = progress.remote_update;
+    const msg = progress.remote_update_msg;
+    const text = $("fw-update-text");
+    const btn = $("fw-update-btn");
+    const updating = progress.active && /^UPDATING REMOTE/.test(progress.status || "");
+    let line = "";
+    if (state === "available") line = `Remote firmware ${progress.remote_fw} — ${progress.remote_fw_latest} is available.`;
+    else if (state === "unknown") line = "This remote's firmware can't update itself yet — flash it once with a USB cable, then future updates are one click.";
+    if (msg) line += ` Update failed (${msg}).`;
+    text.textContent = line;
+    btn.hidden = state !== "available";
+    btn.disabled = !!updating;
+    $("fw-update").hidden = !line;
+  }
+
+  $("fw-update-btn").addEventListener("click", async () => {
+    $("fw-update-btn").disabled = true;
+    try {
+      const r = await fetch("/remote/update", { method: "POST" });
+      if (!r.ok) $("fw-update-text").textContent = await r.text();
+    } catch (_) { /* SSE/poll shows the real state */ }
+  });
+
   async function sendRemoteCmd(cmd) {
     try {
       await fetch("/remote/button", {

package/src/static/index.html

@@ -28,6 +28,11 @@
     </header>
 
     <main>
+      <section id="fw-update" class="fw-update section-rule" hidden>
+        <p id="fw-update-text" class="field-note"></p>
+        <button id="fw-update-btn" class="outline-button" type="button" hidden>UPDATE REMOTE</button>
+      </section>
+
       <section class="capability-strip section-rule">
         <div><strong>01</strong><span>VIDEO DVD</span></div>
         <div><strong>02</strong><span>DATA DVD</span></div>
@@ -139,7 +144,7 @@
     </footer>
   </div>
   <div id="install-slot"></div>
-  <script>if ("serviceWorker" in navigator) navigator.serviceWorker.register("/sw.js?v=17").catch(() => {});</script>
-  <script src="/static/app.js?v=17" defer></script>
+  <script>if ("serviceWorker" in navigator) navigator.serviceWorker.register("/sw.js?v=18").catch(() => {});</script>
+  <script src="/static/app.js?v=18" defer></script>
 </body>
 </html>