Readme first version

README.md

@@ -1,3 +1,64 @@
 # ETcontroller_PRO
 
-Nuova versione di ETcontroller hardware (lo scatolo) basata su scheda ESP 32 Waveshare [https://www.waveshare.com/wiki/ESP32-S3-ETH-8DI-8RO#Resources]
+### Nuova versione di ETcontroller hardware (lo scatolo) basata su scheda ESP32-S3 Waveshare 
+[https://www.waveshare.com/wiki/ESP32-S3-ETH-8DI-8RO#Resources]
+
+## Tool necessari:
+
+### Plugin VScode
+* VScode
+* PlatformIO Plugin per VScode
+* GitGraph
+* C/C++ Extension Pack
+
+### Toolchain e Librerie
+Dipendenze e toolchain vengono installate direttamente da PlatformIO.   
+Il firmware e' basato sul framework _Arduino_ e piattaforma _esp-idf_ di Espressif.  
+La versione della piattaforma inclusa in PlatformIO e' deprecata, quindi e' necessario scaicarne una indipendente da GitHub. La versione corrente e' listata nel file `platformio.ini` nella root directory, se fosse necessario aggiornarla si trova a: [https://github.com/pioarduino/platform-espressif32/releases]
+Vale lo stesso per le librerie dipendenti, se non fossero disponibili tramite PlatformIO si possono cercare su GitHub e scaricare manualmente.
+
+### Documentazione aggiuntiva
+Nella cartella `docs` sono presenti i datasheet di tutti i device collegati.
+I driver sono spesso scritti a manina usando quei documenti come reference.
+
+## Configurazione Hardware e Build
+
+### Definizione della board
+Prima di poter compilare e' necessario copiare il file di descrizione della board `esp32-s3-waveshare8.json` che si trova in questa root directory nella cartella delle board di PlatformIO.  
+* Per Windows `%USERPROFILE%\.platformio\platforms\espressif32\boards`
+* Per Linux `$HOME/.platformio/platforms/espressif32/boards`
+* Per MAC `dovrebbe essere come linux`
+
+### Cofigurazioni di build
+Le configurazioni disponibili sono:
+* **Release**: `esp32-s3-waveshare8`  
+Build adatta per il deploy, log su seriale ma non e' possibile il debug con PlatformIO
+* **Debug**: `esp32-s3-waveshare8-debug`  
+Build per il debug del codice in circuit, attenzione che quando il debugger e' attivo tutti i procesi temporizzati dallo scheduler vanno in pausa per cui le funzioni di rete e comunicazione con le perriferche potrebbero non funzionare correttamente.
+
+Il cambio di configurazione tra Release e Debug causa un rebuild completo del codice.
+
+### Partizioni della flash
+La flash dell'ESP32 e' partizionata secondo lo schema definito in `fatfs_partitions.csv`, che deve rimanere nella root del progetto. 
+Le partizioni sono come segue"
+* **NVS + OTADATA**: Non toccare assoutamente, contengono il bootloader, se si toccano queste addio programmazione via USB, ci vuole il tool apposta.
+* **APP_0 + APP_1**: contengono entrambe il firmware, quando avviene un aggiornamento via OTA una partizione e' in stby e riceve il firmware aggiornato. Se l'aggiornamento va a buon fine il boot successivo avviene dalla partizione aggiornata e cosi' via per i successivi.
+* **FFAT** e' una partizione accessibile dal firmware per essere usata come memoria permanente. Montata dalla classe FSMount. E' di circa 9MB e si comporta come un filesystem FAT32.  
+**Attenzione che e' la flash integrata nel micro, evitare letture e scritture troppo frequenti per non bruciarla**
+
+### Metodi di upload
+La porta di upload e' configurata con `upload_protocol` nel file `platformio.ini`.  
+I valori possibili sono:
+* **_esptool_** per upload USB
+* **_espota_** per upload via Rete.  
+In questo caso il valore di _upload_port_ deve essere l'indirizzo IP della scheda, che sia settato statico o da DHCP. 
+E' possibile ce si debba permettere a VScode di aggiungere una regola al firewall del PC per permettere il collegamento "unsafe" via UDP
+
+Il metodo di defaut e' tramite la porta USB, che ha un nome diverso a seconda del sistema operativo host e della porta a cui viene collegata.
+Se si vuole utilizzare il metoto OTA via rete, questo va abilitato dalla scheda (per motivi di sicurezza).  
+Per abilitare OTA resettare la scheda e nel momento del boot tenere premuto il pulsante blu fino a che il buzzer smette di bippare e il led inizia a lampeggiare verde e giallo alternati: da quel momento e' possibile aggiornare via rete.  
+_Ogni aggiornamento causa il reboot della scheda._
+
+### Logica del Firmware, come funziona?
+
+[TODO]