pm3py/docs/plans/2026-07-05-14a-custom-commands-plan.md

Custom ISO14443-A command handling — Implementation Plan

Status: Planned, unimplemented · Date: 2026-07-05 · Design: 2026-07-05-14a-custom-commands-design.md

Serve custom/vendored ISO14443-A commands in the card sim, layered on the native-EML 14a sim. Two independently shippable tracks: L3 (NTAG I2C SECTOR_SELECT + cross-sector reads, static vendor reads, native auth) and L4 (static ISO-DEP APDUs + WTX relay for dynamic crypto). Reuses the proven 15693 sim_table server, the 120-byte TableEntry format, and the TableCompiler. All firmware line numbers are anchors against the current firmware/armsrc/iso14443a.c; each firmware change lands as an atomic single-file commit anchored to stable symbols (ISO14443A_CMD_RATS, the final else, EmSendPrecompiledCmd), not line numbers.

---

L3 track — mechanisms

• (A) Native-EML (unchanged): REQA/WUPA/anticoll/SELECT/PPS/GET_VERSION/READ_SIG/ READ/FAST_READ/WRITE/COMPAT_WRITE/READ_CNT/INCR_CNT/HALT/RATS. Byte-correct within 86µs, zero new code. WRITE mutates the EM BigBuf so later reads reflect writes natively.
• (B) Native-EML + sector offset (graft): cross-sector READ/FAST_READ. sim_active_sector() maps the sim_table active-group bits → {0,1,3}; native READ (:2033-2058) and FAST_READ (:2081-2093) add sim_active_sector()*0x400 to the emlGet source offset. Python pre-zeroes invalid pages in the uploaded multi-sector EML image so native 00-fill falls out for free. Reads stay O(1)-native, sector-correct.
• (C) Static sim_table (new :2493 hook): the SECTOR_SELECT state machine + genuinely-custom static reads only (see worked example). No per-page entries.
• (D) Native firmware auth (existing branches): UL-C 3DES (:2242), UL-AES (:2273/2324/2355), MFC Crypto1 — model key in EML, firmware computes challenge/response, first cut fixed-nonce. Not table, not relay.

L3 miss policy: reader-retry relay is debug-only (86µs FDT is unreachable over USB). Everything reachable at L3 is covered by A–D.

L4 track — mechanisms

Gated by a new iso_dep_active flag (set at RATS→ATS :2234; cleared on HALT / S(DESELECT)).

• (E) Static sim_table (same :2493 hook): deterministic ISO-DEP APDUs — Type-4 NDEF SELECT-App(AID) / SELECT-File(CC,NDEF) / ReadBinary, canned GET/PUT DATA, fixed 90 00. Firmware masks the PCB ((pcb&0xE2)==0x02 = I-block), computes off = 1 + CID + NAD, strips the trailing CRC, MATCH_PREFIX on the bare APDU; on hit re-wraps (response[0]=pcb, CID re-inserted at response[1] when pcb&0x08, payload at response+off, AddCrc14A). Overrides the bogus blanket 90 00 at :2529-2545 — which is exactly why the hook sits at :2493 (before the switch), not :2576.
• (F) WTX relay (dynamic crypto): on an I-block table miss with iso_dep_active, firmware sends a tag-side S(WTX) to buy time (FWT×59 ≈ 4.8s), relays the normalized APDU to Python, spin-waits for the computed response, re-wraps and sends. The Python transponder model owns per-session nonce/IV/auth state.

L4 chaining (gating dependency for DESFire/NDEF coverage): tag block-number toggle (PCB bit0 per I-block), reader→tag reassembly (PCB bit4 → R(ACK) 0xA2|bn), tag→reader FSD split into chained I-blocks. DYNAMIC_RESPONSE_BUFFER_SIZE bumped 64→256 first. v1 gated to single-frame + 0xAF continuation until chaining lands.

---

Firmware steps

