Skip to content

Guida completa IT

Jump to bottom
zampix1 edited this page Jul 15, 2026 · 9 revisions

Guida completa IT

Questa pagina spiega come usare ha-inkbird-int14 con Home Assistant e cosa aspettarsi realisticamente dall'integrazione.

Modelli e profili

Il target principale resta Inkbird INT-14 / INT-14-BW, cioe' la station con sonde wireless e supporto Wi-Fi/Bluetooth. Questo e' il modello provato davvero con letture live.

Il componente pero' non e' piu scritto come se esistesse solo l'INT-14. Durante il setup scegli un profilo modello. Il profilo serve a dire a Home Assistant quante sonde fisiche e quanti canali temperatura sono attesi, quali trasporti abilitare e quali comandi evitare.

In pratica:

  • INT-14-BW: testato;
  • INT-14P, INT-12, INT-12I e INT-11I: sperimentali;
  • INT-14S-BW: community-validated BLE read-only, con 20 temperature live (4 food + ambiente per ciascuna delle 4 probe);
  • INT-12E-BW: community-validated BLE read-only, con 10 temperature live (4 food + ambiente per ciascuna delle 2 probe), disponibile nella prerelease v0.2.6;
  • INT-11P, INT-11S, INT-31 e INT-33: catalogati, con layout sonde/canali atteso ma senza letture live validate.

Nota INT-11I-B: un report community di Dmitry/dskudrin ha validato la lettura BLE come dispositivo GATT-poll. ff01 espone una temperatura sonda in Fahrenheit centesimi little-endian; 2a19 espone due byte batteria, prima base/booster e poi sonda. Per ora resta read-only: niente write finche' non vengono validati su hardware.

Nota INT-14S-BW: il parser BLE e' nato da diagnostiche autenticate e prove controllate condivise da un utente reale. Le 20 temperature read-only sono disponibili nella versione stabile. Controlli normali, Tuya LAN e cloud restano spenti. La prerelease v0.2.6 contiene due pulsanti diagnostici C/F, disabilitati di default, per un test di scrittura piccolo e reversibile: non sono supporto write generale.

Nota INT-12E-BW: le notifiche aggiornano normalmente le temperature circa ogni tre secondi. L'intervallo configurabile da 5 a 300 secondi governa solo le letture dirette di recupero e non rallenta le notifiche valide. La station puo chiudere ogni sessione BLE dopo circa 30 secondi con motivo 0x13; l'integrazione si riconnette automaticamente. Food 4 e' confermato come canale della punta su entrambe le probe, mentre la posizione fisica di Food 1-3 deve ancora essere mappata. LAN, cloud, write e stati di protocollo restano disabilitati.

La pagina Profili modello tiene la lista aggiornata.

La parte piu' importante e' che il firmware puo' cambiare comportamento in base a:

  • versione hardware;
  • versione firmware;
  • stato Wi-Fi della station;
  • distanza dal Bluetooth adapter o da un Bluetooth proxy;
  • carica della station e delle sonde;
  • sonde inserite, in carica o scollegate.

Se hai un modello vicino ma non identico, apri una Discussion con modello esatto, versione firmware e sintomi. Se il profilo e' sperimentale, anche un test "non funziona" e' utile: basta che i log siano redatti.

Architettura

L'integrazione e' hybrid/local-first. Vuol dire che prova a stare in locale quando puo', senza fingere che tutto passi sempre dalla stessa strada.

In modalita' normale prova a usare prima i canali locali:

  • BLE locale per snapshot, stato, batteria e comandi supportati;
  • Tuya LAN locale per letture Wi-Fi e scritture mappate quando configuri host, device_id e local_key;
  • cloud history opzionale solo per storico DP109.

Non ci sono write cloud. Non c'e' cloud live completo.

Installazione HACS

  1. Apri HACS.
  2. Vai in Custom repositories.
  3. Aggiungi:
https://github.com/zampix1/ha-inkbird-int14
  1. Categoria: Integration.
  2. Installa.
  3. Riavvia Home Assistant.
  4. Aggiungi l'integrazione da Settings -> Devices & services.

