System Design

This chapter defines the architecture for POOM NFC so every lab exercise maps to explicit system boundaries and runtime behavior.

Design Goal: keep protocol handling, hardware control, and UX commands separated so we can add new NFC capabilities without rewriting the whole stack.

Architecture Layers

+-----------------------------------------------------------+
| UX Layer                                                  |
| - CLI commands (nfc-*)                                   |
| - Menu UI NFC flows                                      |
+--------------------------+--------------------------------+
                           |
                           v
+-----------------------------------------------------------+
| NFC Application Services                                  |
| - poom_nfc_controller (orchestration)                    |
| - poom_nfc_reader (scan/connect/read exchange)           |
| - poom_nfc_emulator (3A/T4T/MFUL emulation runtime)      |
| - poom_nfc_dump / profile store / card store             |
+--------------------------+--------------------------------+
                           |
                           v
+-----------------------------------------------------------+
| NFC Protocol Stack                                        |
| - RFAL NFC state machine and technology handlers          |
| - ISO-DEP support (poll + listen)                         |
| - NFC-A/B/F/V discovery                                   |
+--------------------------+--------------------------------+
                           |
                           v
+-----------------------------------------------------------+
| Hardware Abstraction + Driver                             |
| - rfal_platform macros (timers, IRQ lock, bus ops)       |
| - st25r3916 driver + I2C bus provider                     |
+--------------------------+--------------------------------+
                           |
                           v
+-----------------------------------------------------------+
| Physical Layer                                             |
| - ST25R3916 front-end + antenna + target tags/readers     |
+-----------------------------------------------------------+

Component Map

Component	Primary Responsibility	Key Files
CLI entrypoint	Expose user commands and map to controller actions	`applications/cli/src/cli_nfc.c`
NFC controller	Lifecycle and technology selection orchestration	`applications/nfc_read/src/poom_nfc_controller.c`
NFC reader	Discovery, activation, raw exchange, tag extraction	`applications/nfc_read/src/poom_nfc_reader.c`
NFC emulator	Emulate 3A, T4T, and MFUL modes	`applications/nfc_read/src/poom_nfc_emulator.c`
Dump pipeline	Serialize captures to SD and reload IDs	`applications/nfc_read/src/poom_nfc_dump.c`
NVS stores	Persist cards and full activation profiles	`applications/nfc_read/src/poom_nfc_store.c`, `applications/nfc_read/src/poom_nfc_profile_store.c`
RFAL + ST25 core	Protocol engine and RF front-end control	`modules/nfc/include/rfal/rfal_platform.h`, `modules/nfc/src/`

Runtime Flows

Flow A: Scan and Dump

CLI nfc-dump-sd
  -> poom_nfc_controller_dump_to_sd()
    -> poom_nfc_reader_scan_once()
      -> RFAL discovery + activation
    -> poom_nfc_reader_create_dump()
    -> poom_nfc_dump_save_to_sd()
      -> /sdcard/nfc_dumps/*.nfc (structured text)

Flow B: Emulation (Profile Snapshot)

CLI nfc-connect
  -> activation snapshot saved in memory
CLI nfc-emul-set-from-last-scan
  -> apply UID/ATQA/SAK/ATS/mode config
CLI nfc-emul-start
  -> poom_nfc_emulator_start()
    -> listen mode loop
    -> anti-collision / activation / data exchange

Flow C: Type-Specific Filters

CLI nfc-a / nfc-b / nfc-f / nfc-v / nfc-all
  -> poom_nfc_controller_set_technology()
  -> poom_nfc_reader applies RFAL tech mask before discovery

Interface Contracts

API Surface	Contract	Caller Layer
`poom_nfc_controller_*`	Single orchestration entrypoint for start/scan/connect/dump/tech selection	CLI and menu layers
`poom_nfc_reader_*`	Protocol-facing operations; no UX decisions	Controller layer
`poom_nfc_emulator_*`	Owns emulation config/runtime and must be stopped before config mutation	Controller and CLI commands
`poom_nfc_dump_*`	Capture serialization/deserialization for SD artifacts	Controller layer
RFAL APIs	Low-level discovery/activation/transceive/state machine	Reader and emulator internals

State Model

At runtime we keep two important state machines aligned:

RFAL discovery states: not-init, idle, start-discovery, poll detect/select/activation, activated, data exchange, deactivation.
POOM emulator lifecycle: config -> start listen -> wait field -> anti-collision -> activated -> exchange -> restart/stop.

Persistence Model

Store	Medium	Purpose	Capacity
`nfc_cards`	NVS	Compact card IDs for quick emulation/select	30 cards
`nfc_profiles`	NVS	Full activation profiles (mode + UID + ATQA + SAK + ATS)	20 profiles
`/nfc_dumps`	SD Card	Structured capture artifacts for lab evidence	SD-dependent

Design Constraints

RF features are compile-time constrained by RFAL macros (for example NFC-DEP and ST25TB currently disabled).
MFUL emulator path uses raw 64-byte image input; structured text dumps are for analysis/evidence unless converted.
Single front-end hardware means protocol selection and field control must remain centralized in the controller.