Enhances integration with the PC/SC API for smart card readers, offering an object-oriented interface, helper methods, and platform abstraction for streamlined card interaction across platforms.
Kotlin Multiplatform bindings for the PC/SC API (winscard), which targets:
This was developed to support the PC version of Metrodroid (a public transit card reader).
This repository is a fork of kotlin-pcsc by micolous. It mainly updates the build system and provides artifacts via maven-central. There are also some minor changes in the API, but it should mostly work as a drop-in replacement.
The library is published at maven central and can be added like this:
kotlin {
// add all targets that should be supported
linuxX64()
linuxArm64()
macosX64()
macosArm64()
mingwX64()
jvm()
sourceSets {
commonMain.dependencies {
implementation("org.electrologic.pcsc:kotlin-pcsc:1.0.0")
}
}
}
The libraries entry point is the Context class.
For an example refer to the sample project.
Notes:
PCSC.framework or pcsclite.The API documentation can be viewed online, or built locally with:
./gradlew :dokkaGenerate
The generated API documentation can then be found in the build directory
This library mostly follows the PC/SC API, but takes some liberties to make it easier to use in Kotlin, such as using object orientation, providing helper methods for common patterns, parsing bitfields into properties, and abstracting away the small platform-specific API differences.
The result is that the same "common" API can be used on all platforms: see
the sample directory for an example.
The online version of the documentation can be updated with ./update_online_docs.sh.
All targets, even native ones, require JDK 17 or later to be installed (for Gradle).
The complete distribution can be published to the local maven repository with the following command:
./gradlew :publishToMavenLocalFor publishing to maven central, execute the following:
./gradlew :publishToMavenCentralThe version and the group coordinates of the artifact can be overridden by setting the following gradle project properties:
./gradlew -Pversion=1.0.0 -Pgroup=com.example :publishToMavenLocal
Due to the way kotlin multiplatform packages are published to maven repositories, it is necessary to build all targets at once. Unfortunately not all crossplatform toolchains are available on all platforms. Especially the OSX target is problematic as it is only available on OSX. That means in order to build the library, OSX must be used.
To run the tests, you need:
./gradlew :jnaMainClasses :jnaTest
This builds for all platforms, as the prebuilt net.java.dev.jna package already includes
platform-specific JNI helpers. You don't need any cross-compiling or special machine for that.
libpcsclite1./gradlew :linuxX64MainKlibrary :linuxX64Test
or
./gradlew :linuxArm64MainKlibrary :linuxArm64Test
./gradlew :macosX64MainKlibrary :macosX64Test
or
./gradlew :macosArm64MainKlibrary :macosArm64Test
Note: Only x86_64 target is currently supported.
.\gradlew :mingwX64MainKlibrary :mingwX64Test
Install libpcsclite1 and pcscd packages.
If you're using a reader with NXP PN53x series chipset (eg: ACS ARC122U), you
need to disable the pn533 and pn533_usb modules:
# First, unplug the card reader.
# On Linux 3.1 - 4.6:
echo "blacklist pn533" | sudo tee -a /etc/modprobe.d/blacklist.conf
sudo rmmod pn533
# On Linux 4.7 and later:
echo "blacklist pn533_usb" | sudo tee -a /etc/modprobe.d/blacklist.conf
sudo rmmod pn533_usb
# Finally, plug the card reader in again.
The pn533/pn533_usb module is a driver for a new Linux-kernel-specific NFC
subsystem, which is incompatible with all existing software, including
libacsccid1 (its PC/SC IFD handler).
Yes! See the sample directory of this repository.
This supports building on all target platforms, and includes a jnaFatJar task, which pulls in all
dependencies to a single JAR file.
javax.smartcardio?This is entirely different, and does not support these APIs at all, even when they are available (on Java 8 and earlier).
If you want to use that API, take a look at jnasmartcardio. kotlin-pcsc's
JNA implementation was inspired by it.
intarsys smartcard-io is a Java/JRE library which provides a
Java-friendly PC/SC API (and a javax.smartcardio wrapper).
While it can be used with Kotlin, it only targets the JRE (not Native).
This is explicitly not in scope for this project.
Most mobile devices do not offer a PC/SC-compatible API. The few devices that do run a regular enough Linux userland that you should be able to build using that.
You'll need to provide your own implementation of those protocols. PC/SC only provides a very low
level interface, and you'll be sending ByteArray to the ICC and getting ByteArray back.
We don't even parse the APDUs for you...
| Platform | PC/SC Implementation |
|---|
| JVM | see notes |
| Linux x86_64 | pcsclite |
| Linux arm_64 | pcsclite |
| macOS 10.14+ x86_64 | PCSC.framework |
| macOS 10.14+ arm_64 | PCSC.framework |
| Windows 10+ x86_64 | WinSCard.dll |
Surfaced from shared tags and platforms — no rankings paid for.