TapHome

Xiaomi 1T (Valetudo)

Packet Parser → HTTP
Inviato da
Ultimo aggiornamento: 03. 2026
Xiaomi 1T (Valetudo)

Lo Xiaomi Mijia 1T (STYTJ02ZHM) è un robot aspirapolvere-lavapavimenti prodotto da Dreame e venduto con il marchio Xiaomi. Questo template richiede Valetudo — un firmware open-source che sostituisce la dipendenza dal cloud del produttore con un’API HTTP locale. Una volta installato Valetudo sul robot, TapHome comunica direttamente con la Valetudo REST API v2 sulla rete locale. Non è necessaria alcuna connessione cloud o autenticazione.

Il template fornisce monitoraggio della batteria, un indicatore di stato multivalore e pulsanti per avviare, mettere in pausa, fermare e riportare alla base l’aspirapolvere. La funzione di localizzazione emette un segnale acustico per aiutare a trovare il robot.

Valetudo deve essere installato sul robot prima di poter utilizzare questo template. Il template comunica con l’API HTTP di Valetudo, non con i servizi cloud di Xiaomi. Il rooting dello Xiaomi 1T richiede un adattatore USB-UART da 3,3 V e un Dreame Breakout PCB — consulta la pagina dei robot supportati da Valetudo per istruzioni dettagliate.

Configurazione

Durante l’importazione del template, inserisci l’indirizzo IP del robot sulla rete locale (il segnaposto predefinito è 192.168.0.1). La Valetudo REST API ascolta sulla porta 80 senza autenticazione.

Poiché Valetudo non espone un hostname mDNS, assegna al robot un indirizzo IP statico o una prenotazione DHCP per evitare che l’indirizzo cambi dopo un riavvio della rete.

Apri http://<robot-ip>/swagger/ nel browser per esplorare interattivamente tutti gli endpoint API di Valetudo disponibili. È utile per verificare la connettività e ispezionare lo stato attuale del robot.

Capacità del dispositivo

Livello batteria

Il template legge lo stato di carica della batteria dalla risposta di /api/v2/robot/state/attributes. Analizza BatteryStateAttribute.level (riportato come 0–100) e divide per 100 per produrre un intervallo 0,0–1,0 per TapHome. Il valore si aggiorna ogni 2,5 secondi.

Stato aspirapolvere

Uno switch multivalore mostra lo stato operativo attuale del robot. Il template analizza StatusStateAttribute.value dalla risposta degli attributi di stato e lo mappa a un indice intero:

StatoValoreDescrizione
Docked0Il robot è sulla base di ricarica
Cleaning1Ciclo di pulizia attivo
Returning2Ritorno alla base
Paused3Pulizia in pausa
Idle4Non in pulizia, non agganciato
Unknown9Stato non riconosciuto

L’API Valetudo può anche riportare gli stati error, manual_control e moving — questi non sono mappati individualmente e appariranno come “Unknown” (valore 9).

Controlli aspirapolvere

Quattro pulsanti controllano l’aspirapolvere tramite l’endpoint BasicControlCapability:

  • Start — avvia un ciclo di pulizia completo
  • Pause — mette in pausa l’operazione di pulizia corrente
  • Stop — ferma l’operazione di pulizia corrente
  • Home — riporta il robot alla base di ricarica

Ogni pulsante invia una richiesta PUT a /api/v2/robot/capabilities/BasicControlCapability con l’azione corrispondente.

Localizzazione

Il pulsante Locate emette un suono udibile sul robot tramite l’endpoint LocateCapability. È utile per trovare il robot quando è bloccato o in una posizione inaspettata.

Capacità aggiuntive

L’API Valetudo espone diverse capacità non attualmente implementate nel template: controllo velocità ventilatore (preset potenza di aspirazione), controllo utilizzo acqua (intensità lavaggio), pulizia a zone, navigazione verso un punto specifico, istantanee mappa, monitoraggio materiali di consumo (filtro, spazzole, sensori), volume altoparlante, pianificazione non disturbare, stato di carica e potenza segnale WiFi. Queste possono essere aggiunte in un futuro aggiornamento del template.

Risoluzione dei problemi

Il dispositivo non risponde
  1. Verifica che il robot sia acceso, connesso al Wi-Fi e abbia un indirizzo IP valido
  2. Apri http://<robot-ip>/ nel browser — se l’interfaccia web di Valetudo si carica, l’API è raggiungibile
  3. Controlla che TapHome e il robot siano sulla stessa rete o VLAN
  4. Conferma che Valetudo è in esecuzione — se il robot è stato ripristinato alle impostazioni di fabbrica, potrebbe essere necessario reinstallare Valetudo
