Skip to content

Collapse PICC/SAM ACS terminal pairs into one Reader during scan #31

Description

@djwok

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):

  1. Prefer PICC, hide SAM for v0.1 card workflows — simplest; document that SAM is out of scope unless explicitly requested later
  2. Group by physical device identity (Bluetooth address / ACS device id when available) and expose slot metadata, e.g. metadata.slots: ['picc'] or preferredTerminalId
  3. Auto-select PICC on connect when user picks a grouped Reader id

Acceptance criteria (draft)

  • Bounded scan returns one Reader per physical ACS BLE unit for common models that currently emit PICC+SAM
  • connectReader() targets the PICC terminal for MIFARE Classic / card-present flows
  • Android/iOS parity for discovery and connect behavior
  • Example app and README note which interface is used (or that duplicates are collapsed)
  • Tests cover dedupe/grouping logic at the highest stable seam (TypeScript helpers or native unit tests if feasible)

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions