829f254194
Exposes pm3py as a pyws workspace, discovered via the pyws.plugins entry point: - ReaderResource: connects/disconnects a Proxmark3 as `reader`; a missing device is non-fatal (reports disconnected) - namespace injection of the transponder/sim classes, SimSession and Proxmark3 - effect declarations so autoreplay/replay withhold writes/field/sim/destructive while reads and pure model edits replay Hardware-free tests via AsyncMock. The live `sim` resource is P2. See docs/plans/2026-07-05-pm3py-pyws-plugin-plan.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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 | 🔄 | 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 | 📋 | 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 | 📋 | 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 | ✅ | Response-table sim in firmware BigBuf: stateful sim_table + sim_crypto, group/auth state. |
| 2026-03-17-stateful-table-firmware-plan | ✅ | Implementation of the above (15693 sim fully working: inventory, NDEF, NXP custom commands). |
| 2026-03-17-table-compiler-update-plan | ✅ | TableCompiler / ResponseTable — compile per-IC responses into the 120-byte entry format. |
Trace & sniff
| Plan | Status | Summary |
|---|---|---|
| 2026-03-17-trace-formatter-design | ✅ | TraceFormatter — colored, decoded, column-wrapped trace output (sim/reader/sniff modes). |
| 2026-03-17-trace-formatter-plan | ✅ | Implementation of the trace formatter. |
| 2026-03-18-ndef-trace-decode | ✅ | NDEF TLV/record decode for trace annotation. |
| 2026-03-19-live-sniff-design | ✅ | Live streaming sniff (firmware CMD_HF_SNIFF_STREAM + SniffSession). |
| 2026-03-19-live-sniff-plan | ✅ | Implementation of live sniff. |
Package refactor & migration
| Plan | Status | Summary |
|---|---|---|
| 2026-03-18-refactor-design | ✅ | Split the monolith into core/, trace/, sniff/, sim/, transponders/. |
| 2026-03-18-refactor-progress | ✅ | Progress log for the refactor (complete, all on master). |
| 2026-03-18-sim-migration | ✅ | Migrate the sim framework into the new package layout. |
Firmware maintenance
| Plan | Status | Summary |
|---|---|---|
| 2026-07-03-firmware-upstream-rebase-plan | 📎 | Rebase the proxmark3-pm3py fork against upstream PM3 (atomic single-file-commit workflow). |
| 2026-07-05-firmware-fork-dt-migration | 📋 | 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 | ✅ | 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.