frugal-iot-client 2.0.5 → 2.0.6

package/docs/FLASH_PLAN.md

@@ -55,7 +55,7 @@ So an ESP32 board needs three extra regions that are **independent of your sketc
 | Piece | Depends on | Per-app? |
 |---|---|---|
 | `bootloader.bin` | chip + flash mode/freq | No |
-| `partitions.bin` | partition scheme (`min_spiffs`, `frugal_8mb`, …) | No |
+| `partitions.bin` | partition scheme (`min_spiffs`, `default_8MB`, …) | No |
 | `boot_app0.bin` | nothing — fixed 8192-byte blob | No |
 | `firmware.bin` | your app | Yes — this is what the OTA tab already stores |
 
@@ -194,18 +194,25 @@ This can be decided with high confidence by reading the flash back before writin
 exposes `readFlash()`, and with the stub loaded, reading ~7 KB is fast.
 
 1. Read 3 KB at `0x8000`. Absent partition-table magic (`AA 50`) → no valid layout → **provision**.
-2. Parse the on-device table and check the **app slot only** — `app0` at `0x10000`, size `0x1E0000`.
-   Differs → the board is laid out for something else → **provision**.
+2. Parse the on-device table and check the **app slot's position only** — `app0` at `0x10000`.
+   Elsewhere → the board is laid out for something else → **provision**. Its size is not compared
+   here; it becomes the limit the image is checked against once one is chosen (see the refusals).
 3. Read 4 bytes at `chip.BOOTLOADER_FLASH_OFFSET`. Not `0xE9` → **provision**.
 4. Read the first 4 KB of the on-device FS partition (offset from *its* table, not ours) and look for
    the littlefs superblock magic — the ASCII string `littlefs`. Present → a filesystem exists worth
    preserving → **app-only**.
 
-Comparing only the app slot rather than the whole table is deliberate, and it's what the fixed app
-geometry buys: a board whose FS partition is a different size than our scheme would produce is still
-perfectly safe to update app-only. That correctly covers a board provisioned by an earlier version of
-this tool, or flashed by hand from PlatformIO with stock `min_spiffs`, instead of needlessly wiping
-its config.
+Comparing only where the app slot starts, rather than the whole table, is deliberate. An app image
+runs from any slot it fits in, so a board laid out differently from our scheme — a bigger app slot,
+a filesystem elsewhere — is still perfectly safe to update app-only. That correctly covers a board
+provisioned by an earlier version of this tool, or flashed by hand from PlatformIO with any stock
+scheme (`min_spiffs`, `default`, `default_8MB`), instead of needlessly wiping its config.
+
+**App-only also resets otadata.** A board that has taken a wireless OTA update may be booting from
+`app1`, and would then ignore the app just written to `app0`. So the app-only path writes
+`boot_app0.bin` at the otadata offset from the *board's own* table — exactly what a PlatformIO
+upload does — which selects `app0` without touching the filesystem. If the table could not be read,
+otadata is left alone and the log says the old firmware may keep booting.
 
 That resolves the "is it virgin?" question definitively. The one residue is step 4's blind spot: a
 matching partition table plus a valid LittleFS **belonging to a different project**. Flash contents
@@ -272,42 +279,40 @@ base/
   partitions/
     min_spiffs.bin               3 KB   — chip-independent (Arduino stock, 4 MB)
     min_spiffs.csv                      — provenance for the above
