MRT Card Reader #

A Flutter package for reading transaction data from Dhaka MRT (Mass Rapid Transit) metro rail cards using NFC. This package allows you to easily access card balance and transaction history.

Features #

• Cross-platform support: Works on both Android and iOS
• Check NFC availability on the device
• Read Dhaka MRT card balance
• Retrieve transaction history (journeys and top-ups)
• Parse transaction details including:
  • Transaction timestamps
  • Origin and destination
  • Journey costs
  • Top-up amounts
  • Current balance
• Typed exception handling for better error management
• Session management with cancellation and timeout support
• Configurable logging for debugging
• Data validation for card responses

Requirements #

• Flutter 3.0.0 or higher
• Android device with NFC capabilities (API level 19+)
• iOS device with NFC capabilities (iOS 13+)

Platform Support #

• Android: Fully supported using NFC-F (FeliCa) protocol via native transceive() API
• iOS: Fully supported using FeliCa readWithoutEncryption() API. The implementation automatically converts between raw commands (Android) and higher-level FeliCa API (iOS), providing seamless cross-platform compatibility with identical transaction data output.

Installation #

Add mrt_card_reader to your pubspec.yaml:

dependencies:
  mrt_card_reader: ^0.1.0

Then run:

flutter pub get

Platform-specific setup #

Android

Add the following permissions to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="true" />

iOS

Add the following to your Info.plist file:

<key>NFCReaderUsageDescription</key>
<string>This app needs access to NFC to read MRT card data.</string>

<key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>TAG</string>
</array>

You also need to enable the "Near Field Communication Tag Reading" capability in your Xcode project:

1. Open your project in Xcode
2. Select your target
3. Go to "Signing & Capabilities" tab
4. Click "+ Capability"
5. Add "Near Field Communication Tag Reading"

Usage #

Basic Example #

import 'package:flutter/material.dart';
import 'package:mrt_card_reader/mrt_card_reader.dart';

class MrtCardReaderDemo extends StatefulWidget {
  const MrtCardReaderDemo({Key? key}) : super(key: key);

  @override
  State<MrtCardReaderDemo> createState() => _MrtCardReaderDemoState();
}

class _MrtCardReaderDemoState extends State<MrtCardReaderDemo> {
  String _status = 'Ready to scan';
  int? _balance;
  List<MrtTransaction> _transactions = [];

  Future<void> _startScan() async {
    // Check if NFC is available
    final isNfcAvailable = await MrtCardReader.isAvailable();
    
    if (!isNfcAvailable) {
      setState(() {
        _status = 'NFC is not available on this device';
      });
      return;
    }

    // Start NFC session to read the card
    await MrtCardReader.startSession(
      onStatus: (status) {
        setState(() {
          _status = status;
        });
      },
      onBalance: (balance) {
        setState(() {
          _balance = balance;
        });
      },
      onTransactions: (transactions) {
        setState(() {
          _transactions = transactions;
        });
      },
      onError: (exception) {
        setState(() {
          _status = 'Error: ${exception.message}';
        });
      },
      timeout: const Duration(seconds: 30),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('MRT Card Reader')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('Status: $_status'),
            if (_balance != null) Text('Balance: \$${_balance! / 100}'),
            ElevatedButton(
              onPressed: _startScan,
              child: const Text('Scan MRT Card'),
            ),
            if (_transactions.isNotEmpty) ...[
              const SizedBox(height: 20),
              const Text('Recent Transactions', 
                style: TextStyle(fontWeight: FontWeight.bold),
              ),
              Expanded(
                child: ListView.builder(
                  itemCount: _transactions.length,
                  itemBuilder: (context, index) {
                    final transaction = _transactions[index];
                    return ListTile(
                      title: Text(transaction.isTopup 
                        ? 'Top-up at ${transaction.fromStation}'
                        : 'Journey from ${transaction.fromStation} to ${transaction.toStation}'),
                      subtitle: Text(transaction.timestamp),
                      trailing: Text(
                        transaction.isTopup
                          ? '+\$${transaction.cost ?? 0 / 100}'
                          : '-\$${transaction.cost ?? 0 / 100}',
                        style: TextStyle(
                          color: transaction.isTopup ? Colors.green : Colors.red,
                        ),
                      ),
                    );
                  },
                ),
              ),
            ],
          ],
        ),
      ),
    );
  }
}

