Premium · per chi ha già un impianto

Far mandare le misure al termostato

Se hai già un termostato o un igrometro WiFi, non c'è motivo di ricopiare i numeri a mano. Squamy ti dà una chiave e un indirizzo: il tuo impianto ci manda la misura, e la trovi nell'app al prossimo giro di sincronizzazione.

Perché funziona al contrario

La domanda naturale è: perché non ci pensate voi a leggere il mio termostato? Due ragioni, e nessuna delle due si risolve scrivendo codice.

La prima è che per leggere i tuoi sensori dovremmo custodire le credenziali del tuo account SmartLife. Sarebbero i dati più delicati di tutto il prodotto — più dei dati dei tuoi terrari, che a perderli non succede niente a nessuno — e la responsabilità di una fuga sarebbe nostra.

La seconda è che il piano gratuito delle API di Tuya, quelle dietro SmartLife e buona parte dei termostati da venti euro, è dichiaratamente «solo per sviluppo». Per usarlo davvero serve un contratto commerciale, con un costo che non sta in piedi per un abbonamento da 3,99 € al mese.

Invertendo la direzione spariscono entrambe le cose. E in cambio la copertura non è più «le marche che siamo riusciti a integrare», ma qualunque cosa sappia fare una richiesta HTTP: un insieme molto più grande di qualunque elenco avremmo potuto costruire.

Come si comincia

1. Nell'app: menù → API e integrazioni. Serve il Premium.
2. Accendi «Ingestione attiva». Da spenta nessuna chiave scrive: è l'interruttore che ferma tutto insieme se un giorno ti serve.
3. Crea una chiave e dalle un nome che ti dica dove l'hai messa («Home Assistant», «Raspberry sala»).
4. Copiala subito. Si vede una volta sola: sul server ne resta solo l'impronta, quindi nemmeno noi possiamo mostrartela di nuovo. Se la perdi ne generi un'altra, che costa un tocco.
5. Nella stessa schermata trovi gli esempi già compilati col tuo terrario, e un bottone «Prova la chiamata» che manda la richiesta vera senza salvare niente.

Mandare una misura

Una richiesta POST, con la chiave nell'header e tre campi nel corpo:

curl -X POST https://<progetto>.supabase.co/functions/v1/api/v1/readings \
  -H "Authorization: Bearer sqk_LA_TUA_CHIAVE" \
  -H "Content-Type: application/json" \
  -d '{"enclosure": "Deserto 120", "parameter": "temp_hot", "value": 31.4, "unit": "°C"}'

Il terrario si indica per nome, come lo chiami nell'app — nessuno vuole incollare un identificatore in un file di configurazione. Vanno bene anche l'id e gli alias. Se hai due terrari con lo stesso nome la richiesta viene rifiutata invece di scegliere a caso: due terrari diversi ospitano specie diverse e hanno bande di temperatura diverse, quindi una misura finita nel posto sbagliato non è un grafico storto, è un allarme che non scatta.

L'unità è facoltativa (senza, vale quella di riferimento del parametro) e si può scrivere come viene: C, celsius, °C. Anche il valore accetta la virgola: "31,4" va bene, perché è quello che produce un template con la lingua italiana.

I parametri

Chiave	Cos'è	Unità
temp_hot	Punto caldo	°C · °F · K
temp_cool	Punto freddo	°C · °F · K
temp_night	Temperatura notturna	°C · °F · K
substrate_temp	Temperatura del substrato	°C · °F · K
humidity	Umidità	%
uvi	Indice UV	UVI

Se hai creato parametri tuoi, funzionano anche quelli, con la loro unità.

Home Assistant

È il sistema da cui arriva la maggior parte delle integrazioni: chi ce l'ha ha già dentro i sensori Tuya, Zigbee e Bluetooth. Nel configuration.yaml:

rest_command:
  squamy_temp_hot:
    url: "https://<progetto>.supabase.co/functions/v1/api/v1/readings"
    method: POST
    headers:
      Authorization: "Bearer sqk_LA_TUA_CHIAVE"
      Content-Type: "application/json"
    payload: >-
      {"enclosure": "Deserto 120", "parameter": "temp_hot",
       "value": {{ states("sensor.temp_hot_terrario") }} }

Poi un'automazione che lo chiami ogni ora. L'app ti dà questo stesso blocco già compilato col nome del tuo terrario: conviene copiarlo da lì.

Quanto spesso

Parametro	Una misura ogni
Le quattro temperature e l'umidità	60 minuti
Indice UV e parametri tuoi	24 ore

Più in fretta non serve: un valore ogni cinque minuti non aggiunge informazione, aggiunge righe e grafici illeggibili. Temperature e umidità stanno insieme perché sono le due cose che un impianto misura davvero in continuo — e l'umidità in un terrario oscilla nella giornata più della temperatura, fra nebulizzazione e ricambio d'aria. L'indice UV invece si misura con uno strumento puntato a mano, una volta ogni tanto.

C'è anche un tetto di 500 richieste al giorno per chiave. Con i ritmi qui sopra ne consumi qualche decina: serve a fermare un'automazione impazzita, non te.

Se mandi troppo in fretta la risposta è 429 e ti dice fra quanti secondi riprovare. Una misura scritta a mano nell'app non conta: il conto guarda solo quelle arrivate dall'API, perché sono due gesti diversi che possono convivere nella stessa giornata.

Se qualcosa non va

Risposta	Cosa vuol dire
401 invalid_token	La chiave non esiste o è stata revocata.
403 api_disabled	L'interruttore è spento nell'app.
403 premium_required	L'abbonamento collegato alla chiave non è attivo.
400 unknown_enclosure	Nessun terrario con quel nome. Chiedi l'elenco con GET /v1/enclosures.
400 ambiguous_enclosure	Due terrari si chiamano uguale: usa l'id, che la risposta ti riporta.
400 bad_measured_at	La data è nel futuro o di più di un anno fa. Quasi sempre è l'orologio del dispositivo, o un timestamp in secondi letto come millisecondi.
429 too_soon	Troppo presto per quel parametro: la risposta dice quanto aspettare.

Ogni risposta porta un message in inglese scritto per essere letto da una persona: se un'automazione non funziona, quello è il posto dove guardare.

Le domande che si fanno tutti

Se disdico il Premium perdo la chiave? No, la chiave resta: semplicemente smette di scrivere. Se rinnovi, le tue integrazioni ripartono senza rimettere le mani nei file di configurazione.

Posso vedere quali misure sono arrivate dal sensore? Sì. Ogni lettura resta segnata con la sua provenienza, e nello storico distingui quelle del sensore da quelle scritte da te.

Posso revocare una chiave? Quando vuoi, dall'app. E spegnere l'interruttore le ferma tutte insieme, subito, senza doverle revocare una per una.

Torna alle FAQ