frugal-iot-client 2.0.2 → 2.0.4

package/docs/FLASH_PLAN.md

@@ -678,6 +678,27 @@ polling is involved.
 `Monitor` also works standalone, requesting a port if none is held, so a running board can be watched
 without flashing it. It is stopped before `Connect` since esptool cannot open a port the monitor holds.
 
+It also survives the port going away, and follows the device to the port it comes back as. Chrome
+does not revive a `SerialPort` whose device went away: a board that resets or is replugged on native
+USB re-enumerates and appears as a *new* object, so reopening the one being held fails for ever.
+`monitorCandidates()` therefore asks `navigator.serial.getPorts()` on every attempt and tries each
+granted port whose `getInfo()` matches the device's vendor and product ids, keeping whichever opens -
+and putting it in `state.port`, so Connect and Flash use the live one too. A port that never went
+away is returned by `getPorts()` as the same object, so the ordinary case is unchanged.
+
+A matching USB device is required, never merely a port that happens to be there. A Mac always offers
+Bluetooth-Incoming-Port and debug-console, and quietly monitoring one of those is worse than not
+reconnecting at all; neither has a `usbVendorId`. When the port being held has no vendor id either -
+the user picked something that is not a USB device - there is nothing to match on, so only that port
+is retried rather than guessing at a replacement. A frugal-iot node deep-sleeps between readings, and on native
+USB that takes the serial port with it - the stream ends and the port cannot be opened again until
+the board wakes, which is normal operation rather than a fault. `monitorRun()` therefore loops:
+anything but **Stop** leads back to waiting for the port, retrying every `MonitorRetryMs` and saying
+so once per outage rather than once per attempt. Two things are deliberately first-pass only - the
+RTS pulse that restarts the board (a reconnect must not reset a board that has just woken) and the
+25s silence deadline that catches a wrong monitor speed. After that a `read()` with no deadline is
+exactly right: it settles when the board wakes, or when Stop cancels it.
+
 ### Serial monitor speed
 
 frugal-iot's `startSerial()` picks the rate by toolchain, so the boot log needs a selector rather
@@ -796,6 +817,15 @@ rejects it independently, so we know whether our check is the only guard or a se
 Two related refusals in the same code path are likewise untested: an app larger than the app
 partition, and a `<chip>-<flashsize>` combination absent from `boards.json`.
 
+### The ⚡ across two cards
+
+Since the project's back became cards (CARDS_UX.md 11) the OTA list and the flasher are separate
+`mqtt-admin` elements, and the Flash card is not built until it is opened - so neither can hold a
+reference to the other. The bolt fires `frugaliot:flashfile` on `document`; `mqtt-projectback` opens
+the Flash card, scrolls to it, and calls `flashRemote()` on its `mqtt-admin`, which is the only
+thing that can see the `mqtt-flash` in its own shadow root. The bolt is left out entirely without
+OTAFLASH, since there is then no Flash card for it to open.
+
 ### 8. UI polish
 
 Nothing structural — the flow works but is a little unintuitive. Known rough edges:

package/flash.js

@@ -23,9 +23,15 @@ const FlashBaudRates = [921600, 460800, 230400, 115200];
 // 74880 is the ESP8266 ROM's own boot-message rate
 const MonitorBaudRates = [460800, 115200, 921600, 74880];
 const BootLogMs = 25000; // startSerial() waits 5s before printing, then WiFi/captive portal follows
+// How often the monitor tries the port again while it is gone - a deep sleep is measured in
+// seconds to minutes, so there is nothing to gain from trying harder than this
+const MonitorRetryMs = 1000;
 // esptool-js's readFlash waits FLASH_READ_TIMEOUT (100s) for its first packet, which stalls Connect
 // on any board that does not answer the stub's read command
 const FlashReadMs = 8000;
