- Sim facade (bound as `sim`): start(tag) arms the sim, dispatching 14a/15693 by tag
type; stop(), push(tag) -> tag.sync(), frames -> decoded trace
- SimResource: opens SimSession on load, closes on exit; a missing device is non-fatal
- one connection mode per workspace (reader OR sim) — the second is refused (serial contention)
- sim.push added to the write effect patterns (withheld on autoreplay)
Arming stays explicit. Hardware-free tests via injected sessions.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Bump firmware pin to 3b6201d97, which bounds the 14a sim button / host-stop
latency under continuous reader traffic (was multi-second, now ~10ms).
SimSession now treats an HF_MIFARE_SIMULATE (0x0610) reply as end-of-sim for
14a: the sim starts with HF_ISO14443A_SIMULATE but the firmware tears down
with HF_MIFARE_SIMULATE, so _trace_reader and _relay_loop watch for it and
flip _active off on a button-driven stop (previously the host never noticed).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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>
- README: rewrite Install (from source, submodules, deps, Pi/aarch64); new
'Flashing firmware (pm3flash)' section — CLI usage, --build, image resolution,
cross-compile + PLATFORM note, Raspberry Pi bring-up, programmatic API; point
Firmware Compatibility at it; add a License section (MIT).
- CLAUDE.md: flash.py/_firmware.py/flash_cli.py in the structure; a 'Firmware
flashing' section with the maintainer gotchas (OLD frame, fullimage-only,
page-merge, platform != is_rdv4, the pin).
- roadmap: new 2026-07-05-firmware-flasher plan doc + a Firmware-flashing row.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
build_firmware()/find_firmware_src() cross-compile fullimage.elf via
'make -C firmware PLATFORM=<explicit> armsrc/all' and pm3flash --build flashes it.
PLATFORM is explicit (never inferred from is_rdv4 — that's the running firmware's
flag, not the board).
Hardened per an adversarial multi-agent review of the change:
- --build now implies --force: it must flash the image it just built. A dirty
rebuild keeps the same base SHA, so matches_pin can't distinguish it from the
old firmware and would otherwise silently skip the flash (exit 0).
- make missing/not-executable -> FlashError (was an uncaught OSError traceback).
- find_firmware_src no longer falls back to a CWD-relative ./firmware — running
make on a stray Makefile is arbitrary code execution; only explicit arg /
$PM3PY_FIRMWARE_SRC / the package repo root. Suite 1045 pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Found on the first real-hardware flash (PM3 Easy). The fullimage ELF has two
adjacent PT_LOAD segments (seg1 ends at 0x15E5AC, seg2 starts there) that share
the 0x15E400 flash page. build_blocks aligned each segment independently, so the
shared page was written twice — seg2's 0xFF-padded head, written last,
erase-programmed the page and wiped seg1's real bytes there (the SAM7 programs a
whole page atomically). That region holds version_information, so the flashed OS
booted but reported 'Missing/Invalid version information'.
Fix: merge segments whose block-aligned spans touch into one buffer, so every
shared page is written once with both segments' real data; 0xFF only fills gaps
and aligned outer edges. Re-flash verified on hardware: 3df2ed2e8 -> 303bd5873,
valid version, matches_pin true. Bootrom untouched throughout (fullimage-only).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds the 'is the device running the right firmware, and flash it if not'
layer on top of the flasher.
- _firmware.py: FirmwarePin (pinned to the firmware/ submodule commit) and
matches() — a device version-string test against the pinned git SHA (or a
release tag, once tagged releases exist).
- FirmwareInfo gains expected_firmware + matches_pin, computed on connect, so
pm3.firmware.matches_pin tells you whether the fork build is present.
- pm3flash console-script: auto-detect, compare to the pin, resolve the image
(--image / $PM3PY_FIRMWARE / local build), confirm, flash with progress,
then reopen and verify the new version. Flashes only on mismatch unless
--force; fullimage-only unless --allow-bootrom.
Detection + CLI are unit-tested; the auto-download layer (fetch the pinned
release asset) and hardware validation are still to come. Suite 1034 pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Drives the full flash flow over the existing USB-serial link — enter
bootloader, arm window, stream the ELF block-by-block, reset — with no
external pm3-flash/DFU/JTAG.
- core/flash.py: Flasher (device_info, auto OS->bootloader handover,
flash_image block loop with ACK/NACK+EFC status, reset, end-to-end flash);
ELF32-ARM PT_LOAD parsing; 0xFF-padded block alignment; image resolver.
- core/transport.py: OLD 544-byte frame encode/decode, send_old /
send_old_no_response, magic-branching frame reader, reopen() for USB
re-enumeration.
- core/protocol.py: DEVICE_INFO flags, START_FLASH_MAGIC, flash geometry,
BL version helpers.
- Wired as pm3.flasher; reachable through the sync proxy.
Safety: fullimage-only by default; bootrom region refused unless
allow_bootrom=True; every block bounds-checked against the flash window.
Verification is per-block ACK/NACK (as the C flasher does); read-back verify
and hardware validation are follow-ups. 22 tests; suite 1026 pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Add MIT LICENSE (PEP 639 'license = "MIT"' + license-files).
- Move all metadata into a [project] table (description, readme, authors,
keywords, classifiers); drop the now-redundant setup.py.
- Declare bitarray and pycryptodome: used by pm3py.sim and the transponder
crypto paths but previously undeclared, so a clean install failed on the
README's own 'from pm3py.sim import SimSession'.
- gitignore build/ and dist/.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- NfcType2Tag._build_mfu_dump(): assemble the firmware mfu_dump_t (56-byte prefix
version/pages/signature + page data) so the sim serves real memory (UID/CC/NDEF/
PWD/PACK). Firmware is data-driven for tagtype 2/7, so an NTAG213 dump presents
correctly under tagtype 7.
- NfcType2Tag.sync(): push the image via CMD_HF_MIFARE_EML_MEMSET (same primitive
as the client's hf mfu esetblk), chunked. Updates a live sim with the fw host-poll.
- start_14a: load the dump before HF_ISO14443A_SIMULATE so the reader sees real
page data instead of an empty buffer (works on current fw; no reflash for this).
- fix: set_ndef/clear_ndef cleared memory to the end, wiping the lock/config/PWD/
PACK pages on NTAG parts. Bounded to the CC-declared NDEF area now.
- tests: mfu_dump layout, config-page preservation, EML_MEMSET framing/chunking.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The .gitmodules url pointed at github.com/dangerous-tac0s/proxmark3-pm3py, which
lacks our commits and the pinned gitlink — fresh recursive clones broke. Point it
at the real fork on the DT Gitea over SSH.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Add docs/plans/README.md as the roadmap index cataloguing all design/plan docs.
- Add the custom ISO14443-A command handling design + plan (L3 NTAG I2C
SECTOR_SELECT / cross-sector reads + native auth; L4 static APDUs + WTX relay),
produced from a multi-agent design workflow.
- Backfill previously-uncommitted plan docs (trace-formatter, ndef-trace-decode,
live-sniff, firmware-upstream-rebase, 14a-live-trace) and NTAG5_SECURITY.md.
- Sync CLAUDE.md package structure with the committed transponder models.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- start_14a now raises TypeError for a non-Tag14443A transponder, start_15693
likewise for a non-Tag15693 (local imports to avoid the base<->sim circular
import). Prevents silently starting a sim with an incompatible tag model.
- Re-export the full 14a/14b/15693 tag lineup (NTAG21x, Ultralight family, NTAG
I2C, ST25*, OPTIGA, ISO14443B, TI parts) from pm3py.sim for `from pm3py.sim
import NTAG213`-style use.
- Add a read-only `uid` property on the Transponder base (mirrors set_uid()).
- Tests for both guards.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Full-drain flush + EmLogTrace central answer capture (READ/FAST_READ/ACK/NAK now
traced). Builds clean for PM3GENERIC.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
.gitignore had `venv/` but the project's virtualenv is `.venv/`; add it plus
local-only agent/editor state so a `git add -A` can't sweep them in. Also stop
tracking four .pyc files committed before the __pycache__ ignore rule existed.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Y1: Cmd.HF_ISO14443A_SIM_TRACE (0x0339).
Y2: generalize SimSession._trace_reader dispatch to a {cmd: protocol} map so
14a (proto 1) and 15693 (proto 0) share one reader; the ADC field-strength
branch is now guarded to 15693.
Y3: rewrite start_14a as a synchronous trace path mirroring start_15693 (raw
pyserial + the _trace_reader thread). Sends the correct HF_ISO14443A_SIMULATE
NG payload (same layout as hf.iso14a.sim()), sets FLAG_SIM_TRACE when
streaming, and takes trace/on_frame/quiet/tagtype/exit_after kwargs. Loading
tag memory into emulator RAM stays a separate (hardware) step; the trace
streams every reader<->tag frame regardless. The WTX _relay_loop is retained
for the future 14a-4 path.
T1: mocked-transport unit tests for the 14a trace path (tests/test_sim_trace_14a.py).
Requires the bumped firmware submodule. 996 tests pass.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Lands F1 (CMD_HF_ISO14443A_SIM_TRACE 0x0339 + FLAG_SIM_TRACE) and F2+F3
(trace ring + hooks in SimulateIso14443aTagEx). Builds clean for PM3GENERIC.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds CMD_LED_CONTROL (0x011B): payload_led_control_t + PWM/effect helpers + appmain dispatch, on top of the rebased 5530c1269.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The firmware fork now provides CMD_LED_CONTROL at 0x011B (payload_led_control_t). hw.led already packs the matching <BBBHH> struct + action codes, so repointing the id makes it functional. Adds Cmd.SET_HF_FIELD_TIMEOUT (0x011A, upstream's use of that slot). README caveat updated: hw.led works with the fork, no-op on stock.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a 'Structured / scriptable access' subsection under Live Sniff & Simulation covering the on_frame callback, quiet mode, the ANSI-free frame dict shape, and push vs pull (entries) usage for both SniffSession and SimSession.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
SniffSession/SimSession.start_15693 gain on_frame(frame) and quiet kwargs (defaults preserve today's print behavior). Each frame is a plain dict {protocol, direction, timestamp, duration, data, data_hex, decoded[, crc_fail]} with no ANSI. SimSession now accumulates frames (entries property + clear(), mirroring SniffSession) and auto-streams when trace or on_frame is set; printing is gated on trace and not quiet. TraceFormatter.decode() exposes the annotation without color; format()/print() untouched.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Full refresh of the stale 2026-03 README. Fixes sub-module names (iso14a not a14, mf not mfc), adds MIFARE Ultralight/NTAG (mfu) and iso15 inventory() with AFI/DSFID filtering, documents live SniffSession/SimSession streaming + tag.sync() live edits + the transponder/sim framework, and the sync-proxy dir()/help()/tab-completion introspection. Every code example verified against the source; hw.led carries a caveat that it needs the pending CMD_LED_CONTROL firmware port.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Firmware rebased onto RfidResearchGroup/proxmark3 b8911a29a as 5 clean per-file commits (sim_table+sim_crypto modules, command IDs + iso15 fields, appmain dispatch, 15693 sim handler + streaming sniff, build glue). Replaces the old 33-commit branch based on the 2026-02-20 merge-base. Old firmware main preserved as tag pre-rebase-main-2026-07-05 (35db99fa5).
hf.mfc renamed to hf.mf to match the C client's 'hf mf'. New hf.mfu (HFMFUCommands) provides rdbl/wrbl/dump over the dedicated CMD_HF_MIFAREU_READBL/WRITEBL using the firmware mful_readblock_t / mful_writeblock_t structs; a READ returns 4 pages (16 bytes) and the firmware replies them directly. keytype selects auth (0=none, 1=UL-C, 2=EV1/NTAG pwd, 3=UL-AES). Wire formats verified against firmware structs; needs a bench pass for the auth/write-length paths.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
inventory() parses both response formats: slots=1 -> single tag dict (or None); slots=16 -> list of tags from the iso15_inventory_response_t anti-collision struct, each CRC15-validated. Optional request-level AFI filter and client-side DSFID filter. One 16-slot round drops colliding slots (full tree-walk resolution is a follow-up); scan() stays the single-tag convenience.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The sync REPL proxy forwarded methods via __getattr__, so dir()/tab-completion never saw them and the sync wrapper reported (*args, **kwargs) instead of the real signature. Add __dir__ delegating to the wrapped target, and decorate the async wrapper with functools.wraps so inspect.signature()/help() report the real params + docstring.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
lf.tune sends the 2-byte {mode,divisor} the firmware requires (was 3 -> EINVARG/0V). t55.writebl packs the 10-byte {data,pwd,blockno,flags} struct with a single bit-packed flags byte (was 12). t55.wakeup packs 5 bytes {pwd,flags}. t55.config is maintained client-side (firmware has no GET). LF_SAMPLING_SET_CONFIG uses send_ng_no_response (firmware never replies). Pre-existing, independent of the rebase.
14a.sim sent a MIX frame but the handler is NG casting a packed {tagtype,u16 flags,uid[10],exitAfter,rats[20],ulauth...} struct -> whole struct garbled, flags never arrived. Rewrite to send_ng with the exact struct and expose tagtype (2=Ultralight,7=NTAG) so Ultralight/NTAG sim works. 14a.sniff sent MIX (args stripped -> empty asBytes); send NG with the 1-byte param. Pre-existing, independent of rebase.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
dropfield waited on a reply the firmware never sends (bare hf_field_off();break;) -> 2s stall + raise; use send_ng_no_response. hf.sniff under-sent the 10-byte {u32,u32,u8,u8} struct and mis-parsed the uint16 reply. hw.standalone sent an empty payload for a {arg,mlen,mode[10]} struct and blocked; pack it + fire-and-forget. Pre-existing, independent of rebase.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
wrbl padded key to 16 (firmware reads block at asBytes+10) -> corrupt writes; pad to 10. nested sent {block,keytype,key,target...} but firmware struct is {block,keytype,target_block,target_keytype,calibrate,key[6]} -> attacked wrong target; reorder + add calibrate + decode reply. cident/sim sent empty/MIX payloads for NG handlers -> send the packed structs. mf.sniff (no firmware handler) reroutes to CMD_HF_ISO14443A_SNIFF. Pre-existing, independent of rebase.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
rdbl omitted the ISO15693 OPTION flag (0x40) so the tag returned [flags][data] without the lock byte the parser assumes (shifting data one byte) and included the 2-byte CRC in block_data. wrbl reused the read flags (no LONG_WAIT) so the firmware used the short RX timeout and the ~20ms write ack arrived too late -> false failure.
rdbl: set OPTION (0x62/0x42), strip CRC (data[2:-2]). wrbl: CONNECT|READ_RESPONSE|LONG_WAIT (0x61). Mirrors C client CmdHF15Readblock / hf_15_write_blk. Pre-existing, independent of the rebase.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ISO15_READ_RESPONSE was 0x10 but the firmware bit is 0x20 (0x10 is HIGH_SPEED, which pm3py lacked), so scan/rdbl/wrbl sent flags 0x19 with READ_RESPONSE never set -> firmware never listened and replied empty. The ARM firmware also ignores ISO15_APPEND_CRC (the C client adds the CRC host-side via AddCrc15), so pm3py's CRC-less frames were never answered by a real tag.
Fix flag values to match firmware include/iso15.h, add crc15 (CRC-16/X-25), and route all iso15 commands through _iso15_payload (appends CRC, sends CONNECT|HIGH_SPEED|READ_RESPONSE=0x31). Payload now byte-matches the C client getUID. Pre-existing bug, independent of the firmware rebase.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CMD_MEASURE_ANTENNA_TUNING_HF requires a 1-byte mode arg (firmware rejects length!=1 with EINVARG) and returns the voltage as uint16, not uint32. tune() sent no arg (empty reply -> 0 mV) and parsed <I. Now sends mode 1/2/3 (START/MEASURE/STOP) and parses <H. Verified vs firmware appmain.c handler; C client reads the same ~15V on this firmware.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
scan() sent flags=0x06 (16-slot inventory). Since 16-slot became the firmware default, the device replies with an iso15_slot_result_t struct, which this parser misread as a zeroed UID (response_flags 16, uid 0000...). Set SLOT1 (0x26) to get the simple single-tag [flags][dsfid][uid] response. Use hf 15 reader --all for multi-tag anti-collision.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Document ALM as analog-only with no command surface, and seed config blocks 0x40-0x44 with the NTA5332 datasheet Rev 3.4 Table 76 defaults (ALM_CONF/ALM_LUT) so a client reading config memory sees the same bytes a real NTA5332 returns.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tag15693.set_uid() now:
- Accepts None (or no args) to generate a random valid UID with the
correct IC-specific prefix (E0 + mfg + IC type)
- Validates length (must be 8 bytes)
- Warns on prefix mismatch (wrong IC type for product-specific tags)
- Warns on non-NXP manufacturer code
- Warns on missing E0 prefix
Replace lightweight async SniffSession with persistent synchronous
session using raw pyserial (mirroring SimSession pattern). Background
reader thread decodes and prints trace frames live as they arrive.
API:
session = SniffSession.open()
session.start_15693() # live streaming (default)
session.start_15693(live=False) # legacy batch mode
session.stop() # or button press to pause/resume
session.entries # all captured frames
session.clear()
.pythonstartup.py auto-creates session in sniff mode.
Add CMD_HF_SNIFF_STREAM (0x0337) and CMD_HF_SNIFF_STATUS (0x0338) for
fire-and-forget trace streaming during sniff. Unified sniff loop uses
the same proven decode path for both streaming and legacy modes —
streaming replaces LogTrace with ring buffer SNIFF_PUSH/SNIFF_FLUSH.
Firmware features:
- Idle flush: sends buffered trace entries over USB when RF is quiet
for idle_timeout_ms (configurable, default 400ms for 15693)
- Button-toggle: pause/resume sniffing without restarting
- DMA restart on resume for clean decoder state
- BREAK_LOOP support for Python-side session.stop()
- Legacy mode (flags=0) preserved unchanged
Python constants: SNIFF_FLAG_STREAMING, SNIFF_FLAG_BUTTON_TOGGLE,
SNIFF_STATE_STARTED/PAUSED/RESUMED/STOPPED, Cmd.HF_SNIFF_STREAM/STATUS
source activate once, then pm3/pm3 sim/pm3 sniff/pm3 all to launch
REPL with appropriate imports. Uses python -i for reliable startup.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
