Plancia/Console/LEGGIMI.md

# PlanciaConsole

Plancia configurabile su Modbus RTU / RS485. Due modalità, decise dalla riga di
comando; la configurazione vive in un file XML letto all'avvio.

Riusa `..\uModbusRTU.pas` e `..\uGauge.pas` del programma di test
(`ProjectPlancia`): i due progetti condividono quei due file, non ne esistono
copie. Il bus gira in un thread a parte (`uModbusWorker.pas`), così la finestra
non si ferma mai; vedi "Il bus in un thread a parte".

## Avvio

    PlanciaConsole.exe                       aboard, legge plancia.xml
    PlanciaConsole.exe aboard
    PlanciaConsole.exe config                configurazione
    PlanciaConsole.exe config -f rotta.xml   configurazione su un altro file
    PlanciaConsole.exe rotta.xml             aboard su un altro file

Senza indicazioni viene riaperta l'ultima plancia usata, e in mancanza di
quella `plancia.xml` accanto all'eseguibile. `-f <percorso>`,
`-file=<percorso>` o un parametro libero indicano un file diverso.

### Modalità aboard

Legge l'XML, apre la porta seriale indicata nel file, si connette da sola e
opera. A vista c'è solo la plancia più una barra di stato con porta, baud, LED
verde/rosso e ultimo messaggio. Nessun comando di configurazione.

La finestra si dimensiona sulla plancia. Se il pannello è più grande dello
schermo lo zoom si riduce automaticamente per farcelo stare: a bordo è meglio
una plancia rimpicciolita che una da raggiungere scorrendo.

### Cambiare plancia a bordo

In fondo a destra, nella barra di stato, una casella elenca le plance della
stessa cartella del file caricato: tutti gli XML che sono configurazioni di
plancia, mostrati con il loro titolo. Scegliendone una:

- la porta seriale viene chiusa e riaperta con porta e baud del nuovo file;
- la finestra si ridimensiona sul nuovo pannello;
- **le bobine non vengono toccate**: i relè restano come sono e la nuova plancia
  ne rilegge lo stato al primo ciclo di polling.

Il file viene letto per prova prima di lasciare quello in servizio: se è rotto
resta la plancia di prima e l'errore compare nella barra di stato.

La casella compare solo in aboard e solo se nella cartella ci sono almeno due
plance. In configurazione si usa "Apri", che chiede anche delle modifiche non
salvate. Dopo la scelta il fuoco viene tolto alla casella, così le frecce della
tastiera non cambiano plancia per sbaglio.

### Modalità configuration

Palette a sinistra, pannello a destra con le proprietà dell'elemento
selezionato, barra in alto con Nuovo / Apri / Salva / Salva con nome, griglia e
zoom.

- **Inserire**: trascina una voce della palette sul pannello. L'elemento nasce
  centrato sul punto di rilascio; se lì c'è già qualcosa scala in diagonale
  finché trova posto libero, così non si impilano tutti nello stesso punto.
- **Spostare**: trascina l'elemento. Un click senza trascinare non lo sposta:
  il movimento parte solo oltre la soglia di trascinamento di Windows (pochi
  pixel), e un asse su cui il mouse non si è mosso non viene riagganciato alla
  griglia.
- **Ridimensionare**: trascina una delle otto maniglie dell'elemento
  selezionato, oppure scrivi larghezza e altezza nel pannello proprietà.
- **Ritocchi da tastiera**, sull'elemento selezionato: **Ctrl+freccia** lo
  sposta di un pixel, **Maiusc+freccia** cambia le misure di un pixel (destra
  e giù ingrandiscono, sinistra e su rimpiccioliscono). Un pixel esatto anche
  con la griglia attiva. Non funzionano mentre si scrive in una casella, dove
  le frecce restano del testo: cliccare l'elemento riporta i tasti sul pannello.
- **Annulla / Ripeti**: pulsanti nella barra, oppure **Ctrl+Z** e **Ctrl+Y**
  (o Ctrl+Maiusc+Z). Coprono spostamenti, misure, proprietà, tipo, elementi
  aggiunti e cancellati e le impostazioni generali, fino a 100 passi. Le
  modifiche in fila sulla stessa cosa, entro un secondo e mezzo l'una
  dall'altra, contano come un passo solo: le cifre di una larghezza digitata,
  o Ctrl+freccia tenuto premuto. Lo storico si azzera con Nuovo e Apri.
  Un'immagine rimossa dalla libreria non torna con Annulla: tornano i
  riferimenti degli elementi, ma il file va riaggiunto.
- **Griglia**: con "Griglia 10 px" attiva posizioni e bordi si agganciano a
  multipli di 10.
- **Zoom**: da 50% a 200%. È solo una lente di lavoro: le coordinate salvate
  nell'XML restano sempre quelle reali al 100%.
- **Configurare**: seleziona l'elemento e compila i campi. Le modifiche si
  vedono subito.
- **Eliminare**: pulsante "Elimina elemento" o tasto Canc.
- **Chiusura**: chiudendo la finestra la plancia viene **salvata da sola** nel
  file su cui si stava lavorando, senza chiedere niente. Solo se il
  salvataggio non riesce (disco pieno, file di sola lettura) viene chiesto se
  chiudere comunque. Nuovo, Apri e il passaggio in plancia invece continuano a
  chiedere cosa fare delle modifiche: lì si può volerle buttare.

