Mush2 — Controlador de Ambientes para Hongos Adaptógenos

Sistema IoT para monitoreo y control ambiental de cámaras de cultivo de hongos adaptógenos. Lee temperatura, humedad y CO₂, controla actuadores SSR mediante FreeRTOS en ESP32-S3, y expone un dashboard web en tiempo real.

🚀 Preview Explora la aplicación ejecutándose en producción.	📚 Documentation Consulta la documentación técnica del proyecto.

Características Principales

Mush2 es una solución completa de IoT industrial para el cultivo controlado de hongos adaptógenos:

• Monitoreo Ambiental Preciso: Lectura de temperatura, humedad relativa y calidad del aire (CO₂, VOC) mediante sensores AHT21 y ENS160 vía I²C.
• Control de Actuadores SSR: Gestión de 4 canales de relés de estado sólido (active-LOW) para ventilación, calefacción, humidificación e iluminación.
• Arquitectura FreeRTOS: 9 tareas en 2 núcleos Xtensa LX7 con prioridades, colas de sincronización y watchdog jerárquico (TWDT + SWDT + Health Check).
• Comunicación HTTP Polling: Sincronización entre firmware y backend mediante REST API con cola de comandos y backoff exponencial.
• Dashboard en Tiempo Real: Interfaz web React con SSE, visualización de datos históricos y control remoto de actuadores.
• Telemetría de Respaldo: Envío de datos a ThingSpeak como sistema de respaldo y monitoreo externo.
• Seguridad por Capas: JWT + RBAC, API keys por dispositivo, refresh token en httpOnly cookie, rate limiting, Helmet CSP.

---

Stack Tecnológico

Capa	Tecnología
Firmware	C++ (PlatformIO / ESP32-S3) + FreeRTOS
Backend	Node.js 20+ (runtime validado: 22 LTS) / Express 5 / Sequelize 6
Contenedores	Docker / Docker Compose (Broker MQTT + Backend)
Frontend	React 18 + Vite + Chart.js
Base de datos	PostgreSQL 16
Comunicación	HTTP polling (REST API) + MQTT + SSE
Telemetría (respaldo)	ThingSpeak
Watchdog	TWDT (12s) + SWDT (30s) + Health Check (60s)

---

Componentes del Sistema

Firmware (ESP32-S3 / FreeRTOS)

• 8 tareas en 2 núcleos: Sensors (Core 1), SSR (Core 1), Button (Core 1), WiFi (Core 0), Poller (Core 0), OTA (Core 0), Telemetry (Core 0), Monitor (Core 0)
• Lectura de sensores AHT21 y ENS160 vía I²C cada 8s
• Control de 4 canales SSR para actuadores con histéresis
• HTTP polling al backend con backoff exponencial y cola de comandos
• Watchdog jerárquico: TWDT (12s, panic → reboot), SWDT (30s, recovery controlado), Health Check (60s)
• Envío de telemetría a ThingSpeak cada 20s
• OTA v3: 4-capas (Decisor + Safe Shutdown + Ejecutor + Confirmación Post-Boot)
• MQTT para health, maintenance, status y alarmas del dispositivo
• Device ID dinámico derivado de MAC address

Backend (Node.js/Express)

• API REST para gestión de dispositivos, telemetría, actuadores, recetas y ciclos
• Motor de reglas (controlEngine.js) con automatización por fases y VPD
• Sincronización HTTP con dispositivos + cola persistente de comandos
• JWT auth + RBAC (SUPER_ADMIN, ADMIN, OPERATOR, VIEWER)
• Seguridad: Helmet CSP, rate limiting, refresh token en httpOnly cookie
• Persistencia en PostgreSQL 16 con Sequelize ORM
• MQTT para firmware + SSE para frontend

Frontend (React/Vite)

• Dashboard en tiempo real con Chart.js y SSE
• Control remoto de actuadores por canal
• Visualización de datos históricos con filtros
• Gestión de recetas y ciclos de cultivo
• Interfaz responsiva con AuthContext y ErrorBoundary

---

Documentación

• PROJECT_CONTEXT.md — Definición del proyecto
• PROJECT_JOURNAL.md — Bitácora de decisiones
• docs/ADR/ — 33 Architecture Decision Records (ADR-001 a ADR-033)
• docs/architecture/ — Arquitectura por componente
• docs/contracts/ — Contratos (API REST, MQTT)
• docs/roadmap/roadmap.md — Roadmap de desarrollo (18 fases)
• docs/requirements.md — Requerimientos funcionales

ADRs destacados

• ADR-001-ESP32.md — Migración a ESP32-S3 como nodo de telemetría
• ADR-012-FreeRTOS.md — Arquitectura FreeRTOS y watchdog jerárquico
• ADR-014-OTA-v3.md — Sistema OTA v3 con arquitectura 4-capas y rollback nativo
• ADR-020-run-replaces-cultivationcycle.md — Evolución del modelo de dominio
• ADR-025-device-status-policy.md — Modelo multidimensional de estado (Aceptado)
• ADR-028-Per-Device-MQTT-Identity.md — Identidad MQTT por dispositivo (Aceptado)

---

Desarrollo Local

Prerequisitos

• Node.js 20+ (runtime validado: 22 LTS)
• Docker Desktop
• PostgreSQL 16 (opcional, se usa el contenedor Docker)

Bootstrap rápido

# 1. Clonar
git clone <repo>
cd mush2

# 2. Crear archivos de configuración local
cp .env.development.example .env.development
cp docker/mosquitto/dev/password_file.example docker/mosquitto/dev/password_file

# 3. Iniciar stack de infraestructura (PostgreSQL + Mosquitto)
docker compose -f docker-compose.dev.yml up -d

# 4. Generar credenciales MQTT
./scripts/create-mqtt-user.sh backend_bridge <password> dev

# 5. Instalar dependencias del backend
cd backend && npm install

# 6. Iniciar backend
npm run dev

El backend se conecta al stack Docker en localhost:5433 (PostgreSQL) y localhost:1884 (MQTT).

---

Autor

AlejandroMaturana — Ingeniero Industrial & Desarrollador Full Stack

• GitHub: @AlejandroMaturana
• LinkedIn: manugl86

---

Licencia

MIT

---

Estado del Sistema: v1.8.22 — En desarrollo. Mush2 es software libre para el cultivo de hongos adaptógenos e IoT industrial.