polliceverde/DOMANI.md

# Guida per domani

Dove siamo arrivati e cosa conviene fare, nell'ordine giusto.

---

## Come si riparte

Dalla cartella del progetto:

```bash
npm run dev       # solo l'app, con ricarica automatica → http://localhost:5173
npm run agente    # app + centralina insieme → http://localhost:8088
```

Usa `npm run agente` se vuoi lavorare sull'irrigazione automatica, `npm run dev`
se stai solo mettendo mano al codice.

L'indirizzo da aprire dal telefono (stessa Wi-Fi) è quello di rete della macchina
su cui gira l'agente, sulla porta 8088. Per trovarlo: `ipconfig getifaddr en0`.

Tutto è su **https://github.com/luzadev/polliceverde**, un solo commit, niente in
sospeso.

---

## Cosa c'è già

**L'app** — sei sezioni: Oggi (meteo, allerte, cosa bagnare adesso), Orto (aiuole
e colture), Acqua (bilancio idrico per coltura), Turni (programma per la
centralina), Guida (58 schede di ortaggi, frutta e aromatiche), Diario.

**Il motore idrico** — metodo FAO-56: il terreno come serbatoio, consumo
giornaliero pari a evapotraspirazione per coefficiente colturale, ricarica da
pioggia e irrigazioni. Ricostruito su 21 giorni reali e proiettato su 10 di
previsione.

**L'automazione** — un agente Node che apre le valvole all'orario stabilito, un
settore alla volta, e registra nel diario quello che ha erogato. Driver per
ESP32, Shelly e Tasmota. Parte sempre in simulazione.

**Le sonde Watermark** — veto sui turni, riancoraggio del bilancio, confronto fra
misura e calcolo. Firmware ESP32 pronto in `firmware/`.

---

## Da fare domani, in ordine

### 1. Metti dentro il giardino vero

È il passo da cui dipende tutto il resto, ed è anche l'unico che non posso fare
io. In *Orto* → **+ Aiuola**, una per ogni gruppo di piante che condivide terreno
e impianto.

Per ogni aiuola servono: **superficie** in m² (la proiezione della chioma per gli
alberi, non tutto il giardino), **tipo di terreno**, **metodo di irrigazione**,
ed eventualmente pacciamatura e serra.

Per il tipo di terreno, se non lo sai: inumidisci una manciata di terra e prova a
farne un salsicciotto. Si sbriciola subito → sabbioso. Si modella ma si spezza
piegandolo → franco. Fai un anello senza crepe → argilloso.

Poi **+ Pianta qui** per ogni coltura. Per le piante perenni che c'erano già,
scegli la scorciatoia **"C'era già"**: se lasci la data di oggi, l'app crede che
il terreno sia stato appena bagnato all'impianto e per qualche giorno ti dirà che
va tutto bene anche se è secco.

### 2. Misura la portata di ogni settore

Serve a trasformare i millimetri in minuti di valvola aperta, e misurarla è molto
più affidabile che calcolarla dalle schede tecniche: la pressione di casa tua non
è quella nominale.

Apri **una sola** valvola, raccogli per un minuto esatto l'acqua di un
gocciolatore, moltiplica per il numero di gocciolatori del settore e per 60.
Il risultato va in *Orto → modifica aiuola → **Portata del settore (litri/ora)***.