Advanced Usage with Instance API #

For more control, use the instance-based API:

final reader = MrtCardReaderInstance(
  logger: ConsoleLogger(),
  timeout: const Duration(seconds: 60),
);

await reader.startSession(
  onStatus: (status) => print(status),
  onBalance: (balance) => print('Balance: $balance'),
  onTransactions: (transactions) => print(transactions),
  onError: (exception) => print('Error: ${exception.toString()}'),

// Check if session is active
if (reader.isSessionActive) {
  print('Reading in progress...');
}

// Cancel session if needed
await reader.cancelSession();

For a complete example, check out the example directory in the repository.

API Reference #

MrtCardReader #

static Future<bool> isAvailable()

Checks if NFC is available on the device.

Returns true if NFC is available and enabled, false otherwise.

static Future<void> startSession({required Function(String) onStatus, required Function(int?) onBalance, required Function(List<MrtTransaction>) onTransactions, Function(MrtException)? onError, Duration timeout})

Starts an NFC reading session to retrieve MRT card data.

Parameters:

• onStatus: Callback that provides status updates during the reading process.
• onBalance: Callback that provides the current card balance after successful reading (in paisa).
• onTransactions: Callback that provides the list of transactions read from the card.
• onError: Optional callback for typed exceptions (recommended).
• timeout: Optional timeout duration (default: 30 seconds).

MrtTransaction #

Represents a transaction record from an MRT card.

Properties

• fixedHeader: Raw header data from the card's data block.
• timestamp: Timestamp of when the transaction occurred (YYYY-MM-DD HH:MM).
• transactionType: Transaction type in hexadecimal format.
• fromStation: Name of the origin station (or top-up location).
• toStation: Name of the destination station (may be empty for top-ups).
• balance: Card balance after this transaction (in paisa, Taka * 100).
• cost: Cost of the journey or amount topped up (in paisa, null if unknown).
• trailing: Trailing data from the card's data block.
• isTopup: Whether this transaction represents a top-up rather than a journey.

Methods

• copyWith({...}): Creates a copy with updated fields.
• toMap(): Converts to a map for serialization.
• fromMap(Map<String, dynamic>): Factory constructor to create from a map.
• toString(): Returns a string representation.

Exception Types #

The package provides typed exceptions for better error handling:

• MrtException: Base exception class
• NfcNotAvailableException: NFC not available or disabled
• InvalidCardException: Invalid or unsupported card
• DataCorruptionException: Corrupted or unreadable card data
• NfcTimeoutException: Reading operation timed out
• SessionAlreadyActiveException: Session already in progress

Platform-Specific Notes #

Android #

• Uses native NFC-F (FeliCa) transceive() for direct card communication
• Compatible with Android API level 19+

iOS #

• Uses FeliCa readWithoutEncryption() API (iOS 13+)
• Automatically handles platform differences internally
• Same transaction data output as Android
• Requires FeliCa-compatible iPhone (iPhone 7 or later, except iPhone X)

Troubleshooting #

Common Issues #

NFC not available: Ensure NFC is enabled in device settings and the device supports NFC. On iOS, ensure you have a compatible device (iPhone 7 or later).

Card reading timeout: Increase the timeout duration or check card proximity.

Invalid card errors: Ensure you're using a valid Dhaka MRT Line 6 card (FeliCa card).

Data corruption: Card may be damaged or incompatible with the reader.

iOS not reading card: Ensure you have enabled the NFC capability in Xcode and have a FeliCa-compatible iPhone model.

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

This project is licensed under the terms of the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for details.

Acknowledgements #

The core idea and logic for this project were inspired by MRT Buddy, created by Aniruddha Adhikary. Thanks to the team for the original work!