Guía BTHome de CO2 Gadget: Home Assistant sin WiFi ni MQTT

BTHome v2 es un protocolo abierto de beacon BLE que Home Assistant descubre automáticamente: con tu medidor CO2 Gadget transmitiendo por Bluetooth, Home Assistant crea las entidades sin WiFi, sin MQTT ni configuración manual. CO2 Gadget soporta 10 medidas (CO₂, temperatura, humedad, batería, PM2.5, presión, PM10, voltaje, PM1.0 y PM4.0), encriptación AES-CCM y coexistencia con MyAmbiance.

Documentacion en actualizacion. Estamos revisando y mejorando todas las paginas. Es posible que encuentres algun enlace roto o contenido pendiente. Si ves algo que falla, ayudanos a arreglarlo en GitHub.

¿Qué es BTHome?

BTHome es un estándar abierto de beacon BLE para dispositivos domóticos. CO₂ Gadget anuncia sus mediciones como servicio-data BTHome bajo el UUID 0xFCD2. Home Assistant, con el integrador BTHome integrado, descubre el dispositivo automáticamente y crea las entidades correspondientes.

Ventajas frente a MQTT:

  • Zero-config — no necesitas broker MQTT ni configuración en Home Assistant
  • Sin WiFi — funciona aunque el medidor esté en modo avión o sin red
  • Bajo consumo — compatible con deep sleep (anuncios en cada wake)
  • Independiente — funciona junto con MyAmbiance o por separado

Cómo activar BTHome

Desde la Web UI (recomendado)

  1. Abre `http://ip_del_medidor/preferences.html`
  2. Ve a Connectivity
  3. Activa BLE (si no lo está)
  4. Activa BTHome
  5. Se desplegará la configuración BTHome con las opciones de sensores
  6. Pulsa Save

Desde el menú serie

BLE Config
└── BTHome
    ├── BTHome output [ON]
    ├── Encryption [OFF] (opcional)
    ├── BTHome key (32 hex)
    └── Publish Sensors
        ├── Core: CO₂, Temperature, Humidity, Battery
        ├── Optional: PM2.5, Pressure, PM10, Battery Voltage
        └── No BTHome object: PM1.0, PM4.0

Sensores disponibles

CO₂ Gadget puede anunciar hasta 10 tipos de medida. Están agrupados en tres categorías:

GrupoSensoresIDs BTHome
Core (por defecto)CO₂, Temperatura, Humedad, Batería (%)0x12, 0x02, 0x03, 0x01
OptionalPM2.5, Presión, PM10, Voltaje batería0x0D, 0x04, 0x0E, 0x0C
No BTHome objectPM1.0, PM4.00xEE, 0xEF (privados)

Selección por defecto: solo los sensores Core. Los demás son opt-in desde la Web UI o el menú.

Límite de payload: los anuncios BLE tienen un límite de ~24 bytes. Si seleccionas demasiados sensores, los de menor prioridad se omiten automáticamente. La Web UI muestra el presupuesto en vivo.

Nota sobre PM1.0 y PM4.0: usan IDs privados (no estándar BTHome). Home Assistant no los reconoce, pero no interfieren con el resto de sensores. Están pensados para sistemas que puedan parsear IDs personalizados.

Encriptación AES-CCM

BTHome soporta encriptación opcional con AES-CCM de 128 bits.

  1. Activa Encryption en la Web UI o el menú
  2. Se genera automáticamente una bind key de 32 caracteres hexadecimales
  3. Para verla: en la Web UI pulsa Reveal (te pedirá confirmación)
  4. Copia la bind key e introdúcela en Home Assistant al emparejar

⚠️ Importante: La bind key no se incluye en las copias de seguridad (`preferences_backup.json`). Si restauras una copia, tendrás que revelar la clave de nuevo o regenerarla y re-emparejar Home Assistant.

Integración con Home Assistant

  1. Activa BTHome en el medidor (y opcionalmente la encriptación)
  2. Si usas encriptación, revela la bind key desde la Web UI
  3. En Home Assistant: Configuración → Dispositivos y servicios
  4. El medidor aparecerá automáticamente como dispositivo BTHome
  5. Si está encriptado, pega la bind key cuando Home Assistant lo pida
  6. Las entidades de los sensores seleccionados se crearán automáticamente

Las mediciones estándar (CO₂, temperatura, humedad, batería, presión, PM2.5, PM10) aparecen como entidades nativas. PM1.0 y PM4.0 no aparecen (IDs no estándar).

Comportamiento en modo low-power

En modo LOW_POWER (deep sleep), el comportamiento cambia ligeramente:

  • Partículas (PM) — No se anuncian en deep sleep. Los sensores de partículas necesitan varios segundos para el ventilador, incompatibles con el wake de ~0.3 s. La selección se retiene y se reanuda automáticamente al volver a HIGH_PERFORMANCE.
  • Presión — Solo se lee en wake si compilas con `SUPPORT_LOW_POWER_PRESSURE` (opt-in). Actualmente solo compatible con BME280.
  • CO₂, temperatura, humedad — Se anuncian normalmente en cada wake.

El medidor publica un anuncio BTHome inmediatamente al despertar, antes de volver a dormir.

Preguntas frecuentes

¿Puedo tener BTHome y MyAmbiance a la vez? Sí. Ambos pueden estar activos simultáneamente. Si ambos lo están, BTHome viaja en el scan response para no interferir con MyAmbiance.

¿BTHome funciona sin WiFi? Sí. BTHome es puramente BLE. No necesita WiFi para nada.

¿Cuánto consume BTHome en batería? Muy poco. Los anuncios son cortos y se envían con umbrales configurables. En modo low-power, solo se anuncia en cada wake.

¿Por qué no veo PM1.0/PM4.0 en Home Assistant? Porque usan IDs privados que Home Assistant no reconoce. Si los necesitas, tendrás que usar un receptor personalizado (ESPHome, Theengs, etc.).

He restaurado una copia de seguridad y HA no encuentra el medidor. La bind key no se guarda en el backup. Revela la clave de nuevo desde la Web UI o regenera una nueva y re-empareja.

Limitaciones conocidas

  • PM1.0 y PM4.0 no aparecen en Home Assistant (IDs privados)
  • En low-power, PM no se anuncia (se retiene la selección)
  • Presión en wake solo con `SUPPORT_LOW_POWER_PRESSURE` y BME280
  • La temperatura siempre se codifica en °C
  • El presupuesto de bytes se calcula de forma conservadora (24 B), incluso en modo scan response

¿Te ha sido útil? Comparte este artículo. ¿Tambien consulta la Guia del Menu. Tienes dudas? Pregunta en el grupo de Telegram o abre un issue en GitHub.

Deja un comentario