ID	File	Change
FW-1	armsrc/sim_table.h + .c	Generalize sim_table_execute from (iso15_tag_t *tag) to (uint8_t *eml_data, uint16_t eml_size, uint32_t *auth_state); replace tag->data/sizeof(tag->data)/tag->auth_state at sim_table.c:132-169. Drop #include iso15.h from the header. Add #define SIM_FLAG_RESP_4BIT 0x04. Struct unchanged (120 bytes PACKED). Fork-local.
FW-2	armsrc/iso15693.c	Update the single sim_table_execute call site (~:3081) to the new signature: (tag->data, sizeof(tag->data), &tag->auth_state). Keeps 15693 green.
FW-3	armsrc/iso14443a.c (commit A)	#include sim_table.h. Add file-scope static uint32_t s_auth_state and sim_active_sector() near the sim-trace statics (~:1727); reset s_auth_state=0 in the FLAG_SIM_TRACE arm. Bump DYNAMIC_RESPONSE_BUFFER_SIZE 64→256 and the modulation buffer. Insert host-poll block at loop top after sim_trace_flush (~:1907): CMD_SIM_TABLE_UPLOAD (4-byte initial_groups + 120B entries → sim_table_init/add), UPDATE, CLEAR, CMD_HF_MIFARE_EML_MEMSET (emlSet), CMD_BREAK_LOOP. Copied ~verbatim from iso15693.c:2472-2508.
FW-4	armsrc/iso14443a.c (commit B)	L3 table-check at :2493 (after the response_n/modulation_n reset, before tagType==10 and the fake-90 00 switch): sim_table_lookup + sim_table_execute; honor SIM_FLAG_RESP_4BIT (EmSend4bit), response_len==0 (passive-ACK silence), byte response (join the :2591 build path), SIM_FLAG_APPEND_CRC. Sector-offset graft on native READ/FAST_READ (sim_active_sector()*0x400). Add labels build_send: (:2591) and after_send: (past :2620).
FW-5	include/pm3_cmd.h	Append CMD_SIM_RELAY_EVENT 0x0953 and CMD_SIM_RELAY_RESP 0x0954 in the existing 0x095x block. Additive.
FW-6	armsrc/iso14443a.c (commit C)	Add file-scope bool iso_dep_active (near order :1870); set at RATS→ATS (:2234), clear on HALT (:2214) and S(DESELECT). Extend the :2493 hook: detect I-block, off=1+CID+NAD, strip PCB/CID/NAD+CRC, MATCH_PREFIX on the bare APDU; on hit re-wrap and join build_send. Overrides fake 90 00.
FW-7	armsrc/iso14443a.c (commit D, then E)	D: EmSendWtx(uint8_t wtxm) tag-side S(WTX) sender modeled on EmSendCmd (the :3787-3808 send_wtx is reader-side, not reusable). On L4 miss: EmSendWtx(59) → await reader S(WTX) echo ((b&0xF2)==0xF2) → reply_ng(CMD_SIM_RELAY_EVENT,{L4,apdu}) → spin data_available()/receive_ng() for CMD_SIM_RELAY_RESP (GetTickCount timeout) → re-wrap + EmSendCmd. E: block-number toggle + reader→tag chaining reassembly + tag→reader FSD split.

pm3py steps

ID	File	Change
PY-1	pm3py/core/protocol.py	FIX id drift: repoint SIM_TABLE_UPLOAD/CLEAR/UPDATE from stale 0x0900/0901/0902 → 0x0950/0951/0952. Add SIM_RELAY_EVENT=0x0953, SIM_RELAY_RESP=0x0954. Reuse HF_MIFARE_EML_MEMSET=0x0602 for EML load.
PY-2	pm3py/sim/table_compiler.py	Add RESP_FLAG_4BIT=0x04 + group constants (GRP_SEL_PENDING=1, GRP_SECTOR0=2, GRP_SECTOR1=3, GRP_SECTOR3=4). Add compile_ntag_i2c(tag): base=compile_14a(tag) + only the SECTOR_SELECT machine (no per-page reads). Add an enumerate_table_entries() hook so a model can yield full TableEntry objects (groups/flags) alongside the legacy enumerate_responses 3-tuple.
PY-3	pm3py/transponders/hf/iso14443a/nxp/ntag_i2c.py	Add build_eml_image() laying out [mfu prefix][sector0, invalid pages zeroed][sector1][sector3 regs] at 0x400 stride, reusing _masked_page/_page_readable. Add enumerate_table_entries() yielding the SECTOR_SELECT machine. Keep enumerate_responses (sector-0) for other consumers.
PY-4	pm3py/sim/sim_session.py (L3)	Fix constants. In start_14a: if the tag is table-backed, load the EML image (CMD_HF_MIFARE_EML_MEMSET) then _compile_and_upload_table with a 14a dispatch branch (NtagI2C→compile_ntag_i2c, MifareClassic→compile_mifare, else compile_14a). Factor the initial_groups+120B chunked uploader into a shared _upload(table, initial_groups).
PY-5	pm3py/sim/sim_session.py (L4)	Async relay path for L4-crypto tags: send HF_ISO14443A_SIMULATE via async PM3Transport, create_task(self._relay_loop(tag)); do not spawn the sync _trace_reader thread (single async reader owns trace + relay on one fd). Flesh out _relay_loop: CMD_SIM_RELAY_EVENT → RESELECT→tag.power_on(); L4→out=await tag.handle_frame(RFFrame.from_bytes(apdu)), reply CMD_SIM_RELAY_RESP with resp_flags + bare bytes.

