0ba5256d02
- README: rewrite Install (from source, submodules, deps, Pi/aarch64); new 'Flashing firmware (pm3flash)' section — CLI usage, --build, image resolution, cross-compile + PLATFORM note, Raspberry Pi bring-up, programmatic API; point Firmware Compatibility at it; add a License section (MIT). - CLAUDE.md: flash.py/_firmware.py/flash_cli.py in the structure; a 'Firmware flashing' section with the maintainer gotchas (OLD frame, fullimage-only, page-merge, platform != is_rdv4, the pin). - roadmap: new 2026-07-05-firmware-flasher plan doc + a Firmware-flashing row. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
69 lines
4.5 KiB
Markdown
69 lines
4.5 KiB
Markdown
# pm3py roadmap — design & implementation plans
|
|
|
|
This directory is the project roadmap: dated design docs (`*-design.md`) and
|
|
implementation plans (`*-plan.md`). Each file is a self-contained spec — problem,
|
|
approach, concrete steps, tests, risks.
|
|
|
|
> **Status column is best-effort**, inferred from the codebase and memory at the time of
|
|
> writing (2026-07-05). Correct it if a plan's real state differs. Legend:
|
|
> ✅ landed · 🔄 in progress · 📋 planned · 📎 reference/ongoing.
|
|
|
|
## ISO 14443-A sim expansion
|
|
|
|
| Plan | Status | Summary |
|
|
|------|--------|---------|
|
|
| [2026-07-05-14a-live-trace-plan](2026-07-05-14a-live-trace-plan.md) | 🔄 | Live reader↔tag trace for the 14a sim (firmware ring + `EmLogTrace` capture + pm3py consumer). Code complete; flush + direct-send-capture fixes awaiting hardware verify. |
|
|
| [2026-07-05-14a-custom-commands-design](2026-07-05-14a-custom-commands-design.md) | 📋 | **Design:** how to serve custom 14a-3 (NTAG I2C SECTOR_SELECT + cross-sector reads) and 14a-4 (vendor ISO-DEP APDUs) commands — table-first L3 + WTX-L4 hybrid layered on the native-EML sim. |
|
|
| [2026-07-05-14a-custom-commands-plan](2026-07-05-14a-custom-commands-plan.md) | 📋 | **Plan:** sequenced L3 + L4 tracks — `sim_table` hook, sector-offset graft, WTX relay, `TableCompiler` extension, tests. |
|
|
|
|
## Sim framework & response table
|
|
|
|
| Plan | Status | Summary |
|
|
|------|--------|---------|
|
|
| [2026-03-17-stateful-table-firmware-design](2026-03-17-stateful-table-firmware-design.md) | ✅ | Response-table sim in firmware BigBuf: stateful `sim_table` + `sim_crypto`, group/auth state. |
|
|
| [2026-03-17-stateful-table-firmware-plan](2026-03-17-stateful-table-firmware-plan.md) | ✅ | Implementation of the above (15693 sim fully working: inventory, NDEF, NXP custom commands). |
|
|
| [2026-03-17-table-compiler-update-plan](2026-03-17-table-compiler-update-plan.md) | ✅ | `TableCompiler` / `ResponseTable` — compile per-IC responses into the 120-byte entry format. |
|
|
|
|
## Trace & sniff
|
|
|
|
| Plan | Status | Summary |
|
|
|------|--------|---------|
|
|
| [2026-03-17-trace-formatter-design](2026-03-17-trace-formatter-design.md) | ✅ | `TraceFormatter` — colored, decoded, column-wrapped trace output (sim/reader/sniff modes). |
|
|
| [2026-03-17-trace-formatter-plan](2026-03-17-trace-formatter-plan.md) | ✅ | Implementation of the trace formatter. |
|
|
| [2026-03-18-ndef-trace-decode](2026-03-18-ndef-trace-decode.md) | ✅ | NDEF TLV/record decode for trace annotation. |
|
|
| [2026-03-19-live-sniff-design](2026-03-19-live-sniff-design.md) | ✅ | Live streaming sniff (firmware `CMD_HF_SNIFF_STREAM` + `SniffSession`). |
|
|
| [2026-03-19-live-sniff-plan](2026-03-19-live-sniff-plan.md) | ✅ | Implementation of live sniff. |
|
|
|
|
## Package refactor & migration
|
|
|
|
| Plan | Status | Summary |
|
|
|------|--------|---------|
|
|
| [2026-03-18-refactor-design](2026-03-18-refactor-design.md) | ✅ | Split the monolith into `core/`, `trace/`, `sniff/`, `sim/`, `transponders/`. |
|
|
| [2026-03-18-refactor-progress](2026-03-18-refactor-progress.md) | ✅ | Progress log for the refactor (complete, all on master). |
|
|
| [2026-03-18-sim-migration](2026-03-18-sim-migration.md) | ✅ | Migrate the sim framework into the new package layout. |
|
|
|
|
## Firmware maintenance
|
|
|
|
| Plan | Status | Summary |
|
|
|------|--------|---------|
|
|
| [2026-07-03-firmware-upstream-rebase-plan](2026-07-03-firmware-upstream-rebase-plan.md) | 📎 | Rebase the `proxmark3-pm3py` fork against upstream PM3 (atomic single-file-commit workflow). |
|
|
| [2026-07-05-firmware-fork-dt-migration](2026-07-05-firmware-fork-dt-migration.md) | 📋 | Migrate the firmware fork + pm3py to the DT Gitea; clean `master`(RRG-mirror)/`pm3py`(patches) rebase-fork model. |
|
|
|
|
## Firmware flashing
|
|
|
|
| Plan | Status | Summary |
|
|
|------|--------|---------|
|
|
| [2026-07-05-firmware-flasher](2026-07-05-firmware-flasher.md) | ✅ | Pure-Python flasher (OLD-frame bootloader protocol) + `pm3flash` CLI + firmware pin; hardware-validated on a PM3 Easy. Auto-download of the pinned release is the open follow-up (rides on the DT-Gitea migration). |
|
|
|
|
---
|
|
|
|
### Conventions
|
|
|
|
- **Naming:** `YYYY-MM-DD-<topic>-{design,plan}.md`. A design doc explains *why* and *what*;
|
|
a plan doc gives sequenced, implementation-grade steps. Small features may have only a
|
|
`-plan.md`.
|
|
- **Firmware changes** land as atomic single-file commits anchored to stable symbols (not
|
|
line numbers) for easy rebase against upstream — see the firmware-upstream-rebase plan.
|
|
- **Provenance:** plans produced with multi-agent design workflows note it in a Provenance
|
|
section.
|