mtestv2

Aplicacion de escritorio para capturar, analizar y documentar senales PPG con sensor MAX3010x, lectura de temperatura NTC, firmware Arduino y una interfaz PyQt6 pensada para trabajo de campo.

El proyecto combina adquisicion en tiempo real, configuracion del sensor, analisis de pulso y generacion de informes. Esta preparado para publicarse como portfolio sin incluir resultados experimentales ni datos de medicion.

Que hace

• Captura senales RED/IR desde un MAX3010x conectado por Arduino.
• Registra temperatura NTC junto a cada medicion con termometros A0-A3.
• Permite seleccionar especie/animal: oveja, cabra o vaca.
• En oveja/cabra usa sensores izquierda/derecha; en vaca usa FLT, FRT, RLT y RRT.
• La temperatura final se guarda como el maximo del primer golpe de calor, no como media.
• Permite modos de medicion rapida, test de campo, reajustes, solo temperatura y bloques de configuracion.
• Calcula metricas de calidad, BPM, SpO2 estimada, perfusion, artefactos y saturacion.
• Incluye analisis experimental con Fourier, autocorrelacion e Hilbert para comparar configuraciones.
• Genera CSV, JSON, graficas, capturas y PDFs de informe.
• Estadisticas permite revisar sesiones, marcar raws de varias sesiones y preparar un ZIP en el Escritorio para correo.

Tecnologias

• Python
• PyQt6
• pyqtgraph
• NumPy
• pyserial
• bleak para conexion BLE con Arduino Nano 33 IoT
• sounddevice
• Arduino / C++

Estructura del proyecto

main.py                         # punto de entrada
controller.py                   # controlador de ventanas
requirements.txt                # dependencias Python
ARRANCAR_PPG.cmd                # lanzador principal en Windows
instalarmtestv2.cmd             # instalacion inicial
actualizaciones/                # notas visibles desde la interfaz
arduino/
  ppg_max3010x_firmware/
    ppg_max3010x_firmware.ino   # firmware para Arduino
ppg_suite/
  paths.py                      # rutas, resultados y logging
  utils.py                      # utilidades generales
  models.py                     # dataclasses de configuracion y metricas
  processing.py                 # BPM, FFT, autocorrelacion, SpO2 y artefactos
  widgets.py                    # widgets reutilizables
  menu.py                       # menu inicial
  windows/
    measurement_window.py       # base de campo/test
    real_window.py              # medicion de campo
    test_window.py              # test de campo
    temperature_window.py       # solo temperatura
    reajustes_window.py         # medicion larga y diagnostico
    scheduled_window.py         # configuraciones y experimento 3M
    relations_window.py         # estadisticas y explorador de sesiones
    fourier_window.py           # analisis Fourier + Hilbert

Instalacion de desarrollo

Requisitos:

• Windows
• Python 3
• Git, opcional para actualizacion automatica
• Arduino con el firmware del proyecto cargado

Desde la raiz del repositorio:

instalarmtestv2.cmd

El instalador crea el entorno virtual, instala dependencias y prepara un archivo .env local si no existe.

Ejemplo de .env:

PROJECT_DIR=C:\ruta\a\mtestv2
PYTHON_REL=.venv\Scripts\python.exe
MAIN_FILE=main.py
AUTO_UPDATE_GIT=1
AUTO_UPDATE_TIMEOUT_SEC=15

Arranque

La forma recomendada en Windows es:

ARRANCAR_PPG.cmd

El lanzador:

• Lee la configuracion local desde .env.
• Entra en PROJECT_DIR.
• Intenta actualizar con git pull --ff-only si AUTO_UPDATE_GIT=1. Si no hay internet o Git tarda demasiado, omite la actualizacion y abre la version local.
• Comprueba dependencias.
• Ejecuta main.py.

Tambien se puede lanzar manualmente:

.venv\Scripts\python.exe main.py

Empaquetado Windows

El empaquetado actual no usa una carpeta espejo del proyecto. El instalador se construye desde el codigo real del repositorio y copia solo el resultado generado por PyInstaller.

Primero instala las dependencias de desarrollo en tu entorno:

.venv\Scripts\python.exe -m pip install -r requirements-dev.txt

Para crear la aplicacion empaquetada:

CREAR_INSTALADOR_WINDOWS.cmd

El comando genera:

