# ECOBOT-3 — firmware ESP8266 e app Android Un’unica app per installare il firmware via USB OTG e guidare il robot sul suo Wi-Fi, senza Internet. La prima schermata chiede **«Il robot ha già il firmware ECOBOT?»**: **«Sì, vai alla guida»** apre direttamente i comandi; **«No, installa via USB»** apre l’installazione. La WebUI resta disponibile all’indirizzo `http://192.168.4.1/`, anche su Safari. Stato delle prove e attività residue: [piano e avanzamento](docs/PIANO_MIGRAZIONE_E_APP.md) e [collaudo](docs/COLLAUDO.md). La compilazione e i test software non sostituiscono la verifica dei motori e del flash su ciascuna scheda fisica. ## Uso dal telefono Richiede Android 10 o successivo. Installa l’APK di test prodotto in `android/app/build/outputs/apk/debug/app-debug.apk` aprendo il file sul telefono e autorizzando l’installazione per l’app che lo apre. L’AAB serve alla distribuzione Play Store, non si installa direttamente. **Robot già pronto:** scegli «Sì, vai alla guida», accendi il robot, inserisci l’SSID visibile nelle impostazioni Wi-Fi e conferma la richiesta di Android. La rete è aperta e non ha Internet. Per collegamento manuale usa «Apri impostazioni Wi-Fi», resta sulla rete del robot e poi «Sono già collegato al Wi-Fi del robot». L’app riconosce il protocollo 2; un vecchio firmware va aggiornato tramite il percorso USB. **Prima installazione:** telefono con USB host/OTG, cavo **dati**, scheda ESP8266 con almeno 4 MB di flash. Togli alimentazione ai motori e collega la scheda al telefono. Scegli la variante hardware corretta, conferma la sostituzione di firmware e impostazioni, autorizza l’USB. Le tre immagini sono incluse nell’app. La scrittura a 115200 baud richiede alcuni minuti: attendi la verifica prima di scollegare. Al termine scegli «Passa alla guida». Per schede senza reset automatico: tieni FLASH/BOOT, premi e rilascia RESET, rilascia FLASH e seleziona BOOT manuale. Un modulo ESP-12E senza interfaccia USB richiede un adattatore USB seriale con segnali a 3,3 V e cablaggio di boot. Il chip viene identificato prima della scrittura; il driver motori deve essere scelto dall’utente perché non è rilevabile dalla porta seriale. Un’interruzione del flash USB richiede una nuova installazione via USB. **Guida:** «Torretta e guida» raccoglie entrambi i controlli touch e le quattro azioni in una schermata fissa, senza scroll. Il pulsante Wi-Fi apre il pannello di connessione; soltanto parametri e manutenzione scorrono. Trascina il joystick e rilascialo per fermarti. STOP arresta il robot e invalida la sessione. Dopo cambio app, perdita di rete o errore si riprende esplicitamente il controllo. Sono disponibili torretta, cannone, sirena, luci, infrarossi, parametri, rinomina SSID, riavvio e aggiornamento OTA. **OTA:** seleziona il solo file applicativo `ecobot3_.bin`, scegli «Riprendi controllo» se necessario dopo il selettore file, quindi conferma. Il firmware ferma le uscite, controlla dimensione, checksum e identità della scheda e cambia partizione di avvio solo dopo una scrittura valida. La WebUI offre lo stesso aggiornamento in `/update`. Le immagini USB complete non sono file OTA. ## Build firmware su Linux x86-64 Servono Git, curl, tar, make, compilatore C, Python con supporto venv; Node.js per i test WebUI. Il setup scarica dipendenze fissate e le isola in `.tools/`. SDK ufficiale **ESP8266_RTOS_SDK v3.4**, commit `89a3f254b63819035f65d9c5dcdae8864f1a6a8a`, GCC 8.4 esp-2020r3 e Python 3.9.23. La directory `.pio-local/` preesistente non viene usata né modificata. ```bash tools/setup-firmware.sh tools/build-firmware.sh d1mini_mx1919 tools/build-firmware.sh esp12e_l293d tools/build-firmware.sh d1mini_dual_pwm tools/test-firmware.sh ``` Le sorgenti firmware sono solo in `main/`; gli asset gzip sono generati da `assets/` durante la build con timestamp zero. I risultati e le configurazioni sono separati in `build//`. Per personalizzare: ```bash tools/build-firmware.sh d1mini_mx1919 menuconfig ``` Non cambiare la variante motori all’interno della directory di un’altra scheda: la build verifica la corrispondenza. Dopo modifiche a `sdkconfig.defaults`, per ripartire dai valori aggiornati elimina **solo** il file locale `build//sdkconfig` e ricompila. Diagnostica seriale disabilitata nella configurazione distribuita; attivandola, luci e infrarossi su GPIO1/GPIO3 vengono disabilitati. ### Flash da computer Per la prima migrazione dal firmware Arduino le impostazioni vengono azzerate; non è prevista migrazione EEPROM. Con motori non alimentati e porta corretta: ```bash tools/build-firmware.sh d1mini_mx1919 -p /dev/ttyUSB0 erase_flash tools/build-firmware.sh d1mini_mx1919 -p /dev/ttyUSB0 flash ``` La build stampa anche il comando esptool completo. Layout flash 4 MB: | Area | Offset | Dimensione | | --- | --- | --- | | Bootloader | `0x00000` | fino a `0x8000` | | Tabella partizioni | `0x08000` | `0x1000` | | NVS | `0x09000` | `0x6000` | | Selezione OTA | `0x0f000` | `0x2000` | | PHY (riservata) | `0x11000` | `0x1000` | | Applicazione OTA 0 | `0x20000` | `0x180000` (1.572.864 byte) | | Applicazione OTA 1 | `0x1a0000` | `0x180000` | Il confezionamento Android unisce bootloader, tabella, selezione OTA iniziale e applicazione con spazi `0xff`, azzerando anche NVS. Il catalogo SHA-256 viene controllato nell’app; lo stub Espressif rilegge il digest MD5 della flash prima del riavvio. Questi controlli verificano l’integrità, non autenticano un utente sulla rete aperta. ### Pin mantenuti | Variante | Motore sinistro | Motore destro | | --- | --- | --- | | `d1mini_mx1919` | INA GPIO5, INB GPIO4 | INA GPIO0, INB GPIO2 | | `esp12e_l293d` | PWM GPIO5, DIR GPIO0 | PWM GPIO4, DIR GPIO2 | | `d1mini_dual_pwm` | PWM GPIO5, DIR/PWM GPIO4 | PWM GPIO0, DIR/PWM GPIO2 | Comuni: pan GPIO14, tilt GPIO12, buzzer GPIO15, cannone GPIO13, luci GPIO1, infrarossi GPIO3. Servo e sirena usano FRC1, i motori il timer WDEV del driver PWM SDK. Le temporizzazioni elettriche vanno confermate sul robot. ## Build Android Compila prima **tutte e tre** le varianti firmware. JDK 17, Android SDK con `platforms;android-36` e `build-tools;35.0.0`; licenze SDK accettate secondo l’installazione locale. Imposta `JAVA_HOME` e `ANDROID_HOME`, oppure `sdk.dir` in `android/local.properties` (non tracciato). ```bash android/gradlew -p android :app:assembleDebug :app:testDebugUnitTest :app:lintDebug android/gradlew -p android :app:connectedDebugAndroidTest android/gradlew -p android :app:bundleRelease ``` `preBuild` esegue `tools/package-firmware.py` e include automaticamente le tre immagini e il catalogo. Ricompila il firmware dopo ogni sua modifica, prima di creare un nuovo APK. La build fallisce se manca un’immagine. Il progetto usa `it.ecobot.controller`, versione 1.0.0/code 1, min API 29 e target API 36. Per firmare il bundle configura una **propria** chiave di upload in `android/signing.properties`, usando il modello `.example`. Senza quella configurazione viene prodotto un AAB non firmato. Non inserire chiavi o password nel repository. Per scheda store, grafica e privacy: [distribuzione](docs/DISTRIBUZIONE.md). Per il contratto condiviso app/WebUI: [protocollo](docs/PROTOCOLLO.md).