# Fase 0 — Acotación y restricciones del proyecto

> **Documento de cierre de la fase de acotación.** Recoge las decisiones tomadas antes del análisis técnico. Funciona como contrato implícito entre las partes y como contexto inicial recuperable en futuras sesiones de trabajo.

**Fecha de cierre:** 14 de mayo de 2026
**Plazo de proyecto:** ~3 meses (Opción 3, producto completo)
**Fase siguiente:** Fase 1 — Análisis de fuentes (KiCad → STM32 → Atmel → WPF)

---

## 1. Objetivo del proyecto

Sustituir el actual sistema de control basado en PLC Panasonic FP por un **sistema distribuido de control climático y de riego** para naves de cultivo de champiñón. Cada sala dispone de su propia **Daughter Board (DB)** con STM32H7S3L8 que actúa como cerebro autónomo. Las DBs cooperan en red mediante MQTT y se supervisan desde una **app cliente multiplataforma** o desde la **web embebida** de cualquiera de ellas.

### 1.1. Escala de despliegue

| Métrica | Valor |
|---|---|
| **Instalación inicial objetivo** | **12 salas → 12 DBs** |
| **Escalabilidad de diseño** | Hasta **60–100 DBs por instalación** sin reescritura |
| **Disposición física** | Cada DB junto a la UTA de su sala, repartidas por la nave |
| **Cableado de red** | Ethernet conmutado (asumido) |

> **Implicación:** el firmware debe diseñarse desde el día 1 como nodo de una flota, no como dispositivo aislado. Cualquier feature que no escale a 100 nodos se descarta.

### 1.2. Cambio de paradigma respecto al sistema actual

| Aspecto | Sistema actual (PLC) | Sistema objetivo |
|---|---|---|
| Cerebro | PLC Panasonic FP, 1 por instalación | DB STM32 H7S3L8, 1 por sala |
| Topología | Centralizada | Distribuida (peer-to-peer + broker MQTT) |
| HMI | Pantalla táctil Panasonic GT | Web embebida + app cliente Flutter |
| Comunicaciones del cerebro | Modbus RTU maestro/esclavo | Ethernet (MQTT, REST, WebSocket) + 5× RS485 + BLE + CAN |
| Maestros Modbus a sensores | El PLC para todas las salas | Cada DB para su sala |
| Riego | Programa básico en el PLC | Aplicación avanzada portada desde firmware Atmel existente |
| Persistencia | RETAIN del PLC | OctoSPI Flash (config) + SD (histórico) |
| Servicio en campo | Pantalla local | App móvil BLE + web local |
| Histórico de proceso | No | Sí, en SD por sala, accesible vía API |

---

## 2. Hardware base

| Componente | Especificación |
|---|---|
| **MCU** | STM32H7S3L8 sobre placa Nucleo |
| **Forma** | Daughter Board (DB) que monta sobre la Nucleo |
| **Flash externa** | OctoSPI (capacidad por confirmar al ver KiCad) |
| **Almacenamiento masivo** | Tarjeta SD (para histórico y logs) |
| **Red cableada** | Ethernet |
| **Red inalámbrica** | Bluetooth Low Energy (BLE) |
| **Puertos serie** | 5 × RS485 |
| **Bus CAN** | 1 × CAN |
| **Entradas/salidas analógicas y digitales** | Conector dedicado para control clásico del ventilador (E/S analógicas + digitales) y otros actuadores |
| **Otros periféricos** | A determinar al revisar esquemático |

### 2.1. Asignación de puertos serie

| Puerto | Rol | Dispositivo | Función |
|---|---|---|---|
| **1** | Esclavo Modbus RTU | (Maestro externo opcional) | Compatibilidad legacy. Apagado por defecto |
| **2** | Maestro Modbus RTU | **Variador del plug fan de la UTA** (opcional) | Integración avanzada del ventilador si el variador es comunicable. Ver sección 5.4 |
| **3** | Maestro Modbus RTU | **Caja paramétrica interior nº 1** | 2 dispositivos E+E: HR+T + CO₂, direcciones Modbus distintas |
| **4** | Maestro Modbus RTU | **Caja paramétrica interior nº 2** | 2 dispositivos E+E: HR+T + CO₂, direcciones Modbus distintas |
| **5** | Maestro Modbus RTU | **Caja paramétrica exterior** (solo 1 DB de la instalación) | 2 dispositivos E+E: HR+T + CO₂ exterior. La DB con sensor exterior publica el dato por MQTT a las demás |

#### Estructura interna de las cajas paramétricas E+E

Cada caja paramétrica contiene **2 dispositivos Modbus** colgados del mismo bus RS485:

| Dispositivo | Función | Dirección Modbus |
|---|---|---|
| Sensor E+E HR+T | Humedad relativa + temperatura | Una dirección |
| Sensor E+E CO₂ | Concentración de CO₂ | Otra dirección |

El driver de caja paramétrica gestionará ambos dispositivos como un agregado lógico.

### 2.2. Control del plug fan (UTA)

La DB dispone de un **conector dedicado de E/S analógicas y digitales** para control clásico del ventilador:
- Salidas analógicas 0-10 V para consigna de velocidad.
- Salidas digitales para arranque/paro, marcha adelante/atrás si aplica.
- Entradas analógicas para realimentación (corriente, revoluciones si las da).
- Entradas digitales para alarmas y confirmaciones.

**El puerto 2 RS485 es OPCIONAL**: si el ventilador instalado tiene variador comunicable por Modbus, se gana visibilidad adicional (revoluciones precisas, alarmas detalladas, consumo). Si no, el control funciona perfectamente solo con las E/S clásicas.

> **Decisión de diseño:** el lazo de control no depende de Modbus para mover el ventilador. El módulo de "actuador velocidad" tiene driver dual: hardware clásico por defecto, Modbus opcional.

### 2.3. Bus CAN

| Bus | Estado | Función |
|---|---|---|
| **CAN1** | Hardware disponible, **sin uso definido todavía** | Periféricos **locales** de la DB (expansores, actuadores cercanos, redundancia local). **No para inter-DB** — eso va por Ethernet/MQTT |

Se preparará el driver CAN mínimo (init + tx/rx callbacks) sin lógica de aplicación encima. Activable cuando se concrete su uso. Ver D11.

---

## 3. Software base

| Bloque | Decisión |
|---|---|
| **RTOS** | FreeRTOS (ya en uso en el proyecto STM32 actual) |
| **Framework MCU** | STM32 HAL/LL vía STM32CubeIDE |
| **Stack TCP/IP** | A confirmar en Fase 2. Candidato: **LwIP** |
| **Servidor HTTP/WS** | A confirmar en Fase 2. Candidato: **Mongoose** |
| **Cliente MQTT** | A confirmar en Fase 2. Candidato: **Mongoose** (también soporta MQTT) o **paho.mqtt.embedded** |
| **TLS** | A confirmar en Fase 2. Candidato: **mbedTLS** |
| **JSON** | A confirmar en Fase 2. Candidato: **cJSON** |
| **mDNS** | A confirmar en Fase 2. Candidato: **mDNS LwIP app** |
| **Sistema de archivos en SD** | A confirmar. Candidato: **FatFS** |
| **Almacenamiento histórico** | A confirmar (D12). Candidatos: ficheros binarios propios por día / SQLite / TS-DB ligero |
| **Stack BLE** | A confirmar al revisar hardware (depende del módulo BT) |

---

## 4. HMI y aplicaciones cliente

### 4.1. Web embebida (en cada DB)

- Servida por el firmware de la propia DB.
- Tecnología: HTML + CSS + JavaScript vanilla (sin framework pesado).
- Acceso: vía IP de la DB o `<nombre-sala>.local` (mDNS).
- Funciones:
  - Configuración local de esa DB (red, sensores, calibraciones).
  - Supervisión local en tiempo real de esa sala.
  - Asistente de primer arranque (ver sección 8).
  - Acceso al histórico local de esa sala.

### 4.2. App cliente principal (Flutter)

- **Tecnología:** **Flutter** (decisión firme).
- **Objetivos:** tablet, PC (Windows/macOS/Linux), navegador web, móvil (Android/iOS) — todo desde el mismo código base.
- **Modo de operación:** se conecta al **broker MQTT** de la instalación (no a cada DB individualmente) para escalar a 12–100 nodos sin abrir 100 conexiones.
- **Funciones:**
  - **Panel general:** vista de todas las salas a la vez (semáforos: verde / aviso / alarma).
  - **Vista detalle por sala:** datos en tiempo real, estado de actuadores, etapa del proceso.
  - **Gráficas históricas** por sala y por rango temporal.
  - **Gestión de recetas:** edición, propagación a una o varias salas a la vez.
  - **Programación de riegos.**
  - **Alarmas centralizadas** con notificación al móvil.
  - **Modo técnico de servicio** que activa la búsqueda BLE para conexión directa a una DB en campo.

### 4.3. App móvil de servicio (BLE)

- **Es la misma app Flutter** con un modo "técnico de campo".
- **Comunicación:** Bluetooth Low Energy (BLE) directo a una DB cercana, **sin necesidad de Ethernet**.
- **Uso típico:**
  - Instalación inicial de una DB que aún no tiene IP.
  - Configuración de red (asignar IP fija, conectar al MQTT broker).
  - Diagnóstico in situ cuando la DB no responde por red.
  - Calibración de sondas.
  - Test de actuadores en modo seguro.
- **Pareado:** PIN o NFC para evitar acceso no autorizado.

### 4.4. Sobre la aplicación WPF existente

- **No se reutiliza código.**
- Se aporta como **referencia conceptual** de cómo está gestionado el riego avanzado actualmente.
- Su análisis (Fase 1) servirá para extraer requisitos funcionales y modelo de interacción del riego que se reflejarán en la app Flutter.

---

## 5. Red y arquitectura distribuida

### 5.1. Capacidades de red por DB

| Capacidad | Estado |
|---|---|
| **IP fija** | Soportada (configurable) |
| **DHCP** | Soportada (default) |
| **mDNS** | Soportada (descubrimiento `<nombre>.local`) |
| **Internet** | Opcional. Útil para NTP, OTA y telemetría — no bloqueante |
| **BLE** | Activo para app móvil de servicio (ver 4.3) |

### 5.2. Arquitectura distribuida MQTT

**Decisión firme: MQTT como capa de mensajería entre DBs y con la app cliente.**

```
                ┌─────────────────────────┐
                │   Broker MQTT           │
                │   (Mosquitto / similar) │
                │   En 1 DB designada     │
                │   o en mini-PC/RPi      │
                └────────────┬────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
   ┌────┴────┐          ┌────┴────┐          ┌────┴────┐
   │  DB 1   │          │  DB 2   │  ...     │  DB N   │
   │ Sala 1  │          │ Sala 2  │          │ Sala N  │
   └─────────┘          └─────────┘          └─────────┘
        │                    │                    │
        │ Cada DB pub/sub:   │                    │
        │ - publica estado   │                    │
        │ - se suscribe a    │                    │
        │   exterior y       │                    │
        │   comandos         │                    │
        │                    │                    │
        ▼                    ▼                    ▼
   App cliente Flutter / Tablet de operador / PC supervisor
   (todos suscritos al broker MQTT)
```

| Aspecto | Decisión |
|---|---|
| **Broker MQTT** | A decidir ubicación en Fase 2 (D13): una DB designada, mini-PC industrial, Raspberry Pi |
| **Topics base** | Propuesta: `salas/{id}/estado`, `salas/{id}/cmd`, `instalacion/exterior`, `instalacion/alarmas` |
| **QoS** | Telemetría: QoS 0/1. Comandos: QoS 2 |
| **Retención** | Activada para topics de estado (último valor disponible al instante para nuevos suscriptores) |
| **Last Will** | Cada DB publica su "se ha caído" automáticamente si pierde conexión |
| **TLS** | Recomendable. Decisión final en Fase 2 |

### 5.3. Compartición del dato exterior entre DB

Una única DB de la instalación tendrá conectada la **caja paramétrica exterior** (puerto 5). Las demás consumen ese dato por MQTT.