+// How long to wait for the port to close before saying it did not - esptool-js's disconnect() waits
+// on the streams unlocking with no deadline of its own
+const TransportReleaseMs = 5000;
 // JEDEC capacity byte -> size, mirroring esptool-js's own table so we can tell a real detection from
 // its silent 4MB fallback, which on an S3 is also the signature of unsupported octal flash
 const DetectedFlashSizes = {
@@ -36,6 +42,14 @@ const DetectedFlashSizes = {
   0x39: "32MB", 0x3a: "64MB",
 };
 
+// Promise.race leaves the loser's timer running - on a 25s deadline that holds the event loop long
+// after the answer arrived, which is also what kept the test run alive for half a minute
+function withTimeout(promise, ms, value) {
+  let timer = null;
+  const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve(value), ms); });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
 // 32-byte records: magic u16, type, subtype, offset u32, size u32, label[16], flags u32
 function partitionsParse(bytes) {
   const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
@@ -97,19 +111,29 @@ class MqttFlash extends HTMLElementExtended {
   constructor(props) {
     super(props);
     this.state = {elements: {}, log: [], app: null, device: null, busy: false,
-      baudrate: FlashBaudRates[0], monitorBaudrate: MonitorBaudRates[0]};
+      baudrate: FlashBaudRates[0], monitorBaudrate: MonitorBaudRates[0], monitorRetryMs: MonitorRetryMs};
   }
   get supported() { return 'serial' in navigator; }
   // esploader goes null after flashing, so a second flash needs a reconnect rather than a stale loader
   get ready() {
     return !!(this.state.app && this.state.device && this.state.esploader && !this.state.device.refusal && !this.state.busy);
   }
+  /*
+   * The port stays open until this runs, and WebSerial then refuses the next open with "The port is
+   * already open" - so every path out of a connect or a flash, failed ones included, must reach here.
+   *
+   * disconnect() waits for the streams to unlock with no deadline of its own, so it is bounded:
+   * a reader that never releases would otherwise leave the button disabled with nothing said.
+   */
   async transportRelease() {
-    if (this.state.transport) {
-      try { await this.state.transport.disconnect(); } catch (e) { XXX(`transport disconnect: ${e.message}`); }
-    }
+    const transport = this.state.transport;
     this.state.transport = null;
     this.state.esploader = null;
+    if (!transport) return;
+    const released = transport.disconnect().catch((e) => { XXX(`transport disconnect: ${e.message}`); });
+    if (await withTimeout(released, TransportReleaseMs, 'timeout') === 'timeout') {
+      this.logLine("The serial port did not close - unplug the board or reload the page before connecting again.");
+    }
   }
 
   // ---- logging ----
@@ -151,7 +175,7 @@ class MqttFlash extends HTMLElementExtended {
       this.statusRender();
     });
   }
