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 — Transponder models in transponders/

Status: Complete

Moved 23 IC-specific files from sim/ into transponders/ organized by standard/manufacturer:

transponders/
  hf/
    iso14443a/
      base.py              # Tag14443A, Tag14443A_3/4, Reader14443A
      ndef.py              # NfcType2Tag, NfcType4Tag
      nxp/
        crypto1.py         # Crypto1
        mifare_classic.py  # MifareClassicTag, MifareClassicReader
        desfire.py         # DesfireTag, DesfireReader
    iso15693/
      base.py              # Tag15693, Reader15693
      type5.py             # NfcType5Tag, ndef_text/uri/mime
      nxp/
        auth_password.py   # NxpPasswordAuth
        auth_aes.py        # NxpAesAuth
        nxp_icode.py → icode_slix → icode_slix2 → icode3, icode_dna
        ntag5_platform → ntag5_switch, ntag5_link → ntag5_boost
      st/                  # future ST25TV
  lf/
    base.py                # TagLF, ReaderLF, Modulation
    em/em4100.py           # EM4100Tag, EM4100Reader
    hid/hid.py             # HIDProxTag, HIDReader
    atmel/t5577.py         # T5577Tag, T5577Reader
  implants.py              # xEM, xNT, xM1, FlexDF, NExT

Backward-compat shims left in sim/ — from pm3py.sim import IcodeSlix2Tag still works. sim/__init__.py imports from canonical transponders/ locations. 751 tests passing, zero test changes.

Phase 4 — sim/ infrastructure + reader/ scaffold

Status: Complete

sim/ (migrated + cleaned)

Sim framework migrated from .worktrees/sim-framework/, then transponder models extracted to transponders/. sim/ now contains only simulation infrastructure:

• Core: frame.py, memory.py, transponder.py (ABC), reader.py (ABC), medium.py
• Sessions: sim_session.py, dual_session.py
• Tools: table_compiler.py, trace_fmt.py, fuzzer.py, relay.py, replay.py, pm3medium.py
• MCU: mcu_bridge.py, mcu_protocol.py
• Access control: access_control/
• Backward-compat shims for all moved transponder files

reader/ (scaffolded)

• reader/hf/nxp/ — NXP reader ICs (CLRC663, PN5xx)
• reader/hf/st/ — ST reader ICs
• reader/lf/
• reader/modes/ — inventory, programming, access control workflows

DX improvements

• source activate — core imports (Proxmark3, Cmd)
• source activate sim — + SimSession, all transponder models
• source activate sniff — + SniffSession, trace decoders
• source activate all — everything

Next Steps

• 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 with master, then remove .worktrees/sim-framework/