| Aspecto | Decisión |
|---|---|
| **Rol de cada DB** | Auto-detectado: si hay sensor en puerto 5 → **rol maestro meteo**; si no → **rol cliente meteo** |
| **Override manual** | Configurable desde la web |
| **Topic MQTT** | `instalacion/exterior` con HR+T+CO₂ exteriores |
| **Frecuencia de publicación** | **30–60 segundos** (suficiente, las variables exteriores son lentas) |
| **Retención en broker** | Sí — un nuevo suscriptor recibe el último valor al instante |
| **Tolerancia a caída del maestro meteo** | Cada cliente conserva la última lectura recibida y la marca como *stale* tras N minutos sin actualización |

### 5.4. Comunicación con el variador del plug fan (puerto 2 Modbus)

| Aspecto | Estado |
|---|---|
| **Modelo del variador** | Sin definir aún. La capa de driver será sustituible |
| **Control principal** | Por **hardware clásico** (E/S analógicas y digitales del conector dedicado) |
| **Control Modbus** | **Opcional**. Si el ventilador instalado lo soporta, se activa por configuración para ganar visibilidad |
| **Modo seguro ante caída del bus** | Si Modbus cae, fallback automático a control hardware (la última consigna analógica queda válida) |
| **Implicaciones en el lazo PID** | Ninguna crítica, porque el control hardware tiene latencia despreciable |

---

## 6. Histórico de proceso y persistencia

### 6.1. Requisitos firmes

| Aspecto | Decisión |
|---|---|
| **Variables registradas** | T_aire, T_compost, HR, CO₂, % apertura compuerta, % calor, % frío, % ventilación, eventos de riego, alarmas, estado de etapa, todo con timestamp |
| **Frecuencia de muestreo** | Variables analógicas: cada **30–60 s**. Eventos: según ocurran |
| **Soporte físico** | **Tarjeta SD** por DB. Cada sala guarda su propio histórico |
| **Acceso desde app cliente** | Por API REST/WebSocket de la DB. Rango temporal seleccionable para gráficas |
| **Acceso desde web local** | Sí, vista de gráficas de esa sala |
| **Persistencia de configuración** | OctoSPI Flash (recetas, parámetros PID, calibraciones, red) |
| **Persistencia de logs/alarmas** | SD |

### 6.2. Decisiones pendientes (Fase 2)

- **Retención** (D15): ¿1 mes? ¿6 meses? ¿1 año? Definirá el dimensionado de la SD.
- **Formato** (D12): ficheros binarios propios, SQLite, time-series ligero.
- **Política de rotación** (D12): por tamaño, por antigüedad, por archivo diario.

---

## 7. Migración desde el PLC

| Aspecto | Decisión |
|---|---|
| **Sustitución a medio cultivo** | No prevista (no se hará "en caliente") |
| **Importación de recetas del PLC** | No necesaria |
| **Plantillas pre-cargadas** | Sí — el sistema debe arrancar con recetas estándar de champiñón en flash |
| **Operación en paralelo PLC + DB** | Posible durante pruebas, no obligatoria |
| **Despliegue en cultivo ya iniciado sin info previa** | **REQUISITO FIRME**. Ver sección 8 |

---

## 8. Requisito de robustez en despliegue

El sistema debe poder instalarse en una sala con cultivo **ya iniciado**, sin información previa del estado, sin alterar el cultivo durante el bootstrap.

### 8.1. Modo "observación pasiva inicial"

Tras primer arranque o reset de fábrica:

1. **Fase de escucha** (≥ N minutos) — lee sondas sin actuar sobre actuadores.
2. **Estimación de estado** — calcula medias y desviaciones de T, HR, CO₂; clasifica fase probable del cultivo.
3. **Receta sugerida** — propone al operador la receta pre-cargada más coherente con lo observado.
4. **Validación humana** — el operador acepta o ajusta antes de habilitar control activo.
5. **Transición suave** — entrada al modo automático con rampas conservadoras desde la condición actual.

### 8.2. Recetas pre-cargadas por defecto

Mínimo recomendado en flash OctoSPI:

- Incubación.
- Choque térmico (inducción de fructificación).
- Fructificación / formación de primordios.
- Recolección 1er flush.
- Recolección 2º flush.
- Vaciado / desinfección.

