🌱 Pollice Verde

App per gestire orto e frutteto: dice cosa fare, quando, e soprattutto quanta acqua dare a ogni coltura, calcolandolo sul meteo reale della tua zona invece che su un calendario fisso.

Funziona nel browser, si installa sulla schermata home del telefono e resta consultabile anche senza rete in giardino. Nessun account, nessun server: i dati vivono nel browser del tuo dispositivo.

Riprendi da qui: DOMANI.md — dove siamo, come si riparte e cosa fare nell'ordine giusto.

Avvio

npm install
npm run dev      # sviluppo, http://localhost:5173
npm run build    # versione ottimizzata in dist/
npm run preview  # prova la build, anche da telefono sulla rete di casa

Per usarla dal telefono: lancia npm run preview, apri sul telefono l'indirizzo Network: che compare nel terminale (computer e telefono sulla stessa rete Wi-Fi), poi "Aggiungi a schermata Home".

Per averla sempre disponibile senza tenere acceso il computer, la cartella dist/ è un sito statico: caricala su un qualsiasi hosting gratuito (Netlify, Vercel, GitHub Pages) e avrai un indirizzo tuo.

Cosa fa

Sezione	A cosa serve
Oggi	Meteo, allerte (gelate, ondate di calore, vento, piogge lunghe), cosa bagnare adesso e con quanti litri, operazioni del mese
Giardino	Aiuole (terreno, metodo irriguo, pacciamatura, serra, vaso) e colture piantate, con avvisi di rotazione
Acqua	Per ogni coltura: riserva d'acqua nel terreno, consumo giornaliero, dose, minuti di impianto, andamento a 31 giorni
Turni	Programma pronto per una centralina a settori: minuti e intervallo da impostare, giorni esatti con le piogge già scontate, avvisi su settori mal raggruppati e turni troppo lunghi. Con l'agente collegato, anche il pannello di comando delle valvole
Guida	58 schede fra ortaggi, frutta e aromatiche: calendario, sesti, consociazioni, cure, problemi tipici e rimedi. La ricerca capisce i nomi dialettali: cocomero, popone, petonciano, ramerino, rughetta, granoturco
Diario	Registro di irrigazioni, concimazioni, trattamenti, potature e raccolti

Come viene calcolata l'irrigazione

Il metodo è quello FAO-56, lo stesso usato dai consorzi irrigui, riportato alla scala di un orto familiare.

Il terreno è trattato come un serbatoio:

