AR-VMS-Seaman/VMS_Sailor_v2_Parte_04_Hardware_Firmware.md

VMS-Sailor · Brief para Claude Code · Parte 4 de 6

Hardware AR-NMEA-IO-v1.0 + Firmware ESP32

Esta parte detalla la tarjeta de I/O y su firmware. Asume que ya leíste Partes 1-3.

---

1. Descripción física de la tarjeta

La tarjeta AR-NMEA-IO-v1.0 es hardware diseñado por Álvaro, una sola SKU física que se replica idénticamente para todos los proyectos. Lo que varía entre proyectos es la configuración descargada desde el VMS, no el hardware.

Capacidades fijas

Recurso	Cantidad	Detalle
Salidas digitales (DO)	10	MOSFET IRLML6344TRPBF, opto PC817, diodo flyback SS14, 30V/5A
Entradas digitales (DI)	5	Optoacopladas PC817, contacto o 24VDC, resistencia limitadora 4.7kΩ
Entrada frecuencia (RPM)	1	Optoacoplada, pickup magnético / tacómetro / inductivo
Entradas analógicas (AI)	4	Con divisores y filtros V3061, ADC del ESP32 (12 bits + oversampling)
Microcontrolador	1	ESP32-DOWD (módulo ESP32 DevKit china)
Bus serie	RS485	Transceiver SN65HVD1781 (TI), ESD ±16kV, conector RJ45
Bus CAN	NMEA 2000	Transceiver MCP2562T-E_MF (Microchip), ESD SP0502, conector estándar
WiFi	Integrado	Del ESP32, usado para OTA y MQTT opcional
USB	1	Para programación inicial (CH340 o CP2102 del DevKit)
Alimentación	12 VDC	Conector Phoenix de 2 vías, TVS SMET24A, ferrita B2U-1000P
Reguladores	2× MP2338	Bucks 12V→5V y 5V→3.3V

Aislamiento galvánico: TODOS los I/O (DI, DO, RPM) están aislados con optoacopladores PC817. Un fallo eléctrico en un sensor o actuador NO daña el ESP32.

Total: 21 puntos I/O por tarjeta.

GPIOs del ESP32 usados

(Información extraída del esquemático real que me pasó Álvaro:)

• DO: GPIO15, GPIO5, GPIO17, GPIO16 (cuidado: este es Rx2), GPIO18, GPIO22, GPIO25, GPIO26, GPIO27, GPIO34 (cuidado: solo entrada normalmente)
• DI: GPIO13, GPIO2, GPIO0, GPIO4, GPIO14 (algunos son boot-strap)
• AI: GPIO33 (BAT), GPIO34 (SPARE2), GPIO32 (WATER), GPIO35 (OILP)
• RPM: GPIO15 o similar (verificar en esquemático)
• RS485: GPIO04 (DE/RE), pines TX/RX UART
• CAN: GPIO21 (TX), GPIO23 (RX), GPIO22 (STBY)

Nota para Claude Code: Los pines exactos los verificaremos en el firmware. Algunos GPIO del ESP32 tienen restricciones (strapping, solo entrada, conflictos con boot). El firmware debe respetar las asignaciones reales del schematic.

---

2. Filosofía del firmware

Universal y autoconfigurable

Una sola SKU física = un solo firmware base = una sola variante de tarjeta.

La tarjeta sale de fábrica con firmware idéntico. Su rol y configuración se descargan del VMS al conectarse al bus. Patrón "plug-and-produce" estándar industrial moderno (similar a Beckhoff EtherCAT, Wago I/O System).

Lo que NO se programa por hardware

• Qué hace cada DO (eso lo decide el VMS)
• Qué lee cada DI (eso lo decide el VMS)
• Qué tipo de sensor entra en cada AI (eso lo decide el VMS, dentro de los rangos físicos que el divisor permite)
• Dirección Modbus de la tarjeta (la asigna el VMS, junto con confirmación del dipswitch físico)
• Filtros, alarmas locales, permissives locales (todo desde el VMS)

Lo que SÍ va fijo en el firmware

• Pinout: qué GPIO corresponde a qué función (DO1=GPIO15, AI1=GPIO33, etc.)
• Stack de protocolos: Modbus RTU, NMEA 2000, J1939, MQTT (siempre disponibles, se activan según config)
• Stack de WiFi y OTA
• Boot sequence con discovery broadcast
• Cliente OTA seguro
• Watchdog y recuperación ante fallos
• Buffer offline (60s en flash)

---

3. Estructura del firmware

firmware/ar_nmea_io_v1/
├── platformio.ini                   # PlatformIO o ESP-IDF
├── README.md
├── src/
│   ├── main.cpp                     # Entry point + boot sequence
│   ├── config/
│   │   ├── pinout.h                 # Definición física de GPIOs
│   │   ├── card_identity.cpp        # Serial + HWID de cada tarjeta
│   │   ├── dipswitch_reader.cpp     # Lee dipswitches físicos
│   │   └── runtime_config.cpp       # Aplica config descargada del VMS
│   │
│   ├── channels/                    # Manejo de los 21 puntos I/O
│   │   ├── do_handler.cpp           # 10 DO
│   │   ├── di_handler.cpp           # 5 DI
│   │   ├── rpm_handler.cpp          # 1 entrada frecuencia
│   │   └── ai_handler.cpp           # 4 AI con oversampling
│   │
│   ├── filters/                     # Procesamiento local
│   │   ├── moving_average.cpp
│   │   ├── median.cpp
│   │   ├── deadband.cpp
│   │   └── rate_limit.cpp
│   │
│   ├── protocols/
│   │   ├── modbus_slave.cpp         # Modbus RTU esclava
│   │   ├── modbus_master.cpp        # Modbus RTU maestra (si así se configura)
│   │   ├── nmea2000_node.cpp        # Publica y suscribe PGNs
│   │   ├── j1939_listener.cpp       # Escucha J1939 (motores)
│   │   ├── mqtt_client.cpp          # MQTT WiFi (opcional)
│   │   └── discovery.cpp            # Discovery broadcast al arrancar
│   │
│   ├── local_logic/                 # Lógica local en la tarjeta
│   │   ├── local_alarms.cpp         # Alarmas locales con umbrales
│   │   ├── local_permissives.cpp    # Permissives locales críticos (E-stop)
│   │   └── safety_outputs.cpp       # Salidas de seguridad (cortar relé si E-stop)
│   │
│   ├── storage/
│   │   ├── nvs_config.cpp           # Configuración en NVS (flash)
│   │   └── offline_buffer.cpp       # Buffer 60s en flash si bus cae
│   │
│   ├── system/
│   │   ├── watchdog.cpp
│   │   ├── ota_client.cpp           # Cliente OTA seguro
│   │   ├── health_reporter.cpp      # Reporta estado al maestro
│   │   └── reboot_handler.cpp
│   │
│   └── utils/
│       ├── crc.cpp
│       ├── logger.cpp
│       └── time_sync.cpp
│
├── common/                          # Librerías compartidas con futuros firmwares
│   ├── modbus_lib/
│   ├── nmea2000_lib/
│   └── ota_lib/
│
└── test/                            # Tests del firmware (PlatformIO test framework)
    ├── test_pinout.cpp
    ├── test_modbus.cpp
    ├── test_filters.cpp
    └── test_discovery.cpp

---

4. Boot sequence (plug-and-produce)

Cuando la tarjeta arranca por primera vez (o después de un reset):

Paso 1 — Identidad

• Lee su serial number del NVS (asignado en fábrica)
• Lee los dipswitches físicos para obtener su "slot number" en el bus (1-16)
• Lee firmware version

Paso 2 — Inicialización de hardware

• Inicializa GPIOs según pinout.h
• Pone todos los DO en estado seguro (apagados)
• Inicializa transceivers RS485 y CAN
• Inicializa ADC para AI
• Inicia WiFi en modo cliente (si hay credenciales guardadas) o AP (si no)

Paso 3 — Discovery broadcast

Por RS485 envía un mensaje broadcast Modbus:

[broadcast addr 0]
function: 65 (custom)
payload: {
  serial: "ARC-2026-00153",
  hw_version: "1.0",
  fw_version: "1.4.2",
  dipswitch_slot: 5,
  capabilities: { do:10, di:5, rpm:1, ai:4 }
}

Paso 4 — Espera config del maestro

• Si el maestro (VMS) responde con CONFIG_PUSH → aplica la configuración recibida
• Si no responde en 10s → modo "huérfana": espera silencio, reintenta cada 30s

Paso 5 — Config aplicada

La configuración recibida incluye:

• Su rol: ESCLAVA con dirección Modbus N
• Modo de bus: solo Modbus, solo NMEA 2000, dual, o bridge
• Asignación de cada uno de los 21 puntos a un tag específico (con su escalado, tipo de señal, filtros)
• Permissives locales (lista de condiciones if-then críticas)
• Alarmas locales (umbrales que dispararán acciones locales sin esperar al VMS)
• Frecuencia de reporte
• Configuración WiFi para OTA y MQTT (opcional)

La guarda en NVS para persistencia.

Paso 6 — Modo operativo

A partir de aquí, ciclo principal:

• Lee canales según frecuencia configurada
• Aplica filtros locales
• Evalúa alarmas locales y permissives locales
• Responde a queries Modbus del maestro
• Publica PGNs NMEA 2000 si está habilitado
• Envía health beacon cada 60s

---

5. Modos de operación de bus

Configurable por software desde el VMS:

Modo "Modbus solo"

• Solo RS485 activo, CAN apagado
• Esclava Modbus con dirección N
• Útil para tarjetas en sistemas auxiliares (tanques, FiFi, A/A, luces)

Modo "NMEA 2000 solo"

• Solo CAN activo, RS485 apagado (o solo escucha)
• Publica PGNs estándar al backbone
• Útil cuando la tarjeta es de un sistema que se quiere exponer al ecosistema marino (motor, genset)

Modo "Dual" (recomendado para motores y gensets)

• RS485 + CAN ambos activos
• Reporta al VMS por Modbus para control fino
• Publica al backbone NMEA 2000 para que plotters Garmin/Raymarine vean datos del motor
• Doble alcance, mismo dato

Modo "Bridge"

• Escucha CAN/NMEA 2000 y traduce a Modbus
• Útil para tener un equipo que solo habla NMEA 2000 (ej: sensor de viento Airmar) y que el VMS pueda leerlo

---

6. PGNs NMEA 2000 que publica la tarjeta

Cuando una tarjeta está configurada en modo NMEA 2000 (típicamente motores y gensets):

PGN	Nombre	Datos publicados
127488	Engine Parameters Rapid	RPM, boost pressure, trim
127489	Engine Parameters Dynamic	Presión aceite, temp aceite, temp refrigerante, voltaje alternador, % carga, horas
127493	Transmission Parameters	Presión aceite caja, temperatura
127505	Fluid Level	Tanques combustible/agua/aceite (si la tarjeta es de tanques)
127508	Battery Status	Voltaje, corriente, temp batería
127257	Attitude	(consume del backbone, no publica — viene del AR-ECDIS)

Esto le da al cliente un beneficio gratis: el plotter del puente muestra automáticamente datos del motor sin configuración extra.

---

7. Procesamiento local en la tarjeta

Esto es lo que diferencia tu sistema de tarjetas Modbus pasivas:

Filtros locales

Configurables por canal desde el VMS:

• Moving average: promedia últimas N muestras
• Median: filtra spikes (excelente para señales con ruido EMI)
• Deadband: solo reporta si el cambio supera X
• Rate limit: rechaza cambios bruscos (anti-glitch)

Beneficio: reduce tráfico Modbus 10× típicamente, y mejora calidad de la señal.

Alarmas locales

La tarjeta tiene umbrales propios y puede activar una salida si una entrada se sale de rango, sin esperar al VMS. Ejemplo:

IF AI1 (temp aceite) > 110°C
THEN DO1 (relé alarma local) = ON
AND envía mensaje urgente al VMS por Modbus

Tiempo de reacción: <50ms (vs 200-500ms si pasa por el VMS).

Permissives locales críticos

Cuando un permissive es de seguridad funcional (E-stop, sobre-velocidad), se ejecuta LOCAL en la tarjeta:

IF DI2 (pulsador E-stop) == ACTIVO
THEN DO1 (relé arranque motor) = OFF inmediato
AND DO2 (parada emergencia) = ON
AND envía evento al VMS

Esto cumple con SIL (Safety Integrity Level) básico — el corte no depende de que el bus esté disponible.

---

8. OTA (Over-The-Air firmware update)

El ESP32 soporta OTA nativo y maduro. Stack del firmware:

Flujo OTA

1. Álvaro publica nueva versión de firmware en el Studio (ej: 1.5.0)
2. Al generar el .vmspack o .vmsdelta, incluye el .bin
3. El Runtime, vía VPN o presencial, recibe el paquete
4. El Admin del buque aprueba la actualización
5. El Runtime envía el .bin a cada tarjeta vía Modbus o WiFi
6. La tarjeta:
   • Verifica firma criptográfica del firmware (clave pública de Álvaro embebida)
   • Verifica que la versión es compatible
   • Guarda en partición OTA
   • Reinicia
   • Si arranca OK → confirma al VMS
   • Si falla → rollback automático a la partición anterior

Seguridad OTA

• Firma RSA-2048 o Ed25519 del firmware
• Verificación obligatoria antes de aplicar
• Sin firma válida = rechazado
• Rollback automático si nuevo firmware no responde en 60s

Tiempo de actualización

• Por Modbus RTU a 115200 baud: ~2 min por tarjeta de 500KB
• Por WiFi: ~10 segundos
• Para 7 tarjetas, total ~5-15 minutos

---

9. Comunicación tarjeta ↔ VMS

Mensajes Modbus custom (function codes propietarios)

Además del Modbus estándar (read holding, write coils, etc.), agregamos function codes custom para gestión:

FC	Nombre	Propósito
65	DISCOVERY_BROADCAST	Tarjeta anuncia presencia
66	CONFIG_PUSH	VMS empuja configuración
67	CONFIG_ACK	Tarjeta confirma config aplicada
68	HEALTH_BEACON	Tarjeta reporta su salud cada 60s
69	OTA_BEGIN	Inicia transferencia firmware
70	OTA_CHUNK	Bloque de firmware
71	OTA_END	Finalizar y reiniciar
72	LOCAL_ALARM_EVENT	Tarjeta notifica alarma local
73	LOCAL_PERMISSIVE_TRIGGERED	Tarjeta notifica permissive ejecutado

---

10. Identificación de tarjetas (reemplazo de tarjeta dañada)

Combinación A+C (decisión Álvaro):

Dipswitches físicos

Cada tarjeta tiene 4-5 dipswitches que el técnico setea al instalarla. Indican el "slot number" en el bus (1-16). La tarjeta envía este número en su discovery.

Confirmación en pantalla del Runtime

Cuando se conecta una tarjeta nueva (slot que estaba vacío o slot que estaba con otra tarjeta serial), el Runtime alerta:

Nueva tarjeta detectada:
  Serial: ARC-2026-00187
  Slot dipswitch: 5
  Reemplaza a: ARC-2026-00153 (Motor PORT) [confirmado por Álvaro o Técnico]
  
  [Aceptar y reasignar rol] [Rechazar - no esperaba esta tarjeta]

Si los dipswitches no coinciden con lo esperado, alarma: "Tarjeta con dipswitch 7 conectada en slot 5 - corregir dipswitch o reasignar en Studio".

---

11. Sprints relacionados con firmware

• Sprint 0 (parte): definición de pinout.h y estructura básica del firmware
• Sprint 12: firmware completo Modbus RTU esclava + discovery + config push + filtros locales
• Sprint 13: NMEA 2000 publishing + J1939 listening
• Sprint 14: OTA + health reporter + permissives locales + alarmas locales
• Sprint 15: pruebas de stress, watchdog, recovery

Nota: El firmware ES parte del proyecto VMS-Sailor (mismo repositorio, mismo control de versiones). Va junto con el resto.

---

12. Stack tecnológico del firmware

Componente	Tecnología
Framework	PlatformIO + Arduino framework O ESP-IDF (a decidir en Sprint 12)
Lenguaje	C++
Modbus RTU	eModbus o ArduinoModbus
NMEA 2000	NMEA2000_esp32 library
J1939	librería específica
OTA	ArduinoOTA o esp_ota de ESP-IDF
MQTT	PubSubClient o AsyncMqttClient
Filesystem (NVS)	nativo ESP32
Tests	Unity + PlatformIO test runner

---

Fin de Parte 4 de 6. Próxima: Parte 5 — VMS-Sailor Mobile (Flutter).