Los valores concretos se ajustarán durante la integración (con asesoramiento del cliente/cultivador).

### 8.3. Asistente de primer arranque

Flujo guiado disponible por **dos vías**: web embebida o app móvil BLE.

1. Idioma e identificación de la instalación.
2. Configuración de red (IP fija/DHCP, MQTT broker).
3. Tipo de instalación (climatizador / evaporativo / mixto).
4. Inventario de sensores por puerto + descubrimiento Modbus.
5. Calibraciones de sondas.
6. Carga de receta inicial.
7. Test de actuadores en modo seguro.
8. Activación de control automático.

---

## 9. Plazo y fases

| Plazo objetivo | **~3 meses** (Opción 3, producto completo) |
|---|---|

### 9.1. Reparto orientativo

| Periodo | Foco |
|---|---|
| **Semana 1** | Fase 1: análisis de las 4 fuentes + propuesta de arquitectura |
| **Semana 2** | Fase 2: arquitectura objetivo validada + plan de portado |
| **Semanas 3–5** | Núcleo firmware: drivers Modbus (cajas paramétricas + variador), capa de tareas, persistencia OctoSPI, lazos de control (T, HR, CO₂, ventilación) |
| **Semanas 6–7** | Riego avanzado portado + freecooling + evaporativo + control psicrométrico completo |
| **Semanas 8–9** | Stack red completo: LwIP, MQTT cliente, servidor web embebido, REST/WS, mDNS |
| **Semanas 10–11** | App Flutter: panel general, vista detalle, gráficas históricas, gestión de recetas |
| **Semana 12** | BLE de servicio + modo técnico app + asistente primer arranque |
| **Semana 13** | Integración + pruebas + hardening + documentación final |

### 9.2. Features comprometidas (Opción 3)

- ✓ Firmware completo de control climático y riego.
- ✓ Drivers Modbus maestros (cajas paramétricas, variador opcional).
- ✓ Histórico en SD con API de consulta.
- ✓ Cliente MQTT.
- ✓ Web embebida funcional.
- ✓ App Flutter con panel general + detalle + gráficas + alarmas.
- ✓ BLE de servicio.
- ✓ Asistente de primer arranque.
- ✓ Modo observación pasiva inicial.
- ✓ Recetas pre-cargadas.

### 9.3. Features fuera de alcance (post-MVP)

- OTA (over-the-air update) automatizada.
- Sincronización avanzada entre instalaciones remotas.
- Telemetría a cloud externo.
- Analítica avanzada / detección de anomalías por IA.

### 9.4. Condiciones para que el plazo se cumpla

- Base actual del proyecto STM32 está sana y reutilizable.
- Riego avanzado del Atmel está documentado o legible sin sorpresas.
- Sin bloqueos en pruebas de campo (acceso a hardware con la instalación piloto).
- Validación rápida del cliente en hitos (no esperar 2 semanas a recibir feedback de Fase 2).

Si alguna condición falla, se renegocia alcance antes de tocar plazo.

---

## 10. Decisiones diferidas

Cosas que **no bloquean Fase 1** y se resolverán cuando proceda.

| # | Tema | Cuándo se decide |
|---|---|---|
| D1 | Stack TCP/IP definitivo (LwIP vs NetXDuo) | Fase 2 |
| D2 | Distribución del filesystem (qué a OctoSPI, qué a SD) | Fase 2 |
| D3 | Esquema de persistencia de configuración (binario / SQLite / similar) | Fase 2 |
| D4 | Detalles BLE: servicios GATT, pareado (PIN vs NFC) | Fase 2-3 |
| D5 | Política de logs (rotación, tamaño, formato) | Fase 3 |
| D6 | Mecanismo de OTA (post-MVP) | Después de la entrega |
| D7 | Esquema de autenticación de la app cliente (MQTT TLS + credenciales) | Fase 2 |
| D8 | Recetas concretas pre-cargadas (valores) | Fase final, con asesoramiento del cliente |
| ~~D9~~ | ~~Protocolo de compartición exterior~~ | **Resuelta:** MQTT con topic `instalacion/exterior` |
| D10 | Política exacta de fallback Modbus → control hardware del plug fan | Fase 2 |
| D11 | Uso concreto del CAN bus | Cuando se concrete la necesidad |
| **D12** | **Formato y motor de almacenamiento del histórico** (ficheros binarios / SQLite / TS-DB ligero) | Fase 2 |
| **D13** | **Ubicación del broker MQTT** (DB designada / mini-PC / Raspberry Pi) | Fase 2 |
| **D14** | **Esquema de descubrimiento de DBs** (mDNS + auto-suscripción MQTT al inicio) | Fase 2 |
| **D15** | **Retención histórica** (1 mes / 6 meses / 1 año) | Fase 2 |
| **D16** | **Sincronización horaria entre DBs** (NTP local / hora desde broker) | Fase 2 |

