🔋 Nueva Funcionalidad: Lectura de Batería para Beacons HOLYIOT #

Objetivo: Monitorear nivel de batería de beacons HOLYIOT NRF52810 en ambos modos (Normal e iBeacon)

Agregado

• 🔋 Detección automática de batería desde BLE advertisement data
• 📊 Soporte multi-modo:
  • Modo Normal/Generic BLE: Lee desde serviceData UUID 0x5242 (HOLYIOT)
  • Modo iBeacon: Extrae de manufacturerData bytes 25-27
  • Estándar BLE: Soporte para Battery Service UUID 0x180F
• 🎨 Propiedades del modelo BeaconDevice:
  • batteryLevel: Porcentaje 0-100% (nullable)
  • batteryLastRead: Timestamp de última lectura
  • hasBatteryInfo: Getter booleano
  • isBatteryLow: Alerta < 20%
  • isBatteryCritical: Alerta crítica < 10%
  • batteryIcon: Emoji visual 🔋/🪫
  • batteryColor: Color string ('green', 'orange', 'red')
• ⚙️ Parser automático integrado en scanner sin configuración adicional
• 📱 Demo app actualizada con UI de batería y alertas visuales

Compatibilidad

• ✅ 100% compatible con v1.0.1 - sin breaking changes
• ✅ Backward compatible: beacons sin batería siguen funcionando normalmente
• ✅ Detección automática: no requiere configuración manual
• ✅ Performance: parsing optimizado sin impacto en velocidad de escaneo

Formato de Datos Soportados

// HOLYIOT Modo Normal (serviceData UUID 0x5242)
// 13 bytes, batería en byte[1]
Ejemplo: 41 63 ce 07 42 82 e8 59 03 02 06 00 00
         ↑  ↑
         |  batería = 0x63 = 99%

// HOLYIOT Modo iBeacon (manufacturerData)
// 29 bytes, batería en bytes 25-27
Ejemplo: 06 00 01 09 20 ... [25] [26] [27]
                            ↑    ↑    ↑
                            batería (prioridad: 25→26→27)

Ejemplo de Uso

scanner.detectedDevices.listen((devices) {
  for (var device in devices) {
    if (device.hasBatteryInfo) {
      print('${device.name}: ${device.batteryLevel}% ${device.batteryIcon}');
      
      if (device.isBatteryCritical) {
        print('⚠️ CRÍTICO: Reemplazar batería inmediatamente');
      } else if (device.isBatteryLow) {
        print('⚡ Batería baja - programar reemplazo');
      }
    }
  }
});

Documentación Mejorada 📚 #

Objetivo: Hacer el SDK 10x más fácil de usar para desarrolladores externos

Agregado

• 📊 Tabla comparativa completa de los 4 presets con casos de uso y trade-offs
• 🎯 Guía de decisión para elegir el preset correcto según necesidades
• 📡 Documentación detallada de los 3 streams principales:
  • beaconEvents: Cuándo usar para acciones inmediatas
  • detectedDevices: Cuándo usar para UI de listas
  • status: Cuándo usar para indicadores de estado
• 📋 Ejemplo completo funcional con los 3 streams integrados (200+ líneas)
• 🎯 Guía de BeaconRegistry: Cuándo usar y cuándo NO usar
• ✅ Sección de Best Practices con 8 errores comunes y soluciones
• 🚫 DO/DON'T checklist clara y accionable
• 📱 Checklist de producción con 12 puntos de verificación
• 🧪 Ejemplo de testing en dispositivos reales

Mejorado

• README ahora permite a desarrollador entender en 30 segundos si el SDK sirve
• Ejemplos copy-paste listos que funcionan inmediatamente
• Explicación clara de trade-offs entre velocidad y batería
• Documentación práctica para evitar memory leaks, permisos, config incorrecta

Casos de Uso Documentados

• ✅ Control de acceso con código completo
• ✅ Sistema de asistencia con eventos entrada/salida
• ✅ Ejemplo multi-stream con Widget completo
• ✅ Testing en dispositivos reales

Sin Cambios en Código #

• ⚠️ Esta versión es solo documentación - no hay cambios en la API
• ✅ 100% compatible con v1.0.0
• ✅ No requiere cambios en código existente

Agregado #

• ⚡ Detección ultra-rápida: Configuraciones optimizadas desde 100ms hasta 5s
• 🎯 6 nuevos parámetros de optimización:
  • scanMode: Control del modo BLE (opportunistic, lowPower, balanced, lowLatency)
  • prioritizeRegisteredBeacons: Procesa beacons conocidos inmediatamente
  • immediateEventEmission: Emite eventos sin delay
  • enableParsingCache: Cache de parsing para reducir CPU 70%
  • minUpdateInterval: Control de frecuencia por dispositivo
  • streamThrottle: Actualización de UI independiente de detección
• 🏢 4 configuraciones preconfiguradas:
  • BeaconConfig.ultraFast(): 100-300ms para control de acceso crítico
  • BeaconConfig.accessControl(): 500ms balanceado para uso general
  • BeaconConfig.enterprise(): Optimizado para 100+ beacons con cache
  • BeaconConfig.batterySaver(): Mínimo consumo para apps de larga duración
• 📊 Separación de detección y UI: Detección inmediata con stream throttling
• 💾 Sistema de cache: Reduce procesamiento CPU en sistemas grandes
• 🎯 Priorización inteligente: Beacons registrados procesados primero
• 📚 Documentación completa:
  • Guía de configuraciones avanzadas
  • Ejemplos por caso de uso
  • Comparativas de rendimiento

Mejorado #

• ⚡ Velocidad de detección: De 1-2s a 100-300ms en modo ultraFast
• 🏢 Escalabilidad: Soporte eficiente para 100+ beacons simultáneos
• 🔋 Eficiencia energética: Modo batterySaver con consumo mínimo
• 🎨 Flexibilidad: Control total sobre todos los parámetros

Optimizado #

• Cache de parsing para reducir uso de CPU
• Priorización de beacons registrados para respuesta inmediata
• Throttling independiente entre detección y actualización de UI
• Procesamiento por lotes para sistemas grandes

Características Principales #

• Detección universal de beacons BLE (iBeacon, Eddystone, formatos personalizados)
• Sistema de registro y gestión de beacons
• Configuraciones predefinidas para diferentes casos de uso empresariales
• Streams de eventos en tiempo real para entrada/salida de rango
• Cálculo preciso de distancia basado en RSSI
• Sistema de logging configurable
• Persistencia de configuraciones con SharedPreferences
• Soporte completo para Android e iOS
• Manejo robusto de permisos BLE
• API simple y bien documentada

Características Principales #

• UniversalBeaconScanner: Clase principal para escaneo de beacons
• BeaconRegistry: Sistema de gestión de beacons registrados
• BeaconConfiguration: Configuraciones flexibles para diferentes casos de uso
• BeaconLogger: Sistema de logging avanzado
• UniversalBeaconDevice: Modelo completo de datos de beacon
• BeaconEvent: Sistema de eventos tipados

Casos de Uso Soportados #

• Control de acceso empresarial
• Sistemas de asistencia y presencia
• Marketing de proximidad
• Automatización IoT
• Tracking de assets
• Aplicaciones de salud y monitoreo

Arquitectura #

• Patrón Singleton para gestión eficiente de recursos
• StreamControllers para comunicación reactiva
• Manejo robusto de ciclo de vida y disposición de recursos
• Arquitectura escalable para implementaciones empresariales

Dependencias #

• flutter_reactive_ble: ^5.3.1
• permission_handler: ^11.4.0
• shared_preferences: ^2.2.3
• uuid: ^4.4.2

Compatibilidad #

• SDK de Dart: >=3.0.0 <4.0.0
• Flutter: >=3.10.0
• Android: API 21+ (Android 5.0+)
• iOS: 10.0+