1. Capacità — dipende dal tipo di suolo (un terreno franco trattiene 160 mm d'acqua per metro di profondità, uno sabbioso 80) moltiplicato per la profondità delle radici di quella specie. Un pomodoro su terreno franco ha a disposizione ~128 mm; un'insalata su sabbia ~24.
2. Prelievo — ogni giorno la pianta consuma ET0 × Kc, dove ET0 è l'evapotraspirazione di riferimento misurata dal servizio meteo e Kc un coefficiente che dipende dalla specie e dalla fase in cui si trova.
3. Ricarica — pioggia (al netto dei primi millimetri che evaporano) e irrigazioni registrate, corrette per l'efficienza del metodo: a goccia arriva alle radici il 90% dell'acqua, con l'aspersore il 65%.
4. Soglia — quando il consumo raggiunge la frazione di riserva che quella specie tollera (il sedano soffre già al 20%, l'olivo regge fino al 65%) è il momento di irrigare, e la dose è l'acqua mancante.

Il bilancio viene ricostruito sui 21 giorni passati con dati meteo reali e proiettato sui 10 giorni di previsione, così l'app sa dire anche fra quanti giorni servirà la prossima irrigazione — e quando conviene saltare un turno perché sta per piovere.

La soglia di intervento non coincide con la soglia di stress e dipende dal metodo: con la goccia si bagna al 55% della riserva utile (turni brevi e frequenti, bulbo umido costante), con l'aspersione all'85%, irrigando a mano si sfrutta tutta la riserva con turni radi e abbondanti.

Correzioni applicate: pacciamatura (−25% di consumo, regolabile), serra (−25% di evaporazione e nessun apporto di pioggia), coltura in vaso (il serbatoio è il terriccio, non il terreno).

Automazione con una centralina

La sezione Turni traduce il calcolo in qualcosa da digitare sulla centralina. Per ogni aiuola con un'elettrovalvola serve indicare, nel form dell'aiuola, il settore (il nome della stazione) e la portata, in litri/ora del settore oppure per m². La portata si misura meglio di quanto si calcoli: apri solo quella valvola, raccogli per un minuto l'acqua di un gocciolatore, moltiplica per il numero di gocciolatori e per 60.

L'app produce due cose diverse, perché rispondono a due domande diverse:

• il programma fisso — intervallo e minuti di regime, simulati a terreno in equilibrio e tempo asciutto: è il caso peggiore, quello da lasciare impostato sulla centralina;
• i giorni esatti — la sequenza reale dei prossimi 10 giorni, che parte dall'acqua che c'è adesso nel terreno, recupera l'eventuale arretrato e sconta le piogge previste.

Su un settore con più colture il programma è tarato sulla più esigente, e l'app avvisa quando su una stessa valvola convivono piante con ritmi troppo diversi (l'insalata vuole acqua ogni tre giorni, l'olivo ogni tre settimane).

Controllo automatico delle valvole

L'apertura vera è gestita dall'agente (agente/): un piccolo programma Node che gira su qualcosa di sempre acceso — Raspberry Pi, NAS, vecchio portatile — e fa tre cose:

1. custodisce lo stato del giardino, che l'app legge e aggiorna via rete;
2. all'orario stabilito calcola il programma del giorno e apre le valvole, un settore alla volta;
3. registra nel diario quello che ha davvero erogato, così il bilancio idrico resta agganciato alla realtà.

npm run agente        # compila app e agente, poi lo avvia sulla porta 8088

L'agente serve anche l'app compilata: apri http://<ip-della-macchina>:8088 dal telefono e hai tutto. Sta in HTTP sulla rete locale di proposito — è l'unico modo perché una pagina possa parlare con dispositivi locali senza inciampare nel blocco dei contenuti misti. Non esporlo su internet.

Dispositivi supportati: ESP32 col firmware incluso (firmware/), Shelly Gen 1 e Gen 2, Tasmota, più la modalità simulata che è quella predefinita.

Sicurezze

L'automazione parte sempre spenta e va attivata a mano. Quando è attiva:

Blocco	Cosa fa
Minuti massimi per turno	Tronca i turni troppo lunghi (predefinito 180)
Litri massimi al giorno	Tetto su tutto il giardino (predefinito 2000)
Blocco gelo	Niente acqua con minima sotto 3 °C
Blocco vento	Salta i settori ad aspersione sopra 30 km/h
Blocco pioggia	Annulla il turno se sono previsti più di 5 mm
Veto delle sonde	Se una sonda misura il terreno ancora umido, il turno salta: la misura batte la stima
Sonda guasta o muta	Un settore con sonda scollegata, in corto o senza letture recenti non viene irrigato
Canale mancante	Un'aiuola senza canale assegnato non viene mai aperta
Chiusura all'avvio	L'agente chiude tutto all'accensione e all'uscita
Doppia chiusura a tempo	La durata è nota anche al dispositivo: se l'agente muore, l'acqua si chiude lo stesso
Un settore per volta	Mai due valvole aperte insieme

La prova a secco (Turni → Prova a secco) usa sempre il driver simulato: non fa scattare i relè nemmeno per un istante.

Sonde nel terreno (Watermark)

Il bilancio idrico è un modello: bravo a prevedere, ma cieco. Una sonda Watermark 200SS misura la tensione idrica reale in kPa — la fatica che la radice fa per estrarre l'acqua — e il sistema la usa in tre modi:

• veto: se prima di un turno il terreno risulta ancora umido, il turno salta;
• riancoraggio: quando una sonda legge la capacità di campo (≤ 15 kPa), il bilancio riparte da un dato misurato invece che da una stima;
• confronto: nella sezione Acqua, sonda e calcolo vengono messi a confronto, e quando non vanno d'accordo l'app dice quale manopola guardare.

Soglie di intervento predefinite, in kPa: sabbioso 25, franco-sabbioso 30, franco 40, franco-argilloso 50, argilloso 60. Modificabili per singola aiuola.

Il firmware legge le sonde in corrente alternata (due misure a polarità invertita da 50 µs) e converte resistenza in kPa con le equazioni di Shock, Barnum e Seddigh, le stesse usate da Irrometer, con compensazione della temperatura del terreno. Schema di collegamento e istruzioni di posa in firmware/README.md.

Restano fuori portata di un'app nel browser le notifiche ad app chiusa: per quelle servirebbe un servizio di push o un bot di messaggistica sull'agente.

Struttura

src/
  lib/
    types.ts             modello dati
    colture.ts           indice delle colture
    colture.ortaggi.ts   30 ortaggi con coefficienti FAO-56 e schede colturali
    colture.aromatiche.ts 9 aromatiche
    colture.frutta.ts    19 fruttiferi
    meteo.ts             client Open-Meteo (geocoding, previsioni, cache offline)
    irrigazione.ts       motore a bilancio idrico
    programma.ts         generatore del programma per centraline a settori
    agente.ts            client dell'agente della centralina
    sonde.ts             soglie, livelli e confronto sonda/calcolo
    attivita.ts          operazioni del mese, allerte meteo, rotazioni
  state/
    store.tsx            stato dell'app, persistenza in localStorage
    consigli.ts          calcolo dei consigli per tutte le piantagioni
  pages/                 le sette schermate
  components/comuni.tsx  modale, campi, barre, grafico del bilancio
public/
  sw.js                  service worker per l'uso offline
  manifest.webmanifest   installazione come app
agente/
  src/agente.ts          pianificazione, esecuzione dei turni, registro
  src/server.ts          server HTTP e orologio di partenza
  src/driver.ts          ESP32, Shelly Gen1/Gen2, Tasmota, simulato
  src/sicurezza.ts       blocchi gelo, vento, pioggia, sonde, tetti giornalieri
  src/sonde.ts           lettura delle Watermark dal dispositivo
firmware/
  pollice-verde-esp32.ino  firmware ESP32: relè, sonde Watermark, chiusura a tempo

Fonti

• Meteo ed evapotraspirazione: Open-Meteo — gratuito, senza chiave API.
• Coefficienti colturali, profondità radicali e fattori di deplezione: FAO Irrigation and Drainage Paper 56, Crop evapotranspiration.

Nota

Il calcolo è una stima molto buona ma non conosce il tuo microclima: l'ombra del muro a nord, la zona che resta sempre umida, il vento che secca un angolo. Usalo come guida e verifica col dito nel terreno — due falangi: se esce asciutto è ora di bagnare. Dopo qualche settimana saprai di quanto correggere, e le manopole in Impostazioni servono a quello.