APDU Simulator

Play the card. Run an EMV card profile in-process, drive a real card through a PC/SC reader, or push responses to STM32 firmware so an external POS terminal reads your card off a pinboard — with every APDU exchange traced, replayable as a test plan, and exportable as an L3 report.

Overview

The APDU Simulator is the card side of the network. It runs an EMV card profile — scheme, ATR, applications, records, issuer keys — and answers ISO 7816-4 APDUs from whatever is asking, whether that is Studio itself, a physical reader, or a real POS terminal talking to emulator firmware.

APDU Simulator window on the Card Session tab in emulate mode, showing the connect controls, the status strip with phase, last AID and exchange count, and the formatted and raw command and response panels — apdu-simulator Card Session — emulate mode over USB-CDC

🔀

Three Operating Modes

Loopback in-process, a real card through a PC/SC reader, or card emulation over USB-CDC to STM32 firmware.

💳

Card Profiles

Scheme, ATR, AIDs, labels, PAN, expiry, CVN, records and issuer keys — edit, clone and personalise.

▶️

Test Plans

Run a built-in plan through the connected transport and see pass/fail per case.

✅

L3 Report

Export the last run in a certified format — Visa VCPS and Mastercard M/Chip today.

📈

Wire Sniff

Line a logic-analyzer capture up against the exchange log to check what the firmware really put on the wire.

🔧

Firmware

Build and flash the stm32-card firmware without leaving the app.

Quick Start

Create a configuration — Open APDU Simulator and add one.
Pick the mode — On Mode & Transport choose Loopback to start; it needs no hardware.
Choose a card — On Card Profile select a built-in profile such as MasterCard Debit (Test), or clone one and personalise it.
Launch and connect — Open the simulator and press Connect. The status strip shows the phase, the last AID selected, and the exchange count.
Drive it — In loopback and reader modes the Card Session tab gives you quick actions and a raw APDU composer; every exchange lands in Trace Log.

Tip

Develop test plans and personalisation in Loopback first — the EMV runtime is the same one the hardware modes drive, so a plan that passes there is ready for the pinboard.

Mode & Transport

The operating mode decides which role the simulator plays; the transport section below it adapts to that choice.

Mode and Transport tab with the three operating modes listed - loopback, PC/SC reader and card emulator - with card emulator selected, and the STM32 USB-CDC transport showing port, baud rate and an ATR override — apdu-simulator Mode & Transport

Mode	What Studio is	Hardware
Loopback	Both ends. The EMV runtime runs in-process against the active card profile.	None. Ideal for developing test plans and personalisation.
Reader (PC/SC)	The terminal, driving a physical card.	A PC/SC reader such as an ACS ACR39U-I1. The real card is the source of truth — the card profile is informational only.
Card emulator	The card. Studio pushes APDU responses to the firmware over USB-CDC.	A Nucleo-L432KC running the stm32-card firmware, emulating a contact card on the XCRFID pinboard so an external POS terminal can read it.

The hardware modes need hardware you supply

Loopback needs nothing — it is where to start. The other two modes each need a piece of kit that does not ship with ISO8583Studio:

Reader (PC/SC) — any PC/SC contact reader, for example an ACS ACR39U-I1.
Card emulator — an ST Nucleo-L432KC, an XCRFID 4-in-1 SIM/smart-card pinboard, a USB micro-B cable, and a 3V3↔5V level shifter such as a TXS0108E if your terminal drives Class A 5 V cards.

Order the parts yourself — or build the board in-house. ISO8583Studio is Apache 2.0 open source and the emulator firmware ships with it, at firmware/stm32-card/ in the repository: the C source, its PlatformIO project, the full bill of materials and the C1–C8 wiring table from the Nucleo to the ISO 7816 contacts. If you would rather have the board design than a parts list, open an issue and ask for it.

Transport — STM32 / USB-CDC

Port

The serial port the firmware enumerated on. On macOS it appears as /dev/cu.usbmodemXXXX once the firmware boots. Rescan re-enumerates.

Baud rate

Default 115200. The firmware framing is binary, so baud affects throughput, not protocol.

