Skip to content

[FW-898] CLI-Subkommando pack-bf3 zum Erzeugen von BF3-Files - #13

Merged
mrh1997 merged 3 commits into
masterfrom
bf3-pack-cli
Aug 20, 2026
Merged

[FW-898] CLI-Subkommando pack-bf3 zum Erzeugen von BF3-Files#13
mrh1997 merged 3 commits into
masterfrom
bf3-pack-cli

Conversation

@mrh1997

@mrh1997 mrh1997 commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

Teil A von FW-898. Das Makesystem der Firmware (Bros2FW, Python 2.7) erzeugt
BF3-Files kuenftig selbst, statt ein .bf2 zu bauen und es per
Bf3File.bf2_import() zu konvertieren. Weil bec2format Python >=3.10 verlangt,
ruft make2 das neue CLI per uvx in einem eigenen Prozess auf.

Neues Subkommando bec2format pack-bf3

Neues Modul bec2format/cli.py mit argparse-Subkommandostruktur und main()
als Entrypoint (poetry-Skript bec2format).

Das Manifest kommt komplett ueber stdin, weil es den Firmware-Key enthaelt: so
landet der Key weder in einer Datei noch in der Prozessliste. Entsprechend gibt
das Kommando weder das Manifest noch einen Traceback aus - Fehler gehen als
ERROR: ... nach stderr, Exitcode != 0.

cli.py wird bewusst nicht von __init__.py importiert: die CI kopiert das
komplette Paketverzeichnis in die micropython-lib, wo weder argparse noch
json verfuegbar sind. package.json (mip-Manifest) bleibt unveraendert.

Das Manifest-Schema ist im README dokumentiert.

Bugfix in Bf3File.bf2_unpack_payload()

Die Funktion verwarf die erste 128-Byte-Zeile jedes Speicherbereichs nach einer
Luecke und behielt zugleich dessen Startadresse - die Daten landeten 128 Byte zu
frueh im Bereich, die ersten 128 Byte fehlten. Stille Firmware-Korruption.

Bisher latent, weil BF2_TAGTYPE_MAP uc-Firmware auf BF2COMPATIBLE abbildet
und der MEMORYIMAGE-Pfad nie genommen wurde. Mit FW-898 wird er relevant,
sobald jemand ein BF2 nach BF3/MEMIMAGE konvertiert.

Tests / Verifikation

  • Neues tests/-Verzeichnis (27 Tests), invoke-Task test und eigener CI-Job
    in verify-bec2format.yml
  • Round-Trip: Manifest ueber stdin -> pack-bf3 -> Bf3File.read_file() -> mit
    dem fw_key entschluesseln -> auf actual_len kuerzen -> Payload byte-gleich
  • Regressionstest fuer den Bugfix mit zwei Bereichen mit Luecke - ohne den Fix
    rot, mit exakt dem dokumentierten Symptom (128 Byte Versatz)
  • Ende zu Ende: uvx --from ".[aes]" bec2format pack-bf3 < manifest.json, also
    genau die Aufrufform von make2
  • Die vier appnotes-Skripte unter py3.10 gruen; der micropython-Zweig ist
    unberuehrt, weil cli.py nicht am Paket-Init haengt
  • invoke lint ist auf master bereits rot (black 1 Datei, isort
    bec2file.py, 12 flake8-Findings, 45 mypy-Fehler). Gegen diese Baseline
    gediffed: keine neuen Findings aus cli.py, tests/ oder tasks.py;
    mypy 45 -> 44, weil poetry install --all-extras den fehlenden
    cryptography-Stub aufloest.

Zwei Funde ausserhalb des Auftrags (nicht angefasst)

  1. bf3file.py:443 vergleicht description.get(BF3TAG.ENC) (bytes) mit dem
    int BF3ENC.SESSIONKEY - nie wahr. Bf3File.read_file() entschluesselt
    sessionkey-verschluesselte Komponenten also nie.
  2. package.json listet bec2format/compatibility.py; die Datei heisst seit
    einer Umbenennung micropython_compatibility_quirks.py.

Hinweis zur Reihenfolge

Bros2FW pinnt einen bec2format-Commit in
maketools/make2_baltech_ext/bf3_builders.py (BEC2FORMAT_REQ) und in
tox.ini. Der Pin muss nach dem Merge dieses PRs auf den neuen Commit gehoben
werden - vorher ist der Bros2FW-Branch nicht mergefaehig.

FW-898

mrh1997 and others added 3 commits August 20, 2026 11:41
Das Makesystem der Firmware erzeugt BF3-Files kuenftig selbst, statt ein .bf2
zu bauen und es per Bf3File.bf2_import() zu konvertieren. Weil make2 unter
Python 2.7 laeuft, ruft es "bec2format pack-bf3" in einem eigenen Prozess auf.

Das Manifest wird komplett ueber stdin gelesen, weil es den Firmware-Key
enthaelt: so landet der Key weder in einer Datei noch in der Prozessliste.
Entsprechend gibt das Kommando weder das Manifest noch einen Traceback aus,
Fehler gehen als "ERROR: ..." nach stderr.

cli.py wird bewusst nicht von __init__.py importiert - das Paketverzeichnis
wird von der CI in die micropython-lib kopiert, wo weder argparse noch json
verfuegbar sind.

FW-898

Co-Authored-By: Claude <noreply@anthropic.com>
Die Funktion verwarf die erste 128-Byte-Zeile jedes Speicherbereichs nach
einer Luecke und behielt zugleich dessen Startadresse: im Gap-Zweig wurde der
Block geflusht und cur_block geleert, das Payload der ausloesenden Zeile aber
nie angehaengt. Die Daten landeten dadurch 128 Byte zu frueh im Bereich und
die ersten 128 Byte fehlten - eine stille Firmware-Korruption.

Bisher latent, weil BF2_TAGTYPE_MAP uc-Firmware auf BF2COMPATIBLE abbildet und
der MEMORYIMAGE-Pfad nie genommen wurde. Mit FW-898 wird er relevant, sobald
jemand ein BF2 nach BF3/MEMIMAGE konvertiert.

FW-898

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
@mrh1997 mrh1997 self-assigned this Aug 20, 2026
@mrh1997
mrh1997 requested a review from jkatins August 20, 2026 10:07
@mrh1997
mrh1997 merged commit 10b2d2e into master Aug 20, 2026
12 checks passed
@mrh1997
mrh1997 deleted the bf3-pack-cli branch August 20, 2026 14:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants