# Pulcino **Pulcino** è un mini robot bipede open source, stampato in 3D e molto economico (circa 55–70 €, prezzi indicativi), con **telecamera, microfono e speaker**, che **impara da solo a camminare in simulazione** e poi porta quello che ha imparato sul robot vero (sim2real). - Si comanda dall'**iPhone** con una web app servita dal robot stesso (niente App Store). - Può essere **“preso in controllo” da altre persone** tramite un link condiviso. - Può **agire in autonomia** con il **Nido**, un cervello locale che parla con un LLM locale (Laya, Ollama o qualsiasi endpoint compatibile con l'API OpenAI) ed esegue routine. Ispirazione dichiarata, solo concettuale: i piccoli bipedi open source addestrati con apprendimento per rinforzo in simulazione (per esempio “Open Duck Mini”). Nessun asset copiato; tutte le illustrazioni sono originali. **Stato: prototipo software e CAD.** La pipeline di simulazione funziona, ma stampa, assemblaggio, equilibrio, camera e audio non sono stati collaudati su un robot fisico. Il trasferimento sim2real richiede calibrazione e prove; non è una camminata garantita. La fonte di verità per nomi, misure, pin e API è [`SPEC.md`](SPEC.md). ## Struttura del repository ``` site/ sito statico in italiano (HTML/CSS/JS, Three.js da CDN), pubblicato su GitHub Pages js/3d/ viewer 3D condivisi e Palestra (prova 3D e progressi del training server) firmware/pulcino/ sketch Arduino per Seeed XIAO ESP32S3 Sense (config.h, policy.h, web app incorporata) training/ modello MuJoCo, Augmented Random Search in numpy, export di policy.h hardware/ parti stampabili in OpenSCAD parametrico nido/ cervello locale in Python: proxy HTTPS, controllo condiviso, autonomia con LLM, routine scripts/ build.mjs, check.mjs, check-mobile.mjs, serve.mjs .github/workflows/ pages.yml: build e pubblicazione automatica ``` Documentazione delle singole parti: - [firmware/README.md](firmware/README.md) — compilazione, calibrazione, API - [training/README.md](training/README.md) — simulazione e addestramento - [hardware/README.md](hardware/README.md) — parti, parametri, generazione degli STL - [nido/README.md](nido/README.md) — installazione e configurazione del Nido ## Il sito Il sito spiega passo passo come costruire Pulcino: componenti, attrezzi, stampa 3D, elettronica, assemblaggio, firmware, apprendimento, Palestra, controllo, Nido, risoluzione dei problemi e FAQ, con molti modelli 3D interattivi. ### Build locale Serve Node.js ≥ 18. La build non ha dipendenze; Playwright serve solo per il controllo mobile. ```bash npm install # installa playwright (solo per check:mobile) npm run build # site/ → dist/, sorgenti in dist/repo/, STL in dist/stl/ se c'è openscad npm run check # link interni, ancore e HTML di base (exit ≠ 0 se ci sono errori) npm run dev # serve dist/ su http://127.0.0.1:8080 ``` Controllo a 375 px (niente scroll orizzontale, niente errori in console) con screenshot salvati **fuori dal repo**: ```bash npx playwright install chromium # scarica il browser nella cache utente npm run check:mobile -- /tmp/pulcino-screenshot npm run check:interactive # Rapier, allenamento, pausa e download ``` Se `openscad` è nel `PATH`, la build esegue `hardware/render.sh dist/stl`; altrimenti salta con un avviso e i viewer 3D usano modelli procedurali equivalenti. I link del sito ai sorgenti puntano a `repo/` (es. `repo/firmware/pulcino/pulcino.ino`): la build copia lì `firmware/`, `training/`, `hardware/`, `nido/`, `SPEC.md` e questo README, escludendo ambienti virtuali, cache, file pesanti e configurazioni personali. ### Pubblicazione su GitHub Pages 1. Fai il push del repository su GitHub (ramo `main`). 2. In **Settings → Pages → Build and deployment → Source** scegli **GitHub Actions**. 3. Il workflow [`.github/workflows/pages.yml`](.github/workflows/pages.yml) installa OpenSCAD, esegue `npm run build` e `npm run check` e pubblica `dist/`. Si avvia a ogni push su `main` o a mano da **Actions → Run workflow**. Il sito sarà su `https://.github.io//`; il link “GitHub” nel footer viene ricavato automaticamente da questo indirizzo. ## Licenze | Cosa | Licenza | Perché | |---|---|---| | Codice (firmware, training, Nido, script, JS del sito) | **MIT** | la più semplice e permissiva: chiunque può riusarlo, anche in prodotti commerciali | | Hardware (OpenSCAD, STL, schema dei collegamenti) | **CERN-OHL-P-2.0** | una licenza pensata apposta per l'hardware (copre anche i prodotti fisici realizzati dai file, cosa che MIT e CC non fanno bene); la variante *permissiva* è coerente con la MIT del codice | | Testi e immagini del sito | **CC BY-SA 4.0** | la documentazione resta aperta: chi la modifica e la ripubblica deve citare la fonte e usare la stessa licenza | Il testo è in [`LICENSE`](LICENSE). ## Avvertenze - **Prezzi indicativi.** Tutti i prezzi indicati (sito, SPEC, questo file) sono stime: cambiano per negozio, periodo e spedizione. - **Batterie al litio.** Il robot usa due celle 18650 in serie. Usa sempre un BMS 2S, non cortocircuitare le celle, ricarica sotto supervisione con un caricatore adatto, sostituisci celle danneggiate o gonfie. Leggi la sezione sicurezza della pagina *Elettronica* del sito. - **Privacy.** Il robot ha camera e microfono: tutto resta nella tua rete, ma avvisa le persone intorno a te e non condividere i link ospite con sconosciuti. Non committare `config.h` con la password del Wi-Fi né `nido/config.yaml`. - Il progetto è fornito così com'è, senza garanzie: costruirlo e usarlo è sotto la tua responsabilità. Su macOS lo script usa automaticamente Rosetta se Qt arm64 non funziona; si può forzare con `OPENSCAD_ROSETTA=1 npm run build` (vedi il README hardware). Esiti dei controlli e limiti del collaudo: [VALIDATION.md](VALIDATION.md). ## Funnel dedicato rootless Per esporre il sito pubblico con un nodo `pulcino` separato e tag `tag:linkfunnel`, vedi [deploy/LINKFUNNEL.md](deploy/LINKFUNNEL.md). Il gestore supporta anche provisioning automatico OAuth per altri siti.