picoZ80 Manuale Utente

Il picoZ80 e' un sostituto drop-in per una CPU Z80 in qualsiasi computer con socket DIP-40. Si inserisce direttamente nel socket Z80 del vostro computer vintage e — senza alcuna modifica al computer host — fornisce memoria espansa, periferiche virtuali, emulazione di floppy e QuickDisk, filing system e un'interfaccia di gestione basata su browser tramite WiFi.

Questo manuale copre la scheda fisica, la configurazione iniziale, il collegamento a una macchina host e l'utilizzo dell'interfaccia web. Per dettagli sull'architettura, riferimento alla configurazione e informazioni sullo sviluppo consultate la picoZ80 Technical Guide.

Panoramica della Scheda

Il PCB del picoZ80 e' progettato per rientrare nell'ingombro di un package DIP standard a 40 pin. Tutti i 40 pin DIP emergono dal lato inferiore della scheda, corrispondendo esattamente alla piedinatura di uno Z80 reale, cosi' si inserisce direttamente in qualsiasi socket Z80 senza piegare o adattare.

La superficie superiore della scheda ospita tutti i componenti attivi. La scheda e' piu' stretta della maggior parte degli spazi interni dei computer Z80 e l'altezza sopra il socket rientra nell'involucro di un IC standard con un socket DIP-40 montato sotto.

Connettori e Indicatori

La scheda picoZ80 espone i seguenti connettori e indicatori:

Elemento	Descrizione
6-pin Debug Header	Situato sul bordo della scheda. Fornisce accesso SWD (Serial Wire Debug) all’RP2350, linee BOOTSEL e Reset per la programmazione iniziale, e Reset per l’ESP32. Vedere Piedinatura Debug Header di seguito.
Porta USB (Mini-B)	Connettivita’ USB per la programmazione del firmware tramite USB mass-storage (flash iniziale) e per il bridging USB-UART verso l’ESP32. Nelle revisioni della scheda v2.3a e successive puo’ essere presente anche una seconda porta USB dedicata per l’ESP32.
Slot SD Card	Slot SD card full-size gestito dall’ESP32. Contiene `config.json`, immagini ROM, immagini disco e strutture del filing system.

Piedinatura Debug Header

L'header a 6 pin e' l'interfaccia hardware primaria per la programmazione iniziale e il debug a livello di sorgente. I pin sono numerati dal Pin 1 all'estremita' piu' vicina al marcatore del bordo della scheda.

Pin	Segnale	Funzione
1	`SWCLK`	Clock Serial Wire Debug (ARM SWD)
2	`SWDIO`	Dati Serial Wire Debug (ARM SWD)
3	`Reset RP2350`	Reset attivo-basso per l’RP2350. Portare basso per resettare l’RP2350.
4	`Reset ESP32`	Reset attivo-basso per l’ESP32. Portare basso per mantenere l’ESP32 in reset.
5	`GND`	Riferimento di massa
6	`BOOTSEL`	Selezione modalita’ di avvio RP2350. Mantenere basso durante l’accensione/reset per entrare in modalita’ USB mass-storage.

NB. I Pin 1, 2 e 5 sono utilizzati per il debug SWD (SWCLK, SWDIO, GND). I Pin 3 e 6 sono utilizzati solo per la programmazione iniziale. Il Pin 4 e' utilizzato quando si deve impedire l'avvio dell'ESP32 durante il boot dell'RP2350 (ad es. durante la programmazione iniziale del firmware ESP32).

Per Iniziare

Seguire questi passaggi nell'ordine indicato la prima volta che si configura una scheda picoZ80:

Programmare il bootloader RP2350 tramite modalita' USB mass-storage (BOOTSEL).

Programmare il firmware ESP32 tramite esptool.

Preparare una SD card con config.json e le eventuali immagini ROM/disco necessarie.

Installare il picoZ80 nel socket Z80 del computer host.

Accendere, connettersi all'interfaccia web del picoZ80 e configurare come necessario.

Passo 1 — Programmazione del Bootloader RP2350

L'RP2350 non dispone di pulsanti fisici BOOTSEL o Reset. Entrambi i segnali sono disponibili sull'header di debug a 6 pin. Per entrare nel bootloader USB mass-storage:

Non inserire ancora il picoZ80 in un computer host — collegarlo a un PC solo tramite cavo USB.

Utilizzando un jumper o una sonda, mantenere il Pin 6 (BOOTSEL) basso.

Applicare alimentazione alla porta USB — l'RP2350 inizia l'avvio.

Rilasciare BOOTSEL subito dopo che la scheda viene enumerata come dispositivo USB mass-storage. (Se si mantiene BOOTSEL troppo a lungo dopo il reset, l'RP2350 non puo' accedere al chip Flash.)

Il PC montera' un'unita' denominata RPI-RP2 (o simile).

Copiare Bootloader_<version>.uf2 sull'unita' montata. L'RP2350 si auto-programma e si riavvia automaticamente.

Dopo la programmazione del bootloader, tutti gli aggiornamenti firmware successivi dell'RP2350 possono essere effettuati in modalita' wireless tramite la pagina web OTA — non e' necessario toccare nuovamente l'header di debug per i normali aggiornamenti firmware.

Passo 2 — Programmazione del Firmware ESP32

Il firmware ESP32 viene programmato utilizzando esptool. Nelle revisioni della scheda v2.3a e successive, l'ESP32 ha la propria porta USB e appare in modo indipendente sul PC host. Nelle revisioni precedenti (v2.0 – v2.2), l'ESP32 e' accessibile tramite l'RP2350 che funge da bridge USB-UART.

Configurare l'ambiente Python (una sola volta):

python3 -m venv ./venv/
source ./venv/bin/activate
cd $HOME/esptool

Quindi programmare tutti e quattro i componenti del firmware ESP32. Regolare PORT sul nodo dispositivo assegnato dal sistema operativo:

PORT=/dev/ttyUSB0       # Linux — regolare come necessario
# PORT=/dev/tty.usbmodem141403  # macOS

BINPATH=/path/to/esp32/build

python3 ./esptool.py \
  -p ${PORT} -b 115200 \
  --before default_reset --after hard_reset \
  --chip esp32s3 \
  write_flash \
  --flash_mode dio --flash_size 4MB --flash_freq 80m \
  0x0     ${BINPATH}/bootloader.bin \
  0x8000  ${BINPATH}/partition-table.bin \
  0x9000  ${BINPATH}/ota_data_initial.bin \
  0x10000 ${BINPATH}/sd_card.bin

NB. Tutti gli aggiornamenti firmware ESP32 successivi possono essere effettuati tramite la pagina web OTA (ota-esp32.htm) una volta completata la programmazione iniziale.

Passo 3 — Preparazione della SD Card

La SD card e' il supporto di archiviazione primario per il picoZ80. Contiene il file di configurazione, le immagini ROM, le immagini disco e le directory del filing system.

Requisiti di formattazione:

File system FAT32.

Qualsiasi capacita' supportata da FAT32 (tipicamente si raccomanda fino a 32GB per una formattazione affidabile).

File minimi richiesti:

config.json nella root della SD card — il file di configurazione principale. Vedere Configurazione Base per un esempio minimo.

Directory webfs/ — le risorse dell'interfaccia web ESP32. Copiare il contenuto della directory webfs/ dal repository del progetto nella root della SD card.

Directory opzionali ma raccomandate:

Directory	Contenuti
`MZF/`	File di programma in formato MZF per il caricamento tramite il filing system
`ROM/`	Immagini ROM referenziate da `config.json`
`DSK/`	Immagini disco floppy (formato DSK) per l’emulazione WD1773
`QD/`	Immagini QuickDisk per l’emulazione QuickDisk
`TZFS/`	Strutture del TranZPUter Filing System
`RFS/`	Strutture del ROM Filing System

La SD card puo' essere gestita interamente tramite il Gestore File web una volta che il picoZ80 e' in funzione — e' possibile caricare immagini ROM, modificare `config.json` e creare directory dal browser senza rimuovere fisicamente la scheda.

Passo 4 — Installazione nel Computer Host

La sicurezza prima di tutto: Spegnere e scollegare sempre il computer host prima di installare o rimuovere il picoZ80. La scheda opera internamente a 3.3V; i pin DIP-40 si collegano al bus a 5V dell'host tramite circuiteria di interfaccia appropriata, ma la scheda non deve mai essere inserita o rimossa con l'alimentazione attiva.

Procedura di installazione:

Spegnere il computer host e scaricare qualsiasi carica statica.

Rimuovere il chip CPU Z80 esistente dal suo socket DIP-40. Si raccomanda l'uso di un estrattore per chip per evitare di piegare i pin.

Inserire la SD card nello slot SD card del picoZ80.

Allineare il picoZ80 con il socket Z80, assicurandosi che il Pin 1 del picoZ80 (contrassegnato con un punto o una tacca) sia allineato con il Pin 1 del socket (anch'esso contrassegnato, e tipicamente adiacente alla tacca sulla serigrafia del profilo dell'IC).

Premere il picoZ80 delicatamente e uniformemente nel socket. Assicurarsi che tutti i 40 pin siano inseriti. Non forzare — se si avverte resistenza, rimuovere e controllare l'allineamento dei pin.

Accendere il computer host.

Al primo avvio dopo un'installazione firmware fresca, l'ESP32 si avviera' in modalita' Access Point, trasmettendo una rete WiFi denominata picoZ80. Connettersi a questa rete per accedere all'interfaccia web e completare la configurazione WiFi iniziale.

NB. Il picoZ80 si alimenta dalla linea 5V sul pin VCC del socket Z80. Il convertitore buck integrato fornisce 3.3V a tutti i componenti della scheda. Assicurarsi che l'alimentatore 5V del computer host possa erogare almeno 500mA — il picoZ80 puo' assorbire fino a 400mA sotto carico di picco (RP2350 a 300MHz con WiFi attivo).

Configurazione WiFi

La connettivita' WiFi richiede che la rete di adattamento dell'antenna sia popolata sul PCB e che il firmware ESP32 sia compilato con il WiFi abilitato. Vedere l'Avviso Normativo di seguito. Se si utilizza un firmware solo NCM, saltare questa sezione e utilizzare invece la connessione USB NCM.

