MaselliSimulatorApp/.doc/README.md

# Maselli Protocol Simulator/Tracer/NetCom Gateway

## Descripción General

Aplicación de escritorio basada en Python para simular, monitorear y hacer bridge de dispositivos que utilizan el protocolo ADAM/Maselli. La aplicación soporta comunicación Serial (RS485/RS232), TCP y UDP, proporcionando una interfaz gráfica intuitiva construida con Tkinter.

## Características Principales

### 1. **Modo Simulador**
- Emula un dispositivo Maselli enviando paquetes de datos en protocolo ADAM
- Patrones de generación de datos:
  - **Lineal**: Onda triangular entre valores mínimo y máximo
  - **Sinusoidal**: Onda sinusoidal suave
  - **Manual**: Envío de valores individuales mediante slider o entrada directa
- **Tiempo de ciclo configurable**: Define el tiempo total para completar un ciclo de simulación
- Muestras por ciclo ajustables para control fino de la resolución
- Visualización en tiempo real de valores Brix y mA
- Gráfico dual con ejes Y independientes para Brix (azul) y mA (rojo)

### 2. **Modo Trace**
- Escucha y registra datos entrantes de dispositivos Maselli reales
- Parseo automático de mensajes del protocolo ADAM
- Conversión mA ↔ Brix basada en mapeo configurable
- Registro de datos en archivo CSV con campos:
  - Timestamp
  - Dirección ADAM
  - Valor mA
  - Valor Brix calculado
  - Validez del checksum
  - Mensaje raw
- **Gráfico mejorado**: Muestra tanto Brix como mA en tiempo real
- Estadísticas de mensajes recibidos y errores de checksum

### 3. **Modo NetCom (Gateway)**
- Actúa como puente transparente entre:
  - Un puerto COM físico (configurable)
  - Una conexión de red (TCP/UDP usando la configuración compartida)
- **Función Sniffer**: 
  - Log detallado de todo el tráfico en ambas direcciones
  - Identificación visual de la dirección del tráfico (COM→NET, NET→COM)
  - Parseo opcional de mensajes ADAM para mostrar valores interpretados
- Filtros de visualización configurables
- Estadísticas de transferencias y errores

## Estructura Modular

```
MaselliSimulatorApp/
├── main.py                 # Punto de entrada
├── maselli_app.py         # Aplicación principal y GUI
├── protocol_handler.py    # Manejo del protocolo ADAM
├── connection_manager.py  # Gestión de conexiones
├── config_manager.py      # Gestión de configuración
├── utils.py              # Utilidades comunes
└── tabs/
    ├── __init__.py
    ├── simulator_tab.py   # Lógica del simulador
    ├── trace_tab.py       # Lógica del trace
    └── netcom_tab.py      # Lógica del gateway
```

## Protocolo ADAM

Formato de mensaje:
```
#AA[valor_mA][checksum]\r
```
- `#`: Carácter inicial (opcional en respuestas)
- `AA`: Dirección del dispositivo (2 caracteres)
- `valor_mA`: Valor en mA (6 caracteres, formato XX.XXX)
- `checksum`: Suma de verificación (2 caracteres hex)
- `\r`: Carácter de fin

## Requisitos

- Python 3.7+
- Bibliotecas requeridas:
  ```bash
  pip install pyserial matplotlib tkinter
  ```

## Instalación y Uso

1. Clonar o descargar el proyecto
2. Instalar dependencias:
   ```bash
   pip install -r requirements.txt
   ```
3. Ejecutar la aplicación:
   ```bash
   python main.py
   ```

## Configuración

### Parámetros de Conexión
- **Serial**: Puerto COM y velocidad de baudios
- **TCP/UDP**: Dirección IP y puerto

### Mapeo Brix ↔ mA
- **Min Brix [4mA]**: Valor Brix correspondiente a 4mA
- **Max Brix [20mA]**: Valor Brix correspondiente a 20mA
- Interpolación lineal para valores intermedios

### Configuración del Simulador
- **Dirección ADAM**: 2 caracteres (ej: "01")
- **Tiempo de ciclo**: Duración total de un ciclo completo de simulación
- **Muestras/ciclo**: Número de puntos por ciclo (resolución)

### Configuración NetCom
- **Puerto COM físico**: Puerto para el dispositivo real
- **Baud Rate**: Velocidad del puerto COM físico

## Archivos Generados

- `maselli_simulator_config.json`: Configuración guardada
- `maselli_trace_YYYYMMDD_HHMMSS.csv`: Datos capturados en modo Trace

## Iconos

La aplicación buscará automáticamente archivos de icono en el directorio raíz:
- `icon.png` (recomendado)
- `icon.ico` (Windows)
- `icon.gif`

## Uso Típico

### Como Simulador
1. Configurar tipo de conexión y parámetros
2. Seleccionar función de simulación (Lineal/Sinusoidal)
3. Ajustar tiempo de ciclo según necesidad
4. Iniciar simulación

### Como Monitor (Trace)
1. Configurar conexión según el dispositivo a monitorear
2. Iniciar Trace
3. Los datos se mostrarán en tiempo real y se guardarán en CSV

### Como Gateway (NetCom)
1. Configurar puerto COM del dispositivo físico
2. Configurar conexión de red destino
3. Iniciar Gateway
4. Monitorear el tráfico bidireccional en el log

## Notas de Desarrollo

- La aplicación usa threading para operaciones de comunicación sin bloquear la GUI
- Los gráficos se actualizan mediante matplotlib animation
- El protocolo ADAM es parseado con validación de checksum opcional
- Todos los módulos están diseñados para ser reutilizables

## Mejoras Respecto a la Versión Original

1. **Arquitectura modular**: Código dividido en módulos especializados
2. **Tiempo de ciclo configurable**: Control más intuitivo de la velocidad de simulación
3. **Gráfico de Trace mejorado**: Visualización dual de Brix y mA
4. **Modo NetCom**: Nueva funcionalidad de gateway/bridge con sniffer integrado
5. **Mejor manejo de errores**: Validación robusta y recuperación de errores
6. **Estadísticas detalladas**: Contadores de mensajes, errores y transferencias

## Licencia

Este proyecto es de código abierto. Úselo bajo su propia responsabilidad.

## Autor

Desarrollado para monitoreo y simulación de dispositivos Maselli con protocolo ADAM.