Configurazione BLE

BLE non richiede account cloud ne' local key.

Serve pero' che Home Assistant riesca a vedere la station:

  • Bluetooth adapter USB collegato a Home Assistant;
  • oppure ESPHome Bluetooth proxy vicino al termometro;
  • oppure altro proxy Bluetooth supportato da Home Assistant.

Se il rack/server e' lontano dalla cucina/barbecue, un ESPHome Bluetooth proxy vicino al termometro spesso e' piu' utile del dongle USB nel server.

I profili con sessione GATT continua mostrano anche BLE fallback direct-read interval in setup, reconfigure e opzioni. Lascialo a 10 secondi salvo debug: e' una lettura di sicurezza, non un limite agli aggiornamenti ricevuti via notifica.

Autenticazione BLE

Le sessioni BLE della famiglia INT-14 eseguono un challenge/response locale prima di snapshot e readback dei comandi. INT-11I-B e INT-12E-BW usano invece letture GATT dirette specifiche, quindi non tutti i profili espongono gli stessi diagnostici di autenticazione.

Questo non usa credenziali utente. Serve solo a portare la sessione BLE nello stato atteso dalla station.

Entita' diagnostiche utili:

  • BLE Auth OK;
  • Last BLE Auth Error;
  • Last BLE Auth Ack;
  • Last BLE Auth Request Epoch;
  • Last BLE Auth Ack Epoch.

Se BLE Auth OK e' True, la sessione locale e' stata autenticata.

Configurazione Tuya LAN

Per usare la station via Wi-Fi locale devi fornire:

  • host o IP della station;
  • device ID;
  • local key;
  • protocol version, di solito 3.5;
  • poll interval.

Tradotto in modo semplice:

Campo Cosa ci va dentro
Host o IP L'indirizzo della station nella tua LAN. Meglio fissarlo dal router con una prenotazione DHCP.
Device ID L'identificativo Tuya della tua station. Non e' il nome modello.
Local key La chiave locale Tuya del singolo dispositivo. Non e' la password Wi-Fi e non e' la password Inkbird.
Protocol version Di solito 3.5 per la station INT-14-BW testata.
Poll interval Ogni quanti secondi Home Assistant interroga la station. Parti da 10.

La local key non viene recuperata automaticamente dall'integrazione. Devi ottenerla dal tuo dispositivo/account con un metodo Tuya/local-key esterno, poi incollarla nel setup o nelle opzioni di Home Assistant. Se usi gia LocalTuya, TinyTuya o un altro tool Tuya LAN per la stessa station, sono lo stesso tipo di valori. Segui la documentazione aggiornata di quei tool per estrarre la key. Se resetti o riassoci la station, la local key puo' cambiare.

Come recupero device ID e local key?

Questa integrazione non chiede credenziali cloud Tuya. Le servono solo i valori locali finali della tua station.

Strade pratiche:

  1. Se la station e' gia configurata in LocalTuya, Tuya Local o un altro tool Tuya LAN, riusa gli stessi valori: IP/host, device ID, local key e protocol version.
  2. TinyTuya puo scansionare la LAN e avviare il wizard:
python -m pip install tinytuya
python -m tinytuya scan
python -m tinytuya wizard

Dopo il wizard cerca la station in devices.json. I campi utili sono normalmente:

{
  "name": "example name",
  "id": "example-device-id",
  "key": "example-local-key",
  "ip": "192.0.2.10",
  "version": "3.5"
}
  1. Il portale Tuya IoT puo mostrare gli stessi dati dopo aver collegato l'account app che possiede il dispositivo. Di solito si passa da progetto cloud, lista device, API Explorer e query dei dettagli dispositivo.

devices.json, device ID, local key, API key e API secret sono segreti. Non caricarli su GitHub e non incollarli nelle issue.

Riferimenti utili:

Sequenza consigliata:

  1. configura la station nell'app Inkbird e verifica che il Wi-Fi funzioni;
  2. assegna un IP fisso alla station dal router, se puoi;
  3. recupera device ID e local key della tua station;
  4. in Home Assistant apri Settings -> Devices & services -> Inkbird INT;
  5. inserisci host/IP, device ID, local key, versione 3.5 e poll interval 10;
  6. abilita il test LAN prima del salvataggio se vuoi una verifica immediata;
  7. lascia il transport mode su Auto per l'uso normale.