-  // Called by MqttAdmin when the ⚡ beside a server-hosted OTA file is clicked
+  // Reached from the ⚡ in the OTA card, by way of mqtt-projectback and MqttAdmin.flashRemote
   setRemoteSource(org, path) {
     const url = `/ota_get/${org}/${path}`;
     this.logLine(`Fetching ${url}`);
@@ -172,7 +196,7 @@ class MqttFlash extends HTMLElementExtended {
     this.state.busy = true;
     this.state.error = null;
     this.statusRender();
-    portPromise
+    this.state.connectDone = portPromise // kept so a test can await the click
       .then((port) => this.connectAndInspect(port))
       .catch((e) => {
         this.logLine(`Error: ${e.message}`);
@@ -181,20 +205,24 @@ class MqttFlash extends HTMLElementExtended {
       })
       .then(() => { this.state.busy = false; this.statusRender(); });
   }
+  // A seam: the real thing is 214KB of esptool-js and wants a board on the other end of a port
+  esptoolImport() { return import('esptool-js'); }
   async connectAndInspect(port) {
     await this.monitorStop();      // the monitor holds the port open, so esptool cannot have it
     await this.transportRelease(); // clicking Connect twice must not stack transports on one port
-    const {ESPLoader, Transport} = await import('esptool-js'); // 214KB, so not loaded until first use
+    const {ESPLoader, Transport} = await this.esptoolImport(); // not loaded until first use
     const transport = new Transport(port, true);
     const esploader = new ESPLoader({transport, baudrate: this.state.baudrate, terminal: this.terminal});
+    // Recorded before main(), which opens the port: a failure after that has to be releasable, or
+    // the retry meets a port this element no longer knows it holds
+    this.state.port = port;
+    this.state.transport = transport;
+    this.state.esploader = esploader;
     const description = await esploader.main(); // returns the description, not the chip name
     const chipName = esploader.chip.CHIP_NAME;
     const flashIdCapacity = (await esploader.readFlashId()) >> 16 & 0xff;
     const flashSizeGuessed = !DetectedFlashSizes[flashIdCapacity];
     const flashSize = DetectedFlashSizes[flashIdCapacity] || await esploader.detectFlashSize();
-    this.state.port = port;
-    this.state.transport = transport;
-    this.state.esploader = esploader;
     this.state.device = {chipName, description, flashSize, flashSizeGuessed};
     if (flashSizeGuessed) {
       this.logLine(`WARNING: flash size not recognised (capacity byte 0x${flashIdCapacity.toString(16)}), assuming ${flashSize}`);
@@ -239,8 +267,7 @@ class MqttFlash extends HTMLElementExtended {
   async readFlashBounded(offset, length) {
     const read = this.state.esploader.readFlash(offset, length)
       .catch((e) => { this.logLine(`(read of 0x${offset.toString(16)} failed: ${e.message})`); return null; });
-    const timeout = new Promise((resolve) => setTimeout(() => resolve(null), FlashReadMs));
-    const bytes = await Promise.race([read, timeout]);
+    const bytes = await withTimeout(read, FlashReadMs, null);
     if (!bytes) this.logLine(`(could not read 0x${offset.toString(16)} - skipping inspection)`);
     return bytes;
   }
@@ -419,27 +446,100 @@ class MqttFlash extends HTMLElementExtended {
       XXX(`boot log reset signals: ${e.message}`);
     }
   }
-  // Reopen the port with plain WebSerial and stream it until stopped. Runs indefinitely once the
-  // board is talking - the timeout only covers the case where nothing arrives at all.
+  // Reopen the port with plain WebSerial and stream it until stopped.
   monitorStart() {
     if (this.state.monitoring || !this.state.port) return this.state.monitorDone || Promise.resolve();
     this.state.monitoring = true;
-    this.state.monitorDone = this.monitorStream(this.state.port)
-      .catch((e) => XXX(`monitor stream: ${e.message}`)) // cleanup below must run either way
+    this.state.monitorDone = this.monitorRun(this.state.port)
+      .catch((e) => XXX(`monitor run: ${e.message}`)) // cleanup below must run either way
       .then(() => {
         this.state.monitoring = false;
         this.state.monitorReader = null;
+        this.logLine("---- monitor stopped ----");
         this.statusRender();
       });
     this.statusRender();
     return this.state.monitorDone;
   }
+  /*
+   * A board that deep-sleeps takes its USB serial with it - on native USB the port disappears
+   * mid-log and comes back only when the board wakes - so the monitor has to outlive the port, the
+   * way `pio device monitor` does. Stop is the only thing that ends this loop; every other way a
+   * stream can end leads back to waiting for the port.
+   */
+  async monitorRun(port) {
+    let streamed = false; // a stream has run, so a failure to open is the board going away
+    let waiting = false;  // the outage has been reported: not once a second
+    while (this.state.monitoring) {
+      let err = null;
+      let opened = null;
+      for (const candidate of await this.monitorCandidates(port)) {
+        err = await this.monitorOpen(candidate);
+        if (!err) { opened = candidate; break; }
+      }
+      if (opened) {
+        if (waiting) this.logLine("---- port back ----");
+        waiting = false;
+        port = this.state.port = opened; // Connect and Flash must use the live one too
+        await this.monitorStream(port, !streamed); // only the first pass resets the board
+        streamed = true;
+      } else if (!waiting) {
+        waiting = true;
+        this.logLine(streamed ? `(port gone - waiting for the board: ${err})` : `(could not open port: ${err})`);
+      }
+      if (this.state.monitoring) await this.monitorWait(this.state.monitorRetryMs);
+    }
+  }
+  // Settled early by monitorStop, so Stop is not left waiting out a retry delay
+  monitorWait(ms) {
+    return new Promise((resolve) => {
+      this.state.monitorWake = resolve;
+      setTimeout(resolve, ms);
+    });
+  }
+  /*
+   * A device that re-enumerates comes back as a NEW SerialPort: the object being held stays lost
+   * for good, so reopening it can never succeed - which is why unplugging and plugging back in did
+   * not bring the monitor back, while Connect, which asks for a port afresh, did.
+   *
+   * So each attempt tries every port this page already has permission for that looks like the same
+   * device. The one being held comes first while it is still valid, since getPorts() hands back the
+   * very same object for a device that never went away.
+   */
+  async monitorCandidates(port) {
+    const info = (port && port.getInfo) ? port.getInfo() : {};
+    const granted = (navigator.serial && navigator.serial.getPorts)
+      ? await navigator.serial.getPorts().catch((e) => { XXX(`getPorts: ${e.message}`); return []; })
+      : [];
+    /*
+     * The same USB device and nothing else. A Mac always offers Bluetooth-Incoming-Port and
+     * debug-console, and quietly monitoring one of those is worse than not reconnecting at all -
+     * neither has a usbVendorId, so requiring a matching one rules them out. If the port being held
+     * has no vendor id either, there is nothing to match on and only it is retried: the user picked
+     * it themselves, and a port like that does not re-enumerate anyway.
+     */
+    const sameDevice = info.usbVendorId ? granted.filter((p) => {
+      const i = p.getInfo ? p.getInfo() : {};
+      return i.usbVendorId === info.usbVendorId && i.usbProductId === info.usbProductId
+        && !i.bluetoothServiceClassId;
+    }) : [];
+    return [...sameDevice, port].filter((p, i, all) => p && all.indexOf(p) === i);
+  }
+  async monitorOpen(port) {
+    try {
+      await port.open({baudRate: this.state.monitorBaudrate});
+      return null;
+    } catch (e) {
+      return e.message;
+    }
+  }
   // cancel() settles the pending read(), so no polling is needed to notice the stop
   monitorStop() {
     if (!this.state.monitoring) return Promise.resolve();
     this.state.monitoring = false;
     const reader = this.state.monitorReader;
     if (reader) reader.cancel().catch((e) => XXX(`monitor cancel: ${e.message}`));
+    if (this.state.monitorWake) this.state.monitorWake(); // it may be between attempts rather than reading
     return this.state.monitorDone || Promise.resolve();
   }
   onMonitor() {
@@ -454,32 +554,24 @@ class MqttFlash extends HTMLElementExtended {
       .then((port) => { this.state.port = port; return this.monitorStart(); })
       .catch((e) => { this.state.error = e.message; this.logLine(`Error: ${e.message}`); this.statusRender(); });
   }
-  async monitorStream(port) {
-    const baud = this.state.monitorBaudrate;
-    this.logLine(`---- monitor (${baud} baud) ----`);
-    try {
-      await port.open({baudRate: baud});
-    } catch (e) {
-      this.logLine(`(could not open port: ${e.message})`);
-      return;
-    }
+  // Takes an open port and always closes it, so monitorRun can open it again
+  async monitorStream(port, firstPass) {
+    this.logLine(`---- monitor (${this.state.monitorBaudrate} baud) ----`);
     let reader = null;
     let quiet = true;
     try {
-      await this.bootReset(port);
+      if (firstPass) await this.bootReset(port); // a reconnect must not reset a board that just woke
       if (!port.readable) throw new Error("port has no readable stream");
       const decoder = new TextDecoder();
       reader = port.readable.getReader();
       this.state.monitorReader = reader;
       const quietUntil = Date.now() + BootLogMs;
       while (this.state.monitoring) {
-        // Until the first byte arrives, read() may never resolve, so it needs a deadline. Once the
-        // board is talking, plain read() is right - monitorStop() settles it with cancel().
-        const chunk = quiet
-          ? await Promise.race([
-              reader.read(),
-              new Promise((resolve) => setTimeout(() => resolve('timeout'), Math.max(250, quietUntil - Date.now()))),
-            ])
+        // On the first pass silence is worth reporting - it usually means the wrong speed - and
+        // read() on a quiet port may never resolve, so that needs a deadline. Afterwards the wait
+        // is the point: a sleeping board settles the read when it wakes, and Stop cancels it.
+        const chunk = (quiet && firstPass)
+          ? await withTimeout(reader.read(), Math.max(250, quietUntil - Date.now()), 'timeout')
           : await reader.read();
         if (chunk === 'timeout' || chunk.done) break;
         if (chunk.value && chunk.value.length) {
@@ -488,17 +580,16 @@ class MqttFlash extends HTMLElementExtended {
         }
       }
     } catch (e) {
-      this.logLine(`(monitor ended: ${e.message})`);
+      this.logLine(`(stream ended: ${e.message})`);
     } finally {
       if (reader) {
         try { await reader.cancel(); } catch (e) { XXX(`monitor reader cancel: ${e.message}`); }
         try { reader.releaseLock(); } catch (e) { XXX(`monitor reader release: ${e.message}`); }
       }
       try { await port.close(); } catch (e) { XXX(`monitor port close: ${e.message}`); }
-      if (quiet) {
-        this.logLine("(no output - check the monitor speed, that the build defines ANY_DEBUG, or reconnect: a board on native USB re-enumerates after reset and needs picking again)");
+      if (quiet && firstPass) {
+        this.logLine("(no output yet - check the monitor speed and that the build defines ANY_DEBUG. Still listening: a board on native USB drops the port when it sleeps and is picked up again when it wakes.)");
       }
-      this.logLine("---- monitor stopped ----");
     }
   }
 

package/frugaliot.css

@@ -202,6 +202,8 @@ div.mqtt-text {
         }
         /* The \27f3 beside a heading: still a link, but underlining a glyph reads as a typo. */
         .refresh { text-decoration: none; }
+        /* An OTA row's glyphs: the padding is the whole hit area, so a mis-tap cannot reach delete. */
+        .otaicon { text-decoration: none; padding: 0 0.3em; }
         .message {margin: 0.5em; font-weight: bold; font-size: x-large; }
         /* An enrolment secret is a long unbroken string; without this it runs off a phone. */
         .enrolment__line { word-break: break-all; }

package/package.json

@@ -41,5 +41,5 @@
     "unlink:hee": "rm -f node_modules/html-element-extended && npm install html-element-extended"
   },
   "type": "module",
-  "version": "2.0.2"
+  "version": "2.0.4"
 }

package/test/flash.test.js

@@ -0,0 +1,220 @@
+// The flasher's hold on the serial port. WebSerial refuses a second open of the same port, so the
+// element is the only thing that can close it - and a connect that fails is exactly when it must.
+import './setup.js';
+import { test, describe, before, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+
+let ports; // what a fake Transport did, in order
+
+// A Transport that records rather than talking to a board. `fail` is thrown by main() after the
+// port is open, which is what a board that will not sync looks like.
+function fakeEsptool(fail) {
+  return async () => ({
+    Transport: class {
+      constructor(port) { this.port = port; ports.push('opened'); }
+      async disconnect() { ports.push('closed'); }
+    },
+    ESPLoader: class {
+      constructor(o) { this.transport = o.transport; this.chip = {CHIP_NAME: 'ESP8266', BOOTLOADER_FLASH_OFFSET: 0}; }
+      async main() { if (fail) throw new Error(fail); return 'ESP8266EX'; }
+      async readFlashId() { return 0x16 << 16; } // 4MB, so detectFlashSize is not called
+    },
+  });
+}
+function flashElement(fail) {
+  const flash = document.createElement('mqtt-flash');
+  document.body.append(flash);
+  flash.esptoolImport = fakeEsptool(fail);
+  flash.state.boards = {wholeImageChips: ['ESP8266']}; // stands in for the fetch of boards.json
+  return flash;
+}
+const connectButton = (flash) => [...flash.shadowRoot.querySelectorAll('button')]
+  .find((b) => b.textContent === 'Connect board');
+
+before(async () => { await import('../flash.js'); });
+beforeEach(() => {
+  ports = [];
+  // One SerialPort object for the run, as WebSerial hands back for the same device
+  const port = {};
+  Object.defineProperty(navigator, 'serial',
+    {value: {requestPort: async () => port}, configurable: true});
+});
+afterEach(() => { delete navigator.serial; });
+
+describe('connecting to a board', () => {
+  test('a failure still closes the port, so Connect can be clicked again', async () => {
+    // It could not before: the transport was recorded only after main() succeeded, so the release
+    // on the way out had nothing to release and the retry met "The port is already open"
+    const flash = flashElement('Failed to connect to ESP32: Wrong boot mode detected');
+    connectButton(flash).click();
+    await flash.state.connectDone;
+    assert.deepEqual(ports, ['opened', 'closed']);
+    assert.match(flash.state.log.join('\n'), /Wrong boot mode/, 'the reason should be logged');
+    assert.equal(flash.state.transport, null, 'it should not still hold a transport');
+    assert.ok(!flash.state.busy, 'the button should be live again');
+    flash.remove();
+  });
+
+  test('a second try closes the first attempt before opening again', async () => {
+    const flash = flashElement('Failed to connect to ESP32');
+    connectButton(flash).click();
+    await flash.state.connectDone;
+    connectButton(flash).click();
+    await flash.state.connectDone;
+    assert.deepEqual(ports, ['opened', 'closed', 'opened', 'closed']);
+    flash.remove();
+  });
+
+  test('a board that answers leaves the port held, since flashing needs it', async () => {
+    const flash = flashElement(null);
+    connectButton(flash).click();
+    await flash.state.connectDone;
+    assert.deepEqual(ports, ['opened'], 'it should not have let go');
+    assert.equal(flash.state.device.chipName, 'ESP8266');
+    flash.remove();
+  });
+});
+
+/*
+ * The monitor across a deep sleep. A board on native USB takes the port with it when it sleeps, so
+ * the stream ends and the port cannot be opened again until it wakes - which is the normal case for
+ * a frugal-iot node, not a fault.
+ */
+describe('the serial monitor', () => {
+  // Each entry is one open(): {fail} refuses it, otherwise a stream of `chunks` that then ends the
+  // way `end` says. No end at all leaves the read pending, as a live board does between lines.
+  function fakePort(attempts, info) {
+    const port = {opened: 0, closed: 0, signals: 0, readable: null};
+    if (info) port.getInfo = () => info;
+    port.open = async () => {
+      const a = attempts[port.opened++] || {fail: 'The device has been lost.'};
+      if (a.fail) throw new Error(a.fail);
+      port.readable = new ReadableStream({
+        start(c) {
+          (a.chunks || []).forEach((t) => c.enqueue(new TextEncoder().encode(t)));
+          if (a.end === 'error') c.error(new Error('The device has been lost.'));
+          if (a.end === 'done') c.close();
+        },
+      });
+    };
+    port.close = async () => { port.closed++; port.readable = null; };
+    port.setSignals = async () => { port.signals++; };
+    return port;
+  }
+  function monitoring(attempts, granted, info) {
+    const flash = document.createElement('mqtt-flash');
+    document.body.append(flash);
+    flash.state.monitorRetryMs = 5;  // a second per retry is right for a board, not for a test
+    flash.state.port = fakePort(attempts, info);
+    if (granted) Object.defineProperty(navigator, 'serial',
+      {value: {getPorts: async () => granted()}, configurable: true});
+    flash.monitorStart();
+    return flash;
+  }
+  const ESP32 = {usbVendorId: 0x303a, usbProductId: 0x1001};
+  const log = (flash) => flash.state.log.join('\n');
+  // Stops the monitor before failing: a retry loop left running holds the test runner open
+  async function until(flash, test, what) {
+    for (let i = 0; i < 400 && !test(); i++) await new Promise((r) => setTimeout(r, 5));
+    if (!test()) { await flash.monitorStop(); assert.fail(what); }
+  }
+
+  test('picks the port up again when the board wakes, with no click', async () => {
+    const flash = monitoring([
+      {chunks: ['before sleep\n'], end: 'error'},  // the port goes as the board sleeps
+      {fail: 'The device has been lost.'},         // still asleep
+      {chunks: ['awake again\n']},                 // back, and talking
+    ]);
+    await until(flash, () => log(flash).includes('awake again'), 'the monitor did not come back');
+    assert.match(log(flash), /port gone/, 'it should say why it went quiet');
+    assert.match(log(flash), /---- port back ----/);
+    await flash.monitorStop();
+    assert.equal(flash.state.port.opened, 3);
+    flash.remove();
+  });
+
+  test('follows the device to the new port it comes back as', async () => {
+    // Chrome does not revive a SerialPort whose device went away: a replugged board is a new object,
+    // and reopening the old one fails for ever. This is what a reset or a replug actually looks like.
+    const replugged = fakePort([{chunks: ['back from the dead\n']}], ESP32);
+    const flash = monitoring([{chunks: ['before\n'], end: 'error'}], () => [replugged], ESP32);
+    await until(flash, () => log(flash).includes('back from the dead'), 'it did not find the new port');
+    await flash.monitorStop();
+    assert.equal(flash.state.port, replugged, 'and Connect should now use the live one');
+    flash.remove();
+  });
+
+  test('does not take a different device just because one is plugged in', async () => {
+    const other = fakePort([{chunks: ['not the board you want\n']}],
+      {usbVendorId: 0x1a86, usbProductId: 0x7523}); // a CH340, not our ESP32
+    const flash = monitoring([{chunks: ['before\n'], end: 'error'}], () => [other], ESP32);
+    await until(flash, () => log(flash).includes('port gone'), 'it should be waiting');
+    await new Promise((r) => setTimeout(r, 40));
+    await flash.monitorStop();
+    assert.ok(!log(flash).includes('not the board you want'), 'it monitored the wrong device');
+    flash.remove();
+  });
+
+  test('never picks up a Mac\u2019s Bluetooth or debug-console port', async () => {
+    // Both are always on offer and neither is a board. They have no usbVendorId, which is what rules
+    // them out - silently monitoring one of those is worse than not reconnecting at all.
+    const bluetooth = fakePort([{chunks: ['bluetooth noise\n']}], {});
+    const debugConsole = fakePort([{chunks: ['debug console noise\n']}], {});
+    const flash = monitoring([{chunks: ['before\n'], end: 'error'}],
+      () => [bluetooth, debugConsole], ESP32);
+    await until(flash, () => log(flash).includes('port gone'), 'it should be waiting');
+    await new Promise((r) => setTimeout(r, 40)); // several more attempts, with both on offer
+    await flash.monitorStop();
+    assert.equal(bluetooth.opened, 0, 'it opened the Bluetooth port');
+    assert.equal(debugConsole.opened, 0, 'it opened the debug console');
+    flash.remove();
+  });
+
+  test('retries only the port the user picked when that port is not a USB device', async () => {
+    // Nothing to match on, so there is no safe way to guess a replacement
+    const other = fakePort([{chunks: ['someone else\n']}], ESP32);
+    const flash = monitoring([{chunks: ['before\n'], end: 'error'}], () => [other], {});
+    await until(flash, () => log(flash).includes('port gone'), 'it should be waiting');
+    await new Promise((r) => setTimeout(r, 40));
+    await flash.monitorStop();
+    assert.equal(other.opened, 0, 'it wandered off to another device');
+    flash.remove();
+  });
+
+  test('does not reset the board it reconnects to', async () => {
+    // The first pass pulses RTS to catch the boot log from the start; doing that on a reconnect
+    // would restart a board that had just woken from sleep
+    const flash = monitoring([
+      {chunks: ['boot\n'], end: 'error'},
+      {chunks: ['awake\n']},
+    ]);
+    await until(flash, () => log(flash).includes('awake'), 'no reconnect');
+    const afterFirst = flash.state.port.signals;
+    await flash.monitorStop();
+    assert.ok(afterFirst > 0, 'the first pass should have reset the board');
+    assert.equal(flash.state.port.signals, afterFirst, 'the reconnect should not have');
+    flash.remove();
+  });
+
+  test('says the port is gone once, not once per attempt', async () => {
+    const flash = monitoring([{fail: 'No such port'}]);
+    await until(flash, () => log(flash).includes('could not open port'), 'nothing was said');
+    await new Promise((r) => setTimeout(r, 40)); // several more attempts
+    await flash.monitorStop();
+    assert.equal(log(flash).match(/could not open port/g).length, 1);
+    assert.ok(flash.state.port.opened > 1, 'it should have kept trying');
+    flash.remove();
+  });
+
+  test('Stop ends it while it is waiting for a port that never comes back', async () => {
+    const flash = monitoring([{fail: 'No such port'}]);
+    await until(flash, () => flash.state.port.opened > 1, 'it should be retrying');
+    await flash.monitorStop();
+    assert.equal(flash.state.monitoring, false);
+    const opened = flash.state.port.opened;
+    await new Promise((r) => setTimeout(r, 30));
+    assert.equal(flash.state.port.opened, opened, 'it should have stopped trying');
+    assert.match(log(flash), /---- monitor stopped ----/);
+    flash.remove();
+  });
+});

package/test/graph.test.js

@@ -67,3 +67,24 @@ describe('lines sharing a schema colour are told apart', () => {
     assert.equal(new Set(colors).size, 3);
   });
 });
+
+describe('an axis says what it measures', () => {
+  // graphdataset.graph is the route to a graph that does not need a connected element or a canvas
+  const axisOf = (mt, g) => { mt.graphdataset = { graph: g }; const id = mt.yaxisid; return g.state.scales[id]; };
+
+  test('the title is drawn, and carries the unit symbol', () => {
+    const { projectMt } = mock.runScenario('one-device');
+    const g = new (customElements.get('mqtt-graph'))();
+    const axis = axisOf(projectMt.nodes['esp8266-fb94bb'].groups.sht.topics.temperature, g);
+    assert.equal(axis.title.display, true);
+    assert.equal(axis.title.text, 'Temperature (°C)');
+  });
+
+  test('a reading with no unit in the schema gets a bare name', () => {
+    const { projectMt } = mock.runScenario('one-device');
+    const g = new (customElements.get('mqtt-graph'))();
+    const mt = projectMt.nodes['esp8266-fb94bb'].groups.sht.topics.temperature;
+    mt.units = undefined;
+    assert.equal(axisOf(mt, g).title.text, 'Temperature');
+  });
+});