Initial version -- added millennium read funcionality

2026-03-09 22:05:28 +01:00
commit 77c2ded482
2770 changed files with 141927 additions and 0 deletions
@@ -0,0 +1,95 @@
+# 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  
+✅ **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
+
+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
+
+3. **Interfaz de usuario**
+   - Pantalla de espera con instrucciones
+   - Indicador de progreso durante la lectura
+   - Visualización de datos: número de tarjeta y saldo
+   - 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 el número de tarjeta y el saldo
+
+## 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
+
+## 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.
+