nc_program_manager/field-test/README_TESTING_MITSUBISHI.md

# Field Test — Mitsubishi CNC — nc_program_manager

Guida operativa per il test in campo del trasferimento programmi NC verso/da
un controllo **Mitsubishi** (serie M, FTP). Pensata per essere eseguita sul
portatile in officina dal cliente.

> Comunicazione Mitsubishi = **FTP in chiaro** (porta 21). Niente FOCAS, niente
> LSV2. Solo upload/download file. Stato macchina, allarmi, offset utensile e
> origini **non** sono supportati via FTP (vedi §7).

---

## 0. Indice

1. Cosa fa il software
2. Prerequisiti
3. Build dell'eseguibile
4. Ricognizione FTP **(da fare PRIMA dei test)**
5. Parametri CLI
6. Scenari di test (T01–T07)
7. Cosa Mitsubishi NON supporta
8. Codici di uscita
9. Log
10. Criticità note da verificare → vedi `CHECKLIST_CRITICITA.md`

---

## 1. Cosa fa il software

Console app .NET Framework 4.7.2 (Windows). Due azioni:

- **Invia** — carica un file NC locale sul CNC.
- **Scarica** — scarica un programma dal CNC su file locale.

Per Mitsubishi il transport è FTP: `ftp://<ip>:<porta>/PRG/<programma>`.
La cartella programmi è **fissa a `/PRG/`** (hardcoded, vedi criticità C6).

---

## 2. Prerequisiti

- Windows con .NET Framework 4.7.2.
- Rete: il portatile deve raggiungere l'IP del CNC sulla porta FTP (default 21).
  - Verifica rapida: `ping <ip>` e `ftp <ip>`.
- Server FTP **attivo sul controllo** Mitsubishi e cartella `/PRG/` presente.
- Credenziali FTP del controllo (o accesso anonimo).
- Un **numero programma di test concordato col cliente**, non in uso.
- Per la build:
  - **Debug** (consigliata per i test): nessuna licenza richiesta.
  - **Release**: richiede `license.lic` valido accanto all'exe (fingerprint macchina).

---

## 3. Build dell'eseguibile

Da *Developer Command Prompt for VS 2017+* (msbuild + nuget nel PATH):

```bat
cd field-test
build.bat
```

Produce `bin\Debug\NcProgramManager.exe`. In Debug il check licenza è saltato
(`#if !DEBUG`) — comodo in campo. In alternativa apri la solution in Visual
Studio e compila in Debug.

> Se devi testare anche il flusso licenza, compila in **Release** e copia un
> `license.lic` valido nella cartella `bin\Release`.

---

## 4. Ricognizione FTP — DA FARE PRIMA

**Passaggio critico.** Il CLI può indirizzare in download solo `/PRG/<intero>`
(vedi C1). Prima di tutto, connettiti manualmente e annota i nomi reali:

```bat
ftp <ip>
  user <utente>
  pass <password>
  dir /PRG/
  quit
```

Annota:

- La cartella programmi è davvero `/PRG/`? Se no → C6 bloccante.
- I programmi hanno nomi **numerici** (`1`, `100`, `1234`) o con prefisso
  **`O`** / lettere (`O1234`, `PEZZO1`)?
  - Solo numerici e ≤ 32767 sono scaricabili da CLI (C1).
- Permessi di scrittura per l'utente FTP usato (per i test di Invia).

Riporta gli esiti in `CHECKLIST_CRITICITA.md`.

---

## 5. Parametri CLI

```
NcProgramManager.exe -manufacturer=mitsubishi -azione=<Invia|Scarica> -ip=<ip> [opzioni]
```

| Parametro | Obblig. | Default | Note Mitsubishi |
|---|---|---|---|
| `-manufacturer=mitsubishi` | sì | `fanuc` | se omesso/errato → usa Fanuc! |
| `-azione=Invia` \| `-azione=Scarica` | sì | — | case-insensitive |
| `-ip=<ip>` | sì | — | richiesto per non-Fanuc |
| `-pathprogramma=<file>` | sì | — | **richiesto anche per Scarica** (file destinazione) |
| `-porta=<n>` | no | `21` | porta FTP |
| `-username=<u>` | no | vuoto | utente FTP |
| `-password=<p>` | no | vuoto | password FTP |
| `-path=<intero>` | no | `1` | identifica il programma su CNC. **Solo interi (Int16, max 32767)** |
| `-commento=<txt>` | no | — | solo Invia; sostituisce/aggiunge commento `(...)` |
| `-debug` | no | off | tiene aperto il terminale a fine esecuzione (**NON usare negli script**, blocca su ReadLine) |
| `-help` | no | — | stampa la guida ed esce |
| `-compatibility` | no | off | **nessun effetto su Mitsubishi** (parsato ma ignorato dal factory) |
| `-tooloffset` / `-workzero` | no | off | **non supportati** → errore (§7) |