Questi valori sono personali e non devono essere pubblicati in issue o screenshot. Se chiedi aiuto, sostituiscili con placeholder.

La LAN e' utile per polling stabile quando la station e' connessa al Wi-Fi. In Auto, l'integrazione preferisce LAN se e' configurata in modo completo.

Modalita' trasporto

Auto

Usa la scelta piu' sensata. Se LAN e' configurata, tende a usare LAN per non tenere BLE continuamente attivo.

BLE only

Forza il percorso BLE. In base al profilo puo significare snapshot e comandi locali supportati oppure una sessione GATT continua e read-only. Su INT-12E-BW le notifiche vengono applicate subito e l'intervallo di lettura diretta e' solo un recupero.

Wi-Fi LAN only

Usa solo Tuya LAN locale. Richiede host, device ID e local key corretti.

Wi-Fi cloud only

Usa solo lo storico cloud sperimentale e read-only, se configurato.

Entita' principali

L'integrazione espone solo le entita sensate per il profilo scelto. In base al modello possono esserci:

  • temperatura station/base;
  • temperatura core delle sonde previste dal profilo;
  • temperatura ambiente delle sonde previste dal profilo, quando disponibile;
  • stato connessione/charging/paired delle sonde;
  • batteria station;
  • batteria sonde quando la station la riporta;
  • stato trasporto attivo;
  • stato LAN/cloud/BLE;
  • target high/low;
  • timer;
  • pre-alarm;
  • calibrazione;
  • unita' C/F;
  • backlight/display.

Molte entita' grezze o fragili sono diagnostiche o disabilitate di default. La scelta e' voluta: meglio una dashboard pulita e qualche diagnostica attivabile quando serve, invece di cinquanta entita' sconosciute in prima pagina.

Batteria sonde al 100%

Durante i test locali autenticati la station puo' continuare a riportare le sonde al 100% anche quando e' improbabile che siano tutte realmente al 100%.

Per questo l'integrazione:

  • mantiene il valore numerico quando il dato e' fresco;
  • non nasconde il valore;
  • aggiunge Battery Report Quality;
  • aggiunge sensori/binary sensor diagnostici suspect.

Se vedi suspect_probe_100_plateau, significa che la station ha riportato un plateau sospetto, non che Home Assistant abbia corretto o inventato un valore.

Scritture supportate

Le scritture locali usano LAN quando disponibile e BLE quando sia il trasporto sia il profilo modello lo consentono. INT-14S-BW, INT-12E-BW e INT-11I-B restano read-only nell'uso normale.

Comandi previsti:

  • unita' C/F;
  • display/backlight;
  • target temperatura;
  • pre-alarm;
  • timer;
  • timer reset;
  • calibrazione.

Le scritture possono dipendere dal firmware e dallo stato radio. Dopo una scrittura, controlla il readback o la UI della station.

Cloud history sperimentale

La parte cloud e':

  • opzionale;
  • disabilitata di default;
  • solo read-only;
  • limitata allo storico DP109;
  • non usata per write.

Non usare credenziali cloud in issue pubbliche.

Privacy

Non pubblicare:

  • BLE address reale;
  • IP LAN reale;
  • local key;
  • device ID;
  • token;
  • API secret;
  • screenshot con dati privati;
  • entity ID della tua installazione se contengono nomi personali.

Usa placeholder come:

AA:BB:CC:DD:EE:FF
192.0.2.10
example-device-id
example-local-key

Commenti e supporto

Per domande generali o confronto usa Discussions:

https://github.com/zampix1/ha-inkbird-int14/discussions

Per bug riproducibili usa Issues:

https://github.com/zampix1/ha-inkbird-int14/issues

Includi sempre:

  • modello esatto;
  • firmware se visibile;
  • trasporto usato;
  • log filtrato senza segreti;
  • cosa ti aspettavi;
  • cosa hai visto.

Clone this wiki locally