La integración de CO2 Gadget con Home Assistant vía MQTT es totalmente automática gracias al MQTT Discovery: en cuanto tu medidor se conecta al broker, Home Assistant crea todos los sensores, entidades de configuración y selectores sin tocar YAML. Aquí encontrarás la lista completa de topics, comandos remotos soportados y ejemplos de automatizaciones.
Contenidos
El protocolo MQTT permite a CO2 Gadget publicar sus mediciones de CO₂, temperatura, humedad, batería y partículas (PM) en tiempo real, así como recibir comandos remotos para calibrar el sensor o cambiar la configuración. Además, la funcionalidad de Home Assistant Discovery hace que la integración con tu sistema domótico sea totalmente automática.
Configuración básica de MQTT
Para usar MQTT necesitas tener el WiFi activado. Puedes configurar MQTT desde el menú del medidor, desde la página web o desde la App MyAmbiance.
| Parámetro | Descripción |
|---|---|
| MQTT Enable | Activa o desactiva MQTT (ON / OFF) |
| Topic | Raíz de los topics donde se publicarán los datos (default `CO2-Gadget`) |
| Client ID | Identificador único del dispositivo en el broker (default `mqttClientId` macro) |
| Broker IP | Dirección IP de tu broker MQTT (Mosquitto, etc.) |
| Port | Puerto del broker (default 1883) |
| User / Pass | Autenticación con el broker (opcional) |
| Discovery Prefix | Prefijo de discovery (default `homeassistant/`) |
Reintentos de conexión: secondsBetweenRetries = 15 s, maxMQTTmqttConnectionRetries = 2. Buffer PubSubClient: 1024 bytes.
Puedes acceder a la configuración desde la página web: http://ipdelmedidor/preferences.html, o desde el menú en pantalla: Configuración → MQTT Config.
Topics que publica tu medidor de CO₂
Una vez conectado al broker, CO2 Gadget publica las mediciones en los siguientes topics (usando el topic raíz que hayas configurado):
| Topic | Valor | Descripción |
|---|---|---|
| `topic/co2` | 892 | CO₂ en ppm |
| `topic/temp` | 24.50 | Temperatura en °C |
| `topic/humi` | 45.20 | Humedad relativa en % |
| `topic/voltage` | 4.10 | Voltaje de batería en V (float) |
| `topic/battery` | 85 | Porcentaje de batería en % (int) |
| `topic/pm1` | 5 | PM1.0 (µg/m³) si hay sensor PM |
| `topic/pm25` | 12 | PM2.5 (µg/m³) si hay sensor PM |
| `topic/pm4` | 8 | PM4.0 (µg/m³) si hay sensor PM |
| `topic/pm10` | 15 | PM10 (µg/m³) si hay sensor PM |
| `topic/uptime` | `12d 03h 45m` | Tiempo encendida, formato legible |
| `topic/freeMem` | 102400 | Heap libre en bytes |
| `topic/wifiRSSI` | -65 | RSSI WiFi en dBm |
| `topic/IP` | `192.168.1.50` | IP actual del medidor |
| `topic/MAC` | `AA:BB:CC:…` | MAC del ESP32 |
| `topic/hostname` | `CO2-Gadget` | Hostname mDNS |
| `topic/status` | `OK` | Disponibilidad (Last Will & Testament) |
Topics de alarmas
CO2 Gadget también publica mensajes cuando se alcanzan los niveles de concentración configurados. Las alarmas tienen histéresis para evitar oscilaciones: PINHYSTERESIS = 100 ppm para las salidas GPIO, BUZZERHYSTERESIS = 50 ppm para el buzzer. Las salidas se rearman cuando co2 < co2RedRange − hyst.
| Topic | Payload ON | Payload OFF |
|---|---|---|
| `topic/green` | Nivel normal | Se supera el nivel naranja |
| `topic/orange` | Alarma naranja | Baja con histéresis |
| `topic/red` | Alarma roja | Baja con histéresis |
Home Assistant Discovery automático
Si activas MQTT Discovery, CO2 Gadget se autoconfigura en Home Assistant sin que tengas que tocar nada. Se registran 13 entidades bajo el prefijo homeassistant/:
| Entidad | Clase | Icon | Descripción |
|---|---|---|---|
| `battery` | diagnostic | `mdi:battery` | Porcentaje de batería (%) |
| `voltage` | diagnostic | `mdi:flash` | Voltaje de batería (V) |
| `co2` | sensor | `mdi:molecule-co2` | CO₂ en ppm |
| `temp` | sensor | `mdi:temperature-celsius` | Temperatura (°C) |
| `humi` | sensor | `mdi:water-percent` | Humedad relativa (%) |
| `pm1`, `pm25`, `pm4`, `pm10` | sensor | `mdi:air-filter` | Partículas (µg/m³, solo si hay sensor PM) |
| `freeMem` | diagnostic | `mdi:memory` | Heap libre (bytes) |
| `wifiRSSI` | diagnostic | `mdi:wifi` | RSSI WiFi (dBm) |
| `uptime` | diagnostic | `mdi:clock-time-eight-outline` | Tiempo encendida |
Device info: manufacturer = emariete.com, model = CO2 Gadget, hwversion = FLAVOUR, swversion = ", configurationurl = http://. El objectid se genera como co2gadget (fallback). Compatible también con OpenHAB y HomeSeer.
Comandos remotos por MQTT
Además de publicar datos, puedes controlar tu medidor de forma remota:
| Topic | Payload | Función |
|---|---|---|
| `topic/calibration` | 400 | Calibración forzada (400-2000 ppm) |
| `topic/ambientpressure` | 1013 | Compensación por presión (mbar) |
ThresholdManager: publicaciones inteligentes
El sistema de umbrales inteligentes evalúa 4 canales independientes (Display, BLE, MQTT, ESP-NOW). Cada canal publica solo cuando el valor cruza el umbral configurado — evita tráfico MQTT innecesario en bajo consumo. Configurable desde la página /low_power.html (4 pestañas, una por canal) y desde getThresholdsAsJson / saveThresholds. Ideal para ahorrar batería y reducir el ancho de banda en el broker.
Solución de problemas
| Problema | Solución |
|---|---|
| No conecta al broker | Verifica IP del broker y WiFi activado |
| No hay datos en HA | Revisa que el topic raíz coincida |
| Discovery no funciona | Activa MQTT Discovery en configuración |
| No se actualizan valores | Revisa los umbrales del ThresholdManager |
Notas importantes
- MQTT necesita WiFi activado
- En LOW_POWER la frecuencia depende de los ciclos de wake
- Sin servicios cloud — todo en tu red local
- CO2 Gadget ofrece integración MQTT más completa que la mayoría de medidores comerciales
¿Te ha sido útil? Comparte este artículo. ¿Tambien consulta la Guía del Menú. Tienes dudas? Pregunta en el grupo de Telegram o abre un issue en GitHub.