Correggere il sensore Tem&Hum con sonda di Tuya in Home Assistant tramite una quirk personalizzata

Alcuni sensori Tuya di temperatura e umidità con sonda esterna, tramite l’integrazione ufficiale Tuya in Home Assistant, espongono solo la temperatura interna.
La sonda esterna funziona nell’app Tuya e compare sulla Tuya IoT Platform come ext_temp (DP 101), ma Home Assistant non crea alcuna entità per quel valore.

Per risolvere il problema abbiamo creato un quirk Tuya personalizzato usando la libreria tuya-device-handlers, che Home Assistant utilizza internamente per normalizzare il comportamento dei dispositivi Tuya.
Questo quirk fa sì che Home Assistant riconosca i datapoint aggiuntivi del dispositivo, così da esporre la temperatura della sonda esterna (e, opzionalmente, altre impostazioni della sonda) come entità.

Perché è stato necessario il quirk

Il dispositivo in questione è il Tuya “Tem&Hum Sensor with Probe”:

• Categoria Tuya: wsdcg

• Product ID: m7kacaxrxbxeegfs

Sulla Tuya IoT Platform il dispositivo invia anche questi datapoint legati alla sonda:

• ext_temp (DP 101) – temperatura della sonda esterna

• ext_maxtemp (DP 102) – soglia alta di allarme temperatura

• ext_mintemp (DP 103) – soglia bassa di allarme temperatura

• ext_temp_sensivitity (DP 104) – sensibilità alla variazione di temperatura

• ext_temp_alarm (DP 105) – modalità di allarme

• ext_temp_calibration (DP 106) – calibrazione della temperatura

Nelle diagnostiche di Home Assistant e nell’integrazione ufficiale Tuya compaiono però solo:

• temperatura interna (va_temperature)

• umidità (va_humidity)

• stato batteria (battery_state)

La temperatura della sonda esterna in Home Assistant non esiste, e questo limita moltissimo l’utilità del sensore per monitorare frigoriferi, congelatori, boiler o serbatoi, dove interessa proprio il valore misurato dalla sonda.

Come è stato costruito il quirk

L’integrazione Tuya di Home Assistant utilizza la libreria tuya-device-handlers, che definisce i cosiddetti quirks: piccoli script Python che mappano i datapoint grezzi di Tuya (DP) su entità strutturate.

Per questo sensore abbiamo creato un file di quirk che:

1. Aggancia il dispositivo tramite il Product ID

   python

   .applies_to(product_id="m7kacaxrxbxeegfs")

   In questo modo il quirk si applica solo a questo prodotto e non a tutti i dispositivi wsdcg.

2. Aggiunge la sonda esterna come sensore di temperatura intero

   python

   .add_dpid_integer( dpid=101, # ext_temp dpcode="ext_temp", # o un altro codice di temperatura supportato dpmode=DPMode.READ, unit="℃", min=-200, max=1000, scale=1, step=1, )

   Il range e la scala sono allineati alla temperatura interna (va_temperature), per cui il valore grezzo 245 viene interpretato come 24,5 °C.

3. Aggiunge opzionalmente i datapoint di allarme e calibrazioneUlteriori chiamate add_dpid_integer possono mappare ext_maxtemp, ext_mintemp, ext_temp_sensivitity e ext_temp_calibration, permettendo a Home Assistant di leggere (ed eventualmente scrivere) queste impostazioni.

4. Registra il quirk nel registro globale

   python

   .register(TUYA_QUIRKS_REGISTRY)

   In questo modo l’integrazione Tuya trova il quirk all’avvio di Home Assistant.

Il risultato è un piccolo file Python che indica a Home Assistant come interpretare i DP 101–106 come entità di temperatura e configurazione della sonda anziché ignorarli.

Installare il quirk in Home Assistant (File Editor)

Non è necessario modificare i file core di Home Assistant. Il quirk viene installato come quirk Tuya personalizzato all’interno della cartella /config, in modo simile ai custom ZHA quirks.

1. Installare l’add-on File Editor

   • Impostazioni → Componenti aggiuntivi → Add-on Store.

   • Installare File Editor (o Studio Code Server).

2. Creare una cartella per i quirks Tuya

   • Aprire /config in File Editor.

   • Creare una nuova cartella, ad esempio:
     tuya_quirks

   • All’interno, creare un nuovo file, ad esempio:
     wsdcg_bf0376ec16496a5b0apzxs.py (il nome è libero).

3. Incollare il codice del quirk

   • Incollare il codice con DeviceQuirk(), la chiamata a add_dpid_integer per DP 101 e gli eventuali altri DP della sonda, con .register(TUYA_QUIRKS_REGISTRY) in fondo.

   • Salvare il file.

   • 

4. Riavviare Home Assistant

   • È consigliato un riavvio completo, così l’integrazione Tuya può caricare il nuovo quirk.

5. Ricaricare o riaggiungere il dispositivo Tuya

   • Impostazioni → Dispositivi e servizi → Tuya → Reload, oppure rimuovere e aggiungere di nuovo il dispositivo.

Utilizzo della nuova entità di temperatura esterna

Dopo il riavvio e la ricarica, il dispositivo dovrebbe esporre una nuova entità di temperatura, ad esempio:

• sensor.tem_hum_sensor_with_probe_external_temperature
  oppure

• sensor.tem_hum_sensor_with_probe_ext_temp

Questa entità può essere:

• aggiunta alle dashboard,

• usata nelle automazioni (per esempio un allarme se la temperatura del congelatore sale troppo),

• monitorata nelle viste Storico e Statistiche.

Tieni presente che molti sensori Tuya a batteria inviano aggiornamenti solo quando la temperatura cambia in modo significativo o a intervalli predefiniti, quindi gli aggiornamenti potrebbero non essere immediati.