• dist\MedicionPPG\MedicionPPG.exe: carpeta de aplicacion lista para probar.
• release\MEE_VERSION.zip: copia portable de nombre corto para equipos que bloqueen instaladores o fallen por rutas largas.
• release\MedicionPPG_Setup_VERSION.exe: instalador si Inno Setup 6 esta instalado.

Para publicar una actualizacion:

1. Sube la version en ppg_suite\__init__.py.
2. Ejecuta otra vez CREAR_INSTALADOR_WINDOWS.cmd.
3. Entrega el nuevo release\MedicionPPG_Setup_VERSION.exe.
4. En el ordenador del usuario, abre ese instalador nuevo. Como mantiene el mismo AppId, actualiza el ejecutable instalado y conserva los datos.

El instalador usa siempre el mismo AppId, asi que una version nueva sustituye a la anterior. Los resultados del usuario no se guardan dentro de la carpeta del programa, por lo que una actualizacion normal no borra mediciones ni fichas.

Si al abrir el instalador aparece Error 4551 o un aviso de Control de aplicaciones indicando que no se pudo ejecutar un archivo en la carpeta temporal, el bloqueo lo esta aplicando Windows o una politica del ordenador destino. En ese caso prueba primero release\MEE_VERSION.zip: se descomprime en una carpeta corta, por ejemplo C:\MEE, y se abre MedicionPPG.exe. Si tambien bloquea ese exe, hace falta que el departamento de informatica permita la aplicacion o que se firme el ejecutable/instalador con un certificado de confianza.

En modo instalado, la aplicacion escribe por defecto en:

%LOCALAPPDATA%\TripleM\PPGSuite\resultados

Si hace falta forzar otra carpeta de datos, se puede crear un .env junto al exe instalado, o en %LOCALAPPDATA%\TripleM\PPGSuite\.env, con:

PROJECT_DIR=C:\ruta\a\carpeta_de_datos

El menu inicial incluye IMPORTAR DATOS. Ese boton solo acepta una carpeta llamada exactamente resultados y mezcla su contenido en la carpeta de datos actual. Los archivos ya existentes se omiten para evitar sobrescribir mediciones nuevas.

Modos principales

• Medicion de campo: toma rapida con la interfaz minima.
• Test de campo: captura con notas, parametros y graficas diagnosticas.
• Solo temperatura: registro NTC sin PPG.
• Reajustes: medicion larga con controles completos, diagnostico Arduino y snapshots.
• Configuraciones: ejecucion de bloques de parametros del sensor.
• Experimento 3M: busqueda adaptativa de una configuracion util del sensor con ranking final.
• Estadisticas: explorador de sesiones, raws, procesados, informes, graficas, capturas y preparacion de ZIP para correo.
• Analisis Fourier + Hilbert: comparacion de raws para estudiar que configuracion separa mejor el pulso.

Datos generados

Durante el uso normal desde el repositorio, la aplicacion escribe resultados en:

resultados/

En la version instalada, los resultados se escriben en la carpeta de datos del usuario:

%LOCALAPPDATA%\TripleM\PPGSuite\resultados

Esa carpeta esta ignorada por Git porque puede contener datos experimentales, capturas, informes y archivos pesados. Si se clona el proyecto desde cero, la carpeta se crea durante la ejecucion cuando sea necesaria.

Subcarpetas habituales:

• raw/: datos crudos.
• processed/: datos procesados.
• sessions/: resumenes de sesiones.
• reports/: JSON y tablas derivadas.
• documentos_generados/: informes PDF.
• figures/: graficas.
• screenshots/: capturas.
• configs/: configuraciones aplicadas y animal_profiles.json con configuraciones MAX3010x predefinidas por especie.
• logs/: logs de ejecucion.

Animales, sensores y temperatura

Las pantallas de recogida permiten elegir Oveja, Cabra o Vaca.

