iTartanas - Lector de Tarjeta Millennium

Aplicación Android para leer tarjetas Millennium del sistema de transporte público mediante NFC.

Características

✅ Lectura de número de tarjeta: Obtiene y muestra el número completo de la Tarjeta Millennium
✅ Consulta de saldo: Muestra el saldo actual disponible en la tarjeta
✅ Últimos movimientos: Visualiza los últimos 3 movimientos/transacciones de la tarjeta
✅ Interfaz moderna: Diseño con Material 3 y Jetpack Compose
✅ Detección automática: Lee la tarjeta automáticamente al acercarla al dispositivo

Requisitos

• Dispositivo Android con NFC
• Android 7.0 (API 24) o superior
• NFC activado en el dispositivo

Funcionalidades implementadas

La aplicación implementa las siguientes funcionalidades basadas en el código original de iTranvias:

1. Comunicación NFC con protocolo ISO-DEP

   • Selección de red de transporte
   • Lectura de entorno
   • Lectura de contrato
   • Lectura de registros de eventos (últimos movimientos)

2. Procesamiento de datos

   • Decodificación de números de tarjeta BCD a decimal
   • Conversión de PAN a IEP según aplicación
   • Cálculo de dígito de verificación Luhn
   • Enmascaramiento de datos sensibles
   • Conversión de saldo de céntimos a euros
   • Parseo de registros de eventos con fecha, hora, tipo y ubicación

3. Interfaz de usuario

   • Pantalla de espera con instrucciones
   • Indicador de progreso durante la lectura
   • Visualización de datos: número de tarjeta, saldo y últimos movimientos
   • Lista de movimientos con fecha, hora, tipo de operación e importe
   • Manejo de errores con mensajes descriptivos

Cómo usar

1. Instala la aplicación en tu dispositivo Android
2. Asegúrate de que el NFC esté activado
3. Abre la aplicación iTartanas
4. Acerca tu Tarjeta Millennium al lector NFC del dispositivo
5. La aplicación leerá automáticamente:
   • Número de tarjeta
   • Saldo actual
   • Últimos 3 movimientos (fecha, hora, tipo de operación e importe)

Tecnologías utilizadas

• Kotlin: Lenguaje de programación principal
• Jetpack Compose: Framework de UI moderna
• Material 3: Diseño de interfaz
• Coroutines: Manejo de operaciones asíncronas
• NFC Android API: Comunicación con tarjetas NFC/ISO-DEP

Estructura del proyecto

app/src/main/java/com/pjpmosteiro/itartanas/
├── MainActivity.kt                    # Actividad principal con UI
├── nfc/
│   └── CardRepositoryImpl.kt         # Lógica de lectura NFC y procesamiento
└── ui/theme/                          # Tema de la aplicación

Permisos

La aplicación requiere los siguientes permisos:

• android.permission.NFC: Para acceder al hardware NFC
• android.hardware.nfc: Hardware NFC requerido

Notas técnicas

Protocolo de comunicación

La aplicación utiliza comandos APDU para comunicarse con la tarjeta:

1. SELECT Transport Network (0x80 0x26 0x4F 0x11 0x0A)
2. READ Environment (0x80 0x32 0x00 0x00 0x18)
3. READ Contract (0x80 0x2E 0x01 0x00 0x20)

Formato de datos

• Número de tarjeta: 16 dígitos formateados en grupos de 4
• Saldo: Almacenado en 3 bytes (big-endian) en céntimos, convertido a euros
• Movimientos: Últimos 3 registros de eventos con:
  • Fecha y hora de la operación
  • Tipo de operación (Carga, Validación, etc.)
  • Importe de la operación (si aplica)
  • Ubicación/línea (si está disponible)

Créditos

Basado en el análisis del código decompilado de la aplicación iTranvias original.

Licencia

Este proyecto es de código abierto para fines educativos y de aprendizaje.