Add verified USB-only ESP32 partition migration bridges
This commit is contained in:
1 parent
f304b8ff77
commit
cbafd44047
14 files changed
+1366
-27
No files matched your search
@@ -1,5 +1,5 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Build verified in-place Wi-Fi and LoRa ESP32 partition-migration ZIPs.
|
||||
"""Build verified in-place Wi-Fi, USB and LoRa ESP32 partition-migration ZIPs.
|
||||
|
||||
Run in Linux/WSL with PlatformIO installed. PlatformIO steps are deliberately
|
||||
serial: build.sh cleans the shared .pio/build tree between Full targets.
|
||||
@@ -20,7 +20,7 @@ import sys
|
||||
import tempfile
|
||||
import zipfile
|
||||
|
||||
from package_esp32_partition_migration import BOARDS, resolve_pio_build_dir
|
||||
from package_esp32_partition_migration import BOARDS, USB_BRIDGE_PROFILES, resolve_pio_build_dir
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
@@ -47,7 +47,7 @@ def build_steps(boards: list[str], version: str, radio_preset: str,
|
||||
# Full builds can clear .pio/build; every bridge must be built afterwards.
|
||||
built_bridges: set[str] = set()
|
||||
for name in boards:
|
||||
for key in ("wifi_bridge", "lora_bridge", "expander_bridge"):
|
||||
for key in ("wifi_bridge", "usb_bridge", "lora_bridge", "expander_bridge"):
|
||||
bridge = BOARDS[name].get(key)
|
||||
if bridge and bridge not in built_bridges:
|
||||
steps.append((["pio", "run", "-e", bridge,
|
||||
@@ -56,6 +56,45 @@ def build_steps(boards: list[str], version: str, radio_preset: str,
|
||||
return steps
|
||||
|
||||
|
||||
def usb_build_steps(jobs: int) -> list[list[str]]:
|
||||
"""Build only the complete USB utility set, serially, without any Full app."""
|
||||
return [["pio", "run", "-e", environment, "-j", str(jobs)]
|
||||
for _, environment in sorted(USB_BRIDGE_PROFILES.items())]
|
||||
|
||||
|
||||
def build_usb_only(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
|
||||
if args.board or args.role:
|
||||
parser.error("--usb-only builds all six chip/capacity utilities; do not select a board/role")
|
||||
source = git_output("rev-parse", "--short=8", "HEAD")
|
||||
requested_root = args.output_root or Path(".releases") / f"esp32-usb-bridges-{source}"
|
||||
output_root = (requested_root if requested_root.is_absolute()
|
||||
else ROOT / requested_root).resolve()
|
||||
output_file = output_root / "meshcore-usb-partition-bridges.zip"
|
||||
steps = usb_build_steps(args.jobs)
|
||||
for command in steps:
|
||||
print(shlex.join(command), flush=True)
|
||||
print(f"Package all six USB utilities into {output_file}", flush=True)
|
||||
if args.dry_run:
|
||||
return
|
||||
if not shutil.which("pio"):
|
||||
parser.error("pio is unavailable in this environment")
|
||||
environment = os.environ.copy()
|
||||
try:
|
||||
utility_build_dir = resolve_pio_build_dir(environment=environment, project_dir=ROOT)
|
||||
except ValueError as error:
|
||||
parser.error(str(error))
|
||||
environment["PLATFORMIO_BUILD_DIR"] = str(utility_build_dir)
|
||||
for command in steps:
|
||||
subprocess.run(command, cwd=ROOT, env=environment, check=True)
|
||||
# Unlike exact Full release packages, this independent utility set records
|
||||
# its actual dirty state and runtime-source hashes instead of pretending
|
||||
# its binaries came from an older Full app's release commit.
|
||||
subprocess.run([
|
||||
sys.executable, "-B", "scripts/package_usb_partition_bridges.py",
|
||||
"--pio-build-dir", str(utility_build_dir), "--output-file", str(output_file),
|
||||
], cwd=ROOT, env=environment, check=True)
|
||||
|
||||
|
||||
def verify_archive(path: Path, board: str, version: str, source: str) -> None:
|
||||
with zipfile.ZipFile(path) as archive:
|
||||
damaged = archive.testzip()
|
||||
@@ -142,21 +181,27 @@ def main() -> None:
|
||||
help="show the build order without writing files")
|
||||
parser.add_argument("--list-boards", action="store_true",
|
||||
help="print configured board/role keys and exit")
|
||||
parser.add_argument("--usb-only", action="store_true",
|
||||
help="build/package all six independent USB utilities only; "
|
||||
"no Full app, version or radio preset is needed")
|
||||
args = parser.parse_args()
|
||||
if args.list_boards:
|
||||
for name in BOARDS:
|
||||
print(name)
|
||||
return
|
||||
if args.jobs < 1:
|
||||
parser.error("--jobs must be positive")
|
||||
if os.name == "nt" and not args.dry_run:
|
||||
parser.error("run this recipe inside Linux/WSL, where bash and pio are available")
|
||||
if args.usb_only:
|
||||
build_usb_only(args, parser)
|
||||
return
|
||||
if not args.version or not args.radio_preset:
|
||||
parser.error("--version and --radio-preset are required for a build")
|
||||
if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._+\-]*", args.version):
|
||||
parser.error("--version must be a filename-safe version token")
|
||||
if args.jobs < 1:
|
||||
parser.error("--jobs must be positive")
|
||||
if args.board and args.role:
|
||||
parser.error("choose --board or --role, not both")
|
||||
if os.name == "nt" and not args.dry_run:
|
||||
parser.error("run this recipe inside Linux/WSL, where bash and pio are available")
|
||||
|
||||
source = git_output("rev-parse", "--short=8", "HEAD")
|
||||
if args.role:
|
||||
|
||||
@@ -200,7 +200,7 @@ def migration_targets() -> list[str]:
|
||||
|
||||
def migration_bridges() -> list[str]:
|
||||
return sorted({name for spec in BOARDS.values()
|
||||
for name in (spec.get("wifi_bridge"), spec.get("lora_bridge"),
|
||||
for name in (spec.get("wifi_bridge"), spec.get("usb_bridge"), spec.get("lora_bridge"),
|
||||
spec.get("expander_bridge")) if name})
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
"""Build-local NVS preservation for callback-free USB migration bridges.
|
||||
|
||||
Arduino normally erases the entire NVS partition on NO_FREE_PAGES or a newer
|
||||
NVS version before setup() runs. That destroys staged identity/configuration.
|
||||
For dedicated USB bridges only, retain the initialization error and leave NVS
|
||||
untouched; the runtime then refuses and returns to its recovery transport.
|
||||
The shared Arduino SDK and normal firmware builds are never modified.
|
||||
"""
|
||||
|
||||
import hashlib
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
PINNED_MISC_SHA256 = "d6374832d4e7d987e8c9eb71aa36f12e6f03a5d16c298a139a6b222a108788d1"
|
||||
GUARD_MARKER = " // MeshCore USB migrator: preserve NVS on initialization failure.\n"
|
||||
BINARY_MARKER = "MeshCore USB NVS no-autoerase guard v1"
|
||||
MARKER_FUNCTION = '''
|
||||
// Referenced by the dedicated USB runtime: a missing middleware must not link.
|
||||
const char* meshEsp32MigrationNvsGuardMarker(void) {
|
||||
return "MeshCore USB NVS no-autoerase guard v1";
|
||||
}
|
||||
'''
|
||||
AUTOFORMAT = ''' if(err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND){
|
||||
const esp_partition_t* partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_DATA_NVS, NULL);
|
||||
if (partition != NULL) {
|
||||
err = esp_partition_erase_range(partition, 0, partition->size);
|
||||
if(!err){
|
||||
err = nvs_flash_init();
|
||||
} else {
|
||||
log_e("Failed to format the broken NVS partition!");
|
||||
}
|
||||
} else {
|
||||
log_e("Could not find NVS partition");
|
||||
}
|
||||
}
|
||||
'''
|
||||
|
||||
|
||||
def patched_misc_source(source):
|
||||
source = source.replace("\r\n", "\n")
|
||||
# Permit our own exact transformation to be read again without relaxing the
|
||||
# original SDK pin. A stray marker or altered surrounding code is rejected.
|
||||
original = source.replace(GUARD_MARKER, AUTOFORMAT) if source.count(GUARD_MARKER) == 1 else source
|
||||
if original.endswith(MARKER_FUNCTION):
|
||||
original = original[:-len(MARKER_FUNCTION)]
|
||||
if (hashlib.sha256(original.encode("utf-8")).hexdigest() != PINNED_MISC_SHA256
|
||||
or original.count(AUTOFORMAT) != 1):
|
||||
raise RuntimeError("ESP32 USB migration NVS guard: changed Arduino startup; review SDK update")
|
||||
return original.replace(AUTOFORMAT, GUARD_MARKER) + MARKER_FUNCTION
|
||||
|
||||
|
||||
def usb_migration_enabled(build_env):
|
||||
defines = {}
|
||||
for definition in build_env.get("CPPDEFINES", []):
|
||||
if isinstance(definition, (tuple, list)):
|
||||
defines[definition[0]] = str(definition[1])
|
||||
else:
|
||||
defines[str(definition)] = "1"
|
||||
return defines.get("MESHCORE_MIGRATION_USB") == "1"
|
||||
|
||||
|
||||
def replace_source(build_env, node):
|
||||
if not usb_migration_enabled(build_env):
|
||||
return node
|
||||
source = Path(node.srcnode().get_abspath())
|
||||
patched = patched_misc_source(source.read_text(encoding="utf-8"))
|
||||
destination = Path(build_env.subst("$BUILD_DIR")) / "patched-esp32-migration" / source.name
|
||||
destination.parent.mkdir(parents=True, exist_ok=True)
|
||||
if not destination.exists() or destination.read_text(encoding="utf-8") != patched:
|
||||
destination.write_text(patched, encoding="utf-8")
|
||||
build_env.AppendUnique(CPPPATH=[str(source.parent)])
|
||||
return build_env.File(str(destination))
|
||||
|
||||
|
||||
def install(build_env):
|
||||
build_env.AddBuildMiddleware(replace_source, "*cores*esp32*esp32-hal-misc.c")
|
||||
|
||||
|
||||
if "Import" in globals():
|
||||
Import("env")
|
||||
install(env)
|
||||
@@ -1,5 +1,5 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Package the two-stage Wi-Fi and LoRa ESP32 partition migrations."""
|
||||
"""Package verified two-stage Wi-Fi, USB and LoRa ESP32 partition migrations."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -270,10 +270,44 @@ add_roles("generic-e22-sx1268", 4, {
|
||||
"repeater": "Generic_E22_sx1268_repeater",
|
||||
}, bridge="esp32_4mb_partition_migrator")
|
||||
|
||||
USB_BRIDGE_MARKER = b"MeshCore USB partition migration bridge v1"
|
||||
USB_NVS_GUARD_MARKER = b"MeshCore USB NVS no-autoerase guard v1"
|
||||
USB_BRIDGE_PROFILES = {
|
||||
(9, 4): "esp32_s3_4mb_partition_migrator_usb",
|
||||
(9, 8): "esp32_s3_8mb_partition_migrator_usb",
|
||||
(9, 16): "esp32_s3_16mb_partition_migrator_usb",
|
||||
(0, 4): "esp32_4mb_partition_migrator_usb",
|
||||
(0, 8): "esp32_8mb_partition_migrator_usb",
|
||||
(5, 4): "esp32_c3_4mb_partition_migrator_usb",
|
||||
}
|
||||
|
||||
|
||||
def usb_bridge_profile(spec: dict) -> tuple[int, str]:
|
||||
"""Map reviewed chip-family bridges, never a generic S3 fallback."""
|
||||
wifi = spec["wifi_bridge"]
|
||||
if wifi.startswith("esp32_c3_"):
|
||||
chip = 5
|
||||
elif wifi.startswith("esp32_s3_") or wifi in (
|
||||
"heltec_v4_partition_migrator", "xiao_s3_partition_migrator"):
|
||||
chip = 9
|
||||
elif wifi.startswith("esp32_"):
|
||||
chip = 0
|
||||
else:
|
||||
raise ValueError(f"unreviewed USB migration chip-family bridge: {wifi}")
|
||||
flash_mib = spec["flash_bytes"] // (1024 * 1024)
|
||||
if spec["flash_bytes"] != flash_mib * 1024 * 1024:
|
||||
raise ValueError("USB migration flash capacity must be exact MiB")
|
||||
profile = USB_BRIDGE_PROFILES.get((chip, flash_mib))
|
||||
if profile is None:
|
||||
raise ValueError("no reviewed USB bridge for this chip and flash capacity")
|
||||
return chip, profile
|
||||
|
||||
|
||||
for specification in BOARDS.values():
|
||||
specification.setdefault("role", role_for_target(specification["target"]))
|
||||
if specification["lora_bridge"] is None:
|
||||
specification["lora_bridge"] = specification["wifi_bridge"] + "_lora"
|
||||
specification["usb_chip"], specification["usb_bridge"] = usb_bridge_profile(specification)
|
||||
|
||||
LEGACY_SLOT_BYTES = 0x140000
|
||||
|
||||
@@ -282,6 +316,26 @@ def sha256(data: bytes) -> str:
|
||||
return hashlib.sha256(data).hexdigest()
|
||||
|
||||
|
||||
def validate_usb_bridge(image: bytes, spec: dict) -> None:
|
||||
"""Refuse stale Wi-Fi binaries and wrong-family/capacity utility builds."""
|
||||
if len(image) < 24 or image[0] != 0xE9 or not 1 <= image[1] <= 16:
|
||||
raise ValueError("USB bridge is not a valid ESP32 application image")
|
||||
chip, profile = usb_bridge_profile(spec)
|
||||
image_chip = struct.unpack_from("<H", image, 12)[0]
|
||||
expected_flash = {4 * 1024 * 1024: 2, 8 * 1024 * 1024: 3,
|
||||
16 * 1024 * 1024: 4}[spec["flash_bytes"]]
|
||||
if image_chip != chip or image[3] >> 4 != expected_flash:
|
||||
raise ValueError(f"USB bridge chip/flash header does not match {profile}")
|
||||
if image[2] != 2:
|
||||
raise ValueError("USB migration bridge must use the reviewed DIO flash mode")
|
||||
if USB_BRIDGE_MARKER not in image:
|
||||
raise ValueError("USB bridge lacks the automatic-ROM migration capability marker")
|
||||
if USB_NVS_GUARD_MARKER not in image:
|
||||
raise ValueError("USB bridge lacks the reviewed NVS no-autoerase guard")
|
||||
if len(image) > LEGACY_SLOT_BYTES:
|
||||
raise ValueError("USB bridge does not fit the 1.25 MiB legacy slot")
|
||||
|
||||
|
||||
def resolve_pio_build_dir(pio_build_dir: Path | None = None, *,
|
||||
environment: dict[str, str] | None = None,
|
||||
project_dir: Path | None = None) -> Path:
|
||||
@@ -390,6 +444,13 @@ def check_esp32_stage(package: bytes, image: bytes, slot_bytes: int) -> None:
|
||||
|
||||
def readme(board: str, spec: dict, version: str, source: str,
|
||||
has_full_mota: bool = True, full_mota_blocks: int = 0) -> str:
|
||||
usb_return = (
|
||||
"On native ESP32-S3/C3, it then returns to the chip's ROM download "
|
||||
"mode in software."
|
||||
if spec["usb_chip"] != 0 else
|
||||
"On classic ESP32, it publishes settled completion status on UART; "
|
||||
"the host then uses the existing USB-UART bridge's DTR/RTS bootloader reset."
|
||||
)
|
||||
expander_instructions = ""
|
||||
if spec.get("expander_bridge"):
|
||||
expander_instructions = f"""## Partition Expander route (automatic LoRa finish)
|
||||
@@ -424,6 +485,31 @@ installing the bridge; the bridge does not itself repeat normal traffic.
|
||||
2. Keep power stable. Join `MeshCore-Migrate` (password `meshcore-migrate`),
|
||||
open `http://192.168.4.1/`, and wait for **Expanded layout ready**.
|
||||
3. At that page's `/update`, upload `full-application.bin`.
|
||||
"""
|
||||
usb_instructions = f"""## Host-managed USB route
|
||||
|
||||
`usb-bridge.bin` is a separate, verified **{spec['usb_bridge']}** first stage
|
||||
for this chip family and flash capacity. Do not substitute `wifi-bridge.bin`
|
||||
or a USB diagnostic harness. The production USB bridge keeps application USB
|
||||
CDC disabled during cache-disabled flash operations; it does not enable the
|
||||
old unsafe Wi-Fi bridge's native CDC callback path.
|
||||
|
||||
An identity-bound host flasher installs only this small app into the existing
|
||||
OTA slots, inactive first and active last, without erasing the chip. Keep power
|
||||
stable while the bridge expands the table and restores and verifies identity
|
||||
and supported configuration across both boots. {usb_return} Neither route
|
||||
needs physical BOOT/RESET access or a Wi-Fi network change, including on an
|
||||
elevated remote node. A classic board must have a working automatic USB-UART
|
||||
reset circuit; a direct UART adapter without that circuit is not sufficient.
|
||||
|
||||
The host must reverify the same physical USB identity and original chip MAC,
|
||||
read the exact target table, stable NVS restore markers and valid OTA metadata,
|
||||
and refuse the final app unless all completion checks pass. A timer, USB
|
||||
reappearance or partition-table match alone is not success. On a failed
|
||||
migration the bridge can return to ROM for diagnosis; this likewise does not
|
||||
authorize the final app. After verified completion, write `full-application.bin`
|
||||
to the expanded OTA slots with the active slot last. Never write
|
||||
`target-partitions.bin` directly or erase NVS to force success.
|
||||
"""
|
||||
if spec["lora_bridge"]:
|
||||
slot_instructions = (
|
||||
@@ -518,7 +604,8 @@ the 96-byte public/private identity in unchanged NVS, preserves a bootable old
|
||||
receiver, and changes the partition table. On 8/16 MiB LoRa and Wi-Fi routes
|
||||
the bridge restores and verifies the identity in expanded SPIFFS; on the
|
||||
4 MiB LoRa route the new Full firmware does so at first boot. No full-chip
|
||||
erase or USB connection is used.
|
||||
erase is used. The Wi-Fi/LoRa routes need no USB connection; the separate USB
|
||||
route below is managed by an identity-verified host flasher.
|
||||
The table sector and inactive app sectors are erased as part of migration.
|
||||
SPIFFS may be reformatted. The Wi-Fi bridge restores verified radio 1 and
|
||||
radio 2 settings, node name, ACL and login replay state, region keys, and
|
||||
@@ -530,6 +617,7 @@ on an inaccessible node without accepting that risk and testing a sacrificial
|
||||
example of the same board first.
|
||||
|
||||
{wifi_instructions}
|
||||
{usb_instructions}
|
||||
{expander_instructions}
|
||||
{lora_instructions}
|
||||
"""
|
||||
@@ -576,6 +664,8 @@ def package_board(name: str, spec: dict, build_dir: Path, output_dir: Path,
|
||||
raise ValueError(f"{name}: Full image identity or partition fit failed")
|
||||
|
||||
wifi_bridge = (utility_build_dir / spec["wifi_bridge"] / "firmware.bin").read_bytes()
|
||||
usb_bridge = (utility_build_dir / spec["usb_bridge"] / "firmware.bin").read_bytes()
|
||||
validate_usb_bridge(usb_bridge, spec)
|
||||
bridge_ident = FwIdent(pack_version(version.split("-", 1)[0]), target_id, hw_id)
|
||||
if len(wifi_bridge) > LEGACY_SLOT_BYTES:
|
||||
raise ValueError(f"{name}: bridge does not fit the 1.25 MiB legacy slot")
|
||||
@@ -584,6 +674,7 @@ def package_board(name: str, spec: dict, build_dir: Path, output_dir: Path,
|
||||
|
||||
files = {
|
||||
"wifi-bridge.bin": wifi_bridge,
|
||||
"usb-bridge.bin": usb_bridge,
|
||||
"full-application.bin": full_image,
|
||||
"target-partitions.bin": table,
|
||||
"capabilities.json": capability_path.read_bytes(),
|
||||
@@ -635,6 +726,18 @@ def package_board(name: str, spec: dict, build_dir: Path, output_dir: Path,
|
||||
"legacy_slot_bytes": LEGACY_SLOT_BYTES,
|
||||
"expanded_slot_bytes": slot_bytes,
|
||||
"atomic_power_loss_recovery": False,
|
||||
"usb_migration": {
|
||||
"format": "meshcore-usb-partition-migration-v1",
|
||||
"bridge": "usb-bridge.bin",
|
||||
"environment": spec["usb_bridge"],
|
||||
"chip": spec["usb_chip"],
|
||||
"flash_bytes": spec["flash_bytes"],
|
||||
"automatic_rom_return": spec["usb_chip"] != 0,
|
||||
"uart_completion_status": spec["usb_chip"] == 0,
|
||||
"host_software_bootloader_entry": True,
|
||||
"application_usb_cdc": False,
|
||||
"completion": "verified-target-table-nvs-restoration-otadata",
|
||||
},
|
||||
"lora_bridge_mode": ("slot-b-only-full-identity-recovery"
|
||||
if spec["flash_bytes"] == 4 * 1024 * 1024
|
||||
else "either-slot-preserve-receiver"),
|
||||
|
||||
@@ -0,0 +1,179 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Package all six USB-safe bridges without rebuilding or relabeling Full apps.
|
||||
|
||||
This utility set is paired by the host with the exact original Full migration
|
||||
package. It carries its own source provenance, not that Full image's commit.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import hashlib
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
import subprocess
|
||||
import tempfile
|
||||
import zipfile
|
||||
|
||||
from package_esp32_partition_migration import (
|
||||
USB_BRIDGE_PROFILES, resolve_pio_build_dir, validate_usb_bridge,
|
||||
)
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
FORMAT = "meshcore-usb-partition-bridges-v1"
|
||||
SOURCE_FILES = (
|
||||
"examples/esp32_partition_migrator/main.cpp",
|
||||
"src/helpers/ESP32PartitionMigrationPolicy.h",
|
||||
"src/helpers/ESP32PartitionMigrationUsbRecovery.h",
|
||||
"scripts/esp32_partition_migration_nvs_guard.py",
|
||||
"scripts/esp32_wifi_scan_fix.py",
|
||||
"scripts/check_firmware_ram.py",
|
||||
"variants/esp32_partition_migrator/platformio.ini",
|
||||
"platformio.ini",
|
||||
)
|
||||
|
||||
|
||||
def sha256(data: bytes) -> str:
|
||||
return hashlib.sha256(data).hexdigest()
|
||||
|
||||
|
||||
def source_provenance(root: Path = ROOT) -> dict:
|
||||
source = subprocess.check_output(
|
||||
["git", "-c", "core.autocrlf=input", "rev-parse", "HEAD"],
|
||||
cwd=root, text=True).strip()
|
||||
if not re.fullmatch(r"[0-9a-f]{8,40}", source):
|
||||
raise ValueError("invalid USB bridge source commit")
|
||||
dirty = bool(subprocess.check_output(
|
||||
["git", "-c", "core.autocrlf=input", "status", "--porcelain",
|
||||
"--untracked-files=normal"], cwd=root, text=True).strip())
|
||||
files = {name: sha256((root / name).read_bytes().replace(b"\r\n", b"\n"))
|
||||
for name in SOURCE_FILES}
|
||||
# Pin both paths and bytes, making provenance portable across line-ending
|
||||
# conversions while recording a dirty source build truthfully.
|
||||
tree = "".join(f"{digest} {name}\n" for name, digest in sorted(files.items())).encode()
|
||||
return {"source_commit": source, "working_tree_dirty": dirty,
|
||||
"source_tree_sha256": sha256(tree), "source_files": files}
|
||||
|
||||
|
||||
def guide() -> bytes:
|
||||
return b"""# USB-safe ESP32 partition bridge set
|
||||
|
||||
Six chip/capacity profiles: original ESP32 4/8 MiB, ESP32-C3 4 MiB,
|
||||
and ESP32-S3 4/8/16 MiB. These are intermediate applications, NOT final
|
||||
MeshCore firmware, bootloaders, merged images, or partition-table binaries.
|
||||
|
||||
Use an identity-bound host flasher with the exact original Full migration
|
||||
package. Do not relabel an older Full app as built from this utility source.
|
||||
Native S3/C3 bridges keep application USB CDC disabled while writing flash
|
||||
and return to ROM automatically after restoration settles. Classic ESP32
|
||||
reports matching-MAC settled UART status before host DTR/RTS bootloader entry;
|
||||
its USB-UART automatic reset circuit must work. No physical BOOT is required.
|
||||
|
||||
The host must verify exact target table, CRC-valid NVS restored/no-pending
|
||||
markers, current OTA metadata, physical USB identity, original chip MAC, and
|
||||
the unchanged final image before writing that app inactive-first/active-last.
|
||||
USB reappearance, elapsed time, or settled status alone is NOT recovery proof.
|
||||
Keep stable power. Partition-table writes are not power-loss atomic and
|
||||
unsupported stored files may not survive. No full-chip erase is required.
|
||||
"""
|
||||
|
||||
|
||||
def verify_set(path: Path) -> dict:
|
||||
with zipfile.ZipFile(path) as archive:
|
||||
if archive.testzip():
|
||||
raise ValueError("USB bridge ZIP integrity check failed")
|
||||
manifest = json.loads(archive.read("manifest.json"))
|
||||
if manifest.get("format") != FORMAT:
|
||||
raise ValueError("invalid USB bridge set format")
|
||||
expected_profiles = {(chip, mib * 1048576) for chip, mib in USB_BRIDGE_PROFILES}
|
||||
rows = manifest.get("bridges", [])
|
||||
if len(rows) != 6 or {(row["chip"], row["flash_bytes"]) for row in rows} != expected_profiles:
|
||||
raise ValueError("USB bridge set must contain every reviewed chip/capacity profile exactly once")
|
||||
names = set(manifest["files"]) | {"manifest.json", "SHA256SUMS.txt"}
|
||||
if set(archive.namelist()) != names or len(archive.namelist()) != len(names):
|
||||
raise ValueError("USB bridge set inventory is not exact")
|
||||
for name, record in manifest["files"].items():
|
||||
data = archive.read(name)
|
||||
if len(data) != record["bytes"] or sha256(data) != record["sha256"]:
|
||||
raise ValueError("USB bridge set payload hash mismatch")
|
||||
sums = "".join(f"{sha256(archive.read(name))} {name}\n"
|
||||
for name in sorted(names - {"SHA256SUMS.txt"})).encode()
|
||||
if archive.read("SHA256SUMS.txt") != sums:
|
||||
raise ValueError("USB bridge set checksum inventory mismatch")
|
||||
for row in rows:
|
||||
chip = row["chip"]
|
||||
if (row.get("automatic_rom_return") is not (chip != 0)
|
||||
or row.get("uart_completion_status") is not (chip == 0)
|
||||
or row.get("host_software_bootloader_entry") is not True
|
||||
or row.get("application_usb_cdc") is not False):
|
||||
raise ValueError("invalid USB bridge completion capability")
|
||||
environment = USB_BRIDGE_PROFILES[chip, row["flash_bytes"] // 1048576]
|
||||
validate_usb_bridge(archive.read(row["file"]), {
|
||||
"wifi_bridge": environment.removesuffix("_usb"),
|
||||
"flash_bytes": row["flash_bytes"],
|
||||
})
|
||||
return manifest
|
||||
|
||||
|
||||
def package_set(build_dir: Path, output_file: Path, provenance: dict) -> Path:
|
||||
if (not re.fullmatch(r"[0-9a-f]{8,40}", provenance.get("source_commit", ""))
|
||||
or not isinstance(provenance.get("working_tree_dirty"), bool)
|
||||
or not re.fullmatch(r"[0-9a-f]{64}", provenance.get("source_tree_sha256", ""))):
|
||||
raise ValueError("USB bridge set requires honest source provenance")
|
||||
files = {"README.md": guide()}
|
||||
bridges = []
|
||||
# Read and validate all six before creating any output path: no partial set.
|
||||
for (chip, mib), environment in sorted(USB_BRIDGE_PROFILES.items()):
|
||||
image = (build_dir / environment / "firmware.bin").read_bytes()
|
||||
flash_bytes = mib * 1048576
|
||||
validate_usb_bridge(image, {"wifi_bridge": environment.removesuffix("_usb"),
|
||||
"flash_bytes": flash_bytes})
|
||||
filename = environment + ".bin"
|
||||
files[filename] = image
|
||||
bridges.append({"chip": chip, "flash_bytes": flash_bytes, "file": filename,
|
||||
"environment": environment, "automatic_rom_return": chip != 0,
|
||||
"uart_completion_status": chip == 0,
|
||||
"host_software_bootloader_entry": True,
|
||||
"application_usb_cdc": False})
|
||||
manifest = {"format": FORMAT, **provenance, "bridges": bridges,
|
||||
"files": {name: {"bytes": len(data), "sha256": sha256(data)}
|
||||
for name, data in sorted(files.items())}}
|
||||
files["manifest.json"] = (json.dumps(manifest, indent=2) + "\n").encode()
|
||||
files["SHA256SUMS.txt"] = "".join(
|
||||
f"{sha256(data)} {name}\n" for name, data in sorted(files.items())).encode()
|
||||
output_file.parent.mkdir(parents=True, exist_ok=True)
|
||||
with tempfile.NamedTemporaryFile(prefix="usb-bridges-", suffix=".zip",
|
||||
dir=output_file.parent, delete=False) as stream:
|
||||
temporary = Path(stream.name)
|
||||
try:
|
||||
with zipfile.ZipFile(temporary, "w", compression=zipfile.ZIP_STORED) as archive:
|
||||
for name, data in sorted(files.items()):
|
||||
archive.writestr(zipfile.ZipInfo(name, (1980, 1, 1, 0, 0, 0)), data)
|
||||
verify_set(temporary)
|
||||
if output_file.exists():
|
||||
if sha256(output_file.read_bytes()) != sha256(temporary.read_bytes()):
|
||||
raise ValueError("existing USB bridge set differs; choose a new output file")
|
||||
else:
|
||||
temporary.replace(output_file)
|
||||
finally:
|
||||
temporary.unlink(missing_ok=True)
|
||||
return output_file
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--pio-build-dir", type=Path)
|
||||
parser.add_argument("--output-file", type=Path, required=True)
|
||||
args = parser.parse_args()
|
||||
try:
|
||||
build_dir = resolve_pio_build_dir(args.pio_build_dir)
|
||||
result = package_set(build_dir, args.output_file.resolve(), source_provenance())
|
||||
except (OSError, ValueError, subprocess.SubprocessError) as error:
|
||||
parser.error(str(error))
|
||||
print(f"USB bridge set: {result} ({result.stat().st_size} bytes)")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in new issue
Block a user