• Oveja y cabra usan posiciones RT y LT.
• Vaca usa posiciones FLT, FRT, RLT y RRT.
• Los canales fisicos son siempre A0, A1, A2 y A3.
• Por defecto, oveja/cabra usan A0 derecha / A1 izquierda.
• Por defecto, vaca usa A0 FRT / A1 FLT / A2 RRT / A3 RLT.
• La asignacion puede cambiarse desde la app antes de capturar.
• Oveja, cabra y vaca pueden guardar una configuracion MAX3010x predefinida por especie. El boton aparece bajo el bloque del sensor en las pantallas de toma normal, temperatura y reajustes; en Configuraciones/3M el bloque MAX3010x es solo orientativo porque cambia por fila.
• Si ya existe una configuracion previa para esa especie, la app muestra la configuracion antigua y pide confirmacion antes de sustituirla.
• El boton Mostrar resultados de las pantallas de recogida cierra la ventana actual y abre Estadisticas.
• Las recogidas guardan anotaciones de inicio y anotaciones finales. En Configuraciones/3M, cada cambio de configuracion permite anotar lo ocurrido en el tramo que acaba de terminar.

La temperatura final de sesiones y Estadisticas es el maximo independiente de cada termometro/posicion durante el primer golpe de calor. La app ignora el primer segundo de estabilizacion y busca el maximo en los 5 segundos siguientes; las medias antiguas se mantienen solo como referencia tecnica.

Firmware Arduino

El firmware esta en:

arduino/ppg_max3010x_firmware/ppg_max3010x_firmware.ino

Desde el menu inicial, ACTUALIZAR FIRMWARE usa el firmware incluido en la version actual de la app:

• Si el ordenador tiene arduino-cli, la app detecta puertos USB, permite elegir el Arduino conectado y ejecuta compile + upload para arduino:samd:nano_33_iot.
• Si no encuentra arduino-cli, abre el archivo .ino para cargarlo manualmente desde Arduino IDE.

Para la subida automatica con arduino-cli, el ordenador debe tener instalado el core arduino:samd y las librerias ArduinoBLE y SparkFun MAX3010x Pulse and Proximity Sensor Library.

Configuracion recomendada para Arduino Nano 33 IoT:

• Placa en Arduino IDE: Arduino SAMD Boards -> Arduino Nano 33 IoT.
• Librerias Arduino desde Sketch -> Include Library -> Manage Libraries...:
  • ArduinoBLE by Arduino, necesaria para ArduinoBLE.h y Bluetooth BLE.
  • SparkFun MAX3010x Pulse and Proximity Sensor Library, necesaria para MAX30105.h.
• Conexiones: MAX3010x por I2C en SDA/A4 y SCL/A5.
• Termometros NTC: A0, A1, A2, A3. Cada entrada debe tener divisor 3.3V -> NTC -> Ax -> resistencia fija 10k -> GND.
• Para oveja/cabra basta usar A0/A1. Para vaca se pueden usar los cuatro termometros y asignarlos a FLT/FRT/RLT/RRT.
• ADC de temperatura: 12 bits, ya configurado por defecto en placas SAMD como Nano 33 IoT.
• Bluetooth: el Nano 33 IoT tiene BLE mediante el modulo u-blox NINA-W102. Este firmware activa un servicio BLE mtestv2 Nano33IoT cuando compila como Nano 33 IoT. La app puede conectarse desde el selector de puertos con BLE Nano 33 IoT mtestv2.
• BLE no aparece como puerto COM clasico. La app usa bleak y caracteristicas GATT propias para enviar comandos y recibir lineas. Por limite de ancho de banda BLE, USB Serial sigue siendo la opcion con mas muestras por segundo; por BLE se notifican datos a ritmo limitado para mantener estabilidad.

Formato de datos actual del firmware:

micros,red,ir,tempA0C,tempA0Raw,tempA1C,tempA1Raw,tempA2C,tempA2Raw,tempA3C,tempA3Raw

La app sigue aceptando raws y firmware antiguos con solo A0/A1.

La aplicacion se comunica por serie mediante comandos de texto como:

• STATUS
• REINIT_SENSOR
• CONFIG RED=... IR=... AVG=... RATE=... WIDTH=... ADC=... SKIP=... DEBUG=...
• CONFIG_TEMP VCC=... RFIX=... RN=... BETA=... OFFSET=... ADCBITS=...
• START_CONTINUOUS
• START_TEMP
• STOP
• DIAGNOSTICO

Antes de iniciar una toma, el software verifica que la configuracion confirmada por Arduino coincide con la solicitada.

Notas para publicacion

• .env, entornos virtuales y resultados/ no se versionan.
• El repositorio contiene el codigo, scripts de arranque, firmware y documentacion tecnica.
• Los datos reales de medicion deben mantenerse fuera del historial publico.