mykad-reader-api/README.md

# Smart Card Command Tool - User Guide

**Send Command** is an easy-to-use graphical application for communicating with smart card readers and cards. Whether you need to test APDU commands or send low-level escape commands to your reader hardware, this tool provides a simple interface with automatic connection management.

## What You Can Do

- **Send APDU Commands**: Communicate with smart cards using standard protocols.
- **Send Escape Commands**: Access reader hardware directly for advanced operations.
- **Test Commands**: Verify your smart card applications and reader functionality.
- **Debug Issues**: Get detailed response logging and error information.

## Quick Start

1. **Install Dependencies** (see Installation section below).
2. **Run the Application**: `python Send_Command.py`
3. **Select Your Reader** from the dropdown menu.
4. **Choose Command Type** (APDU or Escape) by entering the command in the respective input field.
5. **Enter Your Command** in hexadecimal format.
6. **Click Send** and view the response in the log area.

## Usage Patterns

### GUI Mode (Interactive)
```bash
# Send APDU and escape commands via unified GUI
python Send_Command.py
```

### CLI Mode (Command Line)
```bash
# Run command-line example demonstrating API usage
python example_cli.py
```

The CLI example (`example_cli.py`) demonstrates:
- Listing available readers
- Sending APDU commands (Get Card UID example)
- Sending escape commands (Get Reader Info example)
- Interactive mode for custom commands

### MyKad Reader (macOS and Windows)
Uses the same PC/SC stack (`API.py` + `pyscard`) to read JPN data from a Malaysian MyKad (name, NRIC, address, photo). Insert the card into the ACR39U contact-side down.

```bash
# GUI
python MyKad_Reader.py

# CLI (prints JSON, writes photo.jpg)
python mykad.py
python mykad.py --list-readers

# Local helper API for Laravel (binds 127.0.0.1 only)
python mykad_api.py
# curl http://127.0.0.1:17321/status
# curl -X POST http://127.0.0.1:17321/read
# open http://127.0.0.1:17321/demo
```

Optional photo preview in the GUI: `pip install pillow`.

## Advanced Usage

For developers who wish to integrate smart card functionality into their own Python applications, please refer to the [API Reference (API_REFERENCE.md)](./API_REFERENCE.md) for detailed programmatic examples and function documentation.


---

## Windows

### Dependencies

For **both applications**:
- Python 3.6+ (from `python.org` or Microsoft Store)
- **tkinter** (included with standard Python from `python.org`)
- **pyscard**
- Windows Smart Card API (built into Windows)

### Installation

From an elevated Command Prompt or PowerShell:

```bash
pip install pyscard
```

If you get a `tkinter` import error, reinstall Python from `python.org` and ensure **“tcl/tk and IDLE”** is selected during setup.

### Usage

```bash
REM Run unified Send Command application
python Send_Command.py
```

---

## macOS

### Dependencies

For **both applications**:
- Python 3.6+ (recommended: from `python.org` or via Homebrew)
- **tkinter** (included with Python from `python.org`; on Homebrew Python you may need `python-tk`)
- **pyscard**
- **PCSC framework** (pre-installed on macOS)

### Installation

Using `pip` for the active Python 3:

```bash
pip install pyscard
```

If you get a `tkinter` import error:
- Install Python from `python.org` **or**
- On Homebrew: `brew install python-tk`

### Usage

```bash
# Run unified Send Command application
python3 Send_Command.py
```

---

## Ubuntu / Linux

### Dependencies

For **both applications**:
- Python 3.6+
- **python3-tk** (system package providing Tkinter)
- **pyscard** (Python package)
- **pcscd** (PC/SC daemon)
- **libpcsclite1** and **libpcsclite-dev** (PC/SC libraries)

### Installation

```bash
sudo apt-get update
sudo apt-get install python3-tk
sudo apt-get install pcscd libpcsclite1 libpcsclite-dev
sudo systemctl start pcscd
sudo systemctl enable pcscd
pip install pyscard
```

### Usage

```bash
# Run unified Send Command application
python3 Send_Command.py
```

---

## Features

### Send_Command.py (GUI Application)
- **Unified GUI Interface**: Single application for both APDU and escape commands
- **Automatic Connection Management**: Connect-send-disconnect flow for each command
- **Dual Command Support**:
  - APDU commands: Communicate with smart cards via standard protocols
  - Escape commands: Direct hardware communication with readers
- **Real-time Response Logging**: Detailed command execution feedback
- **Platform Compatibility**: Cross-platform support (Windows/macOS/Linux)
- **Error Handling**: Comprehensive error reporting and troubleshooting guidance

### example_cli.py (CLI Example)
- **Command-Line Interface**: Demonstrates API usage without GUI dependencies
- **Multiple Examples**: Shows APDU and escape command usage patterns
- **Interactive Mode**: Allows custom command input for testing
- **Educational**: Clear examples for developers learning the API