Il bot e le sue parti
Le due schede del bot da scrivania Narsil, cosa fa ciascuna, la distinta dei materiali, il collegamento UART a tre fili tra pancia e testa e come vi scorrono i dati.
Cosa fa
Il bot da scrivania Narsil è Narsil con un corpo. Sta sulla scrivania accanto al tuo computer e fa tre lavori:
- Parla. Tu gli parli e Narsil risponde con una voce. La risposta arriva da Claude, attraverso un piccolo server che gira sul tuo PC.
- Mostra cosa sta facendo Narsil. Uno schermo touch da 4,3 pollici nella pancia mostra gli avvisi di Narsil e le tue pull request aperte su GitHub.
- Ha una faccia. La testa è un piccolo schermo dentro un cubo prismatico di vetro che mostra solo la faccia di Narsil, così sembra un ologramma che fluttua sopra il corpo.
Il bot è composto da due schede unite da tre fili. La pancia è il cervello e fa tutto ciò che tocca la rete. La testa si limita a disegnare. Questa prima guida descrive le parti e come si incastrano; il resto del percorso costruisce ogni pezzo.
Come funziona dentro
La pancia: Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3
La pancia è la Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3. Dalla pagina di Waveshare, le parti che contano per il bot sono:
| Parte | Cos’è |
|---|---|
| Chip principale | ESP32-P4 (ESP32-P4NRW32X sul modulo): RISC-V dual-core più un core a basso consumo |
| Memoria | 32 MB di PSRAM impilata nel package del chip, 32 MB di flash NOR |
| Schermo | IPS da 4,3 pollici, 480 × 800, touch capacitivo, su un’interfaccia MIPI DSI a 2 lane |
| Wireless | Un modulo ESP32-C6-MINI-1 integrato per Wi-Fi 6 e Bluetooth 5 (LE), collegato al P4 tramite SDIO |
| Audio | Codec audio ES8311, ES7210 per la cancellazione dell’eco, un array di due microfoni |
| Altoparlante | Un connettore GH1.25 a 2 pin; Waveshare consiglia un altoparlante da 8 Ω 2 W |
| USB | Una porta Type-C “USB to UART” per alimentazione, flashing e debug; una porta Type-C USB OTG 2.0 |
| Espansione | Un header a 40 pin da 2,54 mm con I2C, GPIO, 3V3, 5V e GND |
L’ESP32-P4 non ha una radio propria. Ogni byte che va in rete passa per l’ESP32-C6 accanto, tramite SDIO. Per il firmware questo è invisibile: il supporto di Xiaozhi per questa scheda (guida 3) imposta già il C6 come coprocessore Wi-Fi (CONFIG_SLAVE_IDF_TARGET_ESP32C6=y nei suoi valori predefiniti per ESP32-P4).
Il controller touch della scheda è un GT911, ed è quello che pilotano sia il codice di scheda di Xiaozhi sia il board support package di Waveshare (waveshare/esp32_p4_wifi6_touch_lcd_4_3 nel registro dei componenti di Espressif).
La testa: ESP32-S3-LCD-1.3-C
La testa è la ESP32-S3-LCD-1.3-C, la versione della ESP32-S3-LCD-1.3 di Waveshare che arriva con un case di plastica e un cubo prismatico. SpotPear la vende come display 3D con prisma trasparente, e Waveshare documenta la scheda base nella sua pagina prodotto:
| Parte | Cos’è |
|---|---|
| Chip principale | ESP32-S3R8, Xtensa LX7 dual-core fino a 240 MHz |
| Memoria | 512 KB di SRAM, 8 MB di PSRAM, 16 MB di flash |
| Schermo | IPS da 1,3 pollici, 240 × 240, 262K colori, driver ST7789V2 su SPI |
| Movimento | IMU a sei assi QMI8658 (accelerometro e giroscopio), sul retro |
| USB | Type-C tramite un chip USB-seriale CH343P |
| Alimentazione | Regolatore da 3,3 V ME6217C33M5G (800 mA massimo), caricatore PL4054, connettore batteria MX1.25 |
| Altro | Slot per scheda TF, un header GPIO da 2,54 mm |
| Prisma | Un cubo di vetro che poggia sullo schermo e ne riflette l’immagine |
Il prisma è il motivo per cui la faccia sembra fluttuare: lo schermo sta in orizzontale e la faccia interna del cubo lo riflette verso di te. Un riflesso è un’immagine speculare, quindi la testa disegna la sua faccia specchiata; se ne occupa la guida 11.
L’ESP32-S3 ha il suo Wi-Fi, e la testa non lo usa. È una decisione, spiegata qui sotto.
Perché la pancia fa tutta la parte di rete
I dati di Narsil vivono su internet: gli avvisi arrivano tramite ntfy, le pull request arrivano dall’API REST di GitHub e la voce va al tuo server. Tutti e tre hanno bisogno di Wi-Fi, credenziali e logica di ritentativo. Se si collegassero entrambe le schede, entrambe avrebbero bisogno della password del Wi-Fi, del token di GitHub e del topic di ntfy, e potrebbero non essere d’accordo su cosa sta facendo Narsil.
Così la pancia possiede ogni connessione e ogni segreto, e decide lo stato di Narsil. La testa riceve solo cosa disegnare: una posa e uno stato, tramite un cavo seriale. Non custodisce segreti e, se si riavvia, aspetta semplicemente il messaggio successivo. La guida 10 definisce quel protocollo.
Il collegamento UART
Le due schede comunicano via UART, il semplice collegamento seriale che ha ogni ESP32, usando cavi Dupont femmina-femmina tra i loro header:
| Filo | Pancia (ESP32-P4) | Testa (ESP32-S3) |
|---|---|---|
| Dati → | GPIO4 (TX) | GPIO13 (RX) |
| Dati ← | GPIO5 (RX) | GPIO14 (TX) |
| Massa | GND | GND |
Il TX di un lato va all’RX dell’altro: ogni scheda parla sul suo pin TX e ascolta sul suo pin RX, quindi i fili si incrociano.
Perché questi pin:
- Sulla pancia, GPIO4 e GPIO5 sono sull’header a 40 pin e non sono usati da niente di ciò che Xiaozhi configura per questa scheda. Il suo
config.hprende da GPIO9 a GPIO13 per l’audio I2S, GPIO7 e GPIO8 per l’I2C, GPIO53 per l’amplificatore dell’altoparlante, GPIO26 e GPIO27 per lo schermo e GPIO35 per il pulsante BOOT. Il supporto di scheda di Waveshare aggiunge da GPIO39 a GPIO44 per la scheda TF. Anche GPIO37 e GPIO38 dell’header restano liberi: ESP-IDF li elenca come TX e RX predefiniti di UART0 sull’ESP32-P4, la porta del log di avvio. - Sulla testa, GPIO13 e GPIO14 sono pin dell’header uno accanto all’altro nello schema di Waveshare (
ESP32S3_1.3inch.pdf, linkato dalla wiki di SpotPear). Lo schermo, l’IMU e la scheda TF usano altri pin, e GPIO43 e GPIO44 portano U0TXD e U0RXD al CH343P, la porta seriale USB della testa.
Controlla le etichette stampate sulle tue schede prima di collegare qualsiasi cosa: la disposizione degli header cambia tra una revisione e l’altra.
Alimentazione: un cavo USB per scheda, massa condivisa, 3V3 non condiviso. Ogni scheda riceve il suo cavo USB-C. La pancia si alimenta dalla sua porta “USB to UART”, e la testa regola i propri 3,3 V con il suo ME6217C33M5G. Unire i due pin 3V3 legherebbe tra loro due regolatori separati, ognuno dei quali cercherebbe di mantenere la linea, e il pin 3V3 dell’header della pancia non è mai stato pensato per alimentare una seconda scheda. Il filo di massa è quello che conta: un segnale UART è una tensione misurata rispetto alla massa, quindi entrambe le schede hanno bisogno della stessa massa. Entrambi i chip usano logica a 3,3 V, quindi non serve un traslatore di livello.
Il flusso dei dati
| Da | A | Tramite | Cosa |
|---|---|---|---|
| Microfoni | Pancia (ES7210, Xiaozhi) | I2S | La tua voce |
| Pancia | Il tuo server (sul tuo PC) | WebSocket, LAN | Audio Opus in salita; audio Opus e testo di ritorno |
| Il tuo server | Claude | HTTPS, Anthropic SDK | Ciò che hai detto, come testo; la risposta di Narsil di ritorno |
| Pancia | Altoparlante (ES8311) | I2S | La voce di Narsil |
| ntfy | Pancia | HTTPS | Gli avvisi di Narsil dal tuo computer |
| GitHub REST API | Pancia | HTTPS, token di sola lettura | Le tue pull request aperte |
| Pancia | Schermo della pancia (LVGL) | MIPI DSI | Avvisi e pull request |
| Pancia | Testa | UART, 3 fili | Posa e stato |
| Testa | Prisma | Schermo ST7789 | La faccia di Narsil, specchiata |
Il percorso della voce è l’unico che ha bisogno del tuo PC. Avvisi, pull request e faccia continuano a funzionare quando il server è spento.
La distinta dei materiali
- 1 × Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3 (la pancia).
- 1 × ESP32-S3-LCD-1.3-C, con il suo case e il cubo prismatico (la testa).
- Cavi Dupont femmina-femmina (se ne usano tre).
- 1 × altoparlante con spina GH1.25 a 2 pin, da 8 Ω 2 W come consiglia Waveshare. I microfoni sono già sulla pancia.
- 2 × cavi dati USB-C, uno per scheda.
- Un PC sulla stessa rete, con Docker, per il server vocale (guida 4).
Il firmware di entrambe le schede vive in un unico repository pubblico, davshn/narsil-bot: un fork di 78/xiaozhi-esp32 per la pancia, con il firmware della testa nella sua cartella head/.
Come è stata chiesta all’IA
Il design è partito da un carrello della spesa. Il 2026-11-17 chi ha creato Narsil ha condiviso uno screenshot di un carrello di AliExpress con le due schede e un pacco di cavi Dupont, e ha descritto l’idea:
va a ser la pantalla grande para una pantalla en la pansa que va a tener la informacion de las tareas que hace narsil y la cabeza va a ser una apntalla holografica que solo sea la cara de narsil
In italiano: “sarà lo schermo grande, per uno schermo nella pancia che avrà le informazioni sui compiti che fa Narsil, e la testa sarà uno schermo olografico che sia solo la faccia di Narsil”.
Questo ha fissato i ruoli delle due schede prima di qualsiasi codice: il P4 con lo schermo grande è la pancia, l’S3 con il prisma è la faccia.
La domanda successiva dell’IA è stata come la testa avrebbe ottenuto i suoi dati: collegandosi alla rete da sola o ricevendoli dalla pancia. Chi ha creato Narsil ha risposto:
Por cable desde la panza
In italiano: “Via cavo dalla pancia”.
Quella risposta è la regola di “Perché la pancia fa tutta la parte di rete” qui sopra: una scheda possiede la rete e i segreti, l’altra si limita a disegnare. L’IA ha fatto le sue domande una alla volta, con le pagine di Waveshare e SpotPear come fonti, e ha registrato ogni risposta nel documento dei task del progetto come specifica numerata.
Un prompt che puoi usare
Il prompt seguente è stato scritto per questa guida come suggerimento. Non è la conversazione usata per progettare il bot.
Voglio costruire un bot da scrivania con due schede ESP32: una Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3 come corpo e una ESP32-S3-LCD-1.3-C (ST7789 240×240 sotto un cubo prismatico) come testa. Il corpo deve fare tutta la parte di rete e la testa deve solo disegnare una faccia che riceve via UART. Leggi le pagine e gli schemi ufficiali di Waveshare e SpotPear, poi proponi: il ruolo di ogni scheda, quali pin liberi dell’header usare per la UART su ciascun lato (evitando i pin che il supporto di scheda o la console di avvio usano già), come alimentare entrambe le schede e una distinta dei materiali. Cita la pagina da cui viene ogni pin, e fammi una domanda alla volta quando qualcosa è una vera scelta.
Il codice minimo
Il cablaggio diventa codice in un solo punto su ogni scheda: la configurazione della UART. Questo è il lato della pancia, scritto per questa guida con il driver UART di ESP-IDF (driver/uart.h, le stesse chiamate dell’esempio uart_echo di ESP-IDF). Il lato della testa è uguale, con i suoi pin.
#include "driver/uart.h"
#define HEAD_UART UART_NUM_1
#define HEAD_UART_TX 4
#define HEAD_UART_RX 5
#define HEAD_UART_BAUD 115200
void head_link_init(void)
{
const uart_config_t config = {
.baud_rate = HEAD_UART_BAUD,
.data_bits = UART_DATA_8_BITS,
.parity = UART_PARITY_DISABLE,
.stop_bits = UART_STOP_BITS_1,
.flow_ctrl = UART_HW_FLOWCTRL_DISABLE,
.source_clk = UART_SCLK_DEFAULT,
};
ESP_ERROR_CHECK(uart_driver_install(HEAD_UART, 1024, 0, 0, NULL, 0));
ESP_ERROR_CHECK(uart_param_config(HEAD_UART, &config));
ESP_ERROR_CHECK(uart_set_pin(HEAD_UART, HEAD_UART_TX, HEAD_UART_RX,
UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE));
}
Un dettaglio è facile da perdere. Sull’ESP32-P4, i pin predefiniti di ESP-IDF per UART1 sono GPIO10 e GPIO11, e su questa scheda quei pin portano l’audio (word select e data in dell’I2S). uart_set_pin instrada invece UART1 su GPIO4 e GPIO5 attraverso la matrice GPIO, così i pin predefiniti non vengono mai toccati. Inviare è poi una sola chiamata, uart_write_bytes(HEAD_UART, data, len); cosa va in data è la guida 10.
Errori comuni e come testarlo
- TX su TX. Se non arriva niente, scambia i due fili dati. Ogni TX va all’RX dell’altra scheda.
- Nessun filo di massa. Senza una massa comune il segnale non ha riferimento, e la testa legge spazzatura o niente.
- Unire i pin 3V3. Ogni scheda è alimentata dal suo cavo USB; lascia 3V3 scollegato.
- Usare i pin della console. GPIO37 e GPIO38 sulla pancia, e GPIO43 e GPIO44 sulla testa, sono UART0, collegati alla porta seriale USB di ogni scheda. I messaggi lì si mescolano con il log di avvio.
- Cavi femmina su un header senza pin. I cavi Dupont femmina-femmina hanno bisogno di pin maschi su entrambe le schede. Controlla che gli header delle tue schede abbiano i pin prima di pianificare il cablaggio.
- Un cavo USB solo di ricarica. Se Windows non mostra una nuova porta COM quando colleghi una scheda, prova un altro cavo (guida 2).
Per testare il collegamento prima che esista qualsiasi protocollo, flasha entrambe le schede con l’esempio uart_echo di ESP-IDF impostato su questi pin, oppure invia una riga dalla pancia e registra ciò che legge la testa con uart_read_bytes. Se il testo arriva intatto a 115200 baud, il cablaggio è giusto.
Per andare oltre
- Lo schermo touch della pancia può fare di più che mostrare: un tocco può segnare un avviso come letto, cosa che la guida 9 costruisce con LVGL.
- Il QMI8658 della testa può capire quando qualcuno solleva il bot o lo tocca. La testa potrebbe rimandarlo indietro sul suo filo TX, ed è per questo che il collegamento ha due fili dati e non uno.
- Entrambe le schede hanno connettori per la batteria (MX1.25 sulla testa, un connettore per batteria al litio da 3,7 V sulla pancia). Il bot di questo percorso funziona via USB, il che mantiene semplice il progetto dell’alimentazione.
- La pagina ESP-IDF di Waveshare per la pancia elenca progetti di esempio (strumenti I2C, Wi-Fi station, codec I2S, LVGL) utili per verificare ogni parte della scheda da sola.
Questa guida ti è stata utile?
Tutte le guide sono gratuite. Se questa ti ha fatto risparmiare tempo, puoi offrirmi un caffè.
Offrimi un caffè