Esempio invio:

```bat
NcProgramManager.exe -manufacturer=mitsubishi -azione=Invia -ip=192.168.1.3 -porta=21 -username=user -password=pass -path=1 -pathprogramma=C:\test\O0001_valid.nc
```

Esempio scarico:

```bat
NcProgramManager.exe -manufacturer=mitsubishi -azione=Scarica -ip=192.168.1.3 -porta=21 -username=user -password=pass -path=1 -pathprogramma=C:\test\out.txt
```

---

## 6. Scenari di test

Modifica **`config.bat`** (IP, porta, credenziali, `PROGNUM`) una volta sola,
poi lancia gli script. Output in `field-test\results\`.

Sequenza completa:

```bat
cd field-test
run_all.bat
```

oppure singoli:

| Script | Scopo | Esito atteso |
|---|---|---|
| `t06_parametri_mancanti.bat` | parsing args (offline) | -101 / -102 / help=0 |
| `t04_errori_connessione.bat` | IP/porta/cred errati | -201 |
| `t02_scarica.bat` | download `/PRG/<PROGNUM>` | 0 se il file esiste |
| `t01_invia_valido.bat` | upload programma valido | 0 (osserva dove finisce, C2/C4) |
| `t03_validatore.bat` | gating pre-invio | 4 blocchi, 1 ok |
| `t05_offset_non_supportati.bat` | tool/workzero | -205 / -206 |
| `t07_roundtrip.bat` | invia + riscarica | osserva mismatch path C1/C2 |

> **Attenzione:** `t01`/`t07` **scrivono** sul CNC. Usa un `PROGNUM` di test
> concordato. Tieni un backup dei programmi del cliente prima di scrivere.

### Dettaglio T03 — validatore (regole Fanuc/Mitsubishi)

Il validatore blocca l'upload (severità Error) se:

- nome programma ≠ `O####` (esatti 4 cifre);
- prima riga ≠ `O####`;
- presenza di lettere **minuscole**;
- blocco > **80 caratteri**;
- caratteri vietati `;` `[` `]`;
- parentesi annidate; commento `(...)` > 32 caratteri.

`#` genera solo **Warning** (macro), upload prosegue.

File di prova in `samples\`:

| File | Atteso |
|---|---|
| `O0001_valid.nc` | 0 — ma verifica C4 (vedi sotto) |
| `O0002_lowercase.nc` | -204, "Lowercase letters not allowed" |
| `O0003_brackets.nc` | -204, "Forbidden char '['" |
| `O0004_longblock.nc` | -204, "Block length 82 exceeds 80" |
| `no_header.nc` | -202 (eccezione: nessun `O####` per GetProgramTitle) |

---

## 7. Cosa Mitsubishi NON supporta (via FTP)

| Funzione | Comportamento |
|---|---|
| Stato macchina / allarmi (`ReadAsync`) | ritorna tutto `Unknown` |
| Programma attivo (`ReadActiveProgram`) | "Not supported via FTP" |
| Selezione programma main (`SelectMainProgram`) | "Not supported via FTP" |
| Tool offset (`-tooloffset`) | exit **-205** |
| Work zero offset (`-workzero`) | exit **-206** |

Solo **Fanuc** (FOCAS) espone offset/stato. Mitsubishi = solo file transfer.

---

## 8. Codici di uscita

| Codice | Significato |
|---|---|
| `0` | OK |
| `-100` | licenza errata/assente (solo build Release) |
| `-101` | parsing parametri fallito (es. manca `-azione`) |
| `-102` | parametri obbligatori mancanti (`-ip`, `-pathprogramma`) |
| `-103` | azione sconosciuta (≠ Invia/Scarica) |
| `-201` | macchina non connessa (FTP irraggiungibile / `/PRG/` assente / cred errate) |
| `-202` | eccezione durante l'azione |
| `-204` | errore invio/ricezione programma (incl. **blocco validatore**) |
| `-205` | tool offset non supportato |
| `-206` | work zero offset non supportato |
| `-207` / `-208` | documentati ma non applicati per Mitsubishi |

> In cmd, `%ERRORLEVEL%` mostra il valore negativo. Gli script lo registrano.

---

## 9. Log

- **Console**: livello Info (ciò che vedi a schermo). Gli script lo redirigono
  nei file `results\tNN_*.log`.
- **File**: `bin\Debug\logs\nc_program_manager.log` — livello **Debug**
  (più dettagliato, con stack trace eccezioni). Rotazione giornaliera, 7 giorni.

Per l'analisi post-test allega entrambi.

---

## 10. Criticità da verificare

Vedi **`CHECKLIST_CRITICITA.md`**: elenco puntuale (C1–C8) dei punti deboli noti
individuati nel codice, con cosa osservare in campo e come compilarne l'esito.
Sono i punti dove è più probabile trovare problemi reali sul controllo del cliente.