New / reused command IDs & flags

• CMD_SIM_RELAY_EVENT = 0x0953 (new) fw→host: normalized L4 APDU on table miss.
• CMD_SIM_RELAY_RESP = 0x0954 (new) host→fw: computed L4 response.
• CMD_SIM_TABLE_UPLOAD/CLEAR/UPDATE = 0x0950/0951/0952 (reused; fix protocol.Cmd stale 0x0900 series).
• CMD_HF_MIFARE_EML_MEMSET = 0x0602 (reused) to load the multi-sector 14a EML image (native sim already reads tag memory from the EM BigBuf via emlGet).
• SIM_FLAG_RESP_4BIT = 0x04 (new) response-flag (fw sim_table.h + RESP_FLAG_4BIT in table_compiler.py) — not a wire command.
• GRP_SEL_PENDING=1 / GRP_SECTOR0=2 / GRP_SECTOR1=3 / GRP_SECTOR3=4 — compiler-side group-bit convention (max 31 groups), not firmware constants.

Wire formats

sim_table_entry_t (120-byte PACKED, reused byte-for-byte, LE <32s B B 64s B B B H B B B B B I I B B B B>): match[32]@0, match_len@32, match_mode@33 (0=EXACT, 1=PREFIX), response[64]@34, response_len@98, response_flags@99 (bit0=APPEND_CRC, bit2=RESP_4BIT new), eml_action@100, eml_offset(u16)@101, eml_len@103, eml_resp_insert@104, cmd_data_offset@105, cmd_data_len@106, group@107, activate_groups(u32)@108, deactivate_groups(u32)@112, set_auth@116, clear_auth@117, flags@118 (bit1=CONSUME), _pad@119. TableEntry.serialize() already emits exactly this.

Upload (unchanged): CMD_SIM_TABLE_UPLOAD first frame = 4-byte initial_groups (LE)