---

## 11. Preguntas abiertas (no bloquean Fase 1)

| # | Pregunta | Estado / Respuesta |
|---|---|---|
| ~~P1~~ | ~~Número y disposición de DBs~~ | **Resuelta:** 12 DBs inicial, escalable a 100. Repartidas junto a las UTAs |
| **P2** | Modelo / familia del variador del plug fan cuando se elija | Pendiente — se diseña la capa de abstracción para ser sustituible |
| ~~P3~~ | ~~Caja paramétrica E+E: 1 dispositivo o 2~~ | **Resuelta:** 2 dispositivos por caja, direcciones Modbus distintas |
| ~~P4~~ | ~~Frecuencia y necesidad de histórico exterior~~ | **Resuelta:** 30–60 s + histórico necesario en todas las variables de proceso |
| ~~P5~~ | ~~Caso de uso Bluetooth~~ | **Resuelta:** BLE para app móvil de servicio (instalación, configuración, diagnóstico) |
| P6 | Caso de uso concreto del bus CAN | Sigue abierta — periféricos locales futuros |
| **P7** | ¿Hay infraestructura para correr un broker MQTT externo (mini-PC, RPi, NAS) o lo hostea una DB designada? | Para D13 |
| **P8** | ¿Existe NTP local en la red del cliente o hay que prever un servidor de tiempo? | Para D16 |
| **P9** | ¿La instalación piloto está disponible para pruebas durante el desarrollo? | Para planificar pruebas de campo |

---

## 12. Fuentes de información que se aportarán

Orden recomendado de entrega:

1. **KiCad** de la Daughter Board (esquemático + PCB + BOM si lo hay).
2. **Proyecto STM32CubeIDE** actual (que ya hace de esclavo Modbus del PLC).
3. **Firmware Atmel** del riego avanzado.
4. **Aplicación WPF** que controla el riego avanzado.

Ya disponible y referenciada:

- **Documentación del PLC Panasonic** (`sistema-control-champinon.md` + `.html`). Especificación funcional del control climático.

---

## 13. Entregables comprometidos

### Por fase

| Fase | Documento(s) / código | Estado |
|---|---|---|
| **0** | `00-fase-0-acotacion.md` (este documento) | **✓ Cerrado** |
| **1** | `01-hardware-DB.md`, `02-firmware-stm32-actual.md`, `03-riego-avanzado-atmel.md`, `04-wpf-cliente.md` | Pendiente |
| **2** | `05-arquitectura-objetivo.md` (validación firme) | Pendiente |
| **3** | `06-plan-de-portado.md` (mapeo módulo a módulo) | Pendiente |
| **4** | Código C/H por módulo + tests + Doxygen | Pendiente |
| **5** | `07-guia-integracion.md` + Flutter + BLE + estado final | Pendiente |

### Globales

- **Documentación del nuevo sistema** (markdown + HTML al estilo de la del PLC).
- **Trazabilidad** PLC ↔ nuevo firmware (qué función nueva sustituye a qué función PLC).
- **Notas de hardening** y diferencias frente al PLC original.
- **App Flutter** con código fuente y guía de despliegue.
- **Guía de instalación** para el técnico que monte una sala nueva.

---

## 14. Próximo paso

Esperar la entrega de los **archivos KiCad de la Daughter Board** para arrancar Fase 1.