Il co-processore ESP32 del picoZ80 fornisce la connettivita' WiFi. Al primo avvio (o quando non sono state salvate credenziali WiFi) l'ESP32 si avvia in modalita' Access Point (AP) cosi' che ci si possa collegare da qualsiasi dispositivo con un browser e configurare le impostazioni della rete domestica.

Connessione in Modalita' Access Point

Sul telefono, tablet o laptop, aprire le impostazioni WiFi e cercare una rete denominata picoZ80 (o come configurato nel campo esp32.wifi.ssid del config.json in modalita' AP).

Connettersi alla rete picoZ80. La password AP predefinita e' pZ80pZ80 (consultare le note di rilascio del firmware se questa e' cambiata).

Aprire un browser e navigare a http://192.168.4.1 — questo e' l'indirizzo IP predefinito in modalita' AP. Apparira' l'interfaccia web del picoZ80.

Navigare alla pagina WiFi Manager per inserire l'SSID e la password della rete domestica.

Cliccare Save & Connect. L'ESP32 si riavviera' e si connettera' alla rete domestica come client.

Modalita' Client (Station)

Una volta configurato in modalita' client, l'ESP32 si unisce alla rete WiFi domestica ed e' raggiungibile all'indirizzo IP mostrato nella pagina Dashboard. Se si e' impostato un IP fisso nel `config.json` (raccomandato per facilita' di accesso), navigare direttamente a:

http://192.168.1.192

Sostituire l'indirizzo IP configurato. Se si utilizza DHCP, trovare l'indirizzo assegnato nella lista dei client DHCP del router.

L'interfaccia web funziona interamente nel browser. Non e' richiesto alcun software aggiuntivo. Il web server del picoZ80 funziona sulla porta 80.

Connessione USB NCM (Senza WiFi)

Se la scheda e' compilata con il firmware NCM (sdkconfig.mode_ncm_only o sdkconfig.mode_wifi_and_ncm), un adattatore Ethernet virtuale appare sul computer host quando la porta USB dell'ESP32 e' collegata. Il server DHCP integrato del picoZ80 assegna automaticamente un indirizzo IP all'host — non e' necessaria alcuna configurazione di rete manuale.

Collegare un cavo USB dal computer host alla porta USB ESP32 sul picoZ80.

Attendere alcuni secondi affinche' il sistema operativo dell'host rilevi il nuovo adattatore di rete.

Aprire un browser web e navigare a http://192.168.7.1.

Dovrebbe apparire la pagina Dashboard del picoZ80.

Questa modalita' fornisce accesso completo a tutte le funzionalita' dell'interfaccia web: modifica della configurazione, aggiornamenti firmware, gestione file e selezione personalita'. Non sono necessari antenna WiFi o componenti radio.

Interfaccia Web

L'interfaccia web del picoZ80 e' un'applicazione Bootstrap 4 a otto pagine servita dall'ESP32. Tutte le pagine — incluso il nuovo editor di configurazione GUI — sono accessibili dalla barra di navigazione in cima a ciascuna pagina. Le risorse web sono memorizzate nella directory webfs/ sulla SD card e possono essere aggiornate indipendentemente dal firmware.

Dashboard (index.htm)

La Dashboard e' la pagina iniziale dell'interfaccia web. Visualizza informazioni di sistema in tempo reale e fornisce una panoramica rapida dello stato del picoZ80.

Le informazioni mostrate nella Dashboard includono:

Firmware Version — la versione firmware RP2350 attualmente in esecuzione e la data di compilazione.

ESP32 Version — la versione firmware del co-processore ESP32.

Active Partition — quale dei due slot firmware (1 o 2) e' attualmente attivo.

Active Persona — la personalita' macchina attualmente caricata (ad es. MZ-700, MZ-80A).

RP2350 Clock — frequenza CPU corrente in MHz.

PSRAM Clock — frequenza clock SPI PSRAM corrente.

WiFi Status / Network Status — nelle modalita' WiFi: modalita' (AP o client), SSID e indirizzo IP assegnato. In modalita' NCM Only: questo pannello e' intitolato Network Configuration e mostra lo stato della rete USB NCM (indirizzo IP, netmask) — non ci sono campi relativi al WiFi.