• N×120B entries filling 512-4 bytes; CMD_SIM_TABLE_UPDATE = (512//120)*120B chunks; CMD_SIM_TABLE_CLEAR = empty.

Relay event (CMD_SIM_RELAY_EVENT payload): byte[0]=ev_type (0=RESELECT, 3=L3-debug, 4=L4), byte[1]=norm_len, byte[2..]=normalized frame (L4: PCB/CID/NAD+CRC stripped). Relay resp (CMD_SIM_RELAY_RESP payload): byte[0]=ev_type echo, byte[1]=resp_flags (bit0=append-CRC, bit1=4BIT, bit2=passive-ACK/no-tx, bit4=chaining-more), byte[2..]=bare response. tag.handle_frame returns bare bytes — firmware owns PCB/CID/NAD framing and block-number.

NTAG I2C worked example (NT3H2211, 2k) — reading Sector 1

Compile (compile_ntag_i2c): initial_groups seeds GRP_SECTOR0 active. Multi-sector EML image loaded via CMD_HF_MIFARE_EML_MEMSET. ~6 table entries (far under any FDT/entry limit):

• E1 [C2 FF] EXACT → [0A] RESP_4BIT, activate GRP_SEL_PENDING.
• E2 [00 00 00 00] EXACT, group=GRP_SEL_PENDING, response_len=0, activate GRP_SECTOR0, deactivate SECTOR1|SECTOR3|SEL_PENDING.
• E3 [01 00 00 00] → GRP_SECTOR1. E4 [03 00 00 00] → GRP_SECTOR3.
• E5 [] PREFIX (last) in GRP_SEL_PENDING → [00] 4-bit NAK, deactivate SEL_PENDING.

Runtime:

1. Native anticoll/SELECT (unchanged). sim_active_sector()==0.
2. Reader → C2 FF → :2493 hit E1 → EmSend4bit(0x0A), active_groups |= SEL_PENDING.
3. Reader → 01 00 00 00 (bare sector byte) → :2493 in SEL_PENDING hit E3 → response_len==0 ⇒ apply state (+SECTOR1, clear others + SEL_PENDING), transmit nothing = the >1ms passive-ACK. sim_active_sector() now returns 1.
4. Reader → FAST_READ 3A 00 0F → native FAST_READ fires first (correct), reads emlGet at base + 1*0x400 = sector-1 memory, returns via EmSendCmd. Sector-correct, O(1), wire-speed, no table scan, no USB.
5. Back to sector 0: C2 FF (E1), 00 00 00 00 (E2 → SECTOR0, silence).
6. Invalid sector: C2 FF then 07 00 00 00 → E5 → 4-bit NAK, SEL_PENDING cleared.

All frames trace via EmLogTrace/sim_trace_push automatically.

Stateful command handling — five representations

1. In-table group state (no host, wire-speed): SECTOR_SELECT active sector, SLIX2-style privacy, PWD_AUTH-gated read sets. activate_groups/deactivate_groups masks; two-phase handshakes use a transient PENDING group so a stray frame can't false-flip; silent success = response_len==0; 4-bit ACK/NAK = RESP_4BIT.
2. Firmware sector projection (the graft): sim_active_sector() derives the active sector read-only from active_groups — single source of truth, native reads O(1).
3. EML-backed mutable state (no host): live WRITE persists into EM BigBuf; later native reads reflect it.
4. Native-auth state (no host): UL-C/UL-AES/MFC via existing firmware branches with key in EML; auth_state word + firmware nonce chain carry session state. First cut fixed-nonce.
5. Relay state (host, L4 only): dynamic ISO-DEP crypto; Python owns per-session nonce/IV/auth in handle_frame. A challenge-prefix entry may be SIM_FLAG_CONSUME (one-shot) to hand the encrypted tail to the relay.

Session reset: on REQA/WUPA/HALT firmware resets active_groups + iso_dep_active and (for L4 relay tags) emits CMD_SIM_RELAY_EVENT{RESELECT} so Python calls tag.power_on(), keeping the C and Python state machines in lockstep across a reader give-up → re-anticollision.

Test plan

• UNIT (pm3py): TableEntry.serialize() round-trips RESP_4BIT/group fields at exact byte offsets (99, 107-118), sizeof==120.
• UNIT: compile_ntag_i2c emits exactly the E1-E5 machine (correct match/groups/masks/ flags); assert no per-page sector reads.
• UNIT: build_eml_image() lays out [prefix][sector0 zeroed-invalid][sector1] [sector3] at 0x400 stride with per-sector PWD/PACK masking (no secret leakage).
• UNIT: protocol.Cmd drift fixed (SIM_TABLE_* == 0x0950/1/2, relay ids); sim_session constants match; FLAG_SIM_TRACE bit confirmed against firmware.
• UNIT: _relay_loop parses CMD_SIM_RELAY_EVENT{L4}, calls handle_frame, replies with correct resp_flags; RESELECT triggers power_on.
• FIRMWARE UNIT (host build of sim_table.c): group gating + activate/deactivate transitions E1→E3; response_len==0 path; RESP_4BIT path; sim_active_sector() maps bits → {0,1,3}.
• FIRMWARE UNIT: worst-case sim_table_lookup latency on the 48MHz ARM for the ~30-entry table vs 86µs FDT — measure, do not hand-wave (must-pass gate).
• HARDWARE L3: PM3 Easy sims NT3H2211; reader issues C2 FF + 01 00 00 00 + FAST_READ; live-trace confirms 4-bit ACK, >1ms silence, sector-1 data, invalid NAK; and that a table hit fully suppresses the fake-90 00 path.
• HARDWARE L3: verify passive-ACK phase-2 emits nothing (no spurious frame the reader misreads as NAK).
• HARDWARE L4 static: Type-4 NDEF SELECT-App/File/ReadBinary from the table, overriding fake 90 00; TagInfo reads NDEF.
• HARDWARE L4 relay: DESFire GET_VERSION (0xAF chaining) and a >FSD NDEF read via WTX relay; assert S(WTX) echo, block-number toggle, chained reassembly both directions.
• REGRESSION: 15693 sim still works after the sim_table_execute signature change; full pytest suite green.

Sequencing

L3 track (ship first, independently testable):

1. FW-1 (sim_table signature + RESP_4BIT) → FW-2 (iso15693.c call site, keeps 15693 green).
2. FW-3 (commit A: include, statics, buffer bump, host-poll upload).
3. FW-4 (commit B: L3 table-check + sector-offset graft).
4. PY-1 (id fix) → PY-2 (compile_ntag_i2c) → PY-3 (build_eml_image + entries) → PY-4 (start_14a upload + dispatch).
5. Test L3 on hardware. Commit + bump firmware gitlink.

L4 track (independent, builds on the L3 host-poll hook): 6. FW-5 (pm3_cmd.h relay ids). 7. FW-6 (commit C: iso_dep_active + static-APDU serve overriding fake 90 00). 8. FW-7 (commit D: EmSendWtx + WTX relay; commit E: block-number toggle + chaining). 9. PY-5 (async start_14a relay path + _relay_loop). 10. Test L4 on hardware (DESFire chaining, NDEF>FSD).

Risks & mitigations

Risk	Mitigation
FDT scan blowout — linear sim_table_lookup approaches 86µs on a big table.	Sector-offset graft keeps the 14a table tiny (~6-30 entries); cross-sector reads are native (O(1)). Firmware-host unit test measures worst-case latency vs 86µs before shipping. Contingency: first-byte bucket index in sim_table.c (benefits 15693 too).
Dispatch order — native READ/FAST_READ fire before :2493 and would serve flat sector-0 data.	Resolved by design: cross-sector reads are not routed through the table; native branches are made sector-aware via one emlGet offset. Native-first is now correct.
Passive-ACK phase-2 emits a spurious frame the reader reads as NAK.	sim_table_execute sets *resp_len=0; hook sets p_response=NULL and jumps past send; the if(response_n>0) build guard yields silence. Hardware test asserts >1ms silence.
Command-id drift — protocol.py at stale 0x0900 series mismatches framing.	PY-1 fixes it as the first Python commit; unit test asserts the values.
UL-C/UL-AES miscategorized as L4.	Routed to existing native firmware auth branches with model key via EML; documented fixed-nonce fidelity gap. Not claimed under table/relay.
L4 relay claims DESFire/NDEF but chaining/block-number don't exist in FW.	Chaining is an explicit gating commit (FW-7 E) before DESFire is claimed; buffer bumped to 256 first; v1 gated to single-frame + 0xAF.
iso14443a.c is a hot upstream file — hooks churn on rebase.	Atomic single-file commits anchored to stable symbols; heavy logic in self-contained blocks; sim_table/sim_crypto fork-local; only one 15693 call site changes.
CONSUME one-shots not reset until re-UPLOAD.	Session-reset emits RESELECT; where a CONSUME challenge must re-arm, Python re-uploads/re-adds; documented constraint.

Open decisions

1. FLAG_SIM_TRACE bit: sim_session.py uses 0x2000, the 14a live-trace plan doc says 0x4000; confirm the firmware's actual bit before wiring the async relay. (Note: reconciled this session — firmware F1 landed FLAG_SIM_TRACE 0x2000; the doc's 0x4000 is stale. Verify against pm3_cmd.h.)
2. Multi-sector EML layout: confirm the EM BigBuf CARD_MEMORY fits sector0+1+3 (~2KB + config) and that CMD_HF_MIFARE_EML_MEMSET writes at the offset the sector graft expects; else add a dedicated CMD_HF_ISO14443A_EML_SETMEM (fallback id 0x033A).
3. NTAG I2C no-rollover fidelity: native READ may roll over at emulator-memory end, not sector end. Decide pre-zeroing vs an explicit sector-length clamp in the READ branch.
4. NTAG21x first-READ NFC counter bump is a side effect the native/static path loses. Accept as documented deviation, or force that first READ through a CONSUME entry (same for EV1 INCR_CNT edges).
5. UL-C 3DES fixed nonce vs model random RndB: acceptable for sim; decide whether firmware 3DES-with-supplied-nonce is wanted or a downscope note suffices.
6. L4 chaining scope for v1: minimum viable = single-frame APDUs + DESFire 0xAF + tag→reader FSD split. Confirm whether reader→tag chaining is needed for any target reader in the first cut or can be deferred.
7. Empirical reader behaviour: do target NTAG I2C reader stacks actually issue SECTOR_SELECT for sector 1, or only read sector-0 NDEF? If the latter, sector-1 can be validated later without blocking the L3 ship.
8. Apply hooks to SimulateIso14443aTagAID (:4716)? Deferred; TagEx is the primary FLAG_SIM_TRACE path.

Provenance

Produced by the plan-14a-custom-commands design workflow (13 agents: 6 readers → 3 designs → 3 adversarial judges → synthesis). Judge outcome: static-table-first and hybrid "adopt-with-changes" (reuse 5/5, fdt_safety 3-4); relay-first "reject" (FDT-unsafe at L3). The recommended architecture is static-table-first L3 grafted with a firmware sector projection to resolve the SECTOR_SELECT/entry-explosion risk, plus a WTX relay for dynamic L4 crypto.