**Come viene scritto il file.** Il salvataggio non scrive mai sopra il file
buono: scrive un `.tmp` accanto e poi scambia i nomi, tenendo la versione
precedente come `.bak`. Così un programma chiuso male, un disco pieno o due
copie del programma che salvano insieme non possono lasciare un XML troncato,
che alla riapertura non si leggerebbe più. Se un file non si apre, accanto c'è
il `.bak` della volta prima: si rinomina e si riparte da lì.

**Se il file non si è aperto**, chiudendo non ci si salva sopra: il programma
avverte e propone "Salva con nome", perché salvare il pannello vuoto
cancellerebbe quello che il file contiene.

All'avvio senza indicazioni viene riaperta **l'ultima plancia usata**: il
percorso è ricordato in `plancia-ultima.txt` accanto all'eseguibile, e si
aggiorna a ogni apertura, salvataggio e cambio di plancia a bordo. Se quel file
non c'è, o la plancia è stata spostata, si riparte da `plancia.xml`. Un file
indicato sulla riga di comando ha comunque la precedenza.

In configurazione la porta seriale **non** viene aperta: si disegna la plancia
senza rischiare di comandare relè per sbaglio. Per provare i canali si usa il
programma di test `ProjectPlancia`.

### Passare da una modalità all'altra

Chi è partito con `config` trova in fondo a destra, nella barra di stato, un
pulsante **"Vai in plancia"**: la palette e le proprietà spariscono, la finestra
si veste sulla plancia e la porta seriale si apre. Da lì il pulsante diventa
**"Torna a configurare"** e riporta indietro, chiudendo la porta.

Serve a provare quello che si è appena disegnato senza chiudere e riaprire il
programma con un'altra riga di comando.

Tre cose da sapere:

- Se ci sono modifiche non salvate viene chiesto cosa farne **prima** di passare
  in plancia, altrimenti si perderebbero in silenzio.
- Tornando a configurare la porta seriale viene **chiusa**, e le spie tornano a
  "dato non disponibile": una plancia che non sta leggendo non deve sembrare in
  servizio.
- Posizione della finestra e zoom di lavoro vengono ritrovati come li si era
  lasciati, perché in plancia la finestra si ridimensiona sul pannello.

**Chi è partito in `aboard` non vede il pulsante.** Una plancia avviata in
servizio non deve offrire la strada per essere modificata per sbaglio; per
configurarla si riavvia con `config`.

### Modalità notturna

Accanto c'è il pulsante **"Notte"**, questo disponibile in entrambe le modalità.
Scurisce l'intera plancia: fondo quasi nero, immagine di sfondo ricalcolata
scura, e ogni colore abbassato alla stessa frazione, così i rapporti fra i
colori restano quelli del giorno e il quadro resta leggibile. Serve in
navigazione notturna, dove un pannello chiaro a tutto schermo brucia
l'adattamento al buio e per qualche minuto non si vede più fuori.

Le scritte non vengono abbassate ma **sostituite con un ambra**: una serigrafia
nera abbassata resterebbe nera, cioè invisibile sul fondo scuro. L'ambra è anche
il colore che disturba meno la visione notturna. Vale per etichette, legende dei
selettori, marchi e scale dei gauge.

Si torna al giorno con lo stesso pulsante, che nel frattempo dice "Giorno". La
scelta **non** viene salvata nell'XML: è una condizione del momento, non una
proprietà della plancia.

## Tipi di elemento

| Tipo | Funzione Modbus | Comportamento |
|---|---|---|
| Pulsante | `WriteSingleCoil` (05) | Chiude alla pressione, riapre al rilascio (es. horn) |
| Interruttore | `WriteSingleCoil` (05) + `ReadCoils` (01) | Commuta alla pressione del mouse e resta premuto |
| Selettore | `WriteSingleCoil` (05) + `ReadCoils` (01) | Manopola rotativa a 2 o 3 posizioni, anche a ritorno di molla |
| Spia | `ReadDiscreteInputs` (02) | Sola lettura, LED di colore configurabile |
| Gauge | `ReadHoldingRegisters` (03) | Colonna con scala, soglie e valore |
| Display | `ReadHoldingRegisters` (03) | Numero a sette segmenti rossi su fondo nero |
| Immagine | nessuna | Grafica decorativa: loghi, sagome, cornici |
| Testo | nessuna | Scritta serigrafata sul pannello |

Il campo `channel` è l'indirizzo Modbus della bobina o del registro, `slave`
l'indirizzo del nodo sul bus. Immagine e Testo non hanno né slave né canale.

Gli interruttori e i selettori rileggono le bobine ad ogni ciclo: se un relè
cambia stato per altra via, o una scrittura non va a segno, il comando a video
si riallinea. I pulsanti momentanei non vengono riallineati, perché il loro
stato dipende dal mouse.

### All'ingresso in plancia la plancia si allinea al campo

Entrando in modalità plancia (all'avvio, tornando dalla configurazione o
cambiando plancia) la prima lettura serve a mettere tutto nella posizione in
cui è il campo, non solo a controllare:

- **interruttori e selettori** dalle bobine (funzione 01);
- **pulsanti** dalle bobine, ma **solo in questa prima lettura**: se un canale
  momentaneo è rimasto eccitato va mostrato chiuso, mentre dopo lo stato del
  pulsante lo decide il mouse e rileggerlo lo farebbe lampeggiare;
