docs: update CLAUDE.md for completed refactor and sim status

- Package structure reflects reality: transponders/ hierarchy,
  sim/ infrastructure files, reader/ scaffold
- Remove worktree references (sim framework merged to master)
- Mark card simulation as working (not "in progress")
- Update firmware submodule (CRC fix for short 15693 frames)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
michael
2026-03-18 22:00:54 -07:00
parent f294aba9ef
commit 874aa688b9
2 changed files with 18 additions and 16 deletions

View File

@@ -37,25 +37,27 @@ pm3py/
format.py # ANSI color formatting, format_sniff_line
sniff/ # sniff orchestration — protocol detection, session lifecycle
session.py # SniffSession — start/download/decode per protocol
sim/ # card simulation framework (~7.8k LOC, 686 tests)
sim/ # card simulation infrastructure (19 files)
transponder.py # Transponder ABC, MemoryRegion
medium.py # Medium, SoftwareMedium (RF simulation)
reader.py # Reader ABC, ScriptedReader, InteractiveReader
frame.py # RFFrame (bit/byte level)
iso14443a.py # Tag14443A, Tag14443A_3/4, Reader14443A
iso15693.py # Tag15693, Reader15693
mifare.py # MifareClassicTag + Crypto1
desfire.py # DesfireTag, DesfireReader
type5.py # NfcType5Tag (NDEF on 15693)
nxp_icode.py # NxpIcodeTag base
icode_slix.py # → icode_slix2 → icode3, icode_dna
ntag5_platform.py # → ntag5_switch, ntag5_link → ntag5_boost
sim_session.py # SimSession (table compile + WTX relay)
dual_session.py # DualInterfaceSession (PM3 RF + MCU I2C)
table_compiler.py # ResponseTable, TableCompiler
trace_fmt.py # TraceFormatter (14443-A + 15693 decoders)
# + lf_base, em4100, hid, t5577, ndef, implants, fuzzer, relay, etc.
pm3medium.py # PM3-backed Medium for real hardware
mcu_bridge.py # COBS serial bridge to MCU
mcu_protocol.py # MCU message types and protocol
fuzzer.py # Transponder fuzzer
relay.py # Card relay
replay.py # Trace replay
access_control/ # Wiegand, OSDP
transponders/ # tag/transponder models (extracted from sim/)
hf/iso14443a/ # Tag14443A_3/4, MifareClassic, DESFire, NfcType2/4
hf/iso15693/ # Tag15693, NfcType5, NXP ICODE/SLIX2/DNA/NTAG5
lf/ # EM4100, HID, T5577
reader/ # higher-level reader modes by protocol/vendor (scaffold)
transponders/ # tag/transponder models independent of hardware (scaffold)
```
## Client API
@@ -97,9 +99,9 @@ pm3.hf.dropfield() # drop field
PWM-capable: Easy = A,B. RDV4 = A,D.
## Sim framework (worktree `feature/sim-framework`)
## Sim framework
Software-defined transponder/reader simulation framework — 750+ tests. Pure-Python models for ISO 14443-A, 15693, MIFARE Classic, DESFire, JCOP, LF (EM4100, HID, T5577), NDEF, NXP ICODE/SLIX2/DNA/NTAG5, access control (Wiegand, OSDP), implant profiles. See `.worktrees/sim-framework/docs/SIM_FRAMEWORK_STATUS.md` for full status.
Software-defined transponder/reader simulation framework — 750+ tests, merged to master. Pure-Python models for ISO 14443-A, 15693, MIFARE Classic, DESFire, JCOP, LF (EM4100, HID, T5577), NDEF, NXP ICODE/SLIX2/DNA/NTAG5, access control (Wiegand, OSDP), implant profiles. Transponder models in `transponders/`, sim infrastructure in `sim/`.
## Table compiler: proprietary command match patterns
@@ -116,9 +118,9 @@ For unaddressed commands (`02 AB 04`), mfg code stays → `02 AB 04`. PREFIX mat
**Rule:** All NXP custom command table entries use `match=bytes([flags, cmd_byte])` with `MATCH_PREFIX`. Never include `0x04` in the match.
## Python-driven card simulation (in progress)
## Python-driven card simulation
Design doc: `docs/PYTHON_SIM_DESIGN.md`. Firmware patch (~320 lines of C) + Python extensions to enable Python-controlled card simulation on unmodified PM3 Easy/RDV4 hardware. Two mechanisms:
Design doc: `docs/PYTHON_SIM_DESIGN.md`. Firmware patch in `firmware/` submodule (proxmark3-pm3py) + Python sim framework. 15693 sim fully working — phone reads all blocks, NDEF, NXP custom commands. Two mechanisms:
- **Response table** in BigBuf — pre-compiled by Python, served by firmware at wire speed (86µs FDT for 14443-A Layer 3)
- **WTX relay** — firmware sends S(WTX) on Layer 4 table miss, relays APDU to Python over USB for real-time crypto (DESFire, JCOP, EMV)
- **15693 retry relay** — reader retry-based relay for unknown commands