diff --git a/test/test_heltec_v3_flash_mode.py b/test/test_heltec_v3_flash_mode.py new file mode 100644 index 000000000..3ba07eadd --- /dev/null +++ b/test/test_heltec_v3_flash_mode.py @@ -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() diff --git a/test/test_mcfirmware_bench_flash.py b/test/test_mcfirmware_bench_flash.py new file mode 100644 index 000000000..5f952ae9e --- /dev/null +++ b/test/test_mcfirmware_bench_flash.py @@ -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() diff --git a/tools/hil/firmware_bench_flash.ps1 b/tools/hil/firmware_bench_flash.ps1 new file mode 100644 index 000000000..7ed6d58ac --- /dev/null +++ b/tools/hil/firmware_bench_flash.ps1 @@ -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() } +} diff --git a/tools/hil/mcfirmware_bench_flash.sh b/tools/hil/mcfirmware_bench_flash.sh new file mode 100644 index 000000000..3f2f253ea --- /dev/null +++ b/tools/hil/mcfirmware_bench_flash.sh @@ -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" diff --git a/variants/heltec_v3/platformio.ini b/variants/heltec_v3/platformio.ini index 8492fd452..1b27dac2c 100644 --- a/variants/heltec_v3/platformio.ini +++ b/variants/heltec_v3/platformio.ini @@ -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}