-    frugal_8mb.bin                      — custom, see below
-    frugal_8mb.csv
-    frugal_16mb.bin
-    frugal_16mb.csv
+    default_8MB.bin                     — Arduino stock, see below
+    default_8MB.csv
+    default_16MB.bin
+    default_16MB.csv
 ```
 
 Target chip set: **ESP8266** (no base needed at all), **ESP32-C3**, **ESP32-S2**, **ESP32-S3**.
 `min_spiffs` for the smaller chips, per Frugal IoT convention.
 
-### Partition schemes: fixed app size, all spare space to LittleFS
-
-Bigger boards get the *same* app partitions as a 4 MB board, with the surplus going to the
-filesystem. Arduino's stock large-flash schemes do the opposite (`default_8MB` gives 3.1 MB app
-slots and only 1.5 MB of FS), so these are custom tables.
-
-Starting from stock `min_spiffs` (4 MB), which is unchanged:
+### Partition schemes: the stock tables PlatformIO uses
 
-| Partition | Type/Subtype | Offset | `min_spiffs` (4 MB) | `frugal_8mb` | `frugal_16mb` |
-|---|---|---|---|---|---|
-| `nvs` | data/nvs | `0x9000` | `0x5000` | `0x5000` | `0x5000` |
-| `otadata` | data/ota | `0xe000` | `0x2000` | `0x2000` | `0x2000` |
-| `app0` | app/ota_0 | `0x10000` | `0x1E0000` | `0x1E0000` | `0x1E0000` |
-| `app1` | app/ota_1 | `0x1F0000` | `0x1E0000` | `0x1E0000` | `0x1E0000` |
-| `spiffs` | data/spiffs | `0x3D0000` | `0x20000` (128 KB) | `0x420000` (4.125 MB) | `0xC20000` (12.125 MB) |
-| `coredump` | data/coredump | *varies* | `0x3F0000` | `0x7F0000` | `0xFF0000` |
+Every scheme is Arduino's own, unmodified, so a board provisioned here has exactly the table a
+PlatformIO upload of the matching env writes. That is the point: a USB upload from PlatformIO onto a
+board provisioned here — or the reverse — rewrites the table with an identical one, and the
+filesystem (with the board's WiFi and MQTT config) stays where it is.
 
-App partitions stay 64 KB-aligned and the FS partition stays 4 KB-aligned in all three, and each
-table sums exactly to its flash size.
+| Partition | Type/Subtype | `min_spiffs` (4 MB) | `default_8MB` | `default_16MB` |
+|---|---|---|---|---|
+| `nvs` | data/nvs | `0x9000` `0x5000` | `0x9000` `0x5000` | `0x9000` `0x5000` |
+| `otadata` | data/ota | `0xe000` `0x2000` | `0xe000` `0x2000` | `0xe000` `0x2000` |
+| `app0` | app/ota_0 | `0x10000` `0x1E0000` | `0x10000` `0x330000` | `0x10000` `0x640000` |
+| `app1` | app/ota_1 | `0x1F0000` `0x1E0000` | `0x340000` `0x330000` | `0x650000` `0x640000` |
+| `spiffs` | data/spiffs | `0x3D0000` `0x20000` | `0x670000` `0x180000` | `0xC90000` `0x360000` |
+| `coredump` | data/coredump | `0x3F0000` `0x10000` | `0x7F0000` `0x10000` | `0xFF0000` `0x10000` |
 
-**Two consequences worth relying on:**
+**What is relied on:** `app0` is at `0x10000` in every scheme, so the app-only path always writes
+there. Its size varies, and an image fits any slot it is no bigger than — so the same
+`firmware.bin` from a 4 MB build flashes to an 8 or 16 MB board, and a wireless OTA moves it between
+`app0` and `app1` regardless. The image is checked against the slot actually on the board.
 
-1. **The app image is flash-size-independent.** `app0` has the same offset *and* size in every
-   scheme, so one `firmware.bin` flashes to a 4, 8 or 16 MB board. The OTA files in the tab need no
-   per-size variants, and the app-only path always writes at `0x10000`.
-2. **A 1.875 MB app slot is generous** and unchanged from what 4 MB boards already run, so nothing
-   about existing builds needs revisiting.
+An earlier version of this plan used custom `frugal_8mb`/`frugal_16mb` tables (`min_spiffs` app
+slots, all surplus to LittleFS). They were dropped because the firmware's PlatformIO envs build for
+the board default, and a PlatformIO upload onto a board provisioned with a different table moves the
+filesystem and loses its config.
 
 **Keep the label `spiffs`, even though the content is LittleFS.** Arduino's LittleFS mounts by
 partition label, defaulting to `"spiffs"`
@@ -315,10 +320,9 @@ partition label, defaulting to `"spiffs"`
 Renaming the partition to `littlefs` would stop the firmware mounting it unless `begin()` is also
 changed. Not worth the coupling.
 
-These CSVs are Frugal IoT's own, so they belong in the **firmware** repo (so builds can reference them
-via `board_build.partitions`), with the generated `.bin` plus a copy of the `.csv` committed here for
-the flasher. Generate with the core's `tools/gen_esp32part.py`, or just harvest
-`.pio/build/<env>/partitions.bin` from a build configured with that CSV.
+The `.csv` files are copied from the core's `tools/partitions/`, and the `.bin` generated from them
+with the core's `tools/gen_esp32part.py` — or harvested from `.pio/build/<env>/partitions.bin` of a
+build using that scheme.
 
 `boards.json` maps a detected `<chip>-<flashsize>` to the parts to use, so lookup after detection is
 a single key:
@@ -329,8 +333,8 @@ a single key:
     "ESP32-C3-4MB": "min_spiffs",
     "ESP32-S2-4MB": "min_spiffs",
     "ESP32-S3-4MB": "min_spiffs",
-    "ESP32-S3-8MB": "frugal_8mb",
-    "ESP32-S3-16MB": "frugal_16mb"
+    "ESP32-S3-8MB": "default_8MB",
+    "ESP32-S3-16MB": "default_16MB"
   },
   "bootloaderByChip": {
     "ESP32-C3": "bootloader/esp32c3.bin",
@@ -380,8 +384,8 @@ support without touching the client code:
 
 1. Build the firmware for the board.
 2. If the **chip** is new, copy `bootloader.bin` to `base/bootloader/<chip>.bin`.
-3. If the **flash size** is new, write a CSV following the table above — same app partitions, all
-   surplus to `spiffs` — and commit both it and the generated `.bin` to `base/partitions/`.
+3. If the **flash size** is new, copy the core's stock CSV for it — the one the board's PlatformIO
+   env uses — and commit both it and the generated `.bin` to `base/partitions/`.
 4. Add one `"<CHIP>-<SIZE>": "<scheme>"` line to `schemeByChipAndSize`.
 
 `boot_app0.bin` never needs touching, and the app binary never needs rebuilding for a different flash
@@ -397,8 +401,10 @@ All four are **refusals, not warnings** — a bad combination here means a board
 2. App image: byte 0 == `0xE9`, and for ESP32-family images `chip_id` (u16 LE at offset 12) ==
    `esploader.chip.IMAGE_CHIP_ID` (0=ESP32, 2=S2, 5=C3, 9=S3, 12=C2, 13=C6, 16=H2 — the ROM classes
    expose it). This catches the classic "C3 build onto a D1 Mini".
-3. App byte length ≤ app-slot size from the parsed partition table. Catches a `min_spiffs` app
-   dropped onto a `default`-scheme board.
+3. App byte length ≤ app-slot size — the board's own slot for an app-only write, the base scheme's
+   when provisioning. Catches a `default_8MB` build too big for a `min_spiffs` board. A too-big image
+   is refused rather than provisioned automatically, since provisioning erases the board's config;
+   the message says when "Provision instead" would make it fit.
 4. `detectFlashSize()` must produce a `<chip>-<flashsize>` key present in `schemeByChipAndSize` — and
    if the size came from the `"4MB"` fallback, require confirmation (and on an S3, warn about octal
    flash).
@@ -847,9 +853,8 @@ Nothing structural — the flow works but is a little unintuitive. Known rough e
   fact rather than a guess.
 - Confirm `writeFlash` tolerates an omitted `calculateMD5Hash` (see Client change 7).
 - **Ship 4 MB only at first.** Larger boards are still more expensive and not seen in practice, so
-  `min_spiffs` is the only scheme that needs to work on day one. The `frugal_8mb` / `frugal_16mb`
-  tables above are specified so they *can* be added without redesign, but they should be generated and
-  tested by someone holding the hardware rather than committed untested — an unlisted
+  `min_spiffs` is the only scheme that needs to work on day one. `default_8MB` / `default_16MB` are
+  the stock tables, but provisioning with them is untested on real hardware — an unlisted
   `<chip>-<flashsize>` already fails cleanly as "unsupported board".
 - Whether an ESP32-S2 `bootloader.bin` is worth harvesting up front, given `ARDUINO_LOLIN_S2_MINI`
   appears in the firmware but may not be in active use.

package/flash.js

@@ -13,9 +13,11 @@ const PartitionTableOffset = 0x8000;
 const PartitionTableMagic = 0x50aa; // AA 50 on the wire
 const PartitionType = {app: 0x00, data: 0x01};
 const PartitionSubtype = {factory: 0x00, ota0: 0x10, otadata: 0x00, spiffs: 0x82, littlefs: 0x83};
-// Every Frugal IoT scheme keeps app0 here, so one firmware.bin suits any flash size - see FLASH_PLAN.md
+// Every Arduino scheme keeps app0 here; only its size varies, and an image fits any slot it is no
+// bigger than - see FLASH_PLAN.md
 const AppPartitionOffset = 0x10000;
-const AppPartitionSize = 0x1e0000;
+// The smallest app0 we provision (min_spiffs) - the limit when the board's own table is unreadable
+const AppPartitionSizeMin = 0x1e0000;
 const ImageMagic = 0xe9;
 const LittleFsMagic = [0x6c, 0x69, 0x74, 0x74, 0x6c, 0x65, 0x66, 0x73]; // "littlefs" in the superblock
 const FlashBaudRates = [921600, 460800, 230400, 115200];
@@ -238,7 +240,6 @@ class MqttFlash extends HTMLElementExtended {
       dev.wholeImage = true;                 // ESP8266 firmware.bin is a complete image at 0x0
       dev.provision = false;                 // and does not overlap the filesystem
       dev.appAddress = 0x0;
-      dev.appLimit = null;
       return;
     }
     const scheme = boards.schemeByChipAndSize[`${dev.chipName}-${dev.flashSize}`];
@@ -255,11 +256,14 @@ class MqttFlash extends HTMLElementExtended {
       partitions: {url: partUrl(boards.partitionsByScheme[scheme]), address: boards.partitionTableOffset},
       otadata: {url: partUrl(boards.otadata), address: null}, // from the partition table below
     };
+    // Fetched now rather than at flash time, so the size check knows the base's app slot
+    const baseApp = partitionApp(partitionsParse(await fetchBytes(dev.base.partitions.url)));
+    dev.base.appSize = baseApp ? baseApp.size : AppPartitionSizeMin;
     // The filesystem partition is deliberately left erased - the firmware's LittleFS.begin(true)
     // formats it on first boot. See FLASH_PLAN.md: it only appeared unable to when we were writing a
     // bootloader from the wrong framework.
     dev.appAddress = AppPartitionOffset;
-    dev.appLimit = AppPartitionSize;
+    dev.onDeviceAppSize = AppPartitionSizeMin;
     await this.deviceInspect();
   }
   // Returns null rather than stalling, so a board that will not answer the stub's read command does
@@ -287,6 +291,7 @@ class MqttFlash extends HTMLElementExtended {
       dev.inspected = false;
       dev.provision = false;
       this.logLine("Could not inspect the board - assuming it is already provisioned. Use \"Provision instead\" if this is a new board.");
+      this.logLine("Without its partition table otadata cannot be reset, so a board that has taken an OTA update may keep booting the old firmware.");
       return;
     }
     dev.inspected = true;
@@ -295,8 +300,13 @@ class MqttFlash extends HTMLElementExtended {
     const app = partitionApp(onDeviceParts);
     if (!onDeviceParts.length) reasons.push("no partition table");
     else if (!app) reasons.push("no app partition");
-    // Only the app slot has to match - a differently sized filesystem is still safe to keep
-    else if (app.offset !== AppPartitionOffset || app.size !== AppPartitionSize) reasons.push("app partition differs");
+    // Only the app slot's position has to match - its size is checked against the image at flash
+    // time, and a differently laid out filesystem is still safe to keep
+    else if (app.offset !== AppPartitionOffset) reasons.push("app partition not at 0x10000");
+    if (app) dev.onDeviceAppSize = app.size;
+    // Only an ota_0 slot is selected through otadata - a factory app boots without it
+    const otadata = partitionOtadata(onDeviceParts);
+    if (app && app.subtype === PartitionSubtype.ota0 && otadata) dev.onDeviceOtadataOffset = otadata.offset;
     // Worth always logging - a layout that disagrees with the base explains most boot failures
     if (onDeviceParts.length) {
       this.logLine("On-device partition table:");
@@ -359,8 +369,15 @@ class MqttFlash extends HTMLElementExtended {
       if (chipId !== this.state.esploader.chip.IMAGE_CHIP_ID) {
         throw new Error(`${this.state.app.name} was built for chip id ${chipId}, but this board is ${dev.chipName} (chip id ${this.state.esploader.chip.IMAGE_CHIP_ID})`);
       }
-      if (dev.appLimit && bytes.length > dev.appLimit) {
-        throw new Error(`${this.state.app.name} is ${bytesToSizeString(bytes.length)}, larger than the ${bytesToSizeString(dev.appLimit)} app partition`);
+      // Not provisioned automatically: that erases the board's configuration, so it is the user's call
+      if (dev.provision && bytes.length > dev.base.appSize) {
+        throw new Error(`${this.state.app.name} is ${bytesToSizeString(bytes.length)}, larger than the ${bytesToSizeString(dev.base.appSize)} app partition of ${dev.scheme}`);
+      }
+      if (!dev.provision && bytes.length > dev.onDeviceAppSize) {
+        const fix = bytes.length <= dev.base.appSize
+          ? ` - "Provision instead" would lay it out as ${dev.scheme}, but erases its configuration`
+          : "";
+        throw new Error(`${this.state.app.name} is ${bytesToSizeString(bytes.length)}, larger than the ${bytesToSizeString(dev.onDeviceAppSize)} app partition on this board${fix}`);
       }
     }
     if (dev.flashSizeGuessed && !this.state.confirmed) {
@@ -381,6 +398,9 @@ class MqttFlash extends HTMLElementExtended {
       files.push({data: partitions, address: dev.base.partitions.address});
       files.push({data: otadata, address: otadataPart.offset});
       dev.verifyAddress = dev.base.partitions.address; // read back below to confirm the write landed
+    } else if (!dev.wholeImage && dev.onDeviceOtadataOffset != null) {
+      // After an OTA update the board boots app1, so the app written to app0 would never run
+      files.push({data: await fetchBytes(dev.base.otadata.url), address: dev.onDeviceOtadataOffset});
     }
     files.push({data: this.state.app.bytes, address: dev.appAddress});
     return files;

package/frugaliot.css

@@ -193,6 +193,8 @@ div.mqtt-text {
     }
 
 
+@keyframes fi-spin { to { transform: rotate(360deg); } }
+
 /* Related to authentication */
     .mqtt-admin {
         .pseudolink {
@@ -201,7 +203,9 @@ div.mqtt-text {
             cursor: pointer;
         }
         /* The \27f3 beside a heading: still a link, but underlining a glyph reads as a typo. */
-        .refresh { text-decoration: none; }
+        .refresh { text-decoration: none; display: inline-block; margin-left: 0.3em; }
+        /* Spins until the fetch it started replies - on a slow link a still glyph got clicked again and again. */
+        .refresh.busy { animation: fi-spin 1s linear infinite; cursor: progress; }
         /* 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; }

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.5"
+  "version": "2.0.6"
 }

package/test/cardui.test.js

@@ -237,6 +237,16 @@ describe('back mode', () => {
     card.remove();
   });
 
+  test('a control that is not a hysteresis still shows its topics to wire', () => {
+    const { card } = cardFor('display-control', 'esp32-48ed20', { mode: 'back', at: T0 });
+    const titles = [...card.querySelectorAll('.fi-section__title')].map((h) => h.textContent);
+    assert.ok(titles.includes('LCD SHT'), `no LCD section in ${titles}`);
+    for (const leaf of ['temperature', 'humidity', 'message']) {
+      assert.ok(card.querySelector(`[topic$="control_lcd_ht/${leaf}"]`), `no widget for ${leaf}`);
+    }
+    card.remove();
+  });
+
   test('nothing but Advanced is collapsed', () => {
     const { card } = cardFor('control-wired', 'esp8266-fb94bb', { mode: 'back', at: T0 });
     assert.equal(card.querySelectorAll('details').length, 1);

package/test/fixtures/config.json

@@ -206,6 +206,141 @@
      }
     ]
    },
+   "control_lcd_ht": {
+    "summary": false,
+    "name": "LCD SHT",
+    "topics": [
+     {
+      "leaf": "temperature",
+      "leaf_from": "controlfloat",
+      "name": "Temperature",
+      "min": -40,
+      "max": 85,
+      "color": "#ff0000"
+     },
+     {
+      "leaf": "humidity",
+      "leaf_from": "controlfloat",
+      "name": "Humidity",
+      "color": "#0000ff"
+     },
+     {
+      "leaf": "message",
+      "leaf_from": "controltext",
+      "name": "Message",
+      "rw": "r"
+     }
+    ]
+   },
+   "control_oled_gps": {
+    "summary": false,
+    "name": "OLED GPS",
+    "topics": [
+     {
+      "leaf": "latitude",
+      "leaf_from": "controlfloat",
+      "name": "Latitude",
+      "min": -90,
+      "max": 90,
+      "width": 10,
+      "color": "#0000ff"
+     },
+     {
+      "leaf": "longitude",
+      "leaf_from": "controlfloat",
+      "name": "Longitude",
+      "min": -180,
+      "max": 180,
+      "width": 11,
+      "color": "#0000ff"
+     },
+     {
+      "leaf": "altitude",
+      "leaf_from": "controlfloat",
+      "name": "Altitude",
+      "min": -500,
+      "max": 9000,
+      "width": 6,
+      "color": "#008000"
+     },
+     {
+      "leaf": "speed",
+      "leaf_from": "controlfloat",
+      "name": "Speed",
+      "max": 999,
+      "color": "#ffa500"
+     },
+     {
+      "leaf": "course",
+      "leaf_from": "controlfloat",
+      "name": "Course",
+      "max": 360
+     },
+     {
+      "leaf": "satellites",
+      "leaf_from": "controlfloat",
+      "name": "Satellites",
+      "max": 32
+     },
+     {
+      "leaf": "hdop",
+      "leaf_from": "controlfloat",
+      "name": "HDOP",
+      "max": 50
+     }
+    ]
+   },
+   "control_oled_ht": {
+    "summary": false,
+    "name": "OLED HT",
+    "topics": [
+     {
+      "leaf": "temperature",
+      "leaf_from": "controlfloat",
+      "name": "Temperature",
+      "max": 50,
+      "color": "#ff0000"
+     },
+     {
+      "leaf": "humidity",
+      "leaf_from": "controlfloat",
+      "name": "Humidity",
+      "color": "#0000ff"
+     },
+     {
+      "leaf": "battery",
+      "leaf_from": "controlfloat",
+      "name": "Battery",
+      "max": 5000,
+      "color": "#00ff00"
+     }
+    ]
+   },
+   "control_oled_loramesher": {
+    "summary": false,
+    "name": "OLED LoRaMesher",
+    "topics": [
+     {
+      "leaf": "battery",
+      "leaf_from": "controlfloat",
+      "name": "Battery",
+      "max": 5000,
+      "color": "#00ff00"
+     }
+    ]
+   },
+   "control_oled_single": {
+    "summary": false,
+    "name": "OLED",
+    "topics": [
+     {
+      "leaf": "value",
+      "leaf_from": "controlfloat",
+      "name": "Value",
+      "max": 10000
+     }
+    ]
+   },
    "controlblinken": {
     "name": "Control Blinken",
     "topics": [
@@ -415,6 +550,24 @@
      }
     ]
    },
+   "hcsr04": {
+    "name": "HC-SR04 Distance",
+    "topics": [
+     {
+      "leaf": "hcsr04",
+      "leaf_from": "ultrasonic",
+      "max": 4000
+     },
+     {
+      "leaf": "temperature",
+      "leaf_from": "controlfloat",
+      "name": "Air Temperature",
+      "min": -20,
+      "max": 50,
+      "color": "#ff0000"
+     }
+    ]
+   },
    "health": {
     "name": "System",
     "insidefrugaliot": true,
@@ -838,14 +991,16 @@
       "leaf_from": "controlfloat",
       "name": "Battery",
       "min": 0,
-      "max": 16000
+      "max": 16000,
+      "log": true
      },
      {
       "leaf": "panel",
       "leaf_from": "controlfloat",
       "name": "Panel",
       "min": 0,
-      "max": 30000
+      "max": 30000,
+      "log": true
      },
      {
       "leaf": "profile",
@@ -889,6 +1044,18 @@
      }
     ]
    },
+   "time": {
+    "name": "Time",
+    "insidefrugaliot": true,
+    "topics": [
+     {
+      "leaf": "epoch"
+     },
+     {
+      "leaf": "offset"
+     }
+    ]
+   },
    "ultrasonic": {
     "name": "Ultrasonic Distance",
     "topics": [
@@ -1178,6 +1345,16 @@
     "rw": "r",
     "graphable": true
    },
+   "epoch": {
+    "leaf": "epoch",
+    "name": "Epoch",
+    "type": "int",
+    "log": false,
+    "display": "text",
+    "color": "#000000",
+    "rw": "r",
+    "units": "s"
+   },
    "gas": {
     "leaf": "gas",
     "name": "Gas Resistance",
@@ -1412,6 +1589,16 @@
     "rw": "w",
     "retain": true
    },
+   "offset": {
+    "leaf": "offset",
+    "name": "UTC Offset",
+    "type": "int",
+    "log": false,
+    "display": "text",
+    "color": "#000000",
+    "rw": "r",
+    "units": "min"
+   },
    "on": {
     "leaf": "on",
     "name": "On",

package/test/flash.test.js

@@ -1,8 +1,9 @@
 // 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 { test, describe, before, after, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
 
 let ports; // what a fake Transport did, in order
 
@@ -218,3 +219,87 @@ describe('the serial monitor', () => {
     flash.remove();
   });
 });
+
+/*
+ * Provision vs app-only, against real partition tables from base/. A board is only re-laid out when
+ * its app slot is somewhere else - a different size is checked against the image instead, since
+ * provisioning erases the board's configuration.
+ */
+describe('flashing over a board that is already laid out', () => {
+  const readBase = (p) => new Uint8Array(readFileSync(new URL(`../base/${p}`, import.meta.url)));
+  const boards = JSON.parse(readFileSync(new URL('../base/boards.json', import.meta.url), 'utf8'));
+  let writes;
+  // An 8MB S3 whose flash holds `table` at 0x8000, a bootloader, and an erased filesystem
+  function fakeS3(table) {
+    return async () => ({
+      Transport: class { async disconnect() {} },
+      ESPLoader: class {
+        constructor() { this.chip = {CHIP_NAME: 'ESP32-S3', BOOTLOADER_FLASH_OFFSET: 0, IMAGE_CHIP_ID: 9}; }
+        async main() { return 'ESP32-S3'; }
+        async readFlashId() { return 0x17 << 16; }
+        async readFlash(offset, length) {
+          const block = new Uint8Array(length).fill(0xff);
+          if (offset === 0) block[0] = 0xe9;
+          if (offset === 0x8000) block.set(table.subarray(0, length));
+          return block;
+        }
+        async writeFlash({fileArray}) { writes.push(...fileArray.map((f) => f.address)); }
+        async after() {}
+      },
+    });
+  }
+  async function connected(table) {
+    const flash = document.createElement('mqtt-flash');
+    document.body.append(flash);
+    flash.esptoolImport = fakeS3(table);
+    flash.state.boards = boards;
+    flash.monitorStart = () => {};
+    await flash.connectAndInspect({});
+    return flash;
+  }
+  const image = (size) => { const b = new Uint8Array(size); b[0] = 0xe9; b[12] = 9; return b; };
+  let realFetch;
+  before(() => {
+    realFetch = globalThis.fetch;
+    globalThis.fetch = async (url) => {
+      const bytes = readBase(String(url).replace(/^\.\/base\//, '').replace(/\?.*$/, ''));
+      return {ok: true, arrayBuffer: async () => bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)};
+    };
+  });
+  after(() => { globalThis.fetch = realFetch; });
+  beforeEach(() => { writes = []; });
+
+  test('a board on a bigger app slot than our scheme is updated app-only, keeping its config', async () => {
+    const flash = await connected(readBase('partitions/default_8MB.bin'));
+    assert.equal(flash.state.device.provision, false, flash.state.log.join('\n'));
+    flash.state.app = {name: 'firmware.bin', bytes: image(0x200000)}; // too big for min_spiffs, fits here
+    await flash.flash();
+    assert.deepEqual(writes, [0xe000, 0x10000], 'otadata reset, then the app - nothing else');
+    flash.remove();
+  });
+
+  test('an app-only write resets otadata where the board says, so it boots app0 and not an older app1', async () => {
+    const flash = await connected(readBase('partitions/min_spiffs.bin'));
+    flash.state.app = {name: 'firmware.bin', bytes: image(0x1000)};
+    await flash.flash();
+    assert.ok(writes.includes(0xe000), 'otadata should have been written');
+    flash.remove();
+  });
+
+  test('an image too big for the board is refused, not provisioned behind the user’s back', async () => {
+    const flash = await connected(readBase('partitions/min_spiffs.bin'));
+    flash.state.app = {name: 'firmware.bin', bytes: image(0x200000)};
+    await assert.rejects(flash.flash(), /larger than the 1\.88MB app partition on this board - "Provision instead"/);
+    assert.deepEqual(writes, []);
+    flash.remove();
+  });
+
+  test('a board whose app slot is somewhere else is provisioned', async () => {
+    const table = readBase('partitions/min_spiffs.bin').slice();
+    new DataView(table.buffer).setUint32(2 * 32 + 4, 0x20000, true); // app0 is the third record
+    const flash = await connected(table);
+    assert.equal(flash.state.device.provision, true);
+    assert.deepEqual(flash.state.device.provisionReasons, ['app partition not at 0x10000']);
+    flash.remove();
+  });
+});