Macchinina

Il problema

Volevo dare un corpo fisico a un agente AI. L'obiettivo era un robot da guidare a mano da una pagina web, che potesse essere pilotato anche da un LLM (Claude Code) e che avesse un po' di autonomia in casa: sapere in quale stanza si trova e muoversi verso gli oggetti che nomino ad alta voce. È un esperimento personale, senza un cliente.

Cosa ho realizzato

• Due metà che comunicano via MQTT: un Mac con Docker Compose (broker, cervello, web controller Flask con video e audio bidirezionale) e un Raspberry Pi 5 con servizi systemd.

• Percezione sul Pi: object detection con YOLO11n circa una volta al secondo, riconoscimento della stanza con embeddings DINOv2 e k-NN su foto di riferimento, distanza a ultrasuoni e un'impronta del segnale WiFi come segnale aggiuntivo.

• Una copia riproducibile del setup del Pi nel repository (script di deploy, provisioning e verifica), e test che girano contro un robot finto, mai sui motori reali.

Come funziona l'agente

Claude si collega tramite un server MCP che espone tool per guidare, seguire un breve percorso, avvicinarsi a un oggetto indicato per nome, fermarsi, guardare attraverso la fotocamera, leggere la percezione, ascoltare e parlare. Ogni tool ha limiti rigidi applicati sul Pi e restituisce un esito strutturato (arrivato, perso, non trovato, bloccato, timeout, operatore). Per gli oggetti indicati per nome, un processo residente sul Mac esegue OWLv2 per la detection open-vocabulary e guida il robot in un loop chiuso.

I guardrail stanno sul robot, non nel modello:

• Una whitelist di comandi sul Pi, così l'output dell'LLM non viene mai inoltrato così com'è.

• Ogni comando dell'AI è valido per meno di un secondo e va rinnovato a circa 10 Hz, quindi se il Mac o la rete cadono il robot si ferma da solo. Un watchdog e uno stop davanti agli ostacoli sotto i 20 cm fanno da ulteriore protezione.

• Human in the loop: l'operatore ha sempre la priorità sull'agente, e l'autonomia (spenta, dry run, accesa) non è mai attiva all'avvio e scade in assenza di un heartbeat dalla UI.

Scelte interessanti

• Divisione per latenza: riflessi deterministici e controllo dei motori sul Pi, deliberazione lenta sul Mac.

• Guida stop-and-go: in movimento l'immagine della fotocamera è sfocata, quindi il pilota guarda da fermo, fa una mossa e poi guarda di nuovo.

• Fotocamera e microfono sono spenti di default e si attivano con un keepalive.