kmp-nfc

0.0.4indexed

NFC toolkit for tag reading/writing: NDEF read/write, raw APDU transceive, capability introspection, plus test doubles with error injection and delay simulation.

AndroidJVMNative·gary-quinn/kmp-nfc

Stars

—

Used by

dependents

Health

/ 100

kmp-nfc

Kotlin Multiplatform NFC library for Android and iOS.

Part of the wireless trifecta: kmp-ble (BLE) + kmp-uwb (UWB) + kmp-nfc (NFC).

Modules

Module

Setup

Android / KMP (Gradle)

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.atruedev:kmp-nfc:0.0.4")

            // Optional: test doubles for unit testing
            // testImplementation("com.atruedev:kmp-nfc-testing:0.0.2")
        }
    }
}

Android initialization happens automatically via AndroidX App Startup. To initialize manually:

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        KmpNfc.init(this)
    }
}

iOS (Swift Package Manager)

In Xcode: File > Add Package Dependencies and enter:

https://github.com/gary-quinn/kmp-nfc

Select the version and add KmpNfc to your target.

import KmpNfc

Usage

Monitor adapter state

val adapter = NfcAdapter()

adapter.state.collect { state ->
    when (state) {
        NfcAdapterState.ON -> println("NFC ready")
        NfcAdapterState.OFF -> println("NFC disabled")
        NfcAdapterState.NOT_SUPPORTED -> println("No NFC hardware")
        NfcAdapterState.UNAUTHORIZED -> println("Permission denied")
    }
}

Check capabilities

val adapter = NfcAdapter()
val caps = adapter.capabilities

if (caps.canReadNdef) { /* NDEF reading available */ }
if (caps.canWriteNdef) { /* NDEF writing available (iOS 13+) */ }
if (caps.canReadRawTag) { /* Raw transceive available */ }

Read NFC tags

val adapter = NfcAdapter()

adapter.tags(ReaderOptions(alertMessage = "Hold near tag")).collect { tag ->
    tag.use {
        val ndef = it.readNdef()
        ndef?.records?.forEach { record ->
            when (record) {
                is NdefRecord.Uri -> println("URL: ${record.uri}")
                is NdefRecord.Text -> println("Text: ${record.text}")
                is NdefRecord.MimeMedia -> println("MIME: ${record.mimeType}")
                 -> {}
            }
        }
    }
}

Write NDEF

val message = ndefMessage {
    uri("https://github.com/gary-quinn/kmp-nfc")
    text("Hello NFC", locale = "en")
}

tag.writeNdef(message)

Raw APDU transceive

For ISO 7816-4 smart cards (Aliro, passports, payment cards):

// SELECT command
val selectAid = byteArrayOf(0x00, 0xA4.toByte(), 0x04, 0x00, 0x07) +
    byteArrayOf(0xA0.toByte(), 0x00, 0x00, 0x00, 0x04, 0x10, 0x10)

val response = tag.transceive(selectAid)
// response includes data + SW1 + SW2 (e.g., 0x90 0x00 = success)

Test without hardware

val adapter = FakeNfcAdapter()

adapter.tags().test {
    val tag = fakeNfcTag {
        identifier(byteArrayOf(0x04, 0x12, 0x34, 0x56))
        type(TagType.ISO_DEP)
        ndef(ndefMessage { uri("https://example.com") })
        onTransceive { command -> byteArrayOf(0x90.toByte(), 0x00) }
    }
    adapter.emitTag(tag)
    assertEquals(tag, awaitItem())
}

// Error injection
val failingTag = fakeNfcTag {
    failWith(TagLost())
    respondAfter(100.milliseconds)
}

Android scan modes

Android exposes two scanning APIs via ReaderOptions.androidScanMode:

val options = ReaderOptions(androidScanMode = AndroidScanMode.ForegroundDispatch)

ReaderMode (default) - NfcAdapter.enableReaderMode. The system suppresses default NDEF intent resolution, so URI tags do not launch the browser.
ForegroundDispatch - NfcAdapter.enableForegroundDispatch. The library owns a per-session broadcast receiver; the app takes priority over other apps' intent filters while in the foreground.

Platform Differences

NFC has significant platform asymmetry. kmp-nfc exposes this through NfcCapabilities rather than hiding it behind a lowest-common-denominator API.

Ecosystem

kmp-ble - Bluetooth Low Energy (scanning, GATT, server, DFU)
kmp-uwb - Ultra-Wideband (precise ranging)
kmp-nfc - NFC (tap-to-access)

Together these form the foundation for an Aliro SDK - the CSA smart lock standard combining NFC + BLE + UWB.

Requirements

Kotlin 2.3.20+
Android minSdk 21
iOS 15+
kotlinx-coroutines 1.10+

Contributing

After cloning, enable the repo's pre-commit hooks once:

git config core.hooksPath .githooks

The hook blocks Unicode typography characters (em/en-dash, smart quotes, ellipsis, NBSP) in staged content. See AGENTS.md for the full list and the typo-ok bypass.

License

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

Kotlin-BLE-Library★ 515

nordicsemiSimplifies Bluetooth Low Energy usage with coroutine-based asynchronous APIs: scanning, connecting (autoConnect), GATT reads/writes, MTU/PHY management, notifications, and mock environments for testing.Shared: wrapper, sdk, kotlin-flow

kaluga★ 397

splendoOffers modular tools for cross-platform mobile app development, including features like MVVM architecture, location services, permissions management, Bluetooth communication, and more, using coroutines and `Flow` for efficient design.Shared: kotlin-flow, kotlin-coroutines, device

konnection★ 170

TM-AppsLibrary emits network connection status, offers immediate connection state checks, IP info retrieval, and network state observation. Supports customizable instance creation and includes default IP resolvers.Shared: sdk, kotlin-flow, kotlin-coroutines

KmpEssentials★ 359

Ares-Defence-LabsLightweight library simplifies development with APIs for battery management, file system operations, and package information retrieval, supporting integration with multiple platforms and providing Swift package availability.Shared: sdk, device, apple

TextToSpeechKt★ 57

Marc-JBCross-platform text-to-speech library enabling speech synthesis with coroutine support. Features include volume, pitch, and rate adjustments, with Compose integration for enhanced functionality.Shared: sdk, kotlin-coroutines, apple

room★ 6.0k

androidxAbstraction layer over SQLite enabling robust database access, compile-time schema export and migrations, annotation-processor tooling, coroutine/RxJava/paging integrations, Gradle plugin for schema management.Shared: test, kotlin-coroutines, jetpack

kmp-nfc	`com.atruedev:kmp-nfc`	Core NFC - tag reading, NDEF read/write, raw transceive (ISO 7816-4 APDU)
kmp-nfc-testing	`com.atruedev:kmp-nfc-testing`	Test doubles - `FakeNfcAdapter`, `FakeNfcTag` with error injection and delay simulation

NDEF Read	Yes	Yes
NDEF Write	Yes	Yes (iOS 13+)
Raw Transceive	Yes (all tag types)	Yes (ISO 7816, MiFare)
Background Read	No (both scan modes require foreground)	Yes (URL tags only, system-managed)
Tag Types	NFC-A/B/F/V, ISO-DEP, MIFARE	NFC-A/B/F/V, ISO-DEP
Session UX	Transparent	System NFC sheet