Fix ESP32 GENERIC board name resolving to ESP8266 firmware when port is specified

[Copilot]

mpflash flash --port esp32 --board GENERIC incorrectly flashed ESP8266 firmware onto an ESP32 board. GENERIC is only an ESP8266 board in the DB; the --port esp32 hint was silently ignored throughout the call chain, and the old-style GENERIC_X board names (pre-v1.21.0) didn't map to their hyphen-variant equivalents (ESP32_GENERIC-SPIRAM, etc.).

Root causes

• find_known_board("GENERIC") returned the esp8266 DB entry regardless of user-specified --port
• --port was never forwarded from cli_flash → create_worklist → _create_manual_board in the manual board path
• find_downloaded_firmware stable-version query lacked a port filter (present for preview but missing for stable)
• alternate_board_names("GENERIC_SPIRAM", "esp32") generated ESP32_GENERIC_SPIRAM (underscore), but firmware from v1.21.0+ uses ESP32_GENERIC-SPIRAM (hyphen), so old board names silently missed their firmware

Changes

• mpboard_id/known.py — find_known_board accepts an optional port; when exact candidates don't match the requested port, falls back through alternate_board_names before last-resort fallback
• mpboard_id/alternate.py — GENERIC_X names now also emit the hyphen form (ESP32_GENERIC-X) alongside the underscore form, covering the v1.20.0→v1.21.0 naming change for all variant suffixes (_SPIRAM, _OTA, _D2WD, etc.)
• downloaded.py — port filter applied consistently to both preview and stable firmware queries
• flash/worklist.py — added port field to WorklistConfig; propagated through create_manual_worklist → _create_manual_board
• cli_flash.py — params.ports[0] forwarded to create_worklist in both manual board flash paths

Naming convention reference

Old name (≤v1.20)	New name (≥v1.21)	Port
GENERIC	ESP8266_GENERIC	esp8266
GENERIC_SPIRAM	ESP32_GENERIC-SPIRAM	esp32
GENERIC_OTA	ESP32_GENERIC-OTA	esp32
GENERIC_D2WD	ESP32_GENERIC-D2WD	esp32

alternate_board_names("GENERIC_SPIRAM", "esp32") now returns:

["GENERIC_SPIRAM", "ESP32_GENERIC_SPIRAM", "ESP32_GENERIC-SPIRAM", "GENERIC", "ESP32_GENERIC"]

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/micropython/micropython
  • Triggering command: /home/REDACTED/work/mpflash/mpflash/.venv/bin/python python -m pytest tests/test_downloaded.py tests/mpboard_id/ tests/flash/ -v ndor/bin/git hub.com/.extraheiptables (http block)
  • Triggering command: /home/REDACTED/work/mpflash/mpflash/.venv/bin/python python -m pytest tests/mpboard_id/test_known_boards.py::test_known_stored_boards_basic -v (http block)
  • Triggering command: /home/REDACTED/work/mpflash/mpflash/.venv/bin/python python -m pytest tests/test_downloaded.py tests/mpboard_id/test_known_boards.py tests/flash/ -v ndor/bin/git (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[codecov]

Codecov Report

❌ Patch coverage is 96.07843% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.82%. Comparing base (0f6e56b) to head (e843d69).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
mpflash/downloaded.py	75.00%	0 Missing and 1 partial ⚠️
mpflash/mpboard_id/alternate.py	90.90%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #54      +/-   ##
==========================================
+ Coverage   72.99%   74.82%   +1.82%     
==========================================
  Files          54       54              
  Lines        2744     2780      +36     
  Branches      421      434      +13     
==========================================
+ Hits         2003     2080      +77     
+ Misses        608      572      -36     
+ Partials      133      128       -5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Josverl]

@copilot

Patch coverage is 68.62745% with 16 lines in your changes missing coverage. Please review.

[Josverl]

@copilot

Additional details and impacted files
@@ Coverage Diff @@

main #54 +/-

==========================================

• Coverage 72.99% 72.87% -0.12%
  ==========================================
  Files 54 54
  Lines 2744 2780 +36
  Branches 421 434 +13
  ==========================================

• Hits 2003 2026 +23

• Misses 608 617 +9
• Partials 133 137 +4
  ☔ View

[Copilot]

@copilot

Patch coverage is 68.62745% with 16 lines in your changes missing coverage. Please review....

Added tests in commit e843d69 that increase patch coverage from 68.6% to 93%. New tests cover:

• known.py → 100% (port/version/alternate-name/description/fallback paths in find_known_board, plus known_versions)
• flash/worklist.py → 99% (create_manual_worklist body, create_filtered_worklist no-match warning path; only line 244 — an unreachable safety-net raise — remains uncovered)
• mpboard_id/alternate.py → 99% (add_renamed_boards, all alternate_board_names branches)
• downloaded.py → 72% (preview exact-match, preview alternate-name with/without port; clean_downloaded_firmwares and the custom=True preview branch remain uncovered as they're unrelated to the bug fix)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/micropython/micropython
  • Triggering command: /home/REDACTED/work/mpflash/mpflash/.venv/bin/python python -m pytest tests/test_downloaded.py tests/mpboard_id/ tests/flash/ --cov=mpflash/downloaded --cov=mpflash/mpboard_id --cov=mpflash/flash/worklist --cov=mpflash/cli_flash --cov-report=term-missing (http block)
  • Triggering command: /home/REDACTED/work/mpflash/mpflash/.venv/bin/python python -m pytest tests/test_downloaded.py tests/mpboard_id/ tests/flash/ --cov=mpflash.downloaded --cov=mpflash.mpboard_id.alternate --cov=mpflash.mpboard_id.known --cov=mpflash.flash.worklist --cov=mpflash.cli_flash --cov-report=term-missing (http block)
  • Triggering command: /home/REDACTED/work/mpflash/mpflash/.venv/bin/python python -m pytest tests/test_downloaded.py tests/mpboard_id/ tests/flash/test_worklist_refactored.py --cov=mpflash.downloaded --cov=mpflash.mpboard_id.alternate --cov=mpflash.mpboard_id.known --cov=mpflash.flash.worklist --cov-report=term-missing -x (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)