- **spie** dagli ingressi digitali (funzione 02), come sempre.

**In questa prima lettura le bobine si chiedono una per una**, non a blocco. Un
blocco che arriva oltre l'ultimo canale del modulo fallisce tutto, e con lui
fallirebbe l'allineamento anche dei comandi su canali che esistono: chiedendo un
canale per volta fallisce solo la richiesta del canale che non c'è. Costa un
giro più lento, una volta sola. Finito l'allineamento si torna alle richieste
raggruppate, che sono quelle che tengono leggero il polling.

Chiudendo il programma non viene scritto niente sul bus: i relè restano come
sono, ed è la plancia che alla ripartenza si adatta a loro. Quando l'allineamento
è fatto la barra di stato dice quanti canali sono stati letti, quanti comandi
risultano chiusi e quanti canali non hanno risposto; se non risponde nessuna
bobina si riprova al ciclo dopo, invece di dare per aperto quello che non si sa.
Una spia già in allarme all'avvio fa suonare il suo cicalino.

### Più comandi sulla stessa bobina

Lo stesso `slave` e `channel` si possono mettere su più elementi: lo stesso relè
comandato da due punti della plancia, o un pulsante e un interruttore sullo
stesso circuito. Premendone uno **gli altri si muovono subito**, senza aspettare
la rilettura: mezzo secondo di disaccordo fra due comandi che sono la stessa cosa
si nota. Vale in tutte le combinazioni, compresi i selettori (per quelli a 3
posizioni conta la bobina del lato).

Le spie no: leggono gli ingressi digitali, che sono un altro spazio di
indirizzi, quindi una spia sullo stesso numero di canale di una bobina non è la
stessa cosa e non viene toccata.

Una risposta **più vecchia del comando appena dato** viene scartata. Le letture
partono a giri regolari e la risposta può arrivare dopo un click: crederle
farebbe tornare indietro il comando per un giro, e si vedrebbe il comando
spegnersi, riaccendersi e rispegnersi. Ogni comando segna l'istante in cui ha
scritto la sua bobina, e le risposte partite prima di quel momento non vengono
applicate a quella bobina.

**Attenzione**: questo riallineamento è anche il motivo per cui un interruttore
può *sembrare* un pulsante. Se la rilettura della bobina risponde 0 — relè
assente, indirizzo sbagliato, scrittura non andata a segno — l'interruttore
torna su da solo entro un ciclo di polling, e a occhio sembra che non resti
premuto. Il tipo dell'elemento non c'entra: si guarda la barra di stato.

### Cambiare tipo dopo il disegno

Pulsante, interruttore e spia si scambiano fra loro in qualsiasi momento, dalla
casella **Tipo** in cima al pannello proprietà, come si fa con la forma o il
canale. Condividono tutti i campi — canale, colori, forma, immagini, etichetta —
quindi il passaggio non perde niente. Cambia solo il funzionamento: il pulsante
chiude il contatto finché lo tieni premuto, l'interruttore commuta e resta, la
spia non si preme e si accende quando l'ingresso è chiuso.

Serve soprattutto per le lenti colorate che sulla foto di un quadro sembrano
pulsanti ma sono allarmi, come FIRE ALARM e OIL STEERING di ZEBRA.

**Attenzione al canale** passando da comando a spia o viceversa: il numero
resta lo stesso ma cambia significato. Per pulsanti e interruttori è una bobina
da comandare, per la spia un ingresso digitale da leggere (funzione 02), che di
solito sta su un altro modulo. La barra di stato lo ricorda al momento del
cambio.

Cambiando tipo l'elemento riparte da spento, perché un pulsante non viene più
riletto dal campo e resterebbe illuminato per sempre. Se l'etichetta era
ancora quella predefinita segue il nuovo tipo, altrimenti resta la tua.

### Selettore rotativo

La leva **ruota**: passando da una posizione all'altra si vede girare, sempre
passando per l'alto, in 130 millisecondi con partenza e arrivo morbidi. È solo
quello che si vede: il comando sul bus parte subito, all'inizio del movimento.
In configurazione la leva sta ferma dove dice la definizione.

Si "gira" premendo dal lato verso cui lo si vuole portare: pressione a sinistra
della manopola per scendere di una posizione, a destra per salire. La legenda
sopra la manopola è testo libero (`OFF ◄ 0 ► ON`, `STOP ◄ 0 ► START`, …).

Il cablaggio dipende dal numero di posizioni:

- **2 posizioni**: una bobina, quella di `channel`. Chiusa = posizione destra.
- **3 posizioni**: **due bobine**, `channel` e (salvo indicazione) `channel+1`.
  La prima chiusa = posizione sinistra, la seconda chiusa = destra, entrambe
  aperte = centro (0).

Quindi un selettore a 3 posizioni **occupa due canali**: nel numerare i canali
va lasciato il buco.

Per configurarlo: tipo Selettore, **Posizioni = 3**, e in **Canale** la bobina
del lato sinistro. La bobina di destra si imposta nel riquadro "Selettore", in
**Canale lato destro**: lasciandolo vuoto è il canale successivo (l'etichetta
ricorda quale sarebbe), e si compila solo quando sul modulo le due bobine non
sono contigue. Nell'XML è l'attributo `channel2`, scritto solo se indicato.