Lo stato mostra “Unknown” (???)

Il template mappa cinque stati (docked, cleaning, returning, paused, idle). Se il robot riporta error, manual_control o moving, lo stato apparirà come “Unknown” (valore 9). Questo è un comportamento atteso — gli stati non mappati si verificano in casi limite come il controllo remoto manuale o il recupero da errori.

Il livello batteria mostra zero
  1. Conferma che Valetudo è in esecuzione e l’API risponde su /api/v2/robot/state/attributes
  2. Verifica che la risposta contenga una voce BatteryStateAttribute con un valore level diverso da zero
  3. Se il robot è stato riavviato di recente, attendi il completamento del primo polling dello stato

Dispositivi disponibili

Xiaomi 1T (Valetudo) Modulo
Variabili personalizzate

Xiaomi 1T (Valetudo)

Lettura (modulo)
VAR response := SENDHTTPREQUEST("/api/v2/robot/state/attributes");
IF response.IsSuccess
 state := response.Content;
ELSE
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
Livello batteria Ingresso analogico Solo lettura

Stato di carica della batteria — percentuale di energia residua (0–100%)

numeric Unità: %

Livello batteria

Lettura livello ingresso
PARSEJSON(state, "$[?(@.__class == 'BatteryStateAttribute')].level") / 100
Home Pulsante
action

Home

Scrittura stato pulsante
VAR response := SENDHTTPREQUEST("/api/v2/robot/capabilities/BasicControlCapability", "PUT", "{\"action\": \"home\"}", "accept: */*", "Content-Type: application/json");
IF response.IsSuccess
 var res := response.Content;
ELSE
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
Localizza Pulsante

Emette un segnale acustico sul robot per aiutare a trovarlo

action

Localizza

Scrittura stato pulsante
VAR response := SENDHTTPREQUEST("/api/v2/robot/capabilities/LocateCapability", "PUT", "{\"action\": \"locate\"}", "accept: */*", "Content-Type: application/json");
IF response.IsSuccess
 var res := response.Content;
ELSE
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
Pausa Pulsante
action

Pausa

Scrittura stato pulsante
VAR response := SENDHTTPREQUEST("/api/v2/robot/capabilities/BasicControlCapability", "PUT", "{\"action\": \"pause\"}", "accept: */*", "Content-Type: application/json");
IF response.IsSuccess
 var res := response.Content;
ELSE
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
Avvio Pulsante
action

Avvio

Scrittura stato pulsante
VAR response := SENDHTTPREQUEST("/api/v2/robot/capabilities/BasicControlCapability", "PUT", "{\"action\": \"start\"}", "accept: */*", "Content-Type: application/json");
IF response.IsSuccess
 var res := response.Content;
ELSE
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
Stato aspirapolvere Interruttore multivalore Solo lettura

Stato operativo attuale — Docked, Cleaning, Returning, Paused, Idle o Unknown

enum mapped
Valori / Stati: Docked · Cleaning · Returning · Paused · Idle · ???

Stato aspirapolvere

Lettura stato interruttore
var status := PARSEJSON(state, "$[?(@.__class == 'StatusStateAttribute')].value");

switch(status,
"docked", 0,
"cleaning", 1,
"returning", 2,
"paused", 3,
"idle", 4,
9);
Stop Pulsante
action

Stop

Scrittura stato pulsante
VAR response := SENDHTTPREQUEST("/api/v2/robot/capabilities/BasicControlCapability", "PUT", "{\"action\": \"stop\"}", "accept: */*", "Content-Type: application/json");
IF response.IsSuccess
 var res := response.Content;
ELSE
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
Connessione: Packet Parser → HTTP
Possibili miglioramenti (10)
  • Fan speed control — Set suction power level (low, medium, high, max). Available via PUT with preset value.
  • Water usage control — Set mopping water flow level (low, medium, high). Available on models with mopping support.
  • Map snapshot — Retrieve current map as PNG image. Available via GET.
  • Zone cleaning — Start cleaning of specific zones defined by coordinates.
  • Go to location — Send robot to specific coordinates on the map.
  • Consumable monitoring — Read remaining life of filter, main brush, side brush, and sensor. Percentage or hours remaining.
  • Charging status — Battery charging state (charging, discharging, charged). Available in state attributes alongside battery level.
  • Speaker volume — Set robot speaker volume level (0-100).
  • Do not disturb — Enable/disable DND mode with start/end time.
  • WiFi signal strength — WiFi RSSI and signal quality. Available in state attributes response.

Fonti