ADR-001: MQTT como bus de sensores¶
Fecha: 2026-05-11 Estado: aceptado Decisión: MQTT (Mosquitto) será el protocolo de comunicación para todos los sensores y actuadores de campo (ESP32 (microcontrolador WiFi para sensores), Shelly (actuador eléctrico WiFi)). Las capas superiores (Node-RED, n8n) consumirán y publicarán en MQTT (protocolo de mensajería ligera para IoT). Los servicios web y APIs usarán HTTP.
Contexto: SmallCountry tiene dos mundos de comunicación: el edge (sensores, actuadores, dispositivos de campo con baja potencia y conectividad intermitente) y el núcleo (servicios web, APIs, bases de datos con conexiones estables). Ambos necesitan un protocolo, pero tienen requisitos opuestos. El edge necesita bajo consumo, baja latencia, push nativo y tolerancia a desconexión. Los servicios web necesitan REST (estilo de arquitectura para APIs web), caché HTTP y ecosistema de herramientas maduro.
Alternativas consideradas:
| Alternativa | Ventajas | Por qué se descartó |
|---|---|---|
| HTTP (REST) para todo | Un solo protocolo, más simple | El edge con HTTP requiere polling o long-polling. Mayor consumo en ESP32. No escala bien con decenas de sensores |
| CoAP | Diseñado para IoT, similar a HTTP pero ligero | Menos maduro en el ecosistema. Peor soporte en Home Assistant y Grafana |
| AMQP (RabbitMQ) | Enrutamiento avanzado, colas persistentes | Sobredimensionado para sensores simples. Mayor complejidad operativa |
| gRPC | Binario, rápido, streaming | Demasiado pesado para ESP32. Ecosistema menos maduro en domótica |
Consecuencias:
- ✅ Push nativo: los sensores publican cuando tienen datos, sin esperar a ser interrogados
- ✅ Bajo consumo: mensajes de pocos bytes, ideal para ESP32 con batería
- ✅ Tolerancia a desconexión: QoS y mensajes retenidos permiten que el edge funcione offline
- ✅ Ecosistema maduro: Home Assistant, Node-RED, Grafana, todos hablan MQTT (protocolo de mensajería ligera para IoT)
- ❌ No apto para APIs web: MQTT no es REST. Los servicios que necesitan HTTP usan Caddy
- ❌ Dos protocolos = dos modelos mentales: push (MQTT) y pull (HTTP). Complejidad aceptada
- ❌ Seguridad: MQTT autentica por usuario/contraseña. La seguridad real viene de la segmentación de red (vmbr3 aislado)
Referencias: - Ficha: Mosquitto - Principio 6: Arquitectura por capas - Principio 8: Observabilidad integral