Il suggerimento a comparsa dell'elemento mostra entrambe le bobine.

#### Ritorno a molla

Con **Ritorno a molla** spuntato (nell'XML `momentary="true"`) il selettore non
resta dove lo porti: tiene la posizione finché lo tieni premuto e torna al
centro appena lasci il mouse, aprendo entrambe le bobine. È il comando di
avviamento dei quadri veri, `STOP ◄ 0 ► START`: si tiene su START finché il
motore parte, e si molla.

- Si preme direttamente dal lato voluto, senza passare per lo zero.
- Al rilascio torna al centro **sempre**, anche se il mouse è finito fuori
  dall'elemento e anche se la scrittura di andata era fallita: un comando di
  avviamento non deve mai restare eccitato.
- Finché è premuto il polling non lo sposta, altrimenti una lettura arrivata in
  quell'istante lo farebbe scattare al centro sotto il dito.
- Vale anche a 2 posizioni: premuto = chiusa, lasciato = aperta.

In `antago.xml` e in `plancia-mfd.xml` è così il selettore **GENERATOR**.

Le due bobine **non vengono mai chiuse insieme**: a ogni cambio di posizione si
apre prima quella del lato opposto e solo dopo si chiude l'altra. Se la seconda
scrittura fallisce il selettore resta al centro, con tutte e due aperte. Questa
però è una protezione del programma: se i due lati comandano qualcosa che non
deve mai partire insieme (due sensi di marcia, due alimentazioni), serve
comunque l'interblocco elettrico fra i due relè.

### Gauge a quadrante

Con `style="dial"` il gauge non è una colonna ma uno strumento a lancetta, come
quelli dei display di plancia: scala su 270 gradi con tacche e numeri, lancetta,
e sotto il perno la lettura in cifre con le unità (`decimals` ne fissa i
decimali). Se l'elemento è più alto che largo il titolo va sotto al quadrante,
altrimenti dentro.

La fascia della scala è grigia. Con `warnBelow` / `warnAbove` impostati diventa
verde nell'intervallo buono e rossa fuori: senza soglie resta grigia, perché un
quadrante tutto verde direbbe "tutto a posto" senza saperlo. Senza dato valido
la lancetta non c'è e la lettura mostra `---`.

Stile e decimali del quadrante per ora si impostano solo nell'XML; il pannello
proprietà non li mostra ma il salvataggio li conserva.

### Display

Mostra il registro scalato in unità reali, allineato a destra sul numero di
cifre richiesto, con zeri davanti come i display veri. `digits` è il numero di
cifre, `decimals` quante dopo la virgola. Senza dato valido i segmenti restano
tutti spenti.

### Spia

Il colore da accesa si imposta con l'attributo `color` (`#RRGGBB`): rosso per
gli allarmi, verde per i consensi, giallo e arancio per i livelli. Se
l'etichetta è vuota il LED — o l'immagine PNG che lo sostituisce — occupa tutto
l'elemento, così si possono appoggiare spie piccole sopra una grafica. Vale per
qualunque elemento con l'etichetta fuori dal disegno: senza etichetta non viene
riservata nessuna fascia.

#### Allarme sonoro

Ogni spia può far suonare qualcosa quando si accende. Nel pannello proprietà,
riquadro **Allarme sonoro**:

- **Suona quando si accende**: la casella che accende o spegne l'allarme.
- **File**: si sceglie fra i suoni presenti nella cartella **`suoni\` accanto
  al file XML della plancia** (MP3 e WAV). Come per le immagini, i suoni
  viaggiano con la plancia quando si copia la cartella.
- **Aggiorna**: rilegge la cartella. Serve quando si aggiunge un file mentre il
  programma è già aperto, senza doverlo riavviare.

Nell'XML sono gli attributi `alarm="true"` e `sound="cicalino.mp3"` sulla spia.
Il nome del file resta salvato anche con l'allarme spento, così si può
riaccendere senza riscegliere il suono.

Come suona:

- **Parte sul fronte**, quando la spia passa da spenta ad accesa, e poi **va in
  ciclo**: finito il file ricomincia, e continua finché l'allarme c'è. Un
  cicalino che suona una volta sola lo si perde se in quel momento si sta
  guardando altrove. Si ferma quando l'allarme rientra, quando lo si zittisce
  premendo la spia, o lasciando la plancia.
- **Se l'allarme è già attivo all'avvio** suona appena arriva la prima lettura:
  una plancia che parte con una sentina piena deve dirlo.
- **Non blocca niente**: il suono va per conto suo, la plancia resta comandabile.
- Due allarmi diversi si sovrappongono; lo stesso allarme che si ripete riparte
  da capo.
- **Quando l'allarme rientra il suono si ferma subito**, senza aspettare la
  fine del file: serve per i suoni lunghi, una sirena che continua a suonare
  su un allarme già passato è peggio del silenzio. Se lo stesso file è
  assegnato a più spie, tace solo quando si è spenta l'ultima ancora accesa.
- **Se il file manca o non si può suonare**, la barra di stato lo dice: un
  cicalino muto senza avviso è peggio di nessun cicalino.
- Uscendo dalla plancia (torna a configurare, chiusura) i suoni si fermano.

#### Zittire un allarme

**Si preme la spia che sta suonando**: è il gesto che viene naturale, si preme
quello che dà fastidio. Ogni pressione allunga il silenzio:

| Pressioni | Silenzio |
|---|---|
| 1 | un minuto |
| 2 | dieci minuti |
| 3 | un'ora |
| 4 | allarme di nuovo attivo |

Le pressioni contano finché il silenzio dura: dopo che è scaduto si ricomincia
da un minuto. Il suono in corso si ferma subito alla prima pressione.

**Il silenzio non spegne la spia**: il LED resta acceso, con una sbarra sopra,
perché guardando il quadro si deve capire che quell'allarme c'è ancora e sta
suonando a vuoto. Premere una spia spenta, o una senza allarme, non fa niente.

**Quando il silenzio scade, se la condizione è ancora presente l'allarme torna
a suonare**: è il senso di zittire "per un minuto" invece che per sempre.

In basso a destra, nella barra di stato, compare il tasto **"N allarmi zittiti
(tempo) — riattiva"**, che dice quanti sono e quanto manca al primo che torna a
suonare. Premendolo si riattivano tutti subito, e quelli ancora presenti
suonano di nuovo. Il tasto si vede solo finché c'è almeno un allarme zittito.

Se l'allarme rientra da solo, il silenzio si azzera con lui: la volta dopo si
riparte da un minuto. Tornando a configurare, o cambiando plancia, i silenzi si
azzerano tutti.

In `suoni\` c'è `cicalino.wav`, due bip generati per provare subito; va
sostituito con il suono vero.

La spia accetta anche la forma (`shape`) dei pulsanti, per somigliare alle
lenti di allarme dei quadri:

- **`round`** — ghiera metallica e lente tonda. Spenta la lente resta del suo
  colore ma scura (`colorOff`, o `color` scurito se manca), accesa prende
  `color` pieno con un riflesso. La ghiera non cambia: è una spia, non un
  comando premuto.
- **`screen`** — tasto a video che si riempie di `color` quando l'ingresso è
  chiuso.
- le altre forme — il LED tondo di sempre.

In ogni forma cliccare una spia non fa nulla e non manda niente sul bus.

### Aspetto di pulsanti, interruttori e spie

**La lente di un pulsante o di un interruttore non cambia mai colore.** Lo stato
si legge solo dal bordo, come su un quadro vero, dove il vetro è sempre dello
stesso colore e quello che cambia è la luce dietro.

- Forma **tonda**: la ghiera attorno alla lente è grigia a riposo e diventa
  **azzurra luminosa** quando il comando è acceso, o mentre un pulsante è tenuto
  premuto — più chiara contro la lente e più carica all'orlo, come se la luce
  venisse da dentro.
- Forma **squadrata o a pillola**: non c'è ghiera, quindi è il bordo stesso che
  si ingrossa e prende lo stesso azzurro.

Il colore della lente è **`colorOff`**. Su pulsanti e interruttori `color` non
tocca più il vetro: resta usato dalle spie, dove il cambio di colore è tutto
quello che c'è da vedere. Anche l'etichetta scritta *dentro* al comando resta
uguale: prima diventava bianca e in grassetto da acceso, ed era un secondo modo
di dire la stessa cosa che ora dice il bordo.

Tre attributi permettono di far somigliare i comandi a quelli del quadro vero,
e si impostano anche dal riquadro "Aspetto" del pannello proprietà:

- **`shape`** — `auto` (pillola per i pulsanti, squadrato per gli
  interruttori), `round`, `rect`, `pill`, `screen`. I quadri di bordo hanno
  quasi sempre pulsanti tondi: con `round` l'elemento viene disegnato con
  ghiera metallica e lente, come un pulsante illuminato da incasso.
  `screen` ("a video") è il tasto di un display multifunzione ed è l'eccezione
  alla regola della lente: spento è un riquadro scuro con il filo chiaro
  (`colorOff` per tingerlo), acceso **si riempie** del colore `color`. La
  scritta sopra passa da chiara a nera quando il fondo diventa chiaro.
- **`captionPos`** — `center` (etichetta scritta sul comando), `below`,
  `above`. Sui quadri veri l'etichetta è serigrafata **sotto** al pulsante:
  con `below` il disegno si restringe per farle posto e il testo resta nero
  sulla lamiera invece di stare sopra la lente. Le etichette lunghe vanno a
  capo e la fascia si allarga da sola.
- **`color`** e **`colorOff`** — colore della lente accesa e a riposo. Serve
  perché un pulsante STOP è rosso anche da spento e si limita a illuminarsi:
  senza `colorOff` la lente a riposo è grigio-azzurra neutra.

### Testo e marchi

L'elemento Testo non serve solo alle scritte: con una cornice diventa un
marchio serigrafato, disegnato **con il font e non con un'immagine**, quindi
nitido a qualsiasi zoom invece di sgranare come farebbe un PNG ingrandito.

- **`fontName`** — nome del font, per esempio `Times New Roman` o
  `Arial Black`. Vuoto = quello del pannello. Funziona su qualsiasi elemento,
  non solo sul Testo.
- **`spacing`** — pixel in più fra una lettera e l'altra. I marchi hanno quasi
  sempre le lettere larghe e senza questo non somigliano.
- **`frame`** — `none`, `oval`, `rect`, `round` (rettangolo stondato, cioè a
  pastiglia). Disegnata con GDI+ in antialiasing, altrimenti un ovale grande
  verrebbe scalettato.
- **`frameWidth`** — spessore del tratto della cornice.
- **`color`** — colore di inchiostro e cornice.

Un marchio su più righe si compone sovrapponendo più elementi: uno con la sola
cornice (etichetta vuota), uno con il nome in grande, uno con il sottotitolo
piccolo. È così che sono fatti i loghi ZEBRA e ANTAGO negli esempi.

Per andare a capo dentro un'etichetta si usa `&#10;`, per esempio
`caption="PORT&#10;ENGINE"`.

## Immagini

La libreria immagini è nel pannello di sinistra: "Aggiungi..." accetta PNG, JPG
e BMP (selezione multipla), "Rimuovi" toglie l'immagine e la sgancia dagli
elementi che la usavano, chiedendo conferma.

Non è una `TImageList`: quella imporrebbe a tutte le immagini la stessa
dimensione, mentre qui un LED da 32 px e un logo da 600 px devono convivere.

**Nell'XML si salvano nome e percorso, non i pixel.** I file restano sul disco e
si possono sostituire senza toccare la configurazione. I percorsi sono relativi
alla cartella del file XML quando possibile, così l'intera plancia si trasporta
copiando una cartella; "Salva con nome" in un'altra cartella ricalcola i
percorsi da solo.

Dove si usano:

- **Pulsante, interruttore, spia**: due immagini, a riposo e attiva. Se il campo
  "immagine a riposo" è vuoto si torna al disegno vettoriale predefinito. Se è
  valorizzata solo quella a riposo, l'elemento non cambia aspetto quando si
  attiva.
- **Immagine**: una sola, decorativa.
- **Sfondo del pannello**: si sceglie in "Generale → Immagine di sfondo", ed è
  stirata su tutto il pannello.

Le PNG con trasparenza funzionano: gli elementi non riempiono il proprio sfondo,
quindi un logo con alpha si fonde con lo sfondo della plancia.

L'etichetta continua a essere scritta sopra l'immagine, in bianco con contorno
nero perché resti leggibile su fondo chiaro e scuro; sulle spie va in basso per
non coprire il LED. Se l'immagine contiene già la scritta, basta svuotare il
campo Etichetta.

Se un file manca o non si apre, nella libreria il nome compare seguito da `[!]`
e l'elemento mostra un riquadro tratteggiato in configurazione.

## Il file XML

    <?xml version="1.0" encoding="UTF-8"?>
    <plancia version="1">
      <connection port="COM1" baud="9600" timeoutMs="500" pollMs="500"/>
      <panel title="Plancia ZEBRA" width="980" height="560" background="sfondo"/>
      <images>
        <image name="sfondo" file="immagini\sfondo.png"/>
        <image name="btn-off" file="immagini\btn-off.png"/>
        <image name="btn-on" file="immagini\btn-on.png"/>
      </images>
      <elements>
        <element kind="button" caption="HORN" slave="1" channel="5"
                 left="40" top="60" width="180" height="70"
                 imageOff="btn-off" imageOn="btn-on"/>
        <element kind="image" caption="" image="logo-zebra"
                 left="620" top="440" width="320" height="90"/>
        <element kind="gauge" caption="Serbatoio" slave="5" channel="1"
                 left="640" top="200" width="130" height="200"
                 rawMin="0" rawMax="4095" engMin="0" engMax="100"
                 units="%" warnBelow="15" warnAbove="1E30"/>
      </elements>
    </plancia>

`kind` vale `button`, `switch`, `rotary`, `lamp`, `gauge`, `display`, `image`
o `label`.

- `fontSize`: altezza del testo in pixel logici; assente = font del pannello.
- `imageOff` / `imageOn`: nomi presi da `<images>`; solo per pulsanti,
  interruttori e spie.
- `image`: l'immagine dell'elemento decorativo.
- `background` su `<panel>`: immagine di sfondo.
- `ink` su `<panel>`: colore della serigrafia, `#RRGGBB`, nero se assente.
  Vale per etichette sotto/sopra i comandi, legende e titoli di selettori,
  display e quadranti, e per i `label` senza `color`. Le plance a fondo scuro
  lo mettono chiaro. Si imposta solo nell'XML.
- `style` (`bar` o `dial`) e `decimals`: aspetto del `gauge`, vedi sopra.
- `color` / `colorOff`: colore acceso e a riposo di spie, pulsanti e
  interruttori, `#RRGGBB`. Su `label` è il colore di inchiostro e cornice.
- `shape` e `captionPos`: forma del comando e posizione dell'etichetta.
- `fontName` e `spacing`: font e spaziatura fra le lettere.
- `frame` e `frameWidth`: cornice attorno a un `label`.
- `alarm` e `sound`: solo per `lamp`, allarme sonoro all'accensione; il file
  sta nella cartella `suoni\` accanto all'XML.
- `positions` (2 o 3), `legend`, `channel2` e `momentary`: solo per `rotary`.
  `channel2` è la bobina del lato destro di un selettore a 3 posizioni;
  assente = `channel+1`. `momentary="true"` è il ritorno a molla.
- `digits` e `decimals`: solo per `display`.
- `raw*`, `eng*` e `units` valgono per `gauge` e `display`:
  `rawMin`/`rawMax` sono il fondo scala del modulo (4095 = ADC a 12 bit),
  `engMin`/`engMax` i valori reali corrispondenti.
- `warnBelow` / `warnAbove`: solo per `gauge`, sono le soglie oltre le quali la
  colonna diventa rossa (`-1E30` e `1E30` significano "soglia non impostata").

I numeri decimali si scrivono con il punto. Il file si può modificare a mano:
un attributo mancante prende il valore di default. Per i caratteri speciali
nelle legende si usano le entità XML, per esempio `&#9664;` e `&#9654;` per le
frecce ◄ ►.

## File di esempio

- `esempio-plancia.xml` — solo elementi vettoriali, nessuna immagine.
- `esempio-immagini.xml` — usa la cartella `immagini\`: sfondo, logo con
  trasparenza, pulsante e LED con grafica. Le immagini sono segnaposto generate
  per la prova, da sostituire con quelle vere.
- `antago.xml` — riproduzione del quadro elettrico ANTAGO, ricavata dalla foto
  del quadro reale. Il pannello è 1270×950 come la foto, così ogni elemento sta
  dove sta sul quadro vero.
- `zebra.xml` — riproduzione della pulsantiera ZEBRA: 7 colonne × 6 righe di
  pulsanti tondi illuminati, i due selettori delle ventole, i comandi motore
  con gli ovali PORT/STBD ENGINE e il selettore PARALLEL a tre posizioni.
  La foto è in prospettiva, quindi la griglia è stata ridisegnata dritta
  (passo 120 in orizzontale, 145 in verticale); etichette, forme e colori delle
  lenti vengono dalla foto.

- `plancia-mfd.xml` — tutti i comandi, le spie e le misure di ZEBRA e ANTAGO
  su una sola plancia, nello stile della foto `immagini\Esempio plancia.jpg`:
  cornice scura con tasti a video ai lati, schermo nero con quattro quadranti,
  i due display dei caricabatterie, il sinottico della barca con le spie e i
  tasti illuminati di motori e servizi; sotto, due file di selettori. Pannello
  1900×1080. Gli indirizzi di ZEBRA sono quelli di `zebra.xml`; **le bobine
  di ANTAGO sono spostate da slave 1 a slave 4**, perché sullo slave 1 si
  sovrapponevano a quelle di ZEBRA, e i due comandi di prova "Luce" e "Horn"
  di `antago.xml` (che stavano sul canale 0, lo stesso del selettore
  VOLTMETER) sono sui canali 26 e 27 dello slave 4.

In tutti **slave e canali sono inventati** e vanno rimappati sui moduli
reali prima di collegare il bus.

## Strumenti

`strumenti\` contiene gli script PowerShell usati per preparare la grafica dei
due quadri:

| Script | Cosa fa |
|---|---|
| `ruota.ps1` | Raddrizza una foto scattata in verticale |
| `ritaglia-grafica.ps1` | Ritaglia un pezzo di serigrafia dalla foto e rende trasparente il fondo chiaro, lasciando solo il tratto |
| `genera-sfondo.ps1` | Disegna la lamiera del pannello con cornice e viti, di qualsiasi misura |
| `genera-mfd.ps1` | Disegna cornice e schermo di `plancia-mfd.xml` e la sagoma della barca ANTAGO in chiaro per il fondo nero |

Il ritaglio dalla foto conviene solo per i disegni che non si possono
ricostruire, come la sagoma della barca del quadro ANTAGO. **Le scritte no**:
i marchi ZEBRA e ANTAGO e gli ovali PORT/STBD ENGINE sono elementi Testo con
font e cornice, non immagini, così restano nitidi a ogni ingrandimento.

### Diagnostica del bus

Due programmi a riga di comando servono quando un modulo non si legge. Vanno
lanciati **con PlanciaConsole chiusa**, perché la porta si apre una volta sola.
Si ricompilano con i `build-*.bat` accanto ai sorgenti.

| Programma | Cosa fa |
|---|---|
| `scanbus.exe [porta] [baud] [ultimoIndirizzo]` | Interroga gli indirizzi uno per uno e dice chi risponde, con quali funzioni e che dati |
| `dumpframe.exe [porta] [baud] [slave] [funzione] [start] [quantità]` | Manda una sola richiesta e stampa i byte grezzi della risposta con la verifica della CRC |
| `monitorio.exe [porta] [baud] [slave] [canali] [cicli]` | Mostra gli ingressi digitali in tempo reale, una riga ad ogni cambiamento |
| `ringtest.exe [file.bmp]` | Disegna i comandi tondi spenti e accesi a tre misure e salva l'immagine: serve a giudicare una modifica ai colori guardandola |

`scanbus` serve a trovare l'indirizzo di un modulo appena montato. `dumpframe`
serve quando `scanbus` dà risultati incoerenti: mostrando il frame byte per byte
distingue un modulo che non risponde da due moduli che rispondono insieme.

**Due nodi con lo stesso indirizzo** è il guasto più frequente quando si
aggiunge un modulo: i moduli escono quasi tutti con indirizzo 1, e sul bus le
due risposte si sovrappongono. Il sintomo è una risposta di lunghezza variabile,
spesso con byte a zero in testa, e la CRC che non torna.

## Il bus in un thread a parte

Il thread principale non parla mai con la porta seriale. Tutto il Modbus vive
in un thread suo (`uModbusWorker.pas`), che apre la COM, fa le letture e le
scritture, e lascia i risultati in una cassetta condivisa. La finestra li
ritira con il suo timer. Così un timeout — mezzo secondo per richiesta — costa
tempo al thread del bus e non alla plancia, che resta trascinabile, ridisegnabile
e cliccabile anche con tutti i moduli staccati.

**Un thread solo, non uno per le letture e uno per le scritture.** Su RS485 il
filo è uno: due richieste insieme si sovrappongono e le risposte arrivano
mescolate. Chi comanda deve comunque aspettare la fine della richiesta in
corso, quindi un secondo thread aggiungerebbe solo un lucchetto attorno alla
porta. La reattività dei comandi si ottiene con la **precedenza**: la coda
delle scritture viene svuotata prima di ogni lettura, non solo a ogni giro,
quindi un pulsante premuto parte al massimo dopo la richiesta in corso.

Come si comporta:

- **Cliccare un comando torna subito.** La scrittura va in coda; l'elemento si
  accende fidandosi. Se la scrittura non va a segno lo dice la barra di stato,
  e la rilettura delle bobine rimette l'elemento a posto entro un ciclo.
- **L'ordine è garantito**: le due bobine di un selettore a 3 posizioni, o la
  pressione e il rilascio di un pulsante, partono nella sequenza in cui sono
  state messe in coda.
- **La porta si riapre da sola.** Se non c'è, o se cade (adattatore USB
  staccato), il thread riprova ogni due secondi: non serve più riavviare il
  programma.
- **Chiudendo**, l'attesa del thread dura al massimo quanto la richiesta in
  corso.

## Aggiungere slave e canali

Niente nel programma è legato ai moduli montati adesso: una plancia si può
disegnare prima, e i moduli si aggiungono quando arrivano.

- **Slave**: qualsiasi indirizzo da 1 a 247, quanti se ne vuole sullo stesso
  bus. Ogni slave nuovo aggiunge solo le sue richieste al giro di polling.
- **Canali**: qualsiasi numero da 0 a 65535, senza doverli tenere contigui.
  Canali molto distanti sullo stesso slave allargano però l'intervallo letto
  (vedi Polling), quindi conviene raggrupparli.
- **Limiti di una singola richiesta**, imposti dal protocollo: 2000 bit per
  bobine e ingressi, 125 registri. Oltre, la richiesta viene saltata e la barra
  di stato lo dice: si spezza l'intervallo o si sposta l'elemento su un altro
  slave.
- **Nuove porte**: la porta è una per plancia (`<connection port=...>`). Due
  bus separati si fanno con due plance, e si passa dall'una all'altra con la
  casella in basso a destra.

**Una richiesta che non riesce si divide da sola.** Se la lettura di un blocco
di bobine fallisce, il programma la spezza a metà e riprova con le due metà, e
così via: un modulo da 32 canali interrogato fino al 38 finisce per farsi
leggere i suoi 32 in poche richieste, invece di non dare più niente. Ogni
divisione compare nella barra di stato. Le divisioni imparate valgono finché
non si cambia plancia o non si riapre la porta.

**Le richieste che non rispondono non danno fastidio.** Dopo tre errori di
fila una richiesta muta viene messa in pausa e riprovata ogni cinque secondi,
invece di costarne il timeout a ogni giro: così una plancia disegnata in
anticipo resta scorrevole e i moduli che rispondono vengono letti alla velocità
giusta. Appena il modulo viene collegato riparte da solo, entro quei cinque
secondi. La barra di stato distingue i due casi: `Timeout: nessuna risposta` è
una richiesta che si sta ancora provando, `non risponde, riprovo fra 4 s` è una
messa in pausa. La pausa si azzera da sola quando si cambia plancia, quando si
modificano i canali in configurazione e quando la porta viene riaperta.

La pausa vale **per singola richiesta**, non per modulo: sullo stesso nodo le
bobine possono rispondere benissimo mentre gli ingressi, che quel modulo non ha,
danno errore. Mettere in pausa tutto il nodo per colpa degli ingressi
lascerebbe la plancia cieca proprio su quello che si legge.

## Polling

Ad ogni ciclo (`pollMs`) gli elementi vengono raggruppati per slave e tipo, e
per ogni gruppo parte **una sola** richiesta che copre i canali da quello più
basso a quello più alto. Aggiungere elementi contigui non aumenta il traffico
sul bus; canali molto distanti sullo stesso slave sì, perché allargano
l'intervallo letto.

Ogni richiesta va per conto suo: se un modulo non risponde, gli altri gruppi
vengono letti comunque. Solo le spie e i gauge di **quella** richiesta passano a
"dato non disponibile"; il resto della plancia continua a leggere. Interruttori
e selettori invece non si azzerano, perché la loro posizione è un comando dato,
non una misura.

L'errore finisce nella barra di stato dicendo **cosa** non si è potuto leggere:
slave, funzione e intervallo di canali, per esempio

    Lettura fallita su 4 richieste, la prima: slave 3, ingressi 0-14 (FC02): timeout

Così si capisce subito se manca un modulo, se l'indirizzo è sbagliato o se si
sta leggendo oltre i canali che il modulo ha (tipico: un modulo da 8 bobine
interrogato per 37, perché un elemento ha un canale alto). Il polling continua
e si riallinea da solo appena il bus risponde.