WiFi RSSI (solo modalita' WiFi) — indicatore di intensita' del segnale ricevuto in tempo reale (dBm) che si aggiorna automaticamente ogni tre secondi. Codificato per colore: verde (≥ -50 dBm, eccellente), blu (≥ -70 dBm, buono), arancione (≥ -80 dBm, discreto), o rosso (< -80 dBm, scarso). Non mostrato in modalita' NCM Only.

WiFi TX Power (solo modalita' WiFi) — potenza di trasmissione corrente in dBm, anch'essa aggiornata in tempo reale. Non mostrata in modalita' NCM Only.

SD Card — se una SD card e' presente e lo stato del montaggio del filesystem.

Uptime — tempo trascorso dall'ultimo riavvio.

La Dashboard fornisce anche pulsanti per riavviare l'RP2350 e per attivare un ricaricamento della configurazione dalla SD card senza un riavvio completo.

Due menu a discesa nell'angolo in alto a destra della barra di navigazione sono disponibili in ogni pagina:

Menu Azioni
- Change Floppy Disk 1 / 2 — selezionare un nuovo file immagine DSK dalla SD card e montarlo nello slot 1 o slot 2 del controller floppy virtuale WD1773 senza riavviare. Il nome del file dell'immagine disco attualmente caricata e' visualizzato accanto a ciascuna voce (o "none" se nessuna immagine e' caricata). Quando il controller floppy attivo supporta piu' di due drive, appaiono anche Change Floppy Disk 3 e 4 (altrimenti sono nascosti).
- Change QD Disk — sostituire al volo il file immagine QuickDisk attivo. Il nome del file dell'immagine QD attualmente caricata e' mostrato accanto alla voce.
- Reload RP2350 Config — inviare un comando di ricaricamento all'RP2350 tramite la UART ESP32-RP2350; l'RP2350 rianalizza il config.json e riapplica la mappa di memoria e la configurazione dei driver senza un ciclo completo di spegnimento e riaccensione.

Menu Riavvio
- ESP32 — riavvio software del co-processore ESP32 (riavvia il web server e lo stack WiFi, l'RP2350 non e' interessato).
- RP2350B — reset del processore RP2350 (riesegue il bootloader e ricarica lo slot firmware attivo, la CPU host viene messa in pausa durante il reset).
- Host — asserire la linea di reset del computer host, riavviando il computer legacy nel socket Z80 senza influire sulla scheda picoZ80 stessa.
- IPL Reset — eseguire un reset IPL (Initial Program Load) commutando il bit 3 della Porta C del PPI 8255, riportando la macchina in modalita' di avvio (BST). Disponibile sulle personalita' MZ-80B, MZ-2000, MZ-2200 e MZ-2500 — equivalente alla pressione del pulsante IPL sull'hardware originale.
- RP2350 UF2 Boot / RP2350 UF2 Boot (App) — riavviare l'RP2350 nel suo bootloader USB (BOOTSEL) in modo che un firmware .uf2 possa essere trascinato e rilasciato sull'unita' montata. La variante semplice entra direttamente nel bootloader; la variante (App) vi rientra dallo slot applicativo in esecuzione.

Editor di Configurazione (config.htm)

La pagina Editor di Configurazione fornisce un editor nel browser per il file config.json memorizzato sulla SD card. L'editor offre evidenziazione della sintassi e validazione JSON di base.

Per modificare la configurazione:

Navigare alla pagina Editor di Configurazione.

Il config.json corrente viene caricato nell'editor automaticamente.

Apportare le modifiche. L'editor evidenziera' gli errori di sintassi in rosso.

Cliccare Save per scrivere il file aggiornato sulla SD card.

Cliccare Apply (o riavviare) per applicare la nuova configurazione. L'RP2350 legge la configurazione all'avvio, la minifica e la memorizza nella Flash — gli avvii successivi utilizzano la copia in Flash se non e' presente una SD card.

Le modifiche alla mappa di memoria, alle immagini ROM e alla mappa I/O hanno effetto al successivo reset dell'RP2350. Le modifiche alle impostazioni WiFi nel blocco esp32.wifi hanno effetto al successivo riavvio dell'ESP32.

NB. L'Editor di Configurazione opera direttamente sul file della SD card. E' buona pratica mantenere una copia di backup di un config.json funzionante sul proprio PC prima di apportare modifiche significative.

Configurazione GUI (configgui.htm)

La pagina Configurazione GUI fornisce un'alternativa grafica all'Editor di Configurazione JSON grezzo. Tutte le impostazioni di configurazione sono presentate come campi di input etichettati, menu a discesa e tabelle modificabili, organizzati in quattro schede:

RP2350 Global — impostazioni globali di tensione core, frequenza CPU e frequenza PSRAM che si applicano a entrambe le partizioni.

Partition 1 / Partition 2 — mappa di memoria per partizione (indirizzo, dimensione, tipo, stati di attesa, banco, file ROM), mappa porte I/O (indirizzo, dimensione, tipo, handler) e configurazione driver (ad es. MZ80AFI, RFS, MZ-1E30, Celestite, PCW9512) con toggle di abilitazione/disabilitazione e un pulsante Add Driver per l'insieme completo dei driver di interfaccia disponibili. Ogni sezione ha pulsanti aggiungi/rimuovi per le righe.

Regolazione del bus GPIO. Le impostazioni core per partizione consentono di regolare le caratteristiche elettriche del bus Z80 in modo indipendente per ciascuno dei tre gruppi di bus — Address, Data e Control. Per ogni gruppo si possono impostare l'intensita' di pilotaggio (2 / 4 / 8 / 12 mA), lo slew rate (slow = bassa EMI, oppure fast), l'ingresso Schmitt-trigger (on / off) e la resistenza di pull (float / up / down). Una tabella opzionale di override per-pin consente di sovrascrivere una qualsiasi di queste impostazioni per singoli pin GPIO dove una particolare macchina host lo richiede. Il valore predefinito e' pilotaggio a 2 mA con slew lento (minima EMI). Le impostazioni core espongono anche il valore Z80 refresh: 0 disabilita il refresh DRAM, 1 emette un refresh a ogni fetch di opcode e N emette un refresh ogni N fetch — consentendo di bilanciare l'attivita' di refresh con la temporizzazione delle periferiche.

ESP32 — tipo dispositivo ESP32, controlli interfaccia di rete (WiFi Enable, NCM Enable, NCM Retries, NCM Retry Period) e configurazione WiFi (SSID, password, indirizzo IP, netmask, modalita' AP/Client, DHCP, TX power). Oltre ai campi WiFi si possono impostare l'indirizzo IP NCM USB e la netmask, e un nome prodotto USB personalizzato — utile per distinguere piu' schede collegate allo stesso host.

Cliccare Save Configuration per scrivere le modifiche nel config.json (la versione precedente viene salvata come backup) e ricaricare automaticamente la configurazione dell'RP2350. Cliccare Reload per rileggere il config.json corrente dalla SD card, scartando eventuali modifiche non salvate. Per modifiche avanzate oltre a cio' che la GUI espone, utilizzare l'Editor di Configurazione per modificare direttamente il JSON grezzo.

Browser file. I campi ROM e immagine disco forniscono un pulsante Browse che apre un selettore file della SD card, cosi' da poter selezionare un file senza digitarne il percorso. Il percorso scelto viene memorizzato relativamente alla radice della SD card.

Porta della scheda seriale. Le interfacce seriali RS-232C MZ-8BIO3 e MZ-1E24 accettano un parametro port — l'indirizzo I/O di base della scheda (predefinito 0xB0) — modificabile nella riga del driver.

Serie di driver e Porta I/O di base. Il menu a discesa Add Driver offre solo i driver validi per il firmware in esecuzione — la pagina rileva se il firmware e' una build Sharp, Amstrad, Tatung o Open (sperimentatore). Per le schede di interfaccia rilocabili — MZ-1R12, MZ-1R18, MZ-1R23, MZ-1R37, PIO-3034, MZ-8BIO3, MZ-1E24, MZ-1E05 e Celestite — viene mostrato un singolo campo Base I/O Port, precompilato con la base autentica della scheda. Modificarlo per spostare le porte della scheda quando il picoZ80 e' utilizzato su una scheda di propria progettazione; la GUI scrive automaticamente la mappatura corretta. Ogni driver puo' anche caricare le proprie immagini System ROM, che sovrascrivono le ROM dell'host quando il driver e' abilitato.

Modalita' demo. Un aiuto opzionale per le presentazioni che oscura i campi sensibili — SSID e password WiFi, e indirizzi IP/gateway — dalle pagine web, cosi' che l'interfaccia possa essere mostrata in sicurezza in screenshot o registrazioni dello schermo senza esporre i dettagli della propria rete.

Gestore File (filemanager.htm)

Il Gestore File fornisce una vista basata su browser del contenuto della SD card. E' possibile navigare le directory, caricare nuovi file (immagini ROM, immagini disco, file di programma MZF), scaricare file esistenti sul PC, creare nuove directory e cancellare file e directory.

Operazioni comuni nel Gestore File:

Caricare un'immagine ROM — navigare alla directory ROM/ e utilizzare il pulsante Upload per trasferire il file ROM dal PC.

Caricare un'immagine disco — navigare a DSK/ (floppy) o QD/ (QuickDisk) e caricare il file immagine. Una volta caricato, il nome del file dell'immagine disco corrente e' visualizzato nel menu Azioni accanto a ciascuno slot floppy e QD per un riferimento rapido.

Caricare programmi MZF — navigare a MZF/ o alla directory del filing system pertinente e caricare i file MZF.

Backup config.json — cliccare l'icona di download accanto a config.json per salvare una copia sul PC.

Backup SD Card — cliccare il pulsante Backup SD per scaricare l'intero contenuto della SD card come un singolo archivio sul computer locale. Questo e' particolarmente utile quando il picoZ80 e' installato all'interno di un computer host e rimuovere fisicamente la SD card e' poco pratico. Il backup cattura tutti i file di configurazione, le immagini ROM, le immagini disco e i dati del filing system in un'unica operazione.

Le operazioni sui file vengono eseguite direttamente sulla SD card tramite l'ESP32. Il caricamento di file di grandi dimensioni puo' richiedere alcuni secondi a seconda della dimensione del file e della qualita' del segnale WiFi.

Selezione Personalita' (personality.htm)

La pagina Selezione Personalita' consente di scegliere quale personalita' macchina (persona) il picoZ80 presenta al computer host. Diverse personalita' caricano diverse mappe di memoria, immagini ROM e associazioni di driver virtuali dalla configurazione.

Personalita' attualmente supportate:

MZ-700 — personalita' MZ-700 completa con bank switching, video virtuale, I/O tastiera, emulazione floppy WD1773, emulazione QuickDisk e ROM Filing System. Include CP/M v2.23 (48K), SA-1510 BASIC e Microsoft BASIC v4.7, tutti con accesso in lettura/scrittura alla SD card.

MZ-80K — personalita' Sharp MZ-80K con monitor SP-1002, PPI 8255, PIT 8253 e tastiera LS367. Sono disponibili due interfacce floppy: la MZ80FIO nativa (Toshiba T3444M) — l'interfaccia disco originale MZ-80FD, che avvia e legge tutti i dischi MZ-80K (giochi, applicazioni, BASIC e CP/M); e la scheda MZ80AFI (l'FDC dell'MZ-80A) — usata per CP/M, in grado di avviare il CP/M MZ-80K e leggere i dischi CP/M MZ-80K originali dall'interno del CP/M come unita' C:/D:. La personalita' puo' inoltre associare le altre schede di interfaccia dell'MZ-80A (RFS, MZ-1E14/E19, MZ-1R12/R18/R37, PIO-3034). Il CP/M richiede la modalita' personalita' virtuale.

MZ-80A — personalita' MZ-80A (in sviluppo).

MZ-80B — personalita' MZ-80B (in sviluppo).

MZ-800 — personalita' Sharp MZ-800 — macchina a doppia modalita' che funziona in modalita' di compatibilita' MZ-700 o in modalita' MZ-800 nativa (grafica 320×200 / 640×200, palette a 4/16 colori tramite il GDG), sonoro PSG SN76489, floppy WD1773 e QuickDisk. Commuta modalita' al volo. Puo' associare l'intero insieme di schede di interfaccia MZ-80A/MZ-700 piu' le schede seriali RS-232C MZ-8BIO3 / MZ-1E24.

PCW-9512 — personalita' Amstrad PCW-9512 con gate array, uPD765 FDC, 512KB RAM paginata e controller per stampante a margherita.

Basic CPU — uno Z80 nudo nel socket senza driver specifici della macchina, per una semplice sostituzione drop-in o per lo sviluppo Z80 generico.

OpenZ80 — la personalita' sperimentatore per una scheda di propria progettazione o una macchina non supportata (vedere Altre Macchine). A differenza delle personalita' sopra elencate, e' una build firmware dedicata anziche' una selezione in questa pagina: programmare il firmware OpenZ80 in una partizione utilizzando le pagine Aggiornamenti Firmware, quindi aggiungere le sue schede di interfaccia e impostare le loro porte I/O di base nella pagina Configurazione GUI.

Il cambio di personalita' modifica la mappa di memoria attiva e le immagini ROM caricate senza riavviare l'host. Il picoZ80 reinizializza il banking della memoria con la configurazione della nuova personalita' e l'host vede il nuovo layout di memoria alla successiva transazione sul bus Z80.

Aggiornamenti Firmware (OTA)

Il firmware sia dell'RP2350 che dell'ESP32 puo' essere aggiornato over-the-air (OTA) dall'interfaccia web senza alcun accesso fisico all'header di debug.

Aggiornamento OTA RP2350 (ota-rp2350.htm)

Compilare il firmware RP2350 utilizzando gli script di build — il binario di output sara' in fw/bin/ con un nome file con versione (ad es. BaseZ80_v3.009.bin).

Navigare a http://<device-ip>/ota-rp2350.htm.

Selezionare quale slot di partizione aggiornare (Slot 1 o Slot 2). Lo slot attualmente attivo e' mostrato nella Dashboard — e' buona pratica aggiornare lo slot inattivo cosi' che il firmware esistente rimanga disponibile se l'aggiornamento fallisce. Sono disponibili due checkbox opzionali: Clear App Config cancella le immagini ROM e i dati di configurazione per lo slot di destinazione, e Clear Flash Header reimposta la tabella delle partizioni ai valori di fabbrica — utilizzarli quando si aggiorna a una versione firmware con uno schema di configurazione incompatibile.

Cliccare Choose File, selezionare il file .bin, quindi cliccare Upload.

Attendere il completamento del caricamento e della verifica. La pagina confermera' il successo e mostrera' la nuova partizione come disponibile.

Per attivare il nuovo firmware, navigare alla sezione di selezione partizione della stessa pagina, scegliere lo slot appena aggiornato e cliccare Set Active & Reboot. L'RP2350 si riavvia con il nuovo firmware.

Le partizioni applicative utilizzano formato binario puro (non UF2) perche' risiedono a indirizzi flash non standard. Il bootloader verifica il checksum dell'immagine prima di attivare la nuova partizione — se la verifica fallisce, lo slot attivo esistente rimane in uso.

Aggiornamento OTA ESP32 (ota-esp32.htm)

Compilare il firmware ESP32 — il binario di output e' esp32/build/tzpuPico_esp32.bin.

Navigare a http://<device-ip>/ota-esp32.htm.

Cliccare Choose File, selezionare il file .bin, quindi cliccare Upload.

L'ESP32 si riavvia automaticamente con il nuovo firmware dopo un caricamento riuscito.

La pagina OTA accetta anche un archivio FilePack per aggiornare le risorse dell'interfaccia web memorizzate nella directory webfs/ sulla SD card. Questo permette di aggiornare la UI web indipendentemente dal binario firmware dell'ESP32.

WiFi Manager (wifimanager.htm)

Nota: La pagina WiFi Manager e' disponibile solo quando il firmware ESP32 e' compilato con il WiFi abilitato (sdkconfig.mode_wifi_only o sdkconfig.mode_wifi_and_ncm). In modalita' NCM Only questa pagina non e' presente — la connettivita' di rete e' fornita automaticamente tramite USB NCM senza alcuna configurazione da parte dell'utente.

La pagina WiFi Manager configura le impostazioni della rete wireless dell'ESP32. Le modifiche effettuate qui vengono salvate nel NVS (non-volatile storage) dell'ESP32 e hanno effetto al successivo riavvio.

Impostazioni disponibili:

WiFi Mode — Access Point (il picoZ80 crea la propria rete) o Client (il picoZ80 si unisce a una rete esistente).

SSID — il nome della rete da creare (modalita' AP) o a cui unirsi (modalita' client).

Password — la passphrase WiFi.

IP Address / Netmask / Gateway — impostazioni IP fisso per la modalita' client (raccomandate per un accesso coerente).

DHCP — abilitare per ottenere un indirizzo automaticamente dal router; disabilitare per utilizzare le impostazioni IP fisso sopra indicate.

TX Power — potenza di trasmissione WiFi in unita' da 0.25 dBm (intervallo 8-84, cioe' 2-21 dBm). Impostare a 0 per utilizzare il valore predefinito specifico della regione. Il PCB del picoZ80 e' progettato per una radiazione RF minima, quindi quando la scheda e' installata all'interno di un case metallico del computer il segnale verso il router potrebbe essere debole. Aumentare la TX Power puo' migliorare la connettivita' a scapito di un consumo energetico leggermente superiore; diminuirla puo' ridurre le interferenze in ambienti con molti dispositivi WiFi. L'RSSI corrente e la TX Power effettiva sono mostrati nella Dashboard e in questa pagina, aggiornati in tempo reale ogni tre secondi.

Dopo il salvataggio, cliccare Reboot ESP32 per applicare le nuove impostazioni. L'ESP32 si riavviera' e si connettera' utilizzando la nuova configurazione. Se la connessione in modalita' client fallisce (SSID o password errati), l'ESP32 tornera' alla modalita' Access Point dopo un timeout, consentendo di riconnettersi e correggere le impostazioni.

Configurazione Base

Tutto il comportamento del picoZ80 e' controllato dal config.json sulla SD card. Quella che segue e' una configurazione minima funzionante per uno Sharp MZ-700. Consultare la Technical Guide — Configuration Reference per una descrizione completa di tutte le opzioni.

{
  "esp32": {
    "core": {
      "device": "Z80",
      "mode":   0
    },
    "wifi": {
      "override":  1,
      "wifimode":  "client",
      "ssid":      "YourNetwork",
      "password":  "YourPassword",
      "ip":        "192.168.1.192",
      "netmask":   "255.255.255.0",
      "gateway":   "192.168.1.1",
      "dhcp":      0,
      "webfs":     "webfs",
      "persist":   0
    }
  },
  "rp2350": {
    "core": {
      "cpufreq":   300000000,
      "psramfreq": 133000000,
      "voltage":   1.10
    },
    "z80": [
      {
        "memory": [
          {
            "enable":   1,
            "addr":     "0x0000",
            "size":     "0x1000",
            "type":     "ROM",
            "bank":     0,
            "tcycwait": 0,
            "tcycsync": 0,
            "task":     "",
            "file":     "/ROM/mz700.rom",
            "fileofs":  0
          },
          {
            "enable":   1,
            "addr":     "0x1000",
            "size":     "0xCFFF",
            "type":     "RAM",
            "bank":     0,
            "tcycwait": 0,
            "tcycsync": 0,
            "task":     "",
            "file":     "",
            "fileofs":  0
          },
          {
            "enable":   1,
            "addr":     "0xD000",
            "size":     "0x3000",
            "type":     "PHYSICAL_VRAM",
            "bank":     0,
            "tcycwait": 2,
            "tcycsync": 1,
            "task":     "",
            "file":     "",
            "fileofs":  0
          }
        ],
        "io":      [],
        "drivers": []
      }
    ]
  }
}

Questo esempio mappa:

0x0000 – 0x0FFF — 4KB ROM caricata da /ROM/mz700.rom sulla SD card nella PSRAM banco 0.

0x1000 – 0xCFFF — 48KB RAM nella PSRAM banco 0 (lettura/scrittura, zero stati di attesa).

0xD000 – 0xFFFF — 12KB passati all'hardware fisico dell'host (VRAM e registri I/O), con 2 stati di attesa e sincronizzazione T1 abilitata.

Configurazione del Server File di Rete

Il picoZ80 puo' caricare, salvare e listare programmi BASIC sulla rete utilizzando il prefisso dispositivo NETx: nello Sharp MZ BASIC. Cio' richiede tre componenti: l'interfaccia virtuale Celestite (configurata nel JSON della personalita'), il picoZ80 connesso alla stessa rete del PC (tramite WiFi o USB NCM) e il file server Python netfs.py in esecuzione sul PC.

Prerequisiti

Python 3.6 o successivo installato sul PC.

La personalita' picoZ80 deve includere l'interfaccia Celestite nella configurazione driver del config.json.

L'interfaccia Celestite deve avere il parametro ip impostato sull'indirizzo IP del PC e la porta di netfs.py nel config.json.

Il picoZ80 e il PC devono trovarsi sulla stessa rete (modalita' client WiFi o USB NCM).

Una directory sul PC contenente file di programma MZF da servire.

Avvio del File Server

Il file server si trova in tools/NetFileServer/netfs.py nel repository picoZ80. Avviarlo da un terminale:

# Servire file dalla directory corrente sulla porta predefinita 6800:
python3 netfs.py --dir ./mzf_files

# Servire file su una porta personalizzata con directory di unita' multiple:
python3 netfs.py --port 6800 --dir ./games --dir2 ./utilities --dir3 ./basic_programs

# Ogni --dirN corrisponde a NETx: in BASIC (--dir = NET1:, --dir2 = NET2:, ecc.)

Il server supporta le unita' 1-7 (NET1: fino a NET7:), ciascuna mappata su una directory separata sul PC. Resta in ascolto per connessioni TCP sulla porta 6800 (configurabile con --port). Il server e' multi-threaded e gestisce automaticamente il parsing degli header MZF.

Formati di file supportati: .mzf, .mzt, .m12 (formato nastro Sharp MZ con header da 128 byte) e file binari grezzi (.bin, .rom, .dat).

Utilizzo di NETx: in BASIC

Una volta che il file server e' in esecuzione sul PC, utilizzare il prefisso dispositivo NETx: nei comandi BASIC. Il driver Celestite W5100 del picoZ80 si connette automaticamente al PC:

DIR NET1:                  Listare file sull'unita' di rete 1 (directory PC)
LOAD "NET1:MYPROG"         Caricare un programma dal PC
SAVE "NET1:MYPROG"         Salvare un programma sul PC
LOAD "NET3:GAME"           Caricare dall'unita' 3 (mappata su --dir3)

Risoluzione Problemi: Se la connessione fallisce, verificare che l'indirizzo IP del picoZ80 possa raggiungere il PC (controllare la pagina di stato della Dashboard per l'IP assegnato), assicurarsi che nessun firewall stia bloccando la porta 6800 e confermare che il file server sia in esecuzione. Il server stampa le informazioni di connessione sul terminale quando un client si connette.

Driver e Interfacce

Il picoZ80 utilizza un'architettura a driver modulare. Ogni macchina host e' implementata come driver di personalita' che definisce la mappa di memoria, gli handler I/O e le periferiche supportate. L'hardware di espansione e' implementato come driver di interfaccia che si collegano a una personalita'. Tutti i driver sono configurati tramite JSON nel config.json sulla SD card. I driver di personalita' sono raggruppati per produttore di seguito.

Serie Sharp MZ / X1

Le macchine delle serie Sharp MZ e X1 sono gli obiettivi primari del progetto picoZ80. Ogni modello di macchina ha un driver di personalita' dedicato con supporto per il proprio set specifico di periferiche.

Driver di Personalita' Macchina

Ogni driver di personalita' emula un computer Sharp MZ completo. La personalita' viene selezionata tramite la pagina web Selezione Personalita' o modificando il campo "name" nell'array "drivers" del config.json.

Personalita’	Driver	Descrizione
MZ-700	`MZ700`	Sharp MZ-700 con memoria bank-switched, VRAM, tastiera, 8253 PIT. La personalita’ predefinita.
MZ-1500	`MZ1500`	Superset dell’MZ-700 con Quick Disk integrato, PCG, PSG stereo (SN76489AN), stampante Z80 PIO.
MZ-80K	`MZ80K`	Sharp MZ-80K con monitor SP-1002, 8253 PIT, 8255 PPI, tastiera LS367, floppy nativo MZ-80FD (T3444M) e MEMSW per CP/M. Puo’ utilizzare l’intero set di schede di interfaccia dell’MZ-80A. Il CP/M richiede la modalita’ virtuale.
MZ-800	`MZ800`	Sharp MZ-800. Doppia modalita’ (compatibile MZ-700 + grafica GDG nativa a 320/640 pixel di larghezza, 4/16 colori), PSG SN76489, FDC WD1773 + QuickDisk. Esegue software MZ-700 e CP/M.
MZ-80A	`MZ80A`	Sharp MZ-80A con monitor SA-1510, 8253 PIT, 8255 PPI, MEMSW per CP/M.
MZ-2000	`MZ2000`	Sharp MZ-2000 con IPL ROM, commutazione modalita’ BST/NST, overlay VRAM, MB8866 FDC.
MZ-2200	`MZ2200`	Sharp MZ-2200, variante dell’MZ-2000 con la stessa architettura.
MZ-80B	`MZ80B`	Sharp MZ-80B. IPL ROM da 2K, modalita’ BST/NST, monocromatico con pagine GRPH doppie, 8253 PIT, 8255 PPI, Z80 PIO.
MZ-2500	`MZ2500`	Sharp MZ-2500 (SuperMZ). MMU a 8 pagine, modalita’ di compatibilita’ MZ-2000/MZ-80B, YM2203 FM+PSG, G-CRTC, MB8876 FDC. La modalita’ virtuale supporta software guidato da interrupt, formato disco nativo D88 e soppressione interrupt one-shot.

Driver di Interfaccia

I driver di interfaccia vengono aggiunti a una personalita' tramite l'array "if" nella configurazione JSON del driver. Ogni interfaccia puo' essere abilitata o disabilitata indipendentemente e ha la propria ROM, immagine disco e configurazione I/O.

Interfaccia	Nome JSON	Porte I/O	Descrizione
ROM Filing System	`RFS`	0x51–0x53, 0xC1–0xC8, 0xEFF8–0xEFFF	Monitor migliorato con archiviazione su SD card, avvio CP/M, banking ROM.
TranZPUter Filing System	`TZFS`	0x60 (modalita’ di memoria), 0x68 (processore di servizio)	Monitor multi-bank + file system CP/M per la personalita’ MZ-700 (mutuamente esclusivo con RFS). Effettua il boot del CP/M; immagini drive impostate per unita’ tramite i campi file di `param`.
Floppy Controller (MZ-700)	`MZ-1E05`	0xD8–0xDE	FDC basato su WD1773. Fino a 4 unita’. Immagini DSK/RAW/D88.
Floppy Controller (MZ-80K)	`MZ80FIO`	0xF8–0xFB, 0xF000–0xF3FF	Interfaccia nativa MZ-80FD/MZ-80FIO che pilota un FDC Toshiba T3444M. Settori FM da 128 byte, fino a 4 unita’, immagini DSK estese CPC.
Floppy Controller (MZ-80A)	`MZ80AFI`	0xD8–0xDE, 0xF3FE–0xF3FF	AFI MZ-80A con toggle A10 basato su DRQ per operazione a 2 MHz.
Floppy Controller (MZ-2000)	`MZ-8BFI` o `E0054PA`	0xD8–0xDE	FDC MB8866 senza ROM driver (codice nella IPL). Supporto D88.
QuickDisk (con ROM)	`MZ-1E14`	0xF4–0xF7	Controller QD con BIOS ROM per MZ-700/MZ-800.
QuickDisk (senza ROM)	`MZ-1E19`	0xF4–0xF7	Controller QD per MZ-800/MZ-2000/MZ-2200/MZ-2500.
32KB Battery RAM	`MZ-1R12`	0xF8–0xFA	SRAM CMOS con batteria, salvata su SD card. Fino a 2 istanze.
64KB RAM Board	`MZ-1R18`	0xEA–0xEB	Espansione RAM utilizzata come disco RAMFILE.
Kanji ROM	`MZ-1R23`	0xB8–0xB9	ROM Kanji da 128KB (16x16 JIS) + ROM Dizionario opzionale da 256KB.
640KB EMM	`MZ-1R37`	0xAC–0xAD	Expanded Memory Manager con spazio indirizzi a 20 bit.
320KB EMM	`PIO-3034`	configurabile	EMM IO DATA con porta dati auto-incrementante.
Celestite LAN	`Celestite`	0x60–0x6F	Ethernet W5100, controller interrupt, UFM, MZ-1R12/MZ-1R37 integrati. IP server configurabile tramite parametro JSON `ip`.
SASI Hard Disk	`MZ-1E30`	0xA4–0xA5, 0xA8–0xA9	Controller hard disk SASI MZ-1E30 (MZ-2500/MZ-80B). Fino a 4 dischi (~21.4 MB ciascuno). IPL ROM da 32KB. Immagini disco su SD card.
Seriale RS-232C (BI)	`MZ-8BIO3`	0xB0–0xB3 (configurabile)	Scheda RS-232C a doppio canale (Z80 SIO emulato). I canali A/B si collegano alle porte seriali USB CDC 2 e 3. Cablaggio connettore “BI”.
Seriale RS-232C (ST)	`MZ-1E24`	0xB0–0xB3 (configurabile)	Come MZ-8BIO3 ma con cablaggio connettore Sharp “ST”.

TZFS e CP/M (personalita' MZ-700)

TZFS e' un monitor a basso livello e file system offerto come interfaccia selezionabile sulla personalita' MZ-700 (in pratica usato al posto di RFS — abilitare l'uno o l'altro). Oltre al monitor, effettua il boot ed esegue CP/M. TZFS viene fornito nella configurazione MZ-700 ma e' disattivato per impostazione predefinita: abilitarlo impostando "enable": 1 sul blocco interfaccia TZFS nel config.json, oppure attivandolo dalla pagina Configurazione della GUI web. La sua ROM (roms/tzfs.bin) deve essere presente sulla SD card.

Le immagini disco CP/M sono configurate per unita' tramite l'array param dell'interfaccia — ogni voce param[].file fornisce il percorso di un file immagine intero sulla SD card per quel drive. Quando un drive non ha una voce file esplicita, viene usato il template di percorso di fallback CPM/SDC16M/RAW/CPMDSK<nn>.RAW. picoZ80 non ha accesso diretto alla SD, quindi questi settori vengono letti e scritti attraverso l'ESP32.

Compatibilita' Personalita'-Interfaccia

Non tutti i driver di interfaccia sono disponibili per ogni personalita'. La tabella seguente mostra quali interfacce possono essere utilizzate con ciascuna personalita' macchina tramite l'array "if".

Interfaccia	MZ-700	MZ-1500	MZ-80K	MZ-800	MZ-80A	MZ-2000	MZ-2200	MZ-80B	MZ-2500
RFS	Si’	Si’	Si’	Si’	Si’	Si’	—	—	—
TZFS	Si’	—	—	—	—	—	—	—	—
MZ-1E05	Si’	Si’	—	Si’	—	—	—	—	—
MZ80FIO	—	—	Si’	Si’	—	—	—	—	—
MZ80AFI	—	—	Si’	Si’	Si’	—	—	—	—
MZ-8BFI / E0054PA	—	—	—	Si’	—	Si’	Si’	Si’	Si’
MZ-1E14	Si’	Si’	Si’	Si’	—	—	—	Si’	Si’
MZ-1E19	Si’	Si’	Si’	Si’	—	Si’	Si’	Si’	Si’
MZ-1R12	Si’	Si’	Si’	Si’	Si’	Si’	Si’	Si’	Si’
MZ-1R18	Si’	Si’	Si’	Si’	Si’	Si’	Si’	Si’	Si’
MZ-1R23	—	Si’	—	Si’	—	—	—	Si’	Si’
MZ-1R37	—	Si’	Si’	Si’	—	—	—	Si’	Si’
PIO-3034	—	Si’	Si’	Si’	—	—	—	Si’	Si’
Celestite	—	Si’	—	Si’	—	—	—	Si’	Si’
MZ-1E30	—	—	—	—	—	—	—	Si’	Si’
MZ-8BIO3	Si’	Si’	—	Si’	—	—	—	Si’	—
MZ-1E24	Si’	Si’	—	Si’	—	—	—	Si’	—

Esempio di Configurazione JSON

L'esempio seguente mostra come configurare una personalita' MZ-700 con RFS, un controller floppy e un'unita' QuickDisk. Questo va posizionato nell'array "drivers" all'interno del blocco z80 della partizione nel config.json:

"drivers": [
  {
    "name": "MZ700",
    "enable": 1,
    "type": "VIRTUAL",
    "if": [
      {
        "name": "RFS",
        "type": "VIRTUAL",
        "enable": 1,
        "rom": [
          {
            "file": "roms/MROM_PICOZ80_256.bin",
            "enable": 1,
            "loadaddr": [
              { "enable": 1, "position": "0x0", "addr": "0x0",
                "bank": 32, "size": "0x80000", "tcycwait": 0, "tcycsync": 0 }
            ]
          },
          {
            "file": "roms/USER_ROM_PICOZ80_256.bin",
            "enable": 1,
            "loadaddr": [
              { "enable": 1, "position": "0x0", "addr": "0x0",
                "bank": 40, "size": "0x80000", "tcycwait": 0, "tcycsync": 0 }
            ]
          }
        ]
      },
      {
        "name": "MZ-1E05",
        "type": "VIRTUAL",
        "enable": 1,
        "param": [
          { "file": "dsk/MZ-2Z009-RFS.dsk", "enable": 1 }
        ]
      },
      {
        "name": "MZ-1E19",
        "type": "VIRTUAL",
        "enable": 1,
        "param": [
          { "file": "qd/BASIC_5Z008A_RFS.qd", "enable": 1 },
          { "file": "qd/BASIC_5Z008B.qd", "enable": 1 }
        ]
      },
      {
        "name": "Celestite",
        "type": "VIRTUAL",
        "enable": 1,
        "param": [
          { "file": "ram/celestite_r12.ram", "enable": 1 },
          { "file": "ram/celestite_r37.ram", "enable": 1 },
          { "ip": "192.168.1.210:6800", "enable": 1 }
        ]
      }
    ]
  }
]

Configurazione dell'indirizzo del file server: Aggiungere una voce ip all'array param dell'interfaccia Celestite nel config.json, specificando l'indirizzo IP del PC e la porta di netfs.py:

{ "ip": "192.168.1.210:6800", "enable": 1 }

Configurazione hard disk SASI MZ-1E30: Aggiungere un'interfaccia MZ-1E30 all'array "if" della personalita'. La voce rom fornisce la IPL ROM da 32KB e le voci param specificano le immagini hard disk (fino a 4):

{
  "name": "MZ-1E30",
  "type": "VIRTUAL",
  "enable": 1,
  "rom": [{ "file": "roms/MZ-1E30.ROM", "enable": 1 }],
  "param": [
    { "file": "hdd/boot.hdd", "enable": 1 },
    { "file": "hdd/data.hdd", "enable": 1 }
  ]
}

Campi JSON principali:

name — nome della personalita' o dell'interfaccia (deve corrispondere a un driver compilato).

enable — impostare a 1 per attivare, 0 per saltare.

type — "VIRTUAL" (emulato in PSRAM) o "PHYSICAL" (pass-through verso hardware reale).

rom — array di immagini ROM da caricare. Ogni voce ha un percorso file (relativo alla root della SD card) e un array loadaddr che specifica dove posizionare i dati (indirizzo Z80, banco PSRAM, dimensione).

param — array di file immagine disco/RAM. param[0].file e' il primo disco, param[1].file il secondo, ecc.

addrmap — rimappatura indirizzi opzionale (sorgente -> destinazione).

iomap — rimappatura porte I/O opzionale.

Tutti i percorsi file sono relativi alla directory root della SD card (ad es. "roms/MROM_PICOZ80_256.bin").

Serie Amstrad PCW

Il picoZ80 supporta l'Amstrad PCW-9512 e il Tatung Einstein TC-01 oltre alla serie Sharp MZ.

Driver di Personalita' Macchina

Ogni driver di personalita' Amstrad emula una macchina Amstrad completa. La personalita' viene selezionata tramite la pagina web Selezione Personalita' o modificando il campo "name" nell'array "drivers" del config.json.

Personalita’	Driver	Descrizione
PCW-9512	`PCW9512`	Amstrad PCW-9512. Z80A @ 4MHz, 512KB RAM con page switching a 4 banchi da 16KB (porte F0-F3), gate array (ASIC) per video/clock di sistema/routing FDC/controllo motore, NEC uPD765 FDC con supporto formato CPC DSK, controller stampante a margherita 8041. Modalita’ virtuale e fisica supportate.
Einstein TC-01	`EinsteinTC01`	Tatung Einstein TC-01. Z80A @ 4MHz, 64KB RAM + 8KB ROM commutabile, WD1770 FDC, TMS9129 VDP, AY-3-8910 PSG, Z80 CTC, Z80 PIO. Modalita’ virtuale e fisica supportate.

La personalita' PCW-9512 include un'emulazione completa della sequenza di bootstrap: il flusso di byte del gate array carica il BIOS, che poi carica CP/M dal disco. I comandi del gate array includono fine bootstrap, riavvio, routing interrupt FDC (NMI/INT/ignora), terminal count e motore on/off.

Imaging disco: Il picoZ80 puo' creare immagini di floppy disk fisici quando e' in esecuzione nella personalita' PCW-9512. Il comando ICE dskimage inietta codice Z80 che legge tutte le tracce tramite il FDC dell'host e salva il risultato come file CPC DSK sulla SD card. Vedere il Riferimento Comandi ICE per i dettagli di utilizzo.

Serie Tatung Einstein

Il picoZ80 supporta il Tatung Einstein TC-01 — un home computer basato su Z80A con unita' floppy disk integrata.

Driver di Personalita' Macchina

Ogni driver di personalita' Tatung emula una macchina Tatung completa. La personalita' viene selezionata tramite la pagina web Selezione Personalita' o modificando il campo "name" nell'array "drivers" del config.json.

Personalita’	Driver	Descrizione
Einstein TC-01	`EinsteinTC01`	Tatung Einstein TC-01. Z80A @ 4MHz, 64KB RAM + 8KB ROM commutabile (X-TAL MOS), toggle ROM/RAM tramite porta 0x24 (qualsiasi accesso commuta; le scritture vanno sempre alla RAM), WD1770 FDC con supporto disco virtuale (40 tracce, 1 testina, 10 settori, 512 byte — dischi da 200KB), TMS9129 VDP (video display processor) con temporizzazione inter-accesso (~2us di intervallo), AY-3-8910 PSG (suono a 3 canali) alle porte 0x02-0x03, Z80 CTC (4 canali) alle porte 0x28-0x2B, Z80 PIO alle porte 0x30-0x33, interfaccia tastiera alla porta 0x20. Imaging disco fisico: lettura floppy fisico su DSK, scrittura DSK su floppy fisico. Modalita’ virtuale e fisica supportate.

Imaging disco: La personalita' Einstein TC-01 supporta l'imaging di dischi fisici tramite il comando ICE dskimage con i sottocomandi read e write. dskimage read crea un'immagine di un floppy fisico in un file DSK sulla SD card, mentre dskimage write scrive un file DSK dalla SD card su un floppy fisico.

Altre Macchine

Il supporto per ulteriori macchine basate su Z80 e' pianificato. Ogni nuova macchina seguira' la stessa architettura a driver di personalita' — un driver di personalita' dedicato che implementa la mappa di memoria della macchina, l'I/O e le periferiche, con driver di interfaccia per l'hardware di espansione. Consultare il repository del progetto per l'elenco aggiornato delle macchine supportate.

OpenZ80 — per la propria scheda o una macchina non supportata. Se si sta costruendo la propria scheda Z80, o si dispone di un computer Z80 che non ha ancora una personalita' picoZ80 dedicata, utilizzare la build firmware OpenZ80. La sua attrattiva principale e' che consente di aggiungere schede interfaccia virtuali prese in prestito da altre macchine Sharp, Amstrad e Tatung sul proprio computer Z80 su misura o sconosciuto, cosi' da poter scrivere nuovo software per quelle schede — o adattare software esistente per funzionare sulla propria macchina. OpenZ80 si comporta come un semplice Z80: in modalita' fisica passa l'intero spazio di memoria e I/O da 64K alla propria scheda, e in modalita' virtuale presenta una RAM piatta da 64K in cui caricare le proprie immagini ROM. Espone solo le schede di interfaccia indipendenti dalla macchina (le schede di memoria MZ-1R12/1R18/1R23/1R37, la scheda parallela PIO-3034, le schede seriali RS-232C MZ-8BIO3 / MZ-1E24, l'interfaccia floppy MZ-1E05 e la scheda LAN Celestite), e ognuna di queste puo' avere la propria Base I/O Port rilocata per corrispondere alla propria scheda nella pagina Configurazione GUI. Per adattare una delle macchine esistenti, gli sviluppatori possono prendere come punto di partenza uno qualsiasi dei driver forniti e il sorgente della sua ROM monitor / IPL / BIOS (fornito come assembler Z80 nelle directory asm/ dei progetti RFS e TZFS) — vedere la Developer's Guide.

ICE (Shell di Debug)

Il picoZ80 include una shell di debug interattiva integrata (ICE — In-Circuit Emulator) per l'ispezione e il controllo in tempo reale dell'emulazione della CPU Z80.

La shell di debug ICE e' inclusa nella variante firmware DBGSH. Se si utilizza il firmware standard, la shell di debug non e' disponibile. Programmare la variante DBGSH per abilitare la funzionalita' ICE.

Connessione: La shell di debug e' disponibile sulla seconda porta seriale USB. Quando il picoZ80 e' collegato tramite USB, appaiono due porte seriali sul computer host — la prima e' l'output del log di debug standard, la seconda e' la shell di debug. Aprirla con qualsiasi emulatore di terminale a 115200 baud, 8N1. Il prompt dbg> appare una volta connessi.

Capacita' principali:

Ispezione registri — regs visualizza tutti i registri Z80, i flag e il conteggio dei cicli.

Dump memoria — dm p 0000 100 esegue il dump di 256 byte dall'indirizzo 0x0000 tramite il bus fisico; dm v 0000 100 legge direttamente dalla PSRAM virtuale.

Breakpoint — bp E800 imposta un breakpoint a 0xE800. Fino a 8 breakpoint. bl li elenca, bc * li cancella tutti.

Single-step — hold mette in pausa la CPU, poi step esegue un'istruzione mostrando lo stato dei registri prima/dopo.

Traccia di esecuzione — trace on registra ogni istruzione eseguita. trace dump 20 mostra le ultime 20 con disassemblaggio.

Disassemblaggio — dis v E800 20 disassembla 32 istruzioni da 0xE800.

Accesso I/O — in D8 legge la porta 0xD8; out D8 03 scrive 0x03 sulla porta 0xD8.

Informazioni di sistema — status mostra frequenza CPU, clock PSRAM, velocita' di emulazione e uptime. drivers elenca i driver attivi.

Digitare help al prompt per un riepilogo rapido.

Riferimento Comandi

L'insieme completo dei comandi ICE e' elencato di seguito. Tutti i valori di indirizzo e dati vengono inseriti in esadecimale senza prefisso 0x.

Comando	Parametri	Descrizione
help	—	Visualizzare un riepilogo di tutti i comandi disponibili.
regs	—	Dump del set completo di registri Z80: registri principali (AF, BC, DE, HL), registri alternativi (AF’, BC’, DE’, HL’), registri indice (IX, IY), stack e program counter (SP, PC), stato interrupt (I, R, IM, IFF1, IFF2), flag decodificati (S, Z, H, P/V, N, C), stato linea HALT, MEMPTR e conteggio cumulativo dei T-cycle.
dm	`<p\|f\|v\|r> <addr> [len]`	Dump memoria in esadecimale e ASCII. Quattro modalita’: p (physical) legge tramite il bus Z80 attivando l’hardware reale; f (fetch) legge utilizzando cicli di fetch M1; v (virtual) legge direttamente dalla PSRAM senza attivita’ sul bus; r (RP2350) legge lo spazio indirizzi del microcontrollore stesso (Flash, SRAM, periferiche). `addr` e’ l’indirizzo iniziale, `len` e’ il numero di byte (predefinito 256).
search	`[p\|v] <start> <end> <hex..>\|"text"`	Cercare in memoria un pattern di byte o una stringa di testo ASCII. `p` = bus fisico, `v` = PSRAM virtuale, omettere per mappato (segue la mappa di memoria). Specificare il pattern come byte esadecimali (ad es. `ED 4D 00`) o una stringa ASCII tra virgolette (ad es. `"HELLO"`). Le corrispondenze vengono visualizzate con 8 byte di contesto prima e dopo. Mette automaticamente in hold la CPU per l’accesso fisico/mappato. Lunghezza pattern fino a 32 byte.
cmp	`[f] <phys> <virt> <len>`	Confrontare la memoria del bus fisico con la PSRAM virtuale. L’opzione `f` utilizza cicli di fetch (M1) anziche’ cicli di lettura. Riporta le differenze con indirizzi e valori.
dis	`[p\|v] [addr] [count]`	Disassemblare codice macchina Z80. `p` legge gli opcode dal bus fisico, `v` dalla PSRAM virtuale (predefinito). `addr` e’ predefinito al PC corrente. `count` e’ il numero di istruzioni (predefinito 16). Il PC corrente e’ marcato con `>`.
asm	`[addr]`	Entrare nell’assemblatore Z80 interattivo all’indirizzo `addr` (predefinito: PC corrente). Digitare i mnemonici Z80 uno per riga; i byte assemblati vengono scritti nella PSRAM virtuale e l’indirizzo avanza. Supporta le direttive `db` e `dw`/`defw`. Inserire una riga vuota o `.` per uscire.
memmap	`[block]`	Visualizzare la tabella dei puntatori ai blocchi di memoria SRAM. Ogni voce mostra il numero del blocco, l’intervallo di indirizzi Z80, il tipo di memoria (PHYSICAL, RAM, ROM, FUNC), il numero del banco e l’offset PSRAM. Se `block` e’ specificato, mostrare solo quel blocco da 512 byte.
memptr	`[addr]`	Visualizzare le tabelle PSRAM memPtr/memioPtr per l’indirizzo dato, mostrando il puntatore alla funzione handler e gli attributi.
iomap	`[port]`	Visualizzare la tabella degli handler delle porte I/O. Ogni voce mostra l’indirizzo della porta, la funzione handler e la direzione (lettura/scrittura/entrambi). Se `port` e’ specificato, mostrare solo quella porta.
status	—	Panoramica dello stato del sistema: frequenza CPU RP2350, clock SPI PSRAM, clock Z80 host, rapporto di velocita’ dell’emulazione, SRAM libera e uptime.
ver	—	Visualizzare versione firmware, data di compilazione, layout partizioni flash (indirizzo, dimensione, checksum, flag attivo), autore e licenza.
drivers	—	Elencare tutti i driver di personalita’ macchina attivi e le relative sotto-interfacce, mostrando lo stato di inizializzazione.
hold	—	Mettere in pausa l’emulazione della CPU Z80. Il core 1 termina l’istruzione corrente e smette di eseguire il fetch. La shell attende che l’hold venga confermato prima di tornare. Necessario prima di utilizzare `out` o altri comandi che modificano lo stato in esecuzione.
release	—	Riprendere l’emulazione della CPU Z80 dal punto in cui e’ stata messa in pausa. I breakpoint rimangono attivi.
go	—	Continuare l’esecuzione (uguale a `release`). Se un breakpoint viene successivamente raggiunto, la CPU si fermera’ automaticamente.
cont	—	Alias per `go`. Continuare l’esecuzione dal punto di pausa corrente. I breakpoint rimangono attivi.
step	`[n]`	Single-step di un’istruzione (o `n` istruzioni). Per ogni step la shell visualizza lo stato dei registri prima dell’esecuzione, l’istruzione disassemblata con byte esadecimali e lo stato dei registri dopo l’esecuzione. La CPU deve essere prima in hold. Se un breakpoint viene raggiunto durante il multi-step, l’esecuzione si interrompe anticipatamente.
bp	`<addr>`	Impostare un breakpoint all’indirizzo Z80 dato. Fino a 8 breakpoint possono essere attivi contemporaneamente. Quando il PC corrisponde a un indirizzo di breakpoint durante il fetch dell’opcode, la CPU viene automaticamente messa in hold e il raggiungimento viene segnalato. Gli indirizzi duplicati vengono rifiutati.
bc	`<n\|*>`	Cancellare lo slot breakpoint `n` (0-7) o tutti i breakpoint (`*`).
bl	—	Elencare tutti i breakpoint attivi mostrando numero dello slot e indirizzo.
wm	`[p\|v] <addr> <byte> [byte]...`	Scrivere uno o piu’ byte in memoria. `p` = bus Z80 fisico, `v` = PSRAM virtuale, omettere per auto (segue la mappa di memoria). Piu’ byte possono essere specificati separati da spazi. Mette automaticamente in hold la CPU per scritture fisiche/mappate.
fill	`[p\|v] <addr> <len> [w\|d] <val>`	Riempire una regione di memoria con un valore costante. `p` = fisico, `v` = virtuale, omettere per auto. Predefinito 8 bit; `w` = 16 bit, `d` = 32 bit (little-endian). Mette automaticamente in hold la CPU quando necessario.
copy	`<pv\|fp\|vp> <src> <len> <dst>`	Copiare memoria tra fisico e virtuale. `pv` = lettura fisica a virtuale, `fp` = fetch fisico a virtuale, `vp` = virtuale a scrittura fisica. Mette automaticamente in hold la CPU.
memtest	`<addr> <len> [pattern]`	Testare la memoria fisica con tre passaggi: scrittura+lettura, scrittura+fetch, interlacciato. Pattern predefinito: byte crescenti. Riporta gli errori per passaggio.
in	`<port>`	Leggere una porta I/O Z80. Esegue un ciclo bus IORQ+RD reale e visualizza il byte letto.
out	`<port> <byte>`	Scrivere un byte su una porta I/O Z80. La CPU deve essere prima in hold. Esegue un ciclo bus IORQ+WR reale.
trace	`<on\|off\|dump [n]\|clear\|rt\|byte ...>`	Controllare la traccia di esecuzione. on abilita la registrazione di ogni istruzione eseguita in un buffer circolare da 512 voci (PC, opcode, flag). off disabilita la registrazione. dump visualizza le ultime `n` voci (predefinito: tutte) con disassemblaggio e flag decodificati. clear resetta il buffer. rt abilita l’output della traccia in tempo reale sulla console di debug mentre le istruzioni vengono eseguite. byte abilita il tracing a livello di byte delle transazioni memoria/IO.
verify	`<on\|off>`	Attivare/disattivare la verifica completa del fetch degli opcode. Quando attivo, ogni fetch viene verificato rispetto a readPhysicalMem (riduzione velocita’ del 50%). Quando disattivo (predefinito), controlla solo gli opcode 0x00/0xFF.
fwait	`<0-4>`	Forzare stati di attesa aggiuntivi sui cicli M1 (fetch opcode). `<n>` e’ 0-4 T-state aggiuntivi (0 = disattivo, predefinito). Utile per il debug di codice che si comporta diversamente con gli stati di attesa — alcune periferiche o dispositivi di memoria richiedono margini di temporizzazione specifici. Senza parametro, visualizza l’impostazione corrente.
iowait	`<0-8>`	Forzare stati di attesa aggiuntivi sui cicli di lettura e scrittura I/O. `<n>` e’ 0-8 T-state aggiuntivi (0 = disattivo, predefinito). Allunga i cicli I/O per diagnosticare periferiche con tempi di risposta lenti. Senza parametro, visualizza l’impostazione corrente.
corrupt	`[clear]`	Visualizzare le corruzioni di fetch rilevate (PC, opcode prelevato, opcode verificato). `clear` resetta il log.
fdctrace	`<on\|off\|dump>`	Abilitare, disabilitare o eseguire il dump della traccia I/O del FDC. on/off controlla la registrazione degli accessi ai registri del WD1773 FDC in un buffer circolare da 64 voci. dump visualizza le ultime 64 operazioni, mostrando il nome del registro (Status/Command, Track, Sector, Data, DriveSel, SideSel, DDEN), direzione lettura o scrittura, valore byte e stato FDC.
qdtrace	`<on\|off\|dump>`	Abilitare, disabilitare o eseguire il dump della traccia I/O del Quick Disk. on/off controlla la registrazione degli accessi ai registri SIO del QD in un buffer circolare da 64 voci. dump visualizza le ultime 64 operazioni, mostrando porta, direzione, valore byte e posizione sul nastro (offset in byte).
piodbg	`[clear]`	Visualizzare la diagnostica hardware PIO dell’RP2350 per tutti e tre i blocchi PIO (PIO 0, PIO 1, PIO 2). Mostra i flag di errore sticky FDEBUG (stallo, RX underflow, TX overflow), stato FSTAT, livelli di riempimento FIFO, program counter per state machine, maschera output-enable GPIO e livelli dei pin GPIO. `clear` resetta i flag sticky FDEBUG. Utile per diagnosticare blocchi delle state machine PIO o contesa del bus.
load	`<p\|v> <file> <addr> [len] [ofs]`	Caricare un file dalla SD card dell’ESP32 nella memoria Z80. `p` = scrivere sul bus fisico, `v` = scrivere nella PSRAM virtuale banco 0. `file` e’ relativo a `/sdcard/` sull’ESP32. `addr` e’ l’indirizzo Z80 iniziale. Se `len` e’ omesso viene caricato l’intero file (fino a 64KB); se specificato, carica quel numero di byte (max 1MB). L’opzione `ofs` e’ l’offset nel file da cui iniziare la lettura. Mette automaticamente in hold la CPU per le scritture fisiche. Utilizza il banco PSRAM 63 come buffer temporaneo.
save	`<p\|pf\|v> <file> <addr> <len>`	Salvare la memoria Z80 in un file sulla SD card dell’ESP32. `p` = leggere tramite bus fisico, `pf` = leggere tramite fetch fisico (cicli M1), `v` = leggere dalla PSRAM virtuale banco 0. `file` e’ relativo a `/sdcard/`. `addr` e’ l’indirizzo Z80 iniziale, `len` e’ il numero di byte da salvare (max 64KB). Mette automaticamente in hold la CPU per le letture fisiche. Esegue refresh DRAM periodico durante le letture fisiche.
dir	`[path]`	Elencare i file sulla SD card dell’ESP32. Il percorso opzionale e’ relativo a `/sdcard/`. Mostra nomi e dimensioni dei file.
echo	`[on\|off]`	Attivare/disattivare o impostare l’echo dei caratteri. Quando attivo (predefinito), i caratteri digitati vengono ripetuti al terminale.
reset	—	Forzare un reset immediato della CPU Z80. L’emulazione riparte dal vettore di reset (tipicamente 0x0000).
set	`<reg\|flags\|memmap\|memptr\|iomap> <idx> <val>`	Modificare un registro Z80, i flag, la mappa di memoria, il memPtr PSRAM o una voce della mappa porte I/O in tempo reale. `reg` imposta un registro Z80, `flags` imposta il registro flag, `memmap`/`memptr`/`iomap` modificano la configurazione memoria o I/O. `idx` e’ il nome del registro o l’indice nella tabella (decimale o esadecimale), `val` e’ il nuovo valore. Questo consente di modificare al volo registri e configurazione memoria/IO senza ricaricare il `config.json`.
hist	`[n]`	Visualizzare il buffer della cronologia comandi. Mostra gli ultimi `n` comandi (predefinito: tutte le voci, fino a 16). La cronologia e’ preservata tra i cicli di accensione tramite lo storage NVS dell’ESP32.
savehst	—	Forzare il salvataggio immediato della cronologia comandi corrente nello storage NVS dell’ESP32. La cronologia viene normalmente salvata automaticamente allo spegnimento regolare; questo comando forza un salvataggio immediato.
ipl	—	Eseguire un reset IPL (modalita’ BST) commutando il bit 3 della Porta C del PPI 8255. Resetta la macchina in modalita’ di avvio senza un reset completo dello Z80. Utile per le macchine MZ-80B, MZ-2000 e MZ-2500 che distinguono tra modalita’ BST (avvio) e NST (normale).
mmutrace	—	Eseguire il dump delle informazioni di traccia specifiche della macchina come lo stato della MMU e gli snapshot dei registri I/O. L’output varia a seconda della personalita’ — ogni driver registra il proprio handler di traccia, quindi le informazioni mostrate dipendono dalla personalita’ macchina attiva.
intcount	—	Mostrare il conteggio degli acknowledge interrupt e lo stato corrente degli interrupt. Utile per il debug di software guidato da interrupt — visualizza quanti cicli di acknowledge interrupt si sono verificati e se gli interrupt sono attualmente pendenti o abilitati.
psync	`[start end]`	Sincronizzare la memoria fisica con la PSRAM leggendo il bus fisico e scrivendo nella memoria virtuale. I parametri opzionali `start` e `end` specificano un intervallo di indirizzi; se omessi, viene sincronizzato l’intero spazio indirizzi. Utile per la diagnostica dopo operazioni DMA o quando la memoria fisica e virtuale potrebbero essere divergenti.
dskimage	`read <filename> [cylinders] [heads]` / `write <filename>`	Creare un’immagine di un floppy disk fisico in un file DSK sulla SD card (`read`), o scrivere un file DSK dalla SD card su un floppy fisico (`write`). `dskimage <filename>` esegue la lettura per impostazione predefinita (retrocompatibile). `filename` e’ il percorso del file DSK relativo a `/sdcard/`. Se `cylinders` e `heads` sono omessi per la lettura, la geometria viene auto-rilevata. La CPU deve essere prima in hold. L’avanzamento viene riportato durante l’imaging.
busdiag	—	Visualizzare la diagnostica del bus inclusi stato PIO, livelli dei segnali e stato di contesa del bus. Utile per diagnosticare problemi elettrici con la connessione al bus dell’host.
fdcimage	—	Visualizzare lo stato e l’avanzamento dell’imaging FDC.
fdcdiag	—	Visualizzare le informazioni diagnostiche del FDC (stato del controller, dump dei registri).
gadiag	—	Visualizzare le informazioni diagnostiche del gate array (stato dei comandi, routing interrupt).

Flusso di lavoro tipico per il debug:

Collegare un terminale alla seconda porta seriale USB (115200, 8N1).

hold — mettere in pausa la CPU.

regs — ispezionare lo stato corrente dei registri.

dis v — disassemblare il codice al PC corrente.

bp E800 — impostare un breakpoint.

go — riprendere. La CPU si fermera' quando raggiungera' 0xE800.

step 5 — single-step di 5 istruzioni dal breakpoint.

dm v D000 80 — ispezionare il contenuto della VRAM.

trace on / go / trace dump 50 — tracciare e rivedere la cronologia di esecuzione.

Risoluzione Problemi

Il computer host non si avvia

Controllare l'orientamento — assicurarsi che il Pin 1 del picoZ80 sia allineato con il Pin 1 del socket. Inserire la scheda al contrario danneggera' sia il picoZ80 che il computer host.

Controllare l'inserimento — rimuovere il picoZ80 e reinserirlo, assicurandosi che tutti i 40 pin siano completamente inseriti e che nessuno sia piegato sotto la scheda.

Controllare la SD card — se il config.json e' mancante o malformato, il firmware tentera' di utilizzare la configurazione Flash precedentemente salvata nella cache. Se non esiste una configurazione valida, l'RP2350 non inizializzera' la mappa di memoria e l'host vedra' un bus aperto.

Confermare che il firmware e' stato programmato — provare a collegare il picoZ80 tramite USB (senza inserirlo nell'host) e verificare che la scheda venga enumerata sul PC.

Controllare l'alimentatore dell'host — il picoZ80 puo' assorbire fino a 400mA dalla linea 5V. Alcuni computer vintage hanno alimentatori marginali; controllare la tensione della linea 5V sotto carico con un multimetro.

Impossibile connettersi all'interfaccia web

Controllare la modalita' WiFi — al primo avvio o dopo un ripristino ai valori di fabbrica l'ESP32 si avvia in modalita' AP. Connettersi prima alla rete WiFi picoZ80, quindi navigare a http://192.168.4.1.

Controllare l'indirizzo IP configurato — se la modalita' client e' configurata con un IP fisso, verificare che l'IP corrisponda alla sottorete della propria rete.

Controllare che la SD card sia presente — le risorse web nella directory webfs/ sulla SD card sono necessarie. Senza la SD card il web server non puo' servire alcuna pagina.

Controllare la directory webfs — confermare che la directory webfs/ esista sulla SD card e contenga i file HTML/CSS/JS dal repository del progetto.

Ripristino di fabbrica WiFi — se le credenziali sono state perse, riprogrammare il firmware ESP32 per cancellare le impostazioni NVS e ricominciare da zero.

SD card non riconosciuta

Assicurarsi che la SD card sia formattata come FAT32. NTFS, exFAT e FAT16 non sono supportati.

Provare una SD card diversa — alcune schede ad alta capacita' o alta velocita' possono avere problemi di compatibilita' con l'interfaccia SPI SD dell'ESP32.

Le schede fino a 32GB sono ben supportate. Le schede molto grandi (>32GB) potrebbero richiedere una formattazione speciale.

Reinserire la SD card — rimuovere e reinserire per assicurare un buon contatto.

Immagini ROM non caricate

Verificare che il percorso del file nel config.json corrisponda esattamente alla posizione del file sulla SD card (i percorsi sono case-sensitive).

Confermare che il file immagine ROM sia presente sulla SD card — utilizzare il Gestore File per navigare alla posizione prevista.

Controllare il valore fileofs — un offset errato carichera' dati spazzatura nel banco ROM.

Verificare che il campo size nella voce della mappa di memoria non sia piu' grande del file immagine ROM. Le mappature sovradimensionate saranno riempite con dati non definiti.

La scheda si resetta o si riavvia inaspettatamente

Il picoZ80 ha un timer watchdog hardware che resetta automaticamente l'RP2350 se il firmware si blocca durante l'avvio o il funzionamento normale. Se la scheda si riavvia ripetutamente, il watchdog si sta attivando perche' una fase di avvio non si sta completando in tempo.

Controllare la SD card — un config.json mancante o corrotto puo' causare lo stallo della sequenza di avvio durante il parsing della configurazione.

Controllare le impostazioni WiFi — se l'ESP32 non riesce a stabilire una connessione, l'handshake SPI tra RP2350 ed ESP32 potrebbe andare in timeout, attivando il watchdog.

Utilizzare il debug SWD — collegare una sonda di debug e ispezionare i registri scratch del watchdog (watchdog_hw->scratch[5] fino a scratch[7]). Il codice di avanzamento dell'avvio in scratch[6] indica quale fase il firmware ha raggiunto prima che il watchdog si sia attivato, e scratch[0-3] contengono una cronologia degli ultimi quattro tentativi di reset.

Controllare il log persistente — il firmware scrive messaggi critici per l'avvio negli ultimi 4KB della PSRAM utilizzando plogf(). Questi messaggi sopravvivono al reset del watchdog e vengono scaricati sulla console di debug al successivo avvio riuscito, rivelando cosa e' successo prima del reset.

Aggiornamento OTA fallito

Assicurarsi di caricare un file .bin (non un .uf2) per gli aggiornamenti OTA dell'RP2350.

Assicurarsi di caricare nello slot inattivo per preservare il firmware funzionante.

Se l'aggiornamento OTA fallisce o risulta in una partizione non avviabile, il bootloader manterra' in esecuzione lo slot attivo precedente — ripetere il processo di caricamento.

Per i fallimenti OTA dell'ESP32, riprogrammare tramite esptool utilizzando la connessione USB dell'header di debug.

Siti di Riferimento

Risorsa	Link
Pagina del progetto picoZ80	/it/picoz80/
picoZ80 Technical Guide	/it/picoz80-technicalguide/
Pagina del progetto pico6502	/it/pico6502/
RP2350 Datasheet	datasheets.raspberrypi.com
Documentazione Pico SDK	raspberrypi.github.io/pico-sdk-doxygen
ESP32-S3 Technical Reference	docs.espressif.com
Anteprima del progetto su X (Twitter)	engineerswork1

Avviso Normativo FCC / RED

La scheda picoZ80 non e' stata sottoposta alla certificazione FCC (USA) o RED (UE) come radiatore intenzionale. Come fornita, la scheda deve avere i componenti di adattamento dell'antenna WiFi non montati e il firmware ESP32 compilato con la configurazione NCM Only. In questo stato non viene emessa alcuna energia a radiofrequenza e la scheda non rientra nelle normative sui radiatori intenzionali.

Gli utenti finali che desiderano utilizzare il WiFi possono montare la rete di adattamento dell'antenna, compilare la variante firmware WiFi e operare sotto l'esenzione hobbistica/sperimentale applicabile nella propria giurisdizione. Qualsiasi soggetto che desideri vendere la scheda commercialmente con il WiFi abilitato deve prima ottenere la certificazione FCC e/o RED per l'assemblaggio completo.