Keep Heltec V3 flash mode consistent and guard bench flashing

This commit is contained in:
mikecarper committed 2026-10-15 11:05:31 -07:00
1 parent 23c9648789
commit 2c4a51c9ba
5 files changed
+1107

No files matched your search

+145
View File
@@ -0,0 +1,145 @@
"""V3 app-only role changes must select the same SDK and bootloader mode.
Image headers alone are not a sufficient witness: the ESP32 builder rewrites
QIO headers to DIO even when it selects the QIO SDK and bootloader ELF.
No PlatformIO process, build, flash, or hardware access is used here.
"""
import ast
import configparser
import json
import os
from pathlib import Path
import re
import unittest
ROOT = Path(__file__).resolve().parents[1]
PROFILE = ROOT / "variants/heltec_v3/platformio.ini"
class Profiles:
def __init__(self):
self.config = configparser.ConfigParser(interpolation=None, inline_comment_prefixes=(";",))
self.config.read([ROOT / "platformio.ini", PROFILE], encoding="utf-8")
def raw(self, section, key):
if key in self.config[section]:
return self.config[section][key].strip()
for parent in self.config[section].get("extends", "").replace(",", " ").split():
try:
return self.raw(parent, key)
except KeyError:
pass
raise KeyError((section, key))
def get(self, section, key):
value = self.raw(section, key)
return re.sub(r"\$\{([^}]+)\}", lambda match: self.get(
*match[1].split(".", 1)), value)
def flatten(value, prefix=""):
result = {}
for key, item in value.items():
name = f"{prefix}.{key}" if prefix else key
if isinstance(item, dict):
result.update(flatten(item, name))
else:
result[name] = item
return result
class BuilderEnvironment:
def __init__(self, values):
self.values = values
def BoardConfig(self):
return self.values
def get(self, key, default=None):
return ["arduino"] if key == "PIOFRAMEWORK" else default
def subst(self, value):
for key, replacement in {
"$PIOFRAMEWORK": "arduino",
"$BOARD_FLASH_MODE": self.values["build.flash_mode"],
"$BOARD_F_FLASH": self.values.get("build.f_flash", "80000000L"),
}.items():
value = value.replace(key, replacement)
return value
class HeltecV3FlashModeTests(unittest.TestCase):
def setUp(self):
self.profiles = Profiles()
def test_common_base_pins_sdk_flash_mode_not_only_full_header(self):
self.assertEqual(self.profiles.config["Heltec_lora32_v3"]["board_build.flash_mode"], "dio")
self.assertEqual(self.profiles.get("Heltec_lora32_v3", "board"), "esp32-s3-devkitc-1")
def test_all_same_board_roles_inherit_dio_without_conflicting_memory_type(self):
checked = []
for section in self.profiles.config.sections():
try:
if self.profiles.get(section, "board") != "esp32-s3-devkitc-1":
continue
except KeyError:
continue
checked.append(section)
with self.subTest(section=section):
self.assertEqual(self.profiles.get(section, "board_build.flash_mode"), "dio")
for key in ("board_build.memory_type", "board_build.arduino.memory_type", "board_build.boot"):
with self.assertRaises(KeyError):
self.profiles.get(section, key)
for role in ("kiss_modem", "repeater", "room_server", "sensor",
"companion_radio_usb", "companion_radio_ble", "companion_radio_full"):
self.assertIn("env:Heltec_v3_" + role, checked)
def test_removing_base_pin_reproduces_non_full_inheritance_gap(self):
self.profiles.config.remove_option("Heltec_lora32_v3", "board_build.flash_mode")
with self.assertRaises(KeyError):
self.profiles.get("env:Heltec_v3_kiss_modem", "board_build.flash_mode")
self.assertEqual(self.profiles.get("env:Heltec_v3_companion_radio_full", "board_build.flash_mode"), "dio")
def test_actual_installed_builder_selects_dio_sdk_and_bootloader(self):
core = Path(os.environ.get("PLATFORMIO_CORE_DIR", str(Path.home() / ".platformio")))
builder = core / "platforms/espressif32/builder/main.py"
sdk_builder = core / "packages/framework-arduinoespressif32/tools/platformio-build-esp32s3.py"
board_file = core / "platforms/espressif32/boards/esp32-s3-devkitc-1.json"
if not all(path.is_file() for path in (builder, sdk_builder, board_file)):
self.skipTest("existing ESP32 SDK/board installation required; never installs or invokes PlatformIO")
tree = ast.parse(builder.read_text(encoding="utf-8"))
names = {"_get_board_memory_type", "_get_board_flash_mode", "_get_board_boot_mode"}
functions = [node for node in tree.body if isinstance(node, ast.FunctionDef) and node.name in names]
self.assertEqual({node.name for node in functions}, names)
namespace = {}
exec(compile(ast.Module(body=functions, type_ignores=[]), str(builder), "exec"), namespace)
sdk_tree = ast.parse(sdk_builder.read_text(encoding="utf-8"))
library_paths = next(keyword.value for node in ast.walk(sdk_tree)
if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)
and node.func.attr == "Append" for keyword in node.keywords
if keyword.arg == "LIBPATH")
manifest = flatten(json.loads(board_file.read_text(encoding="utf-8")))
self.assertEqual(manifest["build.flash_mode"], "qio", "regression witness changed; inspect the board manifest")
for role in ("kiss_modem", "companion_radio_full", "repeater", "sensor", "room_server"):
with self.subTest(role=role):
values = dict(manifest)
values["build.flash_mode"] = self.profiles.get("env:Heltec_v3_" + role, "board_build.flash_mode")
env = BuilderEnvironment(values)
self.assertEqual(namespace["_get_board_memory_type"](env), "dio_qspi")
self.assertEqual(env.subst(namespace["_get_board_boot_mode"](env)), "dio")
self.assertEqual(namespace["_get_board_flash_mode"](env), "dio")
paths = eval(compile(ast.Expression(library_paths), str(sdk_builder), "eval"), {
"join": os.path.join, "FRAMEWORK_DIR": "framework", "env": env})
self.assertTrue(any(Path(path).parts[-1] == "dio_qspi" for path in paths))
self.assertFalse(any("qio_qspi" in Path(path).parts for path in paths))
# Before the fix, a QIO app still had a DIO header: the selected SDK and
# bootloader, rather than that header, expose the real incompatibility.
old = BuilderEnvironment(manifest)
self.assertEqual(namespace["_get_board_flash_mode"](old), "dio")
self.assertEqual(namespace["_get_board_memory_type"](old), "qio_qspi")
self.assertEqual(old.subst(namespace["_get_board_boot_mode"](old)), "qio")
if __name__ == "__main__":
unittest.main()
+357
View File
@@ -0,0 +1,357 @@
"""Run the wrapper against a fake flasher and /dev/null, never a real radio."""
import os
import json
from pathlib import Path
import shutil
import subprocess
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[1]
WRAPPER = ROOT / "tools/hil/mcfirmware_bench_flash.sh"
WINDOWS_WRAPPER = ROOT / "tools/hil/firmware_bench_flash.ps1"
WINDOWS_FLASHER = Path("C:/git/meshfirmware/firmware.cmd")
PWSH = shutil.which("pwsh") or shutil.which("powershell")
FAKE_FLASHER = r'''
set -euo pipefail
cleanup() { printf 'cleanup:%s\n' "$FIRMWARE_ROOT" >>"$TEST_LOG"; }
error_handler() { printf 'error\n' >>"$TEST_LOG"; exit 1; }
trap 'echo UNWANTED_TRAP >>"$TEST_LOG"' EXIT
initialize_privilege_mode() { echo UNWANTED_GROUP_CHANGE >>"$TEST_LOG"; }
meshfirmware_check_pi_usb_host_speed() { echo UNWANTED_REBOOT >>"$TEST_LOG"; }
configure_usb_autosuspend() { echo UNWANTED_USB_CHANGE >>"$TEST_LOG"; }
initialize_privilege_mode
meshfirmware_check_pi_usb_host_speed
configure_usb_autosuspend
FIRMWARE_ROOT=/unrelated/cache
NORESET=no-reset
ERASEFLASH=erase-flash
WRITEFLASH=write-flash
WATCHDOGRESET=watchdog-reset
READMAC=read-mac
BOOTLOADER_PROBE_ACTIVE=0
ESP32_FLASH_EXPECTED_MAC=''
save_selected_serial_port() { echo save-selected >>"$TEST_LOG"; DEVICE_PORT="$1"; }
prepare_esp32_flash_session() { echo prepare >>"$TEST_LOG"; ESP32_FLASH_EXPECTED_MAC=aabbccddeeff; ESP32_SESSION_IS_S3="${TEST_CHIP_IS_S3:-1}"; }
esp32_verified_destructive_port() { echo verify-MAC >>"$TEST_LOG"; printf '%s\n' "$1"; }
run_esp32_session_esptool() { printf 'run:%s\n' "$*" >>"$TEST_LOG"; }
finish_esp32_flash_session() { echo finish >>"$TEST_LOG"; }
esp32_prepare_merged_ota_mirror() { printf 'app' >"$2"; echo 0x650000; }
esp_firmware_layout() { echo merged; }
esp32_validate_image_for_device() { echo validate >>"$TEST_LOG"; }
esp32_write_after_mode() { echo no-reset; }
ensure_pipx_uv_backend() { echo backend >>"$TEST_LOG"; }
get_espcmd() { echo espcmd >>"$TEST_LOG"; }
# MAIN
echo UNWANTED_MENU >>"$TEST_LOG"
'''
@unittest.skipUnless(os.name == "posix" and shutil.which("bash"), "POSIX bash required")
class BenchFlasherTests(unittest.TestCase):
def run_fake(self, mode, mismatch=False, s3=True):
with tempfile.TemporaryDirectory(prefix="meshcore-flasher-wrapper-") as directory:
work = Path(directory)
flasher = work / "fake.sh"
flasher.write_text(FAKE_FLASHER)
log = work / "actions.log"
bindir = work / "bin"
bindir.mkdir()
readlink = bindir / "readlink"
readlink.write_text("#!/bin/sh\nif [ -n \"$TEST_MISMATCH\" ]; then case \"$*\" in *by-id*) echo /dev/zero;exit 0;;esac;fi\necho /dev/null\n")
readlink.chmod(0o755)
image = work / "test-merged.bin"
image.write_bytes(b"fake fixture only")
env = dict(os.environ, PATH=str(bindir) + os.pathsep + os.environ["PATH"],
TEST_LOG=str(log), TEST_MISMATCH="1" if mismatch else "",
TEST_CHIP_IS_S3="1" if s3 else "0")
args = ["bash", str(WRAPPER), "--flasher", str(flasher), "--bench-dir", str(work),
"--port", "/dev/null", "--usb-path", "exact-bench-usb-path",
"--usb-id", "exact-bench-usb-id", "--device", "heltec_v4"]
if mode == "probe":
args.append("--probe")
elif mode == "watchdog":
args.append("--watchdog-recover")
elif mode == "mixed":
args.extend(("--probe", "--watchdog-recover"))
else:
args.extend(("--image", str(image)))
if mode == "erase":
args.append("--erase")
result = subprocess.run(args, text=True, capture_output=True, env=env)
actions = log.read_text() if log.exists() else ""
return result, actions
def test_probe_uses_flasher_and_skips_global_startup_and_erase(self):
result, actions = self.run_fake("probe")
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
for expected in ("save-selected", "prepare", "chip-id", "flash-id", "finish", "cleanup:"):
self.assertIn(expected, actions)
for forbidden in ("UNWANTED", "erase-flash", "write-flash", "/unrelated/cache"):
self.assertNotIn(forbidden, actions)
self.assertIn("/mcfirmware-cache.", actions)
def test_merged_install_requires_explicit_erase(self):
result, actions = self.run_fake("image")
self.assertEqual(result.returncode, 2)
self.assertEqual(actions, "")
def test_install_runs_verified_session_with_dual_slot_mirror(self):
result, actions = self.run_fake("erase")
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
self.assertIn("erase-flash", actions)
self.assertIn("write-flash 0x0000", actions)
self.assertIn("0x650000", actions)
self.assertIn("finish", actions)
self.assertNotIn("UNWANTED", actions)
self.assertLess(actions.index("prepare"), actions.index("erase-flash"))
def test_mismatched_usb_ids_fail_before_flashing_or_startup(self):
result, actions = self.run_fake("probe", mismatch=True)
self.assertNotEqual(result.returncode, 0)
self.assertIn("identities disagree", result.stderr)
self.assertEqual(actions, "")
def test_watchdog_recovery_is_s3_only_masked_and_mac_verified(self):
result, actions = self.run_fake("watchdog")
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
self.assertIn("write-mem 0x6000812c 0 0x1", actions)
self.assertIn("--after watchdog-reset --baud 115200 read-mac", actions)
self.assertEqual(actions.count("verify-MAC"), 2)
self.assertLess(actions.index("verify-MAC"), actions.index("write-mem"))
for forbidden in ("erase-flash", "write-flash", "finish", "UNWANTED"):
self.assertNotIn(forbidden, actions)
self.assertIn("Runtime is not yet verified", result.stdout)
def test_watchdog_recovery_refuses_non_s3_before_volatile_write(self):
result, actions = self.run_fake("watchdog", s3=False)
self.assertNotEqual(result.returncode, 0)
self.assertIn("positively identified ESP32-S3", result.stderr)
self.assertNotIn("write-mem", actions)
self.assertNotIn("--after watchdog-reset", actions)
def test_watchdog_recovery_cannot_be_combined_with_probe(self):
result, actions = self.run_fake("mixed")
self.assertEqual(result.returncode, 2)
self.assertEqual(actions, "")
WINDOWS_APP_HARNESS = r'''
$ErrorActionPreference = 'Stop'
$case = $env:BENCH_TEST_CASE
$work = $env:BENCH_TEST_WORK
$actions = [Collections.Generic.List[string]]::new()
function Add-Action([string]$value) { $script:actions.Add($value) }
function Import-Definition([string]$path, [string[]]$names) {
$tokens = $null; $errors = $null
$ast = [Management.Automation.Language.Parser]::ParseFile($path, [ref]$tokens, [ref]$errors)
if ($errors.Count) { throw 'Source parse failure' }
foreach ($name in $names) {
$definitions = @($ast.EndBlock.Statements | Where-Object {
$_ -is [Management.Automation.Language.FunctionDefinitionAst] -and $_.Name -eq $name
})
if ($definitions.Count -ne 1) { throw "Missing unique function: $name" }
# Install only the named definition in script scope, never top-level source.
. ([scriptblock]::Create(($definitions[0].Extent.Text -replace '^function ', 'function script:')))
}
}
Import-Definition $env:BENCH_TEST_WRAPPER @('Assert-BenchAppImage', 'Get-BenchPartitionFailureReason', 'Get-BenchAppUpdatePlan', 'Assert-BenchUsb')
Import-Definition $env:BENCH_TEST_FLASHER @('updateFlashViaEspTool')
$script:pythonCommand = 'Invoke-FakeValidator'
$script:ESPTOOL_NO_RESET = 'no-reset'
$script:ESPTOOL_FLASH_ID = 'flash-id'
$script:ESPTOOL_WRITE_FLASH = 'write-flash'
$ExpectedUsbInstanceId = 'USB\VID_10C4&PID_EA60\0001'
$ExpectedLocationPath = 'PCIROOT(0)#USBROOT(0)#USB(7)'
$ComPort = 'COM6'
$identity = [pscustomobject]@{
ParentInstanceId = $ExpectedUsbInstanceId; LocationPath = $ExpectedLocationPath
SerialNumber = '0001'; Esp32ChipMac = '3C0F02EE20DC'
}
function Get-CimInstance { @([pscustomobject]@{
PNPDeviceID=$ExpectedUsbInstanceId; Present=$true; ConfigManagerErrorCode=0; Name='USB (COM6)'
}) }
function Get-UsbComPortIdentity {
param($ComPort, $PnpDevice)
$result = $identity.PSObject.Copy()
if ($case -eq 'location') { $result.LocationPath = 'OTHER-PORT' }
if ($case -eq 'identity') { $result.ParentInstanceId = 'USB\VID_10C4&PID_EA60\OTHER' }
return $result
}
function Get-EspUsbBootloaderStrategy { param($UsbIdentity) 'uart' }
function Get-EspFlashStrategy {
param($Path)
if ($case -eq 'merged') { return [pscustomobject]@{Classification='LIKELY_MERGED';ClassifiedMode='install'} }
if ($case -eq 'unknown') { return [pscustomobject]@{Classification='UNKNOWN';ClassifiedMode='unknown'} }
[pscustomobject]@{Classification='LIKELY_SINGLE';ClassifiedMode='update'}
}
function Enter-Esp32Bootloader { param($ComPort,$UsbIdentity,$EspToolCommand) Add-Action 'boot'; $ComPort }
function Assert-Esp32RomChipIdentity {
param($ComPort,$UsbIdentity,$EspToolCommand,$Purpose)
Add-Action 'verify-mac'
if ($case -eq 'mac') { throw 'MAC changed' }
$ComPort
}
function Get-Esp32RomBeforeMode { param($UsbIdentity) 'default-reset' }
function Get-Esp32WriteAfterMode { param($UsbIdentity) 'hard-reset' }
function Resolve-EspUsbComPort { param($PreferredComPort,$UsbIdentity,$TimeoutMs,$Purpose) $PreferredComPort }
function Get-SelectedUsbIdentityForFlash { param($Hardware) $Hardware.UsbIdentity }
function get_esptool_cmd { 'fake-esptool' }
function run_cmd {
param($CommandLine,[switch]$Stream)
Add-Action $CommandLine
if ($Stream) { return 0 }
'Detecting chip type... ESP32-S3; Detected flash size: 8MB'
}
function Read-EspPartitionSnapshot {
param($ComPort,$UsbIdentity,$EspToolCommand,$Offset,$Length,$Path)
Add-Action 'read-table'
$script:snapshotDir = Split-Path $Path -Parent
$bytes = [byte[]]::new(4096)
for ($i=0; $i -lt $bytes.Length; $i++) { $bytes[$i]=255 }
foreach ($entry in @(@(0,0x10000),@(32,0x30000))) {
$o=$entry[0]; $bytes[$o]=0xaa; $bytes[$o+1]=0x50; $bytes[$o+2]=0
[BitConverter]::GetBytes([uint32]$entry[1]).CopyTo($bytes,$o+4)
[BitConverter]::GetBytes([uint32]0x20000).CopyTo($bytes,$o+8)
}
if ($case -eq 'short-table') { $bytes=[byte[]]::new(64) }
if ($case -eq 'bad-table') { $bytes[0]=0 }
[IO.File]::WriteAllBytes($Path,$bytes)
}
function Get-EspOtadataSnapshot {
param($PartitionTable,$ComPort,$UsbIdentity,$EspToolCommand,$Path)
Add-Action 'read-ota'; [IO.File]::WriteAllBytes($Path,[byte[]]::new(8192)); $Path
}
function Get-EspNvsSnapshot {
param($PartitionTable,$ComPort,$UsbIdentity,$EspToolCommand,$Path)
Add-Action 'read-nvs'; [IO.File]::WriteAllBytes($Path,[byte[]]::new(4096)); $Path
}
function Invoke-FakeValidator {
Add-Action ('validator:' + ($args -join ' '))
$global:LASTEXITCODE=0
$proof=[ordered]@{ok=$true;needed=$false;firmware_sha256=$script:hash;app_offsets=@(0x30000,0x10000)
nvs_migration=@{namespace_exists=$true;namespace_empty=$true;'cfg-restored'=$false;'cfg-pending'=$false;'id-pending'=$false}}
if ($case -eq 'pending') { $proof.needed=$true; $proof.resume=$true }
if ($case -eq 'proof-hash') { $proof.firmware_sha256='0'*64 }
if ($case -eq 'duplicate') { $proof.app_offsets=@(0x10000,0x10000) }
if ($case -eq 'missing-slot') { $proof.app_offsets=@(0x10000) }
if ($case -eq 'invalid-offset') { $proof.app_offsets=@(0x8000,0x10000) }
if ($case -eq 'validator-error') { $global:LASTEXITCODE=1; $proof.ok=$false }
if ($case -eq 'nvs-error') {
$global:LASTEXITCODE=1; $proof.ok=$false; $proof.error='Migration NVS entry format is invalid or unsupported.'
}
if ($case -eq 'private-error') {
$global:LASTEXITCODE=1; $proof.ok=$false; $proof.error='PRIVATE-SSID key=private-value C:\secret\snapshot.bin'
}
$proof | ConvertTo-Json -Compress
}
$success=$false; $message=''; $offsets=@()
try {
$null=Assert-BenchUsb
$image=Join-Path $work 'application.bin'
$bytes=if ($case -eq 'oversized') {[byte[]]::new(0x20001)} else {[byte[]]::new(100)}
[IO.File]::WriteAllBytes($image,$bytes)
$script:hash=(Get-FileHash -LiteralPath $image -Algorithm SHA256).Hash.ToLowerInvariant()
$expectedHash=if ($case -eq 'image-hash') {'0'*64} else {$script:hash}
$image=Assert-BenchAppImage -Path $image -Sha256 $expectedHash
$hardware=[pscustomobject]@{ComPort='COM6';FirmwareFile=$image;UsbIdentity=$identity}
$offsets=@(Get-BenchAppUpdatePlan -Hardware $hardware -EspToolCommand 'fake-esptool' `
-FlasherPath (Join-Path $work 'firmware.cmd') -ExpectedImageSha256 $expectedHash)
if ($case -eq 'changed-image') { [IO.File]::AppendAllText($image,'changed') }
$null=Assert-BenchAppImage -Path $image -Sha256 $expectedHash
$success=updateFlashViaEspTool -hw $hardware
} catch { $message=$_.Exception.Message }
[pscustomobject]@{success=$success;error=$message;actions=@($actions.ToArray());offsets=$offsets
nvs_proof=if ($hardware) {$hardware.EspUpdateNvsProof} else {$null}
snapshots_removed=($script:snapshotDir -and -not (Test-Path -LiteralPath $script:snapshotDir))} | ConvertTo-Json -Compress
'''
@unittest.skipUnless(PWSH and WINDOWS_FLASHER.is_file(), "local PowerShell/flasher source required")
class WindowsAppUpdateTests(unittest.TestCase):
"""Only AST-loaded functions plus fake USB/ROM/validator operations run."""
def run_case(self, case):
with tempfile.TemporaryDirectory(prefix="meshcore-app-update-") as directory:
work = Path(directory)
(work / "tools").mkdir()
shutil.copyfile(WINDOWS_FLASHER.parent / "tools/meshcore_partition_expansion.py",
work / "tools/meshcore_partition_expansion.py")
if case == "helper-hash":
(work / "tools/meshcore_partition_expansion.py").write_text("not the pinned helper")
env = dict(os.environ, BENCH_TEST_CASE=case, BENCH_TEST_WORK=str(work),
BENCH_TEST_WRAPPER=str(WINDOWS_WRAPPER), BENCH_TEST_FLASHER=str(WINDOWS_FLASHER))
result = subprocess.run([PWSH, "-NoLogo", "-NoProfile", "-NonInteractive", "-Command",
WINDOWS_APP_HARNESS], text=True, capture_output=True, env=env,
timeout=30)
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
return json.loads(result.stdout.strip().splitlines()[-1])
def test_checked_update_uses_real_flasher_app_writer_inactive_first(self):
result = self.run_case("valid")
self.assertTrue(result["success"], result)
self.assertEqual(result["offsets"], ["0x30000", "0x10000"])
self.assertEqual(result["nvs_proof"], {"namespace_exists": True, "namespace_empty": True,
"restored": False, "config_pending": False, "identity_pending": False})
actions = result["actions"]
write = next(action for action in actions if "write-flash" in action)
self.assertLess(write.index("0x30000"), write.index("0x10000"))
self.assertTrue(result["snapshots_removed"])
self.assertIn("read-ota", actions)
self.assertIn("read-nvs", actions)
self.assertLess(next(i for i, action in enumerate(actions) if action.startswith("validator:")),
actions.index(write))
for forbidden in ("erase", "0x8000 ", "0x9000 ", "migration", "download"):
self.assertNotIn(forbidden, write)
def test_bad_image_identity_and_missing_pinned_helper_fail_before_rom(self):
for case in ("location", "identity", "merged", "unknown", "image-hash", "helper-hash"):
with self.subTest(case=case):
result = self.run_case(case)
self.assertFalse(result["success"], result)
self.assertEqual(result["actions"], [])
def test_bad_table_and_oversize_cannot_enter_validator_or_download_branch(self):
for case in ("short-table", "bad-table", "oversized"):
with self.subTest(case=case):
result = self.run_case(case)
self.assertFalse(result["success"], result)
self.assertTrue(result["snapshots_removed"])
self.assertFalse(any(action.startswith("validator:") for action in result["actions"]))
self.assertFalse(any("write-flash" in action for action in result["actions"]))
def test_bad_proofs_mac_and_changed_application_never_write(self):
for case in ("pending", "proof-hash", "duplicate", "missing-slot", "invalid-offset",
"validator-error", "mac", "changed-image"):
with self.subTest(case=case):
result = self.run_case(case)
self.assertFalse(result["success"], result)
self.assertTrue(result["snapshots_removed"])
self.assertFalse(any("write-flash" in action for action in result["actions"]))
def test_wrapper_never_imports_migration_or_download_driver(self):
text = WINDOWS_WRAPPER.read_text()
self.assertIn("'AppUpdate'", text)
self.assertIn("-ExpectedLocationPath; -Erase is forbidden", text)
for forbidden in ("'Resolve-PartitionExpansionTool'", "'Invoke-EspPartitionExpansion'",
"'Invoke-PartitionExpansionTool'", "Invoke-WebRequest"):
self.assertNotIn(forbidden, text)
def test_planner_failure_reports_only_fixed_safe_reason(self):
known = self.run_case("nvs-error")
self.assertFalse(known["success"])
self.assertIn("Reason: Migration NVS entry format is invalid or unsupported.", known["error"])
self.assertTrue(known["snapshots_removed"])
private = self.run_case("private-error")
self.assertFalse(private["success"])
self.assertIn("unrecognized details were withheld", private["error"])
for secret in ("PRIVATE-SSID", "private-value", "snapshot.bin"):
self.assertNotIn(secret, private["error"])
self.assertTrue(private["snapshots_removed"])
if __name__ == "__main__":
unittest.main()
+397
View File
@@ -0,0 +1,397 @@
# Narrow bench entry to firmware.cmd's actual ESP32 install/update/reset helpers.
# Import definitions only: never execute its menus, dependency installers,
# background upgrades, backup prompts, or top-level cleanup.
[CmdletBinding()]
param(
[ValidateSet('Inventory', 'Probe', 'Install', 'AppUpdate')][string]$Mode = 'Inventory',
[Parameter(Mandatory)][ValidatePattern('^COM[0-9]+$')][string]$ComPort,
[Parameter(Mandatory)][string]$ExpectedUsbInstanceId,
[string]$ExpectedLocationPath = '',
[string]$ExpectedMac = '',
[string]$Image = '',
[string]$ExpectedSha256 = '',
[switch]$Erase,
[string]$Flasher = 'C:\git\meshfirmware\firmware.cmd',
[string]$PythonCommand = ''
)
$ErrorActionPreference = 'Stop'
$ProgressPreference = 'SilentlyContinue'
if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) {
throw 'This bench wrapper requires Windows.'
}
$ComPort = $ComPort.ToUpperInvariant()
if ($ExpectedUsbInstanceId -notmatch '^USB\\VID_10C4&PID_EA60\\[^\\&]+$') {
throw 'This narrow UART bench wrapper requires an exact CP210x USB instance ID with a serial.'
}
if ($Mode -eq 'Install') {
if (-not $Erase -or -not [IO.Path]::IsPathRooted($Image) -or
$ExpectedSha256 -notmatch '^[0-9a-fA-F]{64}$' -or
($ExpectedMac -replace '[:\-]', '') -notmatch '^[0-9a-fA-F]{12}$') {
throw 'Install requires -Erase, an absolute merged -Image, -ExpectedSha256 and the prior probe -ExpectedMac.'
}
} elseif ($Mode -eq 'AppUpdate') {
if ($Erase -or $Image -notmatch '^[A-Za-z]:[\\/]' -or
$ExpectedSha256 -notmatch '^[0-9a-fA-F]{64}$' -or
($ExpectedMac -replace '[:\-]', '') -notmatch '^[0-9a-fA-F]{12}$' -or
[string]::IsNullOrWhiteSpace($ExpectedLocationPath)) {
throw 'AppUpdate requires an absolute plain app -Image, -ExpectedSha256, prior probe -ExpectedMac and -ExpectedLocationPath; -Erase is forbidden.'
}
} elseif ($Erase -or $Image -or $ExpectedSha256) {
throw 'Inventory/Probe cannot erase, install, or select an image.'
}
$tokens = $null; $parseErrors = $null
$flasherPath = (Resolve-Path -LiteralPath $Flasher -ErrorAction Stop).ProviderPath
$ast = [Management.Automation.Language.Parser]::ParseFile(
$flasherPath, [ref]$tokens, [ref]$parseErrors)
if ($parseErrors.Count) { throw "firmware.cmd parse failed: $parseErrors" }
$required = @(
'Get-AvailableComPorts', 'Test-IsWindowsHost', 'Resolve-UsbParentInstanceId',
'Get-UsbInterfaceNumberFromInstanceId', 'Get-UsbIdentityInterfaceNumber',
'Get-UsbPnpProperties', 'Get-UsbComPortIdentity', 'Test-UsbComPortIdentityMatch',
'Get-UsbIdentityDisplayText', 'Resolve-UsbComPortForIdentity', 'Resolve-LiveUsbComPort',
'Resolve-EspUsbComPort', 'Assert-UsbComPortIdentityFor1200Touch',
'Get-EspUsbBootloaderStrategy', 'Get-Esp32RomBeforeMode', 'Get-Esp32RomSessionStamp',
'Get-Esp32WriteAfterMode', 'Assert-Esp32FinishCapability', 'Get-EspRomMac',
'Set-Esp32VerifiedChipMac', 'Assert-Esp32RomChipIdentity', 'Enter-Esp32Bootloader',
'New-EspUsbTouchSerialPort', 'Invoke-EspTinyUsbTouch1200',
'Split-CommandLine', 'run_cmd', 'get_esptool_cmd',
'Wait-FirmwareToolUpdates', 'Enter-FirmwareToolUse', 'Exit-FirmwareToolUse',
'Get-EspRuntimeStorageLayout', 'Complete-Esp32FlashSession',
'Get-EspFileNameMode', 'Get-EspBinClassification', 'Get-EspFlashStrategy',
'Install-SimpleMergedEspImage'
)
if ($Mode -eq 'AppUpdate') {
$required += @('Get-SelectedUsbIdentityForFlash', 'Read-EspPartitionSnapshot',
'Get-EspOtadataSnapshot', 'Get-EspNvsSnapshot', 'updateFlashViaEspTool')
}
foreach ($name in $required) {
$definitions = @($ast.EndBlock.Statements | Where-Object {
$_ -is [Management.Automation.Language.FunctionDefinitionAst] -and $_.Name -eq $name
})
if ($definitions.Count -ne 1) { throw "Expected exactly one firmware.cmd function: $name" }
Invoke-Expression $definitions[0].Extent.Text
}
# This is the sole non-function initializer needed by run_cmd. Select the
# exact existing interop block, not arbitrary executable top-level statements.
$interop = @($ast.EndBlock.Statements | Where-Object {
$_ -is [Management.Automation.Language.IfStatementAst] -and
$_.Extent.Text -match 'public static extern IntPtr CommandLineToArgvW' -and
$_.Extent.Text -match 'public static class NativeMethods'
})
if ($interop.Count -ne 1) { throw 'Missing/ambiguous firmware.cmd native command-line interop.' }
Invoke-Expression $interop[0].Extent.Text
function Assert-BenchAppImage {
param([string]$Path, [string]$Sha256)
$resolved = (Resolve-Path -LiteralPath $Path -ErrorAction Stop).ProviderPath
$item = Get-Item -LiteralPath $resolved -ErrorAction Stop
if ($resolved -match '[\s"]' -or $item.PSIsContainer -or
$item.Extension -ine '.bin' -or
($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) {
throw 'AppUpdate requires a regular plain .bin file without whitespace, quotes or reparse points.'
}
$strategy = Get-EspFlashStrategy -Path $resolved
if ($strategy.Classification -ne 'LIKELY_SINGLE' -or $strategy.ClassifiedMode -ne 'update') {
throw 'AppUpdate accepts only a content-classified single application, never a merged/data/unknown image.'
}
if ((Get-FileHash -LiteralPath $resolved -Algorithm SHA256).Hash -ne $Sha256) {
throw 'The selected application does not match the explicitly expected SHA-256.'
}
return $resolved
}
function Get-BenchPartitionFailureReason {
param([object]$PlannerError, [bool]$MigrationNeeded)
# Only fixed reviewed messages may cross the private-snapshot boundary.
# Never echo arbitrary subprocess output, exception text, paths or NVS data.
$known = @(
'A required partition expansion input is missing or too large.',
'Cannot read a required partition expansion input.',
'ESP32 flash identification output is not valid text.',
'Physical ESP32 chip and flash capacity were not unambiguously detected.',
'This ESP32 chip family has no reviewed partition expansion bridge.',
'Partition expansion requires a valid ESP32 application-only image.',
'ESP32 image declares an unsupported flash capacity.',
'Selected application does not match the connected ESP32 chip/flash capacity.',
'Partition table must contain exactly 4096 bytes.',
'Partition table has malformed trailing data.',
'Partition table MD5 verification failed.',
'Partition table has entries after its checksum.',
'Partition table has an invalid entry.',
'Partition table has an invalid label.',
'Partition table contains invalid, duplicate or out-of-flash geometry.',
'Partition table is empty.',
'Partition table contains overlapping partitions.',
'OTA metadata read must contain exactly 8192 bytes.',
'OTA table does not have unique contiguous OTA slot identities.',
'OTA metadata has no valid active sequence and is not erased initial data.',
'OTA active sequence ordering is ambiguous.',
'ESP32 table has ambiguous NVS partitions for migration-state verification.',
'An actual NVS snapshot is required to check for unfinished partition migration.',
'NVS snapshot size does not match its actual partition geometry.',
'Migration NVS page verification failed or requires recovery.',
'Migration NVS has missing or ambiguous page ordering.',
'Migration NVS has multiple active pages and requires recovery.',
'Migration NVS sequence ordering is ambiguous.',
'Migration NVS contains an invalid entry state.',
'Migration NVS entry CRC verification failed.',
'Migration NVS contains an invalid key.',
'Migration NVS entry format is invalid or unsupported.',
'Migration NVS primitive entry geometry is invalid.',
'Migration NVS variable-length entry is incomplete.',
'Migration NVS data CRC verification failed.',
'No verified partition migration NVS namespace exists.',
'Partition migration NVS namespace identity is ambiguous.',
'Partition migration NVS completion flag has an invalid type/value.',
'Live NVS reports unfinished partition migration; restore the original bridge handoff before final flashing.',
'Device cache contains invalid partition expansion state.',
'Device has ambiguous pending partition expansion state.',
'A partition expansion is pending; select its original exact firmware before updating another image.',
'Pending partition expansion belongs to another physical device.',
'Pending partition expansion layout changed unexpectedly; recovery is required.',
'Bench app-only validation is offline; partition migration is forbidden.',
'Partition expansion preparation or verification failed.'
)
if ($PlannerError -is [string] -and $known -ccontains $PlannerError) { return $PlannerError }
if ($MigrationNeeded) { return 'Partition migration is required or pending.' }
return 'Local partition validation failed; unrecognized details were withheld.'
}
function Get-BenchAppUpdatePlan {
param([psobject]$Hardware, [string]$EspToolCommand, [string]$FlasherPath,
[string]$ExpectedImageSha256)
# Use the exact local flasher validator, never its resolver/downloader or
# migration driver. The precheck below makes its expansion branch unreachable.
$tool = Join-Path (Split-Path $FlasherPath -Parent) 'tools\meshcore_partition_expansion.py'
$toolSha256 = 'fd1cc2c2198d31878587a2a7aa48f7ec49055b29af3cb5f2a9630ec2d8787df8'
if (-not (Test-Path -LiteralPath $tool -PathType Leaf) -or
(Get-FileHash -LiteralPath $tool -Algorithm SHA256).Hash -ine $toolSha256) {
throw 'The required local partition validator is missing or not the reviewed version; no download or update is allowed.'
}
$temporaryPath = Join-Path ([IO.Path]::GetTempPath()) ('meshcore-bench-app-' + [guid]::NewGuid().ToString('N'))
$tempDir = (New-Item -ItemType Directory -Path $temporaryPath -ErrorAction Stop).FullName
$identity = $Hardware.UsbIdentity
try {
$port = Enter-Esp32Bootloader -ComPort $Hardware.ComPort -UsbIdentity $identity -EspToolCommand $EspToolCommand
$Hardware.ComPort = $port
$tablePath = Join-Path $tempDir 'partitions.bin'
$flashPath = Join-Path $tempDir 'flash-id.txt'
$otaPath = Join-Path $tempDir 'otadata.bin'
$nvsPath = Join-Path $tempDir 'nvs.bin'
Read-EspPartitionSnapshot -ComPort $port -UsbIdentity $identity -EspToolCommand $EspToolCommand `
-Offset '0x8000' -Length 4096 -Path $tablePath
$table = [IO.File]::ReadAllBytes($tablePath)
if ($table.Length -ne 4096) { throw 'AppUpdate requires a complete physical partition table.' }
$imageBytes = (Get-Item -LiteralPath $Hardware.FirmwareFile).Length
$physicalAppOffsets = @()
for ($offset = 0; $offset -lt 4096; $offset += 32) {
if ($table[$offset] -eq 0xff -and $table[$offset + 1] -eq 0xff) { break }
if ($table[$offset] -eq 0xeb -and $table[$offset + 1] -eq 0xeb) { break }
if ($table[$offset] -ne 0xaa -or $table[$offset + 1] -ne 0x50) {
throw 'The physical partition table is malformed; no application update is allowed.'
}
if ($table[$offset + 2] -eq 0) {
$physicalAppOffsets += [int64][BitConverter]::ToUInt32($table, $offset + 4)
if ($imageBytes -gt [BitConverter]::ToUInt32($table, $offset + 8)) {
throw 'The application does not fit every physical app slot; this mode never migrates partitions.'
}
}
}
if (-not $physicalAppOffsets.Count) { throw 'No physical application partitions were found.' }
$port = Assert-Esp32RomChipIdentity -ComPort $port -UsbIdentity $identity `
-EspToolCommand $EspToolCommand -Purpose 'App-only physical flash capacity'
$before = Get-Esp32RomBeforeMode -UsbIdentity $identity
$flashId = run_cmd "$EspToolCommand --baud 115200 --port $port --before $before --after $script:ESPTOOL_NO_RESET $script:ESPTOOL_FLASH_ID"
[IO.File]::WriteAllText($flashPath, [string]$flashId)
$ota = Get-EspOtadataSnapshot -PartitionTable $tablePath -ComPort $port -UsbIdentity $identity `
-EspToolCommand $EspToolCommand -Path $otaPath
$nvs = Get-EspNvsSnapshot -PartitionTable $tablePath -ComPort $port -UsbIdentity $identity `
-EspToolCommand $EspToolCommand -Path $nvsPath
# Reuse the flasher's per-MAC cache so interrupted migrations cannot be
# hidden by choosing a new bench cache. Live NVS is independently checked.
$cache = Join-Path (Split-Path $FlasherPath -Parent) ('.tmp\partition-expansion\' + $identity.Esp32ChipMac)
# Keep the pinned planner offline even if an input changes between the
# size precheck and its own read. Never execute its serial/bridge commands.
$offlineChecker = @'
import importlib.util, sys
spec = importlib.util.spec_from_file_location("bench_partition_validator", sys.argv[1])
validator = importlib.util.module_from_spec(spec)
spec.loader.exec_module(validator)
def refuse_download(*args, **kwargs):
raise validator.ExpansionError("Bench app-only validation is offline; partition migration is forbidden.")
validator.download = refuse_download
raise SystemExit(validator.main(sys.argv[2:]))
'@
$arguments = @('-c', $offlineChecker, $tool, 'plan', '--firmware', $Hardware.FirmwareFile,
'--partition-table', $tablePath, '--flash-id-output', $flashPath,
'--output-dir', $cache, '--device-mac', $identity.Esp32ChipMac)
if ($ota) { $arguments += @('--otadata', $ota) }
if ($nvs) { $arguments += @('--nvs', $nvs) }
$previousPreference = $ErrorActionPreference
try {
$ErrorActionPreference = 'Continue'
$output = (& $script:pythonCommand @arguments 2>&1 | Out-String)
$exitCode = $LASTEXITCODE
} finally { $ErrorActionPreference = $previousPreference }
try { $plan = $output | ConvertFrom-Json -ErrorAction Stop }
catch { throw 'The local partition validator returned no valid app-update proof.' }
if ($exitCode -ne 0 -or $plan.ok -ne $true -or $plan.needed -ne $false -or $plan.resume) {
$reason = Get-BenchPartitionFailureReason -PlannerError $plan.error `
-MigrationNeeded ($plan.needed -eq $true -or $plan.resume -eq $true)
throw "Physical partition/NVS/OTA proof failed; no application was written. Reason: $reason"
}
if ($plan.firmware_sha256 -cne $ExpectedImageSha256.ToLowerInvariant() -or
-not @($plan.app_offsets).Count -or @($plan.app_offsets).Count -ne $physicalAppOffsets.Count) {
throw 'The partition proof does not match the exact application and all physical app slots.'
}
$offsets = @($plan.app_offsets | ForEach-Object {
$value = [int64]$_
if ($value -lt 0x10000 -or $value % 0x10000 -ne 0 -or $value -notin $physicalAppOffsets) {
throw 'Invalid verified application offset.'
}
'0x{0:x}' -f $value
})
if (@($offsets | Select-Object -Unique).Count -ne $offsets.Count) { throw 'Duplicate application offsets in proof.' }
$Hardware | Add-Member -NotePropertyName EspUpdateFirmwareSha256 -NotePropertyValue $plan.firmware_sha256 -Force
$Hardware | Add-Member -NotePropertyName EspUpdateOffsets -NotePropertyValue ([string[]]$offsets) -Force
$Hardware | Add-Member -NotePropertyName EspUpdateNvsProof -NotePropertyValue ([pscustomobject]@{
namespace_exists = ($plan.nvs_migration.namespace_exists -eq $true)
namespace_empty = ($plan.nvs_migration.namespace_empty -eq $true)
restored = ($plan.nvs_migration.'cfg-restored' -eq $true)
config_pending = ($plan.nvs_migration.'cfg-pending' -eq $true)
identity_pending = ($plan.nvs_migration.'id-pending' -eq $true)
}) -Force
return $offsets
} finally {
# NVS may contain keys/bonds. Delete only our exact snapshots, never log
# their bytes and never retain them as ordinary bench evidence.
foreach ($name in @('partitions.bin', 'flash-id.txt', 'otadata.bin', 'nvs.bin')) {
$path = Join-Path $tempDir $name
if (Test-Path -LiteralPath $path) { Remove-Item -LiteralPath $path -Force }
}
Remove-Item -LiteralPath $tempDir -Force
}
}
function Assert-BenchUsb {
$device = @(Get-CimInstance Win32_PnPEntity | Where-Object {
$_.PNPDeviceID -eq $ExpectedUsbInstanceId -and $_.Present -ne $false -and
[int]$_.ConfigManagerErrorCode -eq 0 -and $_.Name -match "\($([regex]::Escape($ComPort))\)$"
})
if ($device.Count -ne 1) {
throw 'The exact selected CP210x instance is not healthy on the requested COM port.'
}
$identity = Get-UsbComPortIdentity -ComPort $ComPort -PnpDevice $device[0]
if ($null -eq $identity -or $identity.ParentInstanceId -ne $ExpectedUsbInstanceId -or
[string]::IsNullOrWhiteSpace([string]$identity.LocationPath)) {
throw 'The selected USB parent/location could not be captured; refusing a reset or write.'
}
if ($ExpectedLocationPath -and $identity.LocationPath -ne $ExpectedLocationPath) {
throw 'The selected USB physical location changed; refusing a reset or write.'
}
if ((Get-EspUsbBootloaderStrategy -UsbIdentity $identity) -ne 'uart') {
throw 'The selected CP210x is not recognized as a UART transport by firmware.cmd.'
}
return $identity
}
$identity = Assert-BenchUsb
if ($Mode -eq 'Inventory') {
[pscustomobject]@{
Mode = $Mode; ComPort = $ComPort; UsbInstanceId = $identity.ParentInstanceId
LocationPath = $identity.LocationPath; UsbSerial = $identity.SerialNumber
Description = $identity.BusReportedDescription; HardwareOpened = $false
} | ConvertTo-Json
return
}
$ExpectedLocationPath = [string]$identity.LocationPath
if ($ExpectedMac) {
$identity | Add-Member -NotePropertyName Esp32ChipMac `
-NotePropertyValue ($ExpectedMac -replace '[:\-]', '').ToUpperInvariant() -Force
}
if ($Mode -eq 'Install') {
$imagePath = (Resolve-Path -LiteralPath $Image -ErrorAction Stop).ProviderPath
# firmware.cmd's native streaming adapter currently reparses its arguments.
# Avoid its whitespace-path ambiguity rather than risking a different file.
if ($imagePath -match '[\s"]' -or (Get-Item -LiteralPath $imagePath).PSIsContainer) {
throw 'Use an unambiguous file path without whitespace or double quotes for this bench install.'
}
$strategy = Get-EspFlashStrategy -Path $imagePath
if ($strategy.Classification -ne 'LIKELY_MERGED' -or $strategy.ClassifiedMode -ne 'install') {
throw 'Only a content-classified merged ESP32 image can be installed by this wrapper.'
}
if ((Get-FileHash -LiteralPath $imagePath -Algorithm SHA256).Hash -ne $ExpectedSha256) {
throw 'The selected merged image does not match the explicitly expected SHA-256.'
}
} elseif ($Mode -eq 'AppUpdate') {
$imagePath = Assert-BenchAppImage -Path $Image -Sha256 $ExpectedSha256
}
# Match firmware.cmd's per-user tool lock, without starting an updater or
# installing dependencies. Its helpers observe this already-held mutex.
$script:FirmwareToolUpdateJob = $null
$script:FirmwareToolUseLocked = $false
$account = [Security.Principal.WindowsIdentity]::GetCurrent()
try { $mutexName = "Local\MeshFirmwareTools-$($account.User.Value)" }
finally { $account.Dispose() }
$script:FirmwareToolUseMutex = New-Object Threading.Mutex($false, $mutexName)
try {
try { $script:FirmwareToolUseLocked = $script:FirmwareToolUseMutex.WaitOne(15000) }
catch [Threading.AbandonedMutexException] { $script:FirmwareToolUseLocked = $true }
if (-not $script:FirmwareToolUseLocked) { throw 'Firmware tools are busy in another process.' }
if (-not $PythonCommand) { $PythonCommand = (Get-Command python.exe -ErrorAction Stop).Source }
$script:pythonCommand = $PythonCommand
$esptool = get_esptool_cmd
$fresh = Assert-BenchUsb
if ($fresh.LocationPath -ne $identity.LocationPath) { throw 'USB location changed before handoff.' }
if ($Mode -eq 'Probe') {
$livePort = Enter-Esp32Bootloader -ComPort $ComPort -UsbIdentity $identity -EspToolCommand $esptool
$null = Assert-BenchUsb
$before = Get-Esp32RomBeforeMode -UsbIdentity $identity
$flashInfo = run_cmd "$esptool --baud 115200 --port $livePort --before $before --after $script:ESPTOOL_NO_RESET $script:ESPTOOL_FLASH_ID"
$livePort = Complete-Esp32FlashSession -ComPort $livePort -UsbIdentity $identity -SkipApplicationVerification
[pscustomobject]@{
Mode = $Mode; ComPort = $livePort; UsbInstanceId = $identity.ParentInstanceId
LocationPath = $identity.LocationPath; ChipMac = $identity.Esp32ChipMac
FlashInfo = $flashInfo; FlashWritten = $false; ApplicationVerified = $false
} | ConvertTo-Json
} elseif ($Mode -eq 'AppUpdate') {
$hardware = [pscustomobject]@{ ComPort = $ComPort; FirmwareFile = $imagePath; UsbIdentity = $identity }
$offsets = @(Get-BenchAppUpdatePlan -Hardware $hardware -EspToolCommand $esptool `
-FlasherPath $flasherPath -ExpectedImageSha256 $ExpectedSha256)
$null = Assert-BenchUsb
$null = Assert-BenchAppImage -Path $imagePath -Sha256 $ExpectedSha256
if (-not (updateFlashViaEspTool -hw $hardware)) {
throw 'firmware.cmd did not confirm the checked application-only write.'
}
$livePort = Complete-Esp32FlashSession -ComPort $hardware.ComPort -UsbIdentity $identity -SkipApplicationVerification
[pscustomobject]@{
Mode = $Mode; ComPort = $livePort; UsbInstanceId = $identity.ParentInstanceId
LocationPath = $identity.LocationPath; ChipMac = $identity.Esp32ChipMac
Image = $imagePath; Sha256 = $ExpectedSha256.ToLowerInvariant(); AppOffsets = $offsets
NvsMigration = $hardware.EspUpdateNvsProof
FlashWritten = $true; Erased = $false; PartitionTableWritten = $false
ApplicationVerified = $false
} | ConvertTo-Json
} else {
# No image substitution, backup prompt or update/partition migration:
# call the real flasher's single merged-install path, including its
# MAC rechecks before erase/write and qualified final hardware reset.
$null = Assert-BenchUsb
if ((Get-FileHash -LiteralPath $imagePath -Algorithm SHA256).Hash -ne $ExpectedSha256) {
throw 'The selected image changed before the verified full install.'
}
if (-not (Install-SimpleMergedEspImage -ImagePath $imagePath -ComPort $ComPort -UsbIdentity $identity)) {
throw 'firmware.cmd did not confirm the merged-image write.'
}
$null = Complete-Esp32FlashSession -ComPort $ComPort -UsbIdentity $identity -SkipApplicationVerification
[pscustomobject]@{
Mode = $Mode; ComPort = $ComPort; ChipMac = $identity.Esp32ChipMac
Image = $imagePath; Sha256 = $ExpectedSha256.ToLowerInvariant()
FlashWritten = $true; ApplicationVerified = $false
} | ConvertTo-Json
}
} finally {
Exit-FirmwareToolUse
if ($script:FirmwareToolUseMutex) { $script:FirmwareToolUseMutex.Dispose() }
}
+204
View File
@@ -0,0 +1,204 @@
#!/usr/bin/env bash
# Bench-only noninteractive entry point to mcfirmware.sh's real ESP32 flasher.
# The user must authorize resets/erasure of the explicitly selected radio.
# No direct esptool bypasses: preserve flasher USB/MAC binding, safe serial open,
# transport recovery, verification and guarded runtime handoff.
set -euo pipefail
flasher=/home/mikec/meshfirmware/mcfirmware.sh
bench_dir=''
requested_port=''
expected_usb_path=''
expected_usb_id=''
device=''
image=''
probe=0
watchdog_recover=0
erase=0
usage() {
printf '%s\n' \
'Usage: mcfirmware_bench_flash.sh --port DEVICE --usb-path EXACT_BY_PATH_NAME' \
' --device BUILD_BOARD_NAME --bench-dir ABSOLUTE_BENCH_DIR' \
' [--usb-id EXACT_BY_ID_NAME] [--flasher PATH]' \
' (--probe | --watchdog-recover | --image ABSOLUTE_MERGED_BIN --erase)' \
'' \
'--probe resets only the selected radio, reads chip/flash IDs, then restores runtime.' \
'--watchdog-recover is S3-only: clear volatile forced-ROM bit, reset target MCU by watchdog.' \
' No flash erasure/write; runtime startup must be verified separately afterward.' \
'--image requires explicit --erase and a content-verified merged ESP32 image.' \
'Uses a new isolated flasher-cache child under --bench-dir; skips startup menu,' \
'global USB autosuspend/group changes and Pi reboot/speed prompts.'
}
while (($#)); do
case "$1" in
--flasher|--bench-dir|--port|--usb-path|--usb-id|--device|--image)
(($# >= 2)) || { usage >&2; exit 2; }
case "$1" in
--flasher) flasher=$2 ;;
--bench-dir) bench_dir=$2 ;;
--port) requested_port=$2 ;;
--usb-path) expected_usb_path=$2 ;;
--usb-id) expected_usb_id=$2 ;;
--device) device=$2 ;;
--image) image=$2 ;;
esac
shift 2 ;;
--probe) probe=1; shift ;;
--watchdog-recover) watchdog_recover=1; shift ;;
--erase) erase=1; shift ;;
--help|-h) usage; exit 0 ;;
*) printf 'Unknown option: %s\n' "$1" >&2; usage >&2; exit 2 ;;
esac
done
[[ -f "$flasher" && -n "$requested_port" && -n "$device" && "$bench_dir" == /* ]] \
|| { usage >&2; exit 2; }
[[ -n "$expected_usb_path" && "$expected_usb_path" != */* && "$expected_usb_path" != .* ]] \
|| { echo 'An exact /dev/serial/by-path basename is required.' >&2; exit 2; }
[[ -z "$expected_usb_id" || ( "$expected_usb_id" != */* && "$expected_usb_id" != .* ) ]] \
|| { echo '--usb-id must be an exact basename.' >&2; exit 2; }
if ((probe + watchdog_recover > 1)); then
echo '--probe and --watchdog-recover are mutually exclusive.' >&2; exit 2
elif ((probe || watchdog_recover)); then
[[ -z "$image" && "$erase" == 0 ]] || { echo 'Probe/recovery cannot erase or install.' >&2; exit 2; }
else
[[ "$erase" == 1 && "$image" == /* && -r "$image" && -s "$image" ]] \
|| { echo 'Installing requires --image ABSOLUTE_MERGED_BIN and explicit --erase.' >&2; exit 2; }
fi
guard_selected_usb() {
local live_path live_port live_id
live_path=$(readlink -e -- "/dev/serial/by-path/$expected_usb_path") || {
echo 'The exact selected USB path is absent; refusing another device.' >&2; return 1;
}
live_port=$(readlink -e -- "${DEVICE_PORT:-$requested_port}") || return 1
[[ "$live_port" == "$live_path" ]] || {
echo 'Selected serial port no longer matches the required physical USB path.' >&2; return 1;
}
# Initial by-id must be exact. After the flasher has bound the silicon MAC,
# a runtime-to-ROM product-name change is legitimate; the physical path plus
# its own immediate MAC probe still gate every destructive operation.
if [[ -n "$expected_usb_id" && -z "${ESP32_FLASH_EXPECTED_MAC:-}" ]]; then
live_id=$(readlink -e -- "/dev/serial/by-id/$expected_usb_id") || return 1
[[ "$live_id" == "$live_path" ]] || {
echo 'The exact selected USB by-id and by-path identities disagree.' >&2; return 1;
}
fi
[[ -c "$live_path" ]] || return 1
}
# Validate before loading any flasher state or installing any cleanup handler.
guard_selected_usb
grep -q '^# MAIN$' "$flasher" || { echo 'Unsupported flasher: MAIN marker absent.' >&2; exit 1; }
# Source functions and their normal global defaults, but not the three startup
# actions or their traps. A plain prefix source would change global host USB
# power settings and could offer a Pi reboot before MAIN even starts.
source <(awk '
/^# MAIN$/ { exit }
/^(initialize_privilege_mode|meshfirmware_check_pi_usb_host_speed|configure_usb_autosuspend)$/ { next }
/^trap / { next }
{ print }
' "$flasher")
PWD_SCRIPT=$(cd -- "$(dirname -- "$flasher")" && pwd)
mkdir -p -- "$bench_dir"
FIRMWARE_ROOT=$(mktemp -d "$bench_dir/mcfirmware-cache.XXXXXX")
DOWNLOAD_DIR="$FIRMWARE_ROOT/downloads"
mkdir -p -- "$DOWNLOAD_DIR"
DEVICE_PORT_FILE="$FIRMWARE_ROOT/09device_port_file.txt"
DEVICE_PORT_NAME_FILE="$FIRMWARE_ROOT/10device_port_name_file.txt"
ESPTOOL_FILE="$FIRMWARE_ROOT/12esptool_file.txt"
DEVICE="$device"
ARCHITECTURE=esp32
MESH_DISABLE_1200_RECOVERY=1
MESHFIRMWARE_PI_USB_CHECK=0
trap cleanup EXIT
trap 'error_handler $LINENO' ERR
for required in save_selected_serial_port prepare_esp32_flash_session \
run_esp32_session_esptool finish_esp32_flash_session esp32_prepare_merged_ota_mirror; do
declare -F "$required" >/dev/null || { echo "Flasher lacks required safety function: $required" >&2; exit 1; }
done
ensure_pipx_uv_backend
get_espcmd
DEVICE_PORT=$(readlink -e -- "$requested_port")
guard_selected_usb
save_selected_serial_port "$DEVICE_PORT"
printf 'Bench target: device=%s port=%s usb_path=%s\n' "$DEVICE" "$DEVICE_PORT" "$expected_usb_path"
printf 'Flasher cache: %s\n' "$FIRMWARE_ROOT"
if ((!probe && !watchdog_recover)); then
[[ "$(esp_firmware_layout "$image")" == merged ]] || {
echo 'Image is not content-verified merged firmware; refusing erase.' >&2; exit 1;
}
esp32_validate_image_for_device "$DEVICE" "$image" merged
ESP32_MERGED_WRITE_ARGS=(0x0000 "$image")
ESP32_MERGED_OTA_IMAGE=$(mktemp "$FIRMWARE_ROOT/mirror.XXXXXX.bin")
mirror_output=$(esp32_prepare_merged_ota_mirror "$image" "$ESP32_MERGED_OTA_IMAGE")
if [[ -n "$mirror_output" ]]; then
mapfile -t mirror_offsets <<< "$mirror_output"
for offset in "${mirror_offsets[@]}"; do
ESP32_MERGED_WRITE_ARGS+=("$offset" "$ESP32_MERGED_OTA_IMAGE")
done
fi
fi
prepare_esp32_flash_session "$DEVICE_PORT" "$DEVICE"
guard_selected_usb
if [[ "$NORESET" == no_reset ]]; then
flash_id_command=flash_id
chip_id_command=chip_id
write_mem_command=write_mem
else
flash_id_command=flash-id
chip_id_command=chip-id
write_mem_command=write-mem
fi
run_esp32_session_esptool "$DEVICE_PORT" --after "$NORESET" --baud 115200 "$chip_id_command"
probe_after_mode=$NORESET
if ((probe)); then
# finish_esp32_flash_session() only needs an explicit reset for S3/native
# USB. Ordinary UART ESP32 probes must request their normal final hard reset
# here, just as the real flasher's write command would have done.
probe_after_mode=$(esp32_write_after_mode "$DEVICE_PORT")
fi
run_esp32_session_esptool "$DEVICE_PORT" --after "$probe_after_mode" --baud 115200 "$flash_id_command"
if ((watchdog_recover)); then
[[ "${ESP32_SESSION_IS_S3:-0}" == 1 && -n "${WATCHDOGRESET:-}" ]] || {
echo 'Watchdog recovery requires a positively identified ESP32-S3 and supported reset mode.' >&2
exit 1
}
# Native USB's bootloader-entry sequence sets FORCE_DOWNLOAD_BOOT. A WDT
# alone would retain it. This is the exact masked volatile-register clear
# used by esptool.targets.esp32s3.ESP32S3ROM.hard_reset(), not a flash write.
guard_selected_usb
DEVICE_PORT=$(esp32_verified_destructive_port "$DEVICE_PORT" "S3 volatile forced-ROM bit clear")
guard_selected_usb
run_esp32_session_esptool "$DEVICE_PORT" --after "$NORESET" --baud 115200 \
"$write_mem_command" 0x6000812c 0 0x1
guard_selected_usb
DEVICE_PORT=$(esp32_verified_destructive_port "$DEVICE_PORT" "S3 watchdog recovery")
guard_selected_usb
run_esp32_session_esptool "$DEVICE_PORT" --after "$WATCHDOGRESET" --baud 115200 "$READMAC"
BOOTLOADER_PROBE_ACTIVE=0
BOOTLOADER_PROBE_PORT=''
echo 'Targeted S3 watchdog recovery requested; flash unchanged. Runtime is not yet verified.'
exit 0
fi
if ((!probe)); then
guard_selected_usb
run_esp32_session_esptool "$DEVICE_PORT" --after "$NORESET" --baud 115200 "$ERASEFLASH"
sleep 1
guard_selected_usb
after_mode=$(esp32_write_after_mode "$DEVICE_PORT")
run_esp32_session_esptool "$DEVICE_PORT" --after "$after_mode" --baud 115200 "$WRITEFLASH" \
"${ESP32_MERGED_WRITE_ARGS[@]}"
fi
finish_esp32_flash_session "$DEVICE_PORT"
# Successful finish already verified the runtime USB handoff. Retain guarded
# cleanup recovery for failures, but don't reset that proven runtime a second time.
BOOTLOADER_PROBE_ACTIVE=0
BOOTLOADER_PROBE_PORT=''
printf 'Completed %s: %s\n' "$([[ "$probe" == 1 ]] && printf probe || printf install)" "$DEVICE_PORT"
+4
View File
@@ -1,6 +1,10 @@
[Heltec_lora32_v3]
extends = esp32_base
board = esp32-s3-devkitc-1
; Keep every V3 role compatible with the DIO bootloader used by Full images.
; This must select the DIO SDK/bootloader too, not only rewrite image headers:
; the generic DevKit manifest otherwise defaults non-Full/KISS builds to QIO.
board_build.flash_mode = dio
build_flags =
${esp32_base.build_flags}
${sensor_base.build_flags}