pm3py/docs/plans/2026-03-18-refactor-progress.md

pm3py Refactor Progress

Design: 2026-03-18-refactor-design.md Branch: merged to master Started: 2026-03-18

Phase 1 — Create core/, normalize names, fix imports

Status: Complete

What was done

• Created pm3py/core/ sub-package
• Moved all source modules into core/:
  • protocol.py, transport.py, client.py, hw.py, hf.py, lf.py — moved as-is
  • hf_14a.py → hf_iso14a.py (renamed)
  • hf_15.py → hf_iso15.py (renamed)
  • hf_mf.py → hf_mfc.py (renamed)
• Normalized client attributes:
  • hf.a14 → hf.iso14a
  • hf.mf → hf.mfc
  • hf.iso15 — unchanged
• Created core/__init__.py re-exporting: Proxmark3, FirmwareInfo, PM3Transport, PM3Error, PM3Response, PM3Status, Cmd
• Updated pm3py/__init__.py to import from .core.*
• Updated all 10 test files (imports + attribute references)
• 30/30 tests passing

Backward compatibility

• from pm3py import Proxmark3 still works (re-exported)
• Breaking: hf.a14 → hf.iso14a, hf.mf → hf.mfc
• Breaking: Direct imports like from pm3py.hf_14a import ... → from pm3py.core.hf_iso14a import ...

Phase 2 — Extract sniff/

Status: Complete

Extracted sniff infrastructure from core/hf_iso15.py (615→130 lines) into two packages:

pm3py/trace/ — shared trace infrastructure (used by sniff, sim, reader):

• trace.py — parse_tracelog(), TRACELOG_HDR_SIZE (protocol-agnostic)
• ndef.py — NDEF TLV/record decode (decode_ndef_annotation())
• decode_iso15.py — ISO 15693 command/response decoders, command tables
• format.py — ANSI color formatting, format_sniff_line()

pm3py/sniff/ — sniff orchestration (consumes trace/):

• session.py — SniffSession with iso15() method (replaces sniff_decoded())
• __init__.py — re-exports trace symbols for convenience

core/hf_iso15.py retains HF15Commands (scan/rdbl/wrbl/sniff) and re-exports trace symbols for backward compat. download_trace() and sniff_decoded() delegate to SniffSession.

65/65 tests passing (35 sniff/trace tests work through re-exports, no test changes needed).

Phase 3 — Scaffold transponders/

Status: Complete (scaffolded)

Created full directory tree per design:

• transponders/hf/iso14443a3/nxp/ — MIFARE Classic, Ultralight, NTAG
• transponders/hf/iso14443a4/nxp/ — DESFire
• transponders/hf/iso15693/nxp/ — ICODE SLIX2, NTAG 5
• 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: sim/ migrated, reader/ scaffolded

sim/ migration (complete)

Migrated full sim framework from .worktrees/sim-framework/ to pm3py/sim/:

• 43 source files, ~7.8k LOC
• 23 test files, 686 tests
• Import fixes: 4 source files (..protocol/..transport → ..core.), 1 source file (pm3py.hf_15 → pm3py.trace.ndef), 2 test files (flat → core.)
• Added sim Cmd entries to core/protocol.py (EML_SETMEM, SIM_TABLE_*)
• Added deps to venv: pycryptodome, bitarray
• 751 total tests passing (686 sim + 65 core)

reader/ (scaffolded)

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

All reader directories have __init__.py stubs.

Next Steps

• Reorganize transponder models from sim/ into transponders/ hierarchy (optional — sim/ works as-is)
• Reader modes: implement inventory, programming, access workflows in reader/modes/
• Unify sim/trace_fmt.py with trace/ package (dedup 15693 decoders, move 14443-A decoders)
• Sniff: add decode_iso14a.py using decoders from sim/trace_fmt.py
• Sim worktree cleanup: verify parity, then remove .worktrees/sim-framework/