Problem
When scanning for ACS BLE Readers, many models (e.g. ACR1255U, ACR1555U) appear as two separate Readers in scan results — typically named PICC and SAM — even though they refer to the same physical Bluetooth device.
This confuses app developers and example-app users who expect one Reader per hardware unit.
Background
The ACS SmartCardIO SDK exposes multiple logical CardTerminal instances per physical reader:
- PICC — Proximity Integrated Circuit Card interface (contactless antenna; where users present MIFARE/NFC cards)
- SAM — Secure Access Module slot (internal secure element; not the user-facing card interface)
v0.1 discovery uses terminal.name as both Reader.id and Reader.name, and deduplicates only by that name. PICC and SAM therefore surface as two distinct Readers.
Relevant native code:
- iOS/Android:
readerForTerminal() sets id and name from terminal.name
- Discovery dedupe key: terminal name only
User impact today
- Scan UI lists duplicate entries for one reader
- Connecting to SAM instead of PICC breaks expected MIFARE Classic card workflows (no card-present/UID/auth on the antenna path)
- Docs/README do not explain PICC vs SAM
Workaround: connect to the PICC entry.
Proposed improvement
Collapse terminals that belong to the same physical ACS reader into one public Reader, while preserving correct connect behavior for MIFARE/card operations.
Possible approaches (implementation TBD):
- Prefer PICC, hide SAM for v0.1 card workflows — simplest; document that SAM is out of scope unless explicitly requested later
- Group by physical device identity (Bluetooth address / ACS device id when available) and expose slot metadata, e.g.
metadata.slots: ['picc'] or preferredTerminalId
- Auto-select PICC on connect when user picks a grouped Reader id
Acceptance criteria (draft)
Out of scope (for this issue)
- Full SAM-slot workflows or SAM-specific APIs
- Heuristic card-type detection
Context
Observed during manual hardware testing on a real iPad with an ACS BLE reader after PR #30 review fixes.
Problem
When scanning for ACS BLE Readers, many models (e.g. ACR1255U, ACR1555U) appear as two separate Readers in scan results — typically named PICC and SAM — even though they refer to the same physical Bluetooth device.
This confuses app developers and example-app users who expect one Reader per hardware unit.
Background
The ACS SmartCardIO SDK exposes multiple logical
CardTerminalinstances per physical reader:v0.1 discovery uses
terminal.nameas bothReader.idandReader.name, and deduplicates only by that name. PICC and SAM therefore surface as two distinct Readers.Relevant native code:
readerForTerminal()setsidandnamefromterminal.nameUser impact today
Workaround: connect to the PICC entry.
Proposed improvement
Collapse terminals that belong to the same physical ACS reader into one public
Reader, while preserving correct connect behavior for MIFARE/card operations.Possible approaches (implementation TBD):
metadata.slots: ['picc']orpreferredTerminalIdAcceptance criteria (draft)
Readerper physical ACS BLE unit for common models that currently emit PICC+SAMconnectReader()targets the PICC terminal for MIFARE Classic / card-present flowsOut of scope (for this issue)
Context
Observed during manual hardware testing on a real iPad with an ACS BLE reader after PR #30 review fixes.