ATR override

Hex ATR presented to the terminal. Leave blank to use the card profile’s own ATR.

Card Profile

The card the simulator emulates while running. Pick a profile, then Edit profile for the full editor, Clone & personalize to derive a new card from it, or New blank to start from nothing.

apdu-simulator Card Profile

The profile summary shows the key fields at a glance:

Scheme

The payment scheme the card belongs to, e.g. MASTERCARD.

ATR

Answer To Reset returned on power-up, e.g. 3B6500002063CB6800.

AID / Label

Application Identifier and its label per application — A0000000041010 / DEBIT MASTERCARD.

PAN / Expiry / CVN

Card number, expiry, and the Cryptogram Version Number selecting the derivation tree.

Records

How many records the application exposes through READ RECORD.

Issuer keys

The issuer master keys the card signs with, by key id and type — e.g. TDES_AC with its UDK.

Note

In Reader (PC/SC) mode the profile is informational only. The physical card answers, not this.

The Other Configuration Tabs

Terminal Profile

The terminal side of the exchange — what the simulated reader claims about itself when loopback drives a transaction.

Risk & Behavior

How the card decides, and where it misbehaves on purpose.

Test Plans

Which plans are available to the runtime’s Test Plans tab.

The Simulator Window

Seven tabs, all live.

Tab	What it does
Card Session	The live exchange. In loopback and reader modes it is active — a quick-action toolbar, a raw APDU composer, and the last exchange split into formatted and raw command and response. In card-emulator mode it is passive: the external terminal drives and Studio answers, so there is no composer.
Trace Log	Every exchange as a log entry, with the same filter, auto-scroll and stats chrome as the other simulators. A non-`9000` status word is coloured as an error.
Test Plans	Pick a built-in plan, run it through the connected transport, see pass/fail per case, export the report in the scheme’s preferred format.
Wire Sniff	Imports a sigrok `.sr` or CSV capture from a 24 MHz logic analyzer and lines it up against the exchange log, so you can confirm the firmware emitted on I/O, CLK, RST and VCC what the runtime says it sent.
L3 Report	Generates a certified-format report from the most recent test-plan run.
Firmware	Builds and flashes the stm32-card firmware, with the build log in the shared log panel.
Settings	A live view of how the running simulator is wired. Changing anything means going back to the configuration screen.

Card Session status strip

Status

Idle, or connected and exchanging.

Phase

Which part of the EMV flow the session has reached.

Last AID

The application most recently selected.

Exchanges

How many command/response pairs this session has carried.

Two things are still landing

Hold next APDU in a passive session is a UI placeholder until the firmware-side interception ships, and Wire Sniff imports captures but is not yet a full overlay. L3 Report covers Visa VCPS and Mastercard M/Chip; other schemes can run plans but skip the certified export until their templates are in.

Common Status Words

SW1 SW2	Meaning
`9000`	Success.
`61xx`	Response available; `xx` bytes remain. Issue `GET RESPONSE`.
`6Cxx`	Wrong Le; correct Le is `xx`.
`6300`	Authentication failed (PIN verification with no retry counter).
`63Cx`	PIN verification failed; `x` tries remaining.
`6700`	Wrong length.
`6982`	Security status not satisfied.
`6985`	Conditions of use not satisfied.
`6A82`	File or application not found.
`6A86`	Incorrect P1 / P2.
`6D00`	Instruction code not supported.
`6E00`	Class not supported.

Tips & Troubleshooting

No serial port listed — The firmware has to boot before the device appears. Wait for /dev/cu.usbmodemXXXX, then press Rescan.
No PC/SC readers detected — Check the PC/SC service is running and no other smartcard application is holding the reader exclusively.
ATR mismatch — Some terminals validate the ATR against a list. Set an ATR override on Mode & Transport to match the card you are impersonating.
Terminal times out — A passive session answers as fast as the firmware relays it; if the terminal still gives up, check the wire capture rather than the runtime.
Plan passes in loopback but fails on hardware — Loopback and the hardware modes share the EMV runtime, so the difference is on the wire. Wire Sniff is the tab for that.