Skip to content

Installation

System Dependencies

pythaiidcard requires several system-level dependencies for PC/SC smartcard communication.

Linux (Debian/Ubuntu)

sudo apt-get update
sudo apt-get install -y pcscd libpcsclite-dev python3-dev swig

What these packages do:

  • pcscd - PC/SC Smart Card Daemon (manages smartcard readers)
  • libpcsclite-dev - Development files for PC/SC Lite library
  • python3-dev - Python development headers (required for pyscard compilation)
  • swig - Interface compiler for Python bindings

Other Linux Distributions

sudo dnf install -y pcsc-lite pcsc-lite-devel python3-devel swig

sudo pacman -S pcsclite swig python

sudo zypper install pcsc-lite pcsc-lite-devel python3-devel swig

Verify Installation

After installing system dependencies, verify that the PC/SC daemon is running:

sudo systemctl status pcscd

If it's not running, start it:

sudo systemctl start pcscd
sudo systemctl enable pcscd  # Enable on boot

Python Package Installation

pip install pythaiidcard

Using uv (Fast)

uv add pythaiidcard

From Source

git clone https://github.com/ninyawee/pythaiidcard.git
cd pythaiidcard
uv sync --group dev

Dependency Check

pythaiidcard automatically checks for required system dependencies on Linux systems. If dependencies are missing, you'll see a helpful error message:

from pythaiidcard import ThaiIDCardReader

reader = ThaiIDCardReader()
# SystemDependencyError: Missing required system dependencies:
#
#   ✗ PC/SC Smart Card Daemon (pcscd)
#   ✗ PC/SC Lite development library (libpcsclite-dev)
#
# To install missing dependencies, run:
#
#   sudo apt-get update && sudo apt-get install -y pcscd libpcsclite-dev python3-dev swig

Skipping the Check

If you've installed dependencies via other means or want to skip the check:

reader = ThaiIDCardReader(skip_system_check=True)

Hardware Setup

Hardware Compatibility

Not all smartcard readers behave the same. Some readers have hardware limitations that may affect functionality. See Hardware Compatibility for tested readers and known issues.

The library works with any PC/SC compatible smartcard reader. The author uses and recommends:

USB-C Smart Card Reader

USB-C Card Reader

  • Product: USB-C Smart Card Reader
  • Link: Available on Shopee (affiliate link)
  • Features:
  • USB-C connection
  • Compact and portable
  • Works with Thai National ID cards
  • PC/SC compatible
  • Plug and play on Linux

Affiliate Disclosure

The Shopee link above is an affiliate link. The author may earn a commission from purchases made through this link at no additional cost to you.

Alternative Readers

Any PC/SC compatible smartcard reader will work, including:

  • Generic USB smartcard readers
  • Gemalto readers
  • ACS ACR122U
  • Built-in laptop smartcard readers

Known Limitations

Alcor Link AK9563: This reader has known limitations with auto-read functionality. It works perfectly in on-demand mode (default in v2.2.0+). See Hardware Compatibility for details.

Connect Your Smartcard Reader

  1. Plug in your PC/SC compatible smartcard reader
  2. Verify it's detected:
pcsc_scan

You should see output like:

PC/SC device scanner
V 1.6.2 (c) 2001-2022, Ludovic Rousseau <ludovic.rousseau@free.fr>
...
Reader 0: Generic USB Smart Card Reader

Press Ctrl+C to exit.

Permissions (Optional)

If you encounter permission issues, add your user to the scard group:

sudo usermod -a -G scard $USER

Then log out and log back in for the changes to take effect.

Verify Installation

Test that everything is working:

from pythaiidcard import ThaiIDCardReader

# List available readers
readers = ThaiIDCardReader.list_readers()
for r in readers:
    print(f"Reader {r.index}: {r.name}")
    print(f"  Status: {'Card Present' if r.connected else 'No Card'}")

Development Installation

For development with all optional dependencies:

# Clone the repository
git clone https://github.com/ninyawee/pythaiidcard.git
cd pythaiidcard

# Install with development dependencies
uv sync --group dev

# Install system dependencies
mise run install-deps  # If you have mise installed

Development Tools

The development environment includes:

  • ruff - Linting and formatting
  • streamlit - Web UI for debugging
  • mkdocs-material - Documentation generation

Running Tests

# Run linting
uv run ruff check .

# Format code
uv run ruff format .

# Run the web UI
uv run streamlit run debug/app.py

Troubleshooting

See the Troubleshooting guide for common installation issues.

Next Steps