diff --git a/docs/plans/2026-03-18-refactor-progress.md b/docs/plans/2026-03-18-refactor-progress.md index f4ab79c..9ca6678 100644 --- a/docs/plans/2026-03-18-refactor-progress.md +++ b/docs/plans/2026-03-18-refactor-progress.md @@ -33,20 +33,42 @@ ## Phase 2 — Extract `sniff/` -**Status: Deferred — no sniff infrastructure exists yet** +**Status: Scaffolded — extraction deferred** `hf_iso15.py` is 94 lines of clean reader commands + thin `sniff()` firmware call. The trace parsing, 15693 decoders, NDEF annotation, and ANSI formatting described in the design doc haven't been written yet. Nothing to extract. -Will revisit when sniff infrastructure is implemented. +Created `pm3py/sniff/__init__.py` placeholder. Will extract into sub-modules when sniff infrastructure is implemented. ## Phase 3 — Scaffold `transponders/` -**Status: Not started — models live in sim worktree** +**Status: Complete (scaffolded)** -Transponder models exist in `.worktrees/sim-framework/` but haven't been merged to master. Scaffold when ready to migrate. +Created full directory tree per design: +- `transponders/hf/iso14443a3/nxp/` — MIFARE Classic, Ultralight, NTAG +- `transponders/hf/iso14443a4/nxp/` — DESFire, NTAG 5 +- `transponders/hf/iso15693/nxp/` — ICODE SLIX2 +- `transponders/hf/iso15693/st/` — ST25TV +- `transponders/lf/atmel/` — T55xx +- `transponders/lf/em/` — EM4100, EM4x05 + +All directories have `__init__.py`. Model migration from sim worktree is a separate effort — the sim framework has ~7.8k LOC with deep inheritance chains (`Transponder` → `Tag15693` → `NxpIcodeTag` → `IcodeSlix2Tag`, etc.) and auth mixins (`NxpPasswordAuth`, `NxpAesAuth`). Base class extraction needs to happen alongside model migration. ## Phase 4 — Scaffold `reader/` and `sim/` -**Status: Not started** +**Status: Complete (scaffolded)** -Depends on Phase 3 and sim worktree merge. +Created directory trees per design: +- `reader/hf/nxp/` — NXP reader ICs (CLRC663, PN5xx) +- `reader/hf/st/` — ST reader ICs +- `reader/lf/` +- `reader/modes/` — inventory, programming, access control workflows +- `sim/` — sim session, table compiler, relay (migrate from worktree) + +All directories have `__init__.py`. Sim migration (~41 files, 7.8k LOC) is a separate effort. + +## Next Steps + +- Sniff infrastructure: implement trace parsing, 15693 decoders, NDEF annotation, ANSI formatting in `sniff/` +- Transponder migration: extract base classes from sim worktree, populate `transponders/` modules +- Sim migration: move sim session, table compiler, relay into `sim/` +- Reader modes: implement inventory, programming, access workflows in `reader/modes/` diff --git a/pm3py/reader/__init__.py b/pm3py/reader/__init__.py new file mode 100644 index 0000000..2ae2ba6 --- /dev/null +++ b/pm3py/reader/__init__.py @@ -0,0 +1 @@ +"""pm3py.reader — Higher-level reader modes composing core commands.""" diff --git a/pm3py/reader/hf/__init__.py b/pm3py/reader/hf/__init__.py new file mode 100644 index 0000000..057a822 --- /dev/null +++ b/pm3py/reader/hf/__init__.py @@ -0,0 +1 @@ +"""HF reader modes organized by reader IC manufacturer.""" diff --git a/pm3py/reader/hf/nxp/__init__.py b/pm3py/reader/hf/nxp/__init__.py new file mode 100644 index 0000000..d4c975c --- /dev/null +++ b/pm3py/reader/hf/nxp/__init__.py @@ -0,0 +1 @@ +"""NXP reader ICs (CLRC663, PN5xx).""" diff --git a/pm3py/reader/hf/st/__init__.py b/pm3py/reader/hf/st/__init__.py new file mode 100644 index 0000000..00c3ccd --- /dev/null +++ b/pm3py/reader/hf/st/__init__.py @@ -0,0 +1 @@ +"""ST Microelectronics reader ICs.""" diff --git a/pm3py/reader/lf/__init__.py b/pm3py/reader/lf/__init__.py new file mode 100644 index 0000000..2fbb71c --- /dev/null +++ b/pm3py/reader/lf/__init__.py @@ -0,0 +1 @@ +"""LF reader modes.""" diff --git a/pm3py/reader/modes/__init__.py b/pm3py/reader/modes/__init__.py new file mode 100644 index 0000000..2e64599 --- /dev/null +++ b/pm3py/reader/modes/__init__.py @@ -0,0 +1 @@ +"""Reader workflow modes — inventory, programming, access control.""" diff --git a/pm3py/sim/__init__.py b/pm3py/sim/__init__.py new file mode 100644 index 0000000..314f07a --- /dev/null +++ b/pm3py/sim/__init__.py @@ -0,0 +1 @@ +"""pm3py.sim — Card simulation sessions, table compiler, relay.""" diff --git a/pm3py/sniff/__init__.py b/pm3py/sniff/__init__.py new file mode 100644 index 0000000..68db8db --- /dev/null +++ b/pm3py/sniff/__init__.py @@ -0,0 +1 @@ +"""pm3py.sniff — Sniff sessions, trace parsing, protocol decoders, formatting.""" diff --git a/pm3py/transponders/__init__.py b/pm3py/transponders/__init__.py new file mode 100644 index 0000000..2dc23ab --- /dev/null +++ b/pm3py/transponders/__init__.py @@ -0,0 +1 @@ +"""pm3py.transponders — Tag/transponder models independent of hardware.""" diff --git a/pm3py/transponders/hf/__init__.py b/pm3py/transponders/hf/__init__.py new file mode 100644 index 0000000..896c1a6 --- /dev/null +++ b/pm3py/transponders/hf/__init__.py @@ -0,0 +1 @@ +"""HF transponder models organized by ISO standard, then manufacturer.""" diff --git a/pm3py/transponders/hf/iso14443a3/__init__.py b/pm3py/transponders/hf/iso14443a3/__init__.py new file mode 100644 index 0000000..fa4c38d --- /dev/null +++ b/pm3py/transponders/hf/iso14443a3/__init__.py @@ -0,0 +1 @@ +"""ISO 14443-A Layer 3 transponders (MIFARE Classic, Ultralight, NTAG).""" diff --git a/pm3py/transponders/hf/iso14443a3/nxp/__init__.py b/pm3py/transponders/hf/iso14443a3/nxp/__init__.py new file mode 100644 index 0000000..afd4290 --- /dev/null +++ b/pm3py/transponders/hf/iso14443a3/nxp/__init__.py @@ -0,0 +1 @@ +"""NXP ISO 14443-A Layer 3 transponders.""" diff --git a/pm3py/transponders/hf/iso14443a4/__init__.py b/pm3py/transponders/hf/iso14443a4/__init__.py new file mode 100644 index 0000000..06e8bf8 --- /dev/null +++ b/pm3py/transponders/hf/iso14443a4/__init__.py @@ -0,0 +1 @@ +"""ISO 14443-A Layer 4 (ISO-DEP) transponders (DESFire, NTAG 5 via -4).""" diff --git a/pm3py/transponders/hf/iso14443a4/nxp/__init__.py b/pm3py/transponders/hf/iso14443a4/nxp/__init__.py new file mode 100644 index 0000000..ce960da --- /dev/null +++ b/pm3py/transponders/hf/iso14443a4/nxp/__init__.py @@ -0,0 +1 @@ +"""NXP ISO 14443-A Layer 4 transponders.""" diff --git a/pm3py/transponders/hf/iso15693/__init__.py b/pm3py/transponders/hf/iso15693/__init__.py new file mode 100644 index 0000000..084b839 --- /dev/null +++ b/pm3py/transponders/hf/iso15693/__init__.py @@ -0,0 +1 @@ +"""ISO 15693 transponder models and NFC Forum Type 5 NDEF.""" diff --git a/pm3py/transponders/hf/iso15693/nxp/__init__.py b/pm3py/transponders/hf/iso15693/nxp/__init__.py new file mode 100644 index 0000000..fd37fbc --- /dev/null +++ b/pm3py/transponders/hf/iso15693/nxp/__init__.py @@ -0,0 +1 @@ +"""NXP ICODE / NTAG 5 ISO 15693 transponders.""" diff --git a/pm3py/transponders/hf/iso15693/st/__init__.py b/pm3py/transponders/hf/iso15693/st/__init__.py new file mode 100644 index 0000000..d02b2b0 --- /dev/null +++ b/pm3py/transponders/hf/iso15693/st/__init__.py @@ -0,0 +1 @@ +"""ST Microelectronics ISO 15693 transponders.""" diff --git a/pm3py/transponders/lf/__init__.py b/pm3py/transponders/lf/__init__.py new file mode 100644 index 0000000..02b215a --- /dev/null +++ b/pm3py/transponders/lf/__init__.py @@ -0,0 +1 @@ +"""LF transponder models organized by manufacturer.""" diff --git a/pm3py/transponders/lf/atmel/__init__.py b/pm3py/transponders/lf/atmel/__init__.py new file mode 100644 index 0000000..3ab188b --- /dev/null +++ b/pm3py/transponders/lf/atmel/__init__.py @@ -0,0 +1 @@ +"""Atmel/Microchip LF transponders (T55xx).""" diff --git a/pm3py/transponders/lf/em/__init__.py b/pm3py/transponders/lf/em/__init__.py new file mode 100644 index 0000000..befc7c2 --- /dev/null +++ b/pm3py/transponders/lf/em/__init__.py @@ -0,0 +1 @@ +"""EM Microelectronic LF transponders (EM4100, EM4x05)."""