From 2398004e67443e7f21aac9e6d3e700093a4e9364 Mon Sep 17 00:00:00 2001 From: mikecarper Date: Sun, 6 Sep 2026 21:31:44 -0700 Subject: [PATCH] Clarify RAK firmware picker storage choices --- docs/_javascript/firmware_picker.js | 31 +++++++++++++++++++++-------- docs/firmware_picker.md | 11 +++++++--- test/test_firmware_picker.js | 2 +- 3 files changed, 32 insertions(+), 12 deletions(-) diff --git a/docs/_javascript/firmware_picker.js b/docs/_javascript/firmware_picker.js index 5031d76ba..008099b74 100644 --- a/docs/_javascript/firmware_picker.js +++ b/docs/_javascript/firmware_picker.js @@ -796,7 +796,7 @@ return String(value || "").replace(/_/g, " ").replace(/\s+/g, " ").trim(); } - function humanizeVariant(value) { + function humanizeVariant(value, hardware) { if (!value || value === "default") return "Default"; const tokenLabels = { ps: "Power save", @@ -807,8 +807,8 @@ serial2: "Serial 2", sim: "SIM", rak15001: "RAK15001", - rak13302: "RAK13302", - w25q16: "W25Q16", + rak13302: value.includes("w25q16") ? "RAK13302 +" : "RAK13302", + w25q16: "External storage board (W25Q16)", qspi: "QSPI", lora: "LoRa", ota: "OTA", @@ -823,7 +823,9 @@ ) { // The legacy target token is an OTA identity, not a literal statement // that the I2C bus and every external peripheral have been removed. - labels.push("Reduced optional environmental/ranging drivers"); + labels.push(/^RAK_(3401|4631)$/i.test(hardware || "") + ? "Internal storage (no external storage board)" + : "Reduced optional environmental/ranging drivers"); index += 2; continue; } @@ -836,7 +838,7 @@ return labels.join(" "); } - function labelFor(field, value) { + function labelFor(field, value, hardware) { if (field === "chipFamily") return CHIP_FAMILY_LABELS[value] || value; if (field === "hardwareFamily") return humanizeHardware(value); if (field === "hardware") return humanizeHardware(value); @@ -845,7 +847,7 @@ if (field === "ota") return OTA_LABELS[value] || value; if (field === "mode") return MODE_LABELS[value] || value; if (field === "feature") return FEATURE_LABELS[value] || value; - if (field === "variant") return humanizeVariant(value); + if (field === "variant") return humanizeVariant(value, hardware); if (field === "install") return INSTALL_LABELS[value] || value; return value; } @@ -919,6 +921,19 @@ ], }; const extra = []; + if (profile.variant.includes("w25q16")) { + extra.push( + "Requires the external W25Q16 storage board, its exact documented wiring, and the matching storage-aware OTAFIX bootloader." + ); + } + if (profile.variant.includes("no-external-sensors")) { + if (/^RAK_(3401|4631)$/i.test(profile.hardware)) { + extra.push("This profile uses internal storage for LoRa OTA; no external storage board is required."); + } + extra.push( + "This compact profile omits selected optional environmental/ranging sensor drivers. Generic I2C and supported board peripherals remain available; see the hardware and variant notes for retained sensors." + ); + } if (profile.ota === "lora-receiver") { extra.push( "This installs the LoRa OTA repeater profile. The later update package must still match the exact target and partition signature." @@ -1181,7 +1196,7 @@ ["Logging", labelFor("logging", selection && selection.logging || profile.logging)], ["OTA", labelFor("ota", profile.ota)], ["Feature profile", labelFor("feature", profile.feature)], - ["Variant", labelFor("variant", profile.variant)], + ["Variant", labelFor("variant", profile.variant, profile.hardware)], ["Install operation", labelFor("install", installKind)], ["File", asset.name], ["Size", formatBytes(asset.size)], @@ -1266,7 +1281,7 @@ }).forEach(function (value) { const label = field === "hardware" ? humanizeHardwareVariant(value, filters.hardwareFamily) - : labelFor(field, value); + : labelFor(field, value, filters.hardware || filters.hardwareFamily); const option = createElement("option", label); option.value = value; select.appendChild(option); diff --git a/docs/firmware_picker.md b/docs/firmware_picker.md index 3d9ddce00..2a563126e 100644 --- a/docs/firmware_picker.md +++ b/docs/firmware_picker.md @@ -281,8 +281,11 @@ menu. It separates revisions, display type, expansion kit, radio/PA layout, pin map, and other physical differences without crowding the first menu. The firmware-variant menu separately exposes choices that still require different code or wiring, such as serial port or the legacy `no_external_sensors` target -suffix. The picker labels that suffix **Reduced optional environmental/ranging drivers**: -it does not disable generic I2C or unrelated board-integrated peripherals. +suffix. For RAK3401 and RAK4631, the picker labels that compact LoRa OTA option +**Internal storage (no external storage board)**. Its result details explain +the omitted optional environmental/ranging sensor drivers; the reduction does +not disable generic I2C or unrelated board-integrated peripherals. Other boards +retain the **Reduced optional environmental/ranging drivers** label. Reduced RAK3401 and RAK4631 targets retain INA219/INA226/INA260/INA3221 as voltage/current entries in the optional sensor table. They are not the only I2C users: the SSD1306 OLED, supported autodiscovered RTCs, and RAK12500 GPS remain @@ -297,7 +300,9 @@ rather than separate recommended firmware files. Do not substitute a similarly named physical target. The header-wired RAK19007 W25Q16 LoRa-OTA recipes are also exact hardware -variants. Choose the W25Q16 variant for RAK4631 or for RAK3401 + RAK13302 only +variants, labeled **External storage board (W25Q16)** in the picker. W25Q16 is +the flash-memory part on the added storage board; RAK13302 identifies the radio +module, not the storage board. Choose this variant for RAK4631 or for RAK3401 + RAK13302 only when that core/radio combination, the `EF4015` flash wiring, and its matching OTAFIX bootloader are all present. The common base-board wiring does not make the two firmware or bootloader identities interchangeable. diff --git a/test/test_firmware_picker.js b/test/test_firmware_picker.js index 2d3df82ae..9e92af9c8 100644 --- a/test/test_firmware_picker.js +++ b/test/test_firmware_picker.js @@ -852,7 +852,7 @@ assert.deepStrictEqual( assert.strictEqual(picker.humanizeHardware("RAK_4631"), "RAK 4631"); assert.strictEqual( picker.humanizeVariant("rak13302-w25q16-lora-ota"), - "RAK13302 W25Q16 LoRa OTA" + "RAK13302 + External storage board (W25Q16) LoRa OTA" ); assert.strictEqual(picker.formatBytes(2097152), "2.00 MiB"); assert.strictEqual(