Nella stessa schermata metti il **canale** (l'uscita a relè, si conta da 0) e il
nome del **settore** sulla centralina.

### 3. Collega l'app all'agente

Avvia `npm run agente` e apri l'app **dall'indirizzo dell'agente** (porta 8088),
non dalla 5173. In *Impostazioni → Centralina* scrivi quell'indirizzo nel campo
**Indirizzo dell'agente**.

> ⚠️ Attenzione a un dettaglio che fa perdere lavoro: i dati stanno nel
> `localStorage` del browser, che è **separato per ogni indirizzo**. Se hai già
> inserito il giardino sulla 5173 e poi apri la 8088, trovi tutto vuoto. Prima di
> cambiare porta fai *Impostazioni → **Esporta backup*** e importalo dall'altra
> parte. Poi lavora sempre e solo sulla 8088.

### 4. Lascia tutto in simulazione e verifica col dito

Per **una o due settimane** tieni il driver su *Simulato*. L'agente calcola,
scrive nel registro cosa farebbe, e non tocca niente.

Nel frattempo fai la prova che conta: quando l'app dice di irrigare, prima infila
il dito nel terreno a 15-20 cm. Se le due cose concordano, del calcolo ti puoi
fidare. Se l'app anticipa o ritarda sistematicamente, le manopole sono in
*Impostazioni → Taratura del calcolo* (efficienza dei metodi e risparmio della
pacciamatura).

Registra le irrigazioni che fai, anche quelle a mano: è quello che aggancia il
bilancio alla realtà. Finché non c'è nessuna irrigazione registrata per una
coltura, l'app scrive **"stima provvisoria"** in giallo, e ha ragione.

### 5. Quando arrivano le sonde Watermark

Prima di interrarle, **provale in un bicchiere d'acqua**: dopo dieci minuti
`/sensori` deve leggere 0-5 kPa. Lasciale asciugare all'aria un giorno e devono
salire oltre 100 kPa. Se restano inchiodate, il problema è nel cablaggio.

Per la posa: a **metà della profondità delle radici** (15-20 cm per l'orto, 30-40
per un albero) e a 15-20 cm **di lato** dal gocciolatore, mai sotto — sotto
misureresti il bulbo bagnato, non il terreno che la pianta esplora. Fai il foro
con una punta di legno, bagna la sonda prima di inserirla, e versa un po' di
terra stemperata nel foro: una sonda con aria attorno legge sempre secco.

Poi assegnale alle aiuole in *Orto → modifica aiuola → **Sonda Watermark***.

Schema di collegamento completo in `firmware/README.md`.

### 6. Solo alla fine, accendi l'automazione

Nell'ordine, prima di attivarla: prova **ogni canale a mano** dal pannello in
*Turni* e verifica che apra la valvola giusta; controlla che le sicurezze
(minuti e litri massimi) siano tarate sul tuo impianto; fai una **prova a secco**
e guarda se i risultati hanno senso.

Poi *Impostazioni → Centralina → **Automazione attiva***. Ti chiede conferma.

Il pulsante rosso **Chiudi tutto** in *Turni* è sempre lì.

---

## Cose che è utile sapere

**I turni non sono a intervallo fisso.** In *Turni* trovi due cose diverse: il
*programma fisso* è il ritmo di regime, simulato a terreno in equilibrio e tempo
asciutto — il caso peggiore, quello da lasciare impostato sulla centralina. I
*giorni esatti* partono invece dall'acqua che c'è adesso e scontano le piogge
previste. Ricontrollali una volta a settimana.

**Fai un backup ogni tanto.** *Impostazioni → Esporta backup*. Se svuoti i dati
del browser, il giardino sparisce. Con l'agente collegato il rischio è minore,
perché lo stato vive anche in `agente/dati/stato.json`, ma quel file non è nel
repo (giustamente: sono dati tuoi, e il repo è pubblico).

**L'app funziona offline**, ma il meteo no: senza rete usa l'ultima previsione
scaricata. In giardino va benissimo; dopo qualche giorno senza connessione, meno.

**In caso di dubbio il sistema si ferma.** Sonda guasta, dispositivo che non
risponde, dati meteo mancanti, canale non assegnato: in tutti questi casi il
settore non viene irrigato invece di essere irrigato alla cieca.

---

## Cosa è rimasto fuori

Cose di cui abbiamo parlato ma che non abbiamo fatto, se un giorno servissero:

- **Notifiche a app chiusa** — servirebbe un servizio push o un bot di
  messaggistica sull'agente. Un bot Telegram è la via più semplice e gratuita.
- **Integrazione con Home Assistant** — esporre il calcolo come sensore e
  lasciare le automazioni là.
- **App pubblica su hosting** (Netlify, Vercel) per consultarla ovunque. Nota che
  una pagina in HTTPS non può comandare dispositivi locali in HTTP: resterebbe
  per consultazione, mentre l'irrigazione si comanda dall'indirizzo di casa.
- **Più sonde per settore**, per mediare invece di fidarsi di un punto solo.

---

*Ultimo aggiornamento: 7 settembre 2026.*