Added README

2026-03-29 23:59:43 +01:00
parent d4176afb30
commit e19a22fce6
2 changed files with 638 additions and 0 deletions
--- a/README.ja.md
+++ b/README.ja.md
@@ -0,0 +1,319 @@
+# picoZ80 / pico6502
+
+**RP2350 ベースのドロップイン CPU 交換ボード — サイクル精度 PIO バスインターフェース、WiFi 管理、仮想デバイスフレームワーク搭載**
+
+Copyright (c) 2019-2026 Philip Smart — [eaw.app](https://eaw.app)
+
+---
+
+## 概要
+
+**picoZ80** は、レガシー Z80 ベースコンピュータの Z80 DIP-40 CPU ソケットに直接装着できるカスタム PCB です。個別の Z80 プロセッサの代わりに、**RP2350B** マイクロコントローラ（デュアルコア 150 MHz Cortex-M33、最大 300 MHz）を搭載し、プログラマブル I/O（PIO）ステートマシンが Z80 のアドレス、データ、制御バスをサイクル精度で完全に制御します。
+
+**pico6502** は同じアーキテクチャを MOS 6502 に適用し、互換ホストの 6502 DIP-40 CPU を置換します。
+
+すべてのバストランザクションは RP2350 の PIO エンジンによりリアルタイムで処理され、ホストシステムは実際の CPU と同じバスタイミングを認識します。RP2350 の第 2 コア、512 KB オンチップ SRAM、8 MB 外部 PSRAM、16 MB Flash により、高速実行、仮想化メモリ、ROM バンキング、仮想ディスクドライブ、マシンペルソナエミュレーションなど、ほぼ無制限の機能が実現されます。
+
+**ESP32** コプロセッサが WiFi、Bluetooth、SD カードマスストレージ、ブラウザベースの管理インターフェースを提供します。すべての設定は SD カード上の `config.json` ファイルで駆動され、メモリマップ、ROM イメージ、ドライバ選択の再設定にリコンパイルは不要です。
+
+### 主な機能
+
+- **ドロップイン Z80/6502 交換** — DIP-40 CPU ソケットに装着するだけ。ホストは通常のバスタイミングを認識
+- **サイクル精度 PIO バスインターフェース** — 3 つの RP2350 PIO ブロックがアドレス、データ、制御信号をフルバス速度で処理
+- **8 MB PSRAM** — 64 バンク x 64 KB のバンクアドレス空間、512 バイト単位で設定可能
+- **ROM/RAM バンキング** — ブロックを ROM、RAM、物理ホストメモリ、仮想関数ハンドラとしてマッピング可能
+- **仮想デバイスフレームワーク** — メモリブロックや I/O ポート範囲を C 関数で実装可能
+- **マシンペルソナ** — JSON 駆動設定で任意の Z80/6502 ホストに対応。Sharp MZ ペルソナ同梱
+- **フロッピーおよび QuickDisk エミュレーション** — SD カードイメージからの WD1773 FDC および Sharp QuickDisk ドライブエミュレーション
+- **WiFi ウェブ管理** — 設定、ファイル管理、OTA アップデート、ペルソナ選択用の 7 ページ Bootstrap ウェブインターフェース
+- **デュアルファームウェアパーティション** — 安全な OTA アップグレード用の 2 つの独立した 5 MB ファームウェアスロット
+- **USB ファームウェアアップデート** — ブートローダが USB ブリッジを公開し、ハードウェアデバッガ不要で初期フラッシュ可能
+
+---
+
+## ハードウェア
+
+picoZ80 PCB（リビジョン 2.5）は、Z80 DIP-40 パッケージの物理的フットプリント内に収まるコンパクトな 6 層基板です。すべてのロジックは 3.3 V で動作し、5 V ホストバスに対するレベルシフトを備えています。
+
+### 主要コンポーネント
+
+| コンポーネント | 説明 |
+|------------|------|
+| **RP2350B** | デュアルコア Cortex-M33（最大 300 MHz）、512 KB SRAM、48 GPIO（QFN-80） |
+| **16 MB SPI Flash** | ブートローダ、2 つのファームウェアスロット、2 つの設定スロット、パーティションテーブル |
+| **8 MB PSRAM** | 外部疑似スタティック RAM — 64 バンク x 64 KB |
+| **ESP32-S3-PICO-1** | WiFi/BT コプロセッサ、SD カード、ウェブサーバ |
+| **SD カードスロット** | FAT32 — config.json、ROM イメージ、ディスクイメージを格納 |
+| **USB ハブ** | CH334F — ホスト接続とファームウェアアップデートブリッジ |
+| **電源** | TLV62590BV 5 V-to-3.3 V バックコンバータ（Z80 ソケット VCC から給電） |
+
+### 回路図シート
+
+KiCad 設計（`kicad/PICOZ80/`）は 5 シートに分かれています:
+
+1. **RP2350B プロセッサ** — GPIO 割り当て、水晶、Flash、PSRAM
+2. **ESP32 コプロセッサ** — WiFi モジュール、SD カード、FSPI/UART プロセッサ間通信
+3. **Z80 バスインターフェース** — DIP-40 ソケット、全バス信号用直列抵抗ネットワーク
+4. **電源** — 5 V-to-3.3 V 同期バックコンバータ
+5. **USB ハブコントローラ** — CH334F（Mini-B コネクタ付き）
+
+---
+
+## アーキテクチャ
+
+### デュアルコア設計
+
+- **Core 0** — 非リアルタイムタスク: USB ブリッジ、ファイル I/O（ESP32 中継）、ファームウェアアップデート調整、ウォッチドッグ監視、障害診断
+- **Core 1** — CPU エミュレーションホットループ専用: PIO FIFO サービス、メモリマップに対するアドレス解決、物理ホスト・PSRAM・仮想デバイスハンドラへのディスパッチ
+
+### PIO バスインターフェース
+
+Z80 バスインターフェースは RP2350 PIO アセンブリ（`z80.pio`）で完全に実装されています。3 つの PIO ブロックすべてを使用:
+
+| PIO | プログラム | 機能 |
+|-----|----------|------|
+| 0 | `z80_addr`, `z80_data`, `z80_cycle`, `z80_fetch` | アドレス/データバス、サイクルシーケンス、オペコードフェッチ |
+| 1 | `z80_mem_read/write`, `z80_io_read/write`, `z80_busrq`, `z80_nmi`, `z80_clk_sync`, `z80_int_ack` | メモリ/IO サイクル、バス制御、割り込み |
+| 2 | `z80_reset`, `z80_refresh`, `z80_wait`, `z80_sync` | ホストタイミング、DRAM リフレッシュ、ウェイトステート、T1 同期 |
+
+### 3 層メモリモデル
+
+| 層 | ストレージ | 説明 |
+|----|----------|------|
+| 1 | RP2350 SRAM（512 KB） | O(1) ブロックタイプルックアップテーブル — 512 バイトブロック用 128 エントリ |
+| 2 | PSRAM（8 MB、SPI） | 64 バンク x 64 KB RAM/ROM イメージ、ポインタ配列、関数ポインタ配列 |
+| 3 | Flash（16 MB、SPI） | ファームウェア、ROM イメージ（起動時に PSRAM にコピー）、設定 JSON |
+
+メモリブロックタイプ: `PHYSICAL`, `PHYSICAL_VRAM`, `PHYSICAL_HW`, `RAM`, `ROM`, `VRAM`, `FUNC`, `PTR`
+
+### Flash メモリレイアウト
+
+| パーティション | アドレス範囲 | サイズ | 内容 |
+|------------|-----------|------|------|
+| ブートローダ | `0x10000000-0x1001FFFF` | 128 KB | USB ブリッジ、ファームウェアアップデート、パーティション選択 |
+| App スロット 1 | `0x10020000-0x1051FFFF` | 5 MB | Z80 ファームウェア（パーティション 1） |
+| App スロット 2 | `0x10520000-0x10A1FFFF` | 5 MB | Z80 ファームウェア（パーティション 2） |
+| App 設定 1 | `0x10A20000-0x10C9FFFF` | 2.5 MB | ROM イメージ + 設定 JSON（スロット 1） |
+| App 設定 2 | `0x10CA0000-0x10F1FFFF` | 2.5 MB | ROM イメージ + 設定 JSON（スロット 2） |
+| 全般設定 | `0x10F20000-0x10FFEFFF` | 892 KB | コア設定 |
+| パーティションテーブル | `0x10FFF000-0x11000000` | 4 KB | アクティブスロット、チェックサム、メタデータ |
+
+---
+
+## マシンペルソナ
+
+ファームウェアは複数のマシンペルソナをサポートし、各ペルソナは異なる PSRAM バンクに関連付けられます。ペルソナの切り替えにより、ホストをリブートせずにアクティブなメモリマップとロード済み ROM イメージが変更されます。
+
+### ペリフェラルおよびファイリングシステムドライバ
+
+| ドライバ | 説明 |
+|--------|------|
+| `MZ700.c` | Sharp MZ-700 ペリフェラルセット — バンク切り替え、ビデオ、キーボード I/O |
+| `WD1773.c` | WD1773 フロッピーディスクコントローラ — SD カードからの 80 トラック DSK/RAW イメージ |
+| `QDDrive.c` | Sharp QuickDisk ドライブ — QD イメージファイルによる完全な SIO/2 エミュレーション |
+| `RFS.c` | ROM ファイリングシステム — SD からの MZF ロード、CP/M v2.23、SA-1510 BASIC、MS-BASIC v4.7 |
+| `TZFS.c` | TranZPUter ファイリングシステム *（開発中）* |
+| `MZ-1E05.c` | Sharp MZ-1E05 フロッピーディスクインターフェースユニット |
+| `MZ-1E14.c` | BIOS ROM 付き QuickDisk コントローラ（MZ-700/MZ-800） |
+| `MZ-1E19.c` | BIOS ROM なし QuickDisk コントローラ（MZ-800/MZ-2000/MZ-2200/MZ-2500） |
+| `MZ-1R12.c` | 32 KB バッテリバックアップ RAM ボード（SD カードに永続化） |
+| `MZ-1R18.c` | 64 KB RAM 拡張 / RAMFILE |
+
+---
+
+## ビルド手順
+
+### 前提条件
+
+- **CMake 3.20+**
+- **ARM GCC ツールチェーン** — `arm-none-eabi-gcc`
+- **Docker** — ESP32 ファームウェアビルド用（Espressif IDF コンテナ `espressif/idf:release-v5.4`）
+- **Python 3** — Pico SDK ビルドツールに必要
+- **Perl** — 自動バージョンインクリメントに使用
+
+### ディレクトリ構成
+
+```
+<root>/
+├── get_and_build_sdk.sh      # pico-sdk のクローンとビルド
+├── build_tzpuPico.sh         # RP2350 ファームウェアのビルド（+ オプションで ESP32）
+├── picoZ80.h.tmpl            # ボード定義テンプレート（ビルド時に SDK にコピー）
+├── pico-sdk/                 # get_and_build_sdk.sh でクローン
+├── pico-extras/              # get_and_build_sdk.sh でクローン
+└── projects/
+    ├── Z80/                  # Z80 エミュレーターライブラリ（別途クローン）
+    └── tzpuPico/             # 本プロジェクト
+```
+
+### ステップ 1 — プロジェクトのクローン
+
+```bash
+mkdir -p <root>/projects
+cd <root>/projects
+
+# メインプロジェクトのクローン
+git clone https://git.eaw.app/eaw/pico.git tzpuPico
+
+# Z80 エミュレーターライブラリのクローン
+git clone https://github.com/redcode/Z80.git Z80
+```
+
+### ステップ 2 — PICO_PATH の設定
+
+`get_and_build_sdk.sh` と `build_tzpuPico.sh` の先頭にある `PICO_PATH` 変数を編集:
+
+```bash
+export PICO_PATH=/your/chosen/root/
+```
+
+### ステップ 3 — Pico SDK の取得とビルド
+
+```bash
+cd <root>
+./get_and_build_sdk.sh
+```
+
+### ステップ 4 — RP2350 ファームウェアのビルド
+
+```bash
+cd <root>
+
+# 標準リリースビルド（RP2350 のみ）
+./build_tzpuPico.sh
+
+# デバッグビルド
+./build_tzpuPico.sh DEBUG
+
+# フルビルド — RP2350 + Docker 経由の ESP32 ファームウェア
+./build_tzpuPico.sh ALL
+```
+
+出力ファイル:
+- `projects/tzpuPico/fw/uf2/` — ブートローダ UF2 イメージ（初期 USB フラッシュ用）
+- `projects/tzpuPico/fw/bin/` — アプリケーションパーティションバイナリ（OTA アップデート用）
+
+### ESP32 ファームウェアの個別ビルド
+
+```bash
+alias idf54='docker run --rm --privileged \
+  --volume /dev:/dev --volume /sys:/sys:ro \
+  --volume /dev/bus/usb:/dev/bus/usb \
+  -v $PWD:/project -w /project \
+  -it espressif/idf:release-v5.4 idf.py "$@"'
+
+cd <root>/projects/tzpuPico/esp32
+idf54 build
+```
+
+---
+
+## フラッシュ
+
+### 初期 RP2350 フラッシュ
+
+6 ピンデバッグヘッダのピン配置:
+
+| ピン 1 | ピン 2 | ピン 3 | ピン 4 | ピン 5 | ピン 6 |
+|--------|--------|--------|--------|--------|--------|
+| SWCLK | SWDIO | Reset RP2350 | Reset ESP32 | GND | BOOTSEL |
+
+1. **ピン 6（BOOTSEL）**を Low に保持
+2. 電源を投入するか、**ピン 3（Reset）**を Low にして解放
+3. 起動開始後すぐに BOOTSEL を解放
+4. USB を接続 — RP2350 がマスストレージデバイスとして列挙
+5. マウントされたドライブに `Bootloader_<version>.uf2` をコピー
+
+### 初期 ESP32 フラッシュ
+
+```bash
+python3 -m venv ./venv/ && source ./venv/bin/activate
+cd $HOME/esptool
+
+PORT=/dev/ttyUSB0          # システムに合わせて調整
+BINPATH=/path/to/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
+```
+
+### OTA アップデート（初期フラッシュ後）
+
+- **RP2350** — `http://<device-ip>/ota-rp2350.htm` にアクセスし、`.bin` ファイルをアップロード
+- **ESP32** — `http://<device-ip>/ota-esp32.htm` にアクセスし、ファームウェアバイナリまたは FilePack アーカイブをアップロード
+
+### SD カードの準備
+
+FAT32 でフォーマットしてください。ルートディレクトリに `config.json` を配置します。設定で参照される ROM イメージおよびディスクイメージ用のサブディレクトリを作成します。ボード稼働後は、ウェブファイルマネージャページからも SD カードを管理できます。
+
+---
+
+## ウェブインターフェース
+
+ESP32 が WiFi 経由で 7 ページの Bootstrap ウェブインターフェースを提供:
+
+| ページ | 機能 |
+|------|------|
+| **ステータス** | システム概要 — RP2350/ESP32 ファームウェアバージョン、パーティション情報、稼働時間 |
+| **パーソナリティ** | マシンペルソナの選択と切り替え |
+| **設定** | シンタックスハイライト付きの config.json 編集 |
+| **ファイルマネージャ** | SD カード上のファイルの閲覧、アップロード、ダウンロード、削除 |
+| **OTA RP2350** | RP2350 ファームウェアバイナリの OTA アップロード |
+| **OTA ESP32** | ESP32 ファームウェアまたは FilePack アーカイブのアップロード |
+| **WiFi 設定** | AP/クライアントモード、SSID、パスワードの設定 |
+
+---
+
+## ドキュメント
+
+詳細なドキュメントは [eaw.app](https://eaw.app) で公開されています:
+
+- [picoZ80 概要](https://eaw.app/ja/picoz80/) — ハードウェア写真と機能概要
+- [picoZ80 ユーザーマニュアル](https://eaw.app/ja/picoz80-usermanual/) — セットアップ、設定、操作ガイド
+- [picoZ80 テクニカルガイド](https://eaw.app/ja/picoz80-technicalguide/) — アーキテクチャ詳細、PIO 内部、メモリモデル
+- [picoZ80 デベロッパーズガイド](https://eaw.app/ja/picoz80-developersguide/) — ビルド、デバッグ、ペルソナとドライバの追加
+- [pico6502 概要](https://eaw.app/ja/pico6502/) — 6502 バリアント
+
+---
+
+## クレジット
+
+- **Manuel Sainz de Baranda y Goni** — [Z80](https://github.com/redcode/Z80) C 言語 Z80 CPU エミュレーターライブラリ（GPL v3）
+- **Raspberry Pi Ltd** — Pico SDK および RP2350 ハードウェア
+- **Espressif Systems** — ESP-IDF フレームワークおよび ESP32 ハードウェア
+- **Philip Smart** — ハードウェア設計、RP2350 PIO ファームウェア、ESP32 ウェブアプリケーション、JSON 設定システム、Sharp MZ ペルソナドライバ、ドキュメント
+
+---
+
+## 商用利用の制限
+
+**書面による明示的な許可なく商用利用は認められません。**
+
+picoZ80/pico6502 のハードウェア設計、ファームウェア、および関連するすべてのソフトウェアは、個人使用、教育目的、および非商用利用のみに提供されています。この設計のいかなる部分も、著者の書面による明示的な許可なく、商用製品に使用、複製、製造、販売、または組み込むことはできません。
+
+商用ライセンスのお問い合わせ: [info@eaw.app](mailto:info@eaw.app)
+
+---
+
+## ライセンス
+
+| コンポーネント | ライセンス |
+|------------|----------|
+| picoZ80/pico6502 RP2350 ファームウェア（PIO、C ソース） | GNU General Public License v3 |
+| picoZ80/pico6502 ESP32 ファームウェアおよびウェブインターフェース | GNU General Public License v3 |
+| Z80 CPU エミュレーターライブラリ（Manuel Sainz de Baranda y Goni） | GNU General Public License v3 |
+| KiCad ハードウェア設計ファイル（回路図、PCB、ガーバー） | Creative Commons BY-NC-SA 4.0 |
+| ドキュメントおよびユーザーガイド | Creative Commons BY-NC-SA 4.0 |
+| Raspberry Pi Pico SDK | BSD 3-Clause |
+| ESP-IDF フレームワーク | Apache License 2.0 |
+| Bootstrap 4（ウェブインターフェース） | MIT License |
+
+ファームウェアとソフトウェアは GPL v3 の下でオープンソースです。ハードウェア設計とドキュメントは CC BY-NC-SA 4.0 の下でライセンスされています（非商用利用のみ — 商用ライセンスはリクエストに応じて提供可能）。サードパーティライブラリは各自のライセンスを保持します。
+
+**picoZ80**、**pico6502**、**engineers@work** の名称は Philip Smart の商標です。帰属表示、商標、および盗用防止の条項の詳細は [NOTICE](NOTICE) ファイルをご覧ください。
+
+ライセンス全文: [LICENSE](LICENSE) | [LICENSE-HARDWARE.txt](LICENSE-HARDWARE.txt) | [LICENSE-SOFTWARE.txt](LICENSE-SOFTWARE.txt)
--- a/README.md
+++ b/README.md
@@ -0,0 +1,319 @@
+# picoZ80 / pico6502
+
+**RP2350-based drop-in CPU replacements with cycle-accurate PIO bus interface, WiFi management, and virtual device framework.**
+
+Copyright (c) 2019-2026 Philip Smart — [eaw.app](https://eaw.app)
+
+---
+
+## Overview
+
+The **picoZ80** is a custom PCB designed to drop directly into the Z80 DIP-40 CPU socket of any legacy Z80-based computer. Rather than using a discrete Z80 processor, the board hosts an **RP2350B** microcontroller — a dual-core 150 MHz Cortex-M33 (up to 300 MHz) — whose programmable I/O (PIO) state machines take full, cycle-accurate control of the Z80 address, data, and control buses.
+
+The **pico6502** applies the same architecture to the MOS 6502, replacing the 6502 DIP-40 CPU in any compatible host.
+
+Every bus transaction is handled in real time by the RP2350's PIO engines, giving the host system exactly the same bus timing it would see from a real CPU. The RP2350's second core, 512 KB on-chip SRAM, 8 MB external PSRAM, and 16 MB Flash allow an almost unlimited range of capabilities: accelerated execution, virtualised memory, ROM banking, virtual disk drives, and full machine-persona emulation.
+
+An **ESP32** co-processor provides WiFi, Bluetooth, SD-card mass storage, and a browser-based management interface. All configuration is driven from a single `config.json` file on the SD card — no recompilation is required to reconfigure the memory map, ROM images, or driver selection.
+
+### Key Features
+
+- **Drop-in Z80/6502 replacement** — installs in any DIP-40 CPU socket; the host sees normal bus timing throughout
+- **Cycle-accurate PIO bus interface** — three RP2350 PIO blocks handle address, data, and control signals at full bus speed
+- **8 MB PSRAM** — 64 banks x 64 KB of banked address space, configurable in 512-byte granularity
+- **ROM/RAM banking** — blocks can be mapped as ROM, RAM, physical host memory, or virtual function handlers
+- **Virtual device framework** — any memory block or I/O port range can be backed by a C function
+- **Machine personas** — JSON-driven configuration for any Z80/6502 host; Sharp MZ personas included
+- **Floppy and QuickDisk emulation** — WD1773 FDC and Sharp QuickDisk drive emulation from SD card images
+- **WiFi web management** — seven-page Bootstrap web interface for configuration, file management, OTA updates, and persona selection
+- **Dual firmware partitions** — two independent 5 MB firmware slots for safe OTA upgrades
+- **USB firmware update** — bootloader exposes a USB bridge for initial flashing without a hardware debugger
+
+---
+
+## Hardware
+
+The picoZ80 PCB (revision 2.5) is a compact, 6-layer board designed to fit within the physical footprint of the Z80 DIP-40 package. All logic operates at 3.3 V with level shifting for the 5 V host bus.
+
+### Key Components
+
+| Component | Description |
+|-----------|-------------|
+| **RP2350B** | Dual-core Cortex-M33 @ up to 300 MHz, 512 KB SRAM, 48 GPIO (QFN-80) |
+| **16 MB SPI Flash** | Bootloader, two firmware slots, two config slots, partition table |
+| **8 MB PSRAM** | External pseudo-static RAM — 64 banks x 64 KB |
+| **ESP32-S3-PICO-1** | WiFi/BT co-processor, SD card, web server |
+| **SD card slot** | FAT32 — stores config.json, ROM images, disk images |
+| **USB hub** | CH334F — host connectivity and firmware update bridging |
+| **Power supply** | TLV62590BV 5 V-to-3.3 V buck converter from Z80 socket VCC |
+
+### Schematic Sheets
+
+The KiCad design (`kicad/PICOZ80/`) is divided into five sheets:
+
+1. **RP2350B Processor** — GPIO assignments, crystal, Flash, PSRAM
+2. **ESP32 Co-processor** — WiFi module, SD card, FSPI/UART inter-processor communication
+3. **Z80 Bus Interface** — DIP-40 socket, series resistor network for all bus signals
+4. **Power Supply** — 5 V-to-3.3 V synchronous buck converter
+5. **USB Hub Controller** — CH334F with Mini-B connector
+
+---
+
+## Architecture
+
+### Dual-Core Design
+
+- **Core 0** — non-real-time tasks: USB bridge, file I/O (relayed to ESP32), firmware update coordination, watchdog supervision, fault diagnostics
+- **Core 1** — CPU emulation hot loop exclusively: services PIO FIFOs, resolves addresses against the memory map, dispatches to physical host, PSRAM, or virtual device handlers
+
+### PIO Bus Interface
+
+The Z80 bus interface is implemented entirely in RP2350 PIO assembly (`z80.pio`). All three PIO blocks are used:
+
+| PIO | Programs | Function |
+|-----|----------|----------|
+| 0 | `z80_addr`, `z80_data`, `z80_cycle`, `z80_fetch` | Address/data bus, cycle sequencing, opcode fetch |
+| 1 | `z80_mem_read/write`, `z80_io_read/write`, `z80_busrq`, `z80_nmi`, `z80_clk_sync`, `z80_int_ack` | Memory/IO cycles, bus control, interrupts |
+| 2 | `z80_reset`, `z80_refresh`, `z80_wait`, `z80_sync` | Host timing, DRAM refresh, wait states, T1 synchronisation |
+
+### Three-Tier Memory Model
+
+| Tier | Storage | Description |
+|------|---------|-------------|
+| 1 | RP2350 SRAM (512 KB) | O(1) block-type lookup table — 128 entries for 512-byte blocks |
+| 2 | PSRAM (8 MB, SPI) | 64 banks x 64 KB RAM/ROM images, pointer arrays, function-pointer arrays |
+| 3 | Flash (16 MB, SPI) | Firmware, ROM images (copied to PSRAM at boot), config JSON |
+
+Memory block types: `PHYSICAL`, `PHYSICAL_VRAM`, `PHYSICAL_HW`, `RAM`, `ROM`, `VRAM`, `FUNC`, `PTR`
+
+### Flash Memory Layout
+
+| Partition | Address Range | Size | Contents |
+|-----------|--------------|------|----------|
+| Bootloader | `0x10000000-0x1001FFFF` | 128 KB | USB bridge, firmware update, partition selector |
+| App Slot 1 | `0x10020000-0x1051FFFF` | 5 MB | Z80 firmware (partition 1) |
+| App Slot 2 | `0x10520000-0x10A1FFFF` | 5 MB | Z80 firmware (partition 2) |
+| App Config 1 | `0x10A20000-0x10C9FFFF` | 2.5 MB | ROM images + config JSON (slot 1) |
+| App Config 2 | `0x10CA0000-0x10F1FFFF` | 2.5 MB | ROM images + config JSON (slot 2) |
+| General Config | `0x10F20000-0x10FFEFFF` | 892 KB | Core settings |
+| Partition Table | `0x10FFF000-0x11000000` | 4 KB | Active slot, checksums, metadata |
+
+---
+
+## Machine Personas
+
+The firmware supports multiple machine personas, each associated with a different PSRAM bank. Switching persona changes the active memory map and loaded ROM images without rebooting.
+
+### Peripheral and Filing-System Drivers
+
+| Driver | Description |
+|--------|-------------|
+| `MZ700.c` | Sharp MZ-700 peripheral set — bank-switching, video, keyboard I/O |
+| `WD1773.c` | WD1773 floppy disk controller — 80-track DSK/RAW images from SD card |
+| `QDDrive.c` | Sharp QuickDisk drive — full SIO/2 emulation with QD image files |
+| `RFS.c` | ROM Filing System — MZF loading from SD, CP/M v2.23, SA-1510 BASIC, MS-BASIC v4.7 |
+| `TZFS.c` | TranZPUter Filing System *(work in progress)* |
+| `MZ-1E05.c` | Sharp MZ-1E05 floppy disk interface unit |
+| `MZ-1E14.c` | QuickDisk controller with BIOS ROM (MZ-700/MZ-800) |
+| `MZ-1E19.c` | QuickDisk controller without BIOS ROM (MZ-800/MZ-2000/MZ-2200/MZ-2500) |
+| `MZ-1R12.c` | 32 KB battery-backed RAM board (persisted to SD card) |
+| `MZ-1R18.c` | 64 KB RAM expansion / RAMFILE |
+
+---
+
+## Build Instructions
+
+### Prerequisites
+
+- **CMake 3.20+**
+- **ARM GCC toolchain** — `arm-none-eabi-gcc`
+- **Docker** — for ESP32 firmware build (Espressif IDF container `espressif/idf:release-v5.4`)
+- **Python 3** — required by Pico SDK build tools
+- **Perl** — used for automatic version incrementing
+
+### Directory Structure
+
+```
+<root>/
+├── get_and_build_sdk.sh      # clones and builds pico-sdk
+├── build_tzpuPico.sh         # builds RP2350 firmware (+ optionally ESP32)
+├── picoZ80.h.tmpl            # board definition, copied into SDK at build time
+├── pico-sdk/                 # cloned by get_and_build_sdk.sh
+├── pico-extras/              # cloned by get_and_build_sdk.sh
+└── projects/
+    ├── Z80/                  # Z80 emulator library (clone separately)
+    └── tzpuPico/             # this project
+```
+
+### Step 1 — Clone the Projects
+
+```bash
+mkdir -p <root>/projects
+cd <root>/projects
+
+# Clone the main project
+git clone https://git.eaw.app/eaw/pico.git tzpuPico
+
+# Clone the Z80 emulator library
+git clone https://github.com/redcode/Z80.git Z80
+```
+
+### Step 2 — Set PICO_PATH
+
+Edit the `PICO_PATH` variable at the top of `get_and_build_sdk.sh` and `build_tzpuPico.sh`:
+
+```bash
+export PICO_PATH=/your/chosen/root/
+```
+
+### Step 3 — Get and Build the Pico SDK
+
+```bash
+cd <root>
+./get_and_build_sdk.sh
+```
+
+### Step 4 — Build the RP2350 Firmware
+
+```bash
+cd <root>
+
+# Standard release build (RP2350 only)
+./build_tzpuPico.sh
+
+# Debug build
+./build_tzpuPico.sh DEBUG
+
+# Full build — RP2350 + ESP32 firmware via Docker
+./build_tzpuPico.sh ALL
+```
+
+Output files:
+- `projects/tzpuPico/fw/uf2/` — Bootloader UF2 images (for initial USB flashing)
+- `projects/tzpuPico/fw/bin/` — Application partition binaries (for OTA updates)
+
+### Build ESP32 Firmware Separately
+
+```bash
+alias idf54='docker run --rm --privileged \
+  --volume /dev:/dev --volume /sys:/sys:ro \
+  --volume /dev/bus/usb:/dev/bus/usb \
+  -v $PWD:/project -w /project \
+  -it espressif/idf:release-v5.4 idf.py "$@"'
+
+cd <root>/projects/tzpuPico/esp32
+idf54 build
+```
+
+---
+
+## Flashing
+
+### Initial RP2350 Flash
+
+The 6-pin debug header pinout:
+
+| Pin 1 | Pin 2 | Pin 3 | Pin 4 | Pin 5 | Pin 6 |
+|-------|-------|-------|-------|-------|-------|
+| SWCLK | SWDIO | Reset RP2350 | Reset ESP32 | GND | BOOTSEL |
+
+1. Hold **Pin 6 (BOOTSEL)** low
+2. Apply power or assert **Pin 3 (Reset)** low then release
+3. Release BOOTSEL promptly after boot begins
+4. Connect USB — the RP2350 enumerates as a mass-storage device
+5. Copy `Bootloader_<version>.uf2` to the mounted drive
+
+### Initial ESP32 Flash
+
+```bash
+python3 -m venv ./venv/ && source ./venv/bin/activate
+cd $HOME/esptool
+
+PORT=/dev/ttyUSB0          # adjust to your system
+BINPATH=/path/to/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
+```
+
+### OTA Updates (after initial flash)
+
+- **RP2350** — navigate to `http://<device-ip>/ota-rp2350.htm`, upload the `.bin` file
+- **ESP32** — navigate to `http://<device-ip>/ota-esp32.htm`, upload the firmware binary or FilePack archive
+
+### SD Card Preparation
+
+Format as FAT32. Place `config.json` in the root directory. Create subdirectories for ROM images and disk images as referenced in your configuration. The SD card can also be managed via the web File Manager page.
+
+---
+
+## Web Interface
+
+The ESP32 serves a seven-page Bootstrap web interface over WiFi:
+
+| Page | Function |
+|------|----------|
+| **Status** | System overview — RP2350 and ESP32 firmware versions, partition info, uptime |
+| **Personality** | Select and switch machine personas |
+| **Configuration** | Edit config.json with syntax highlighting |
+| **File Manager** | Browse, upload, download, delete files on the SD card |
+| **OTA RP2350** | Upload RP2350 firmware binary for over-the-air update |
+| **OTA ESP32** | Upload ESP32 firmware or FilePack archive |
+| **WiFi Settings** | Configure AP/client mode, SSID, password |
+
+---
+
+## Documentation
+
+Full documentation is available at [eaw.app](https://eaw.app):
+
+- [picoZ80 Overview](https://eaw.app/picoz80/) — project page with hardware photos and feature overview
+- [picoZ80 User Manual](https://eaw.app/picoz80-usermanual/) — setup, configuration, and operation guide
+- [picoZ80 Technical Guide](https://eaw.app/picoz80-technicalguide/) — architecture deep-dive, PIO internals, memory model
+- [picoZ80 Developer's Guide](https://eaw.app/picoz80-developersguide/) — building, debugging, adding personas and drivers
+- [pico6502 Overview](https://eaw.app/pico6502/) — the 6502 variant
+
+---
+
+## Credits
+
+- **Manuel Sainz de Baranda y Goni** — [Z80](https://github.com/redcode/Z80) C-language Z80 CPU emulator library (GPL v3)
+- **Raspberry Pi Ltd** — Pico SDK and RP2350 hardware
+- **Espressif Systems** — ESP-IDF framework and ESP32 hardware
+- **Philip Smart** — Hardware design, RP2350 PIO firmware, ESP32 web application, JSON configuration system, Sharp MZ persona drivers, documentation
+
+---
+
+## Commercial Use Restriction
+
+**No commercial use permitted without express written permission.**
+
+The picoZ80/pico6502 hardware designs, firmware, and all associated software are made available for personal, educational, and non-commercial use only. No part of this design may be used, reproduced, manufactured, sold, or incorporated into any commercial product without the express written permission of the author.
+
+To request a commercial licence, contact: [info@eaw.app](mailto:info@eaw.app)
+
+---
+
+## Licences
+
+| Component | Licence |
+|-----------|---------|
+| picoZ80/pico6502 RP2350 firmware (PIO, C sources) | GNU General Public License v3 |
+| picoZ80/pico6502 ESP32 firmware and web interface | GNU General Public License v3 |
+| Z80 CPU emulator library (Manuel Sainz de Baranda y Goni) | GNU General Public License v3 |
+| KiCad hardware design files (schematics, PCB, Gerbers) | Creative Commons BY-NC-SA 4.0 |
+| Documentation and user guides | Creative Commons BY-NC-SA 4.0 |
+| Raspberry Pi Pico SDK | BSD 3-Clause |
+| ESP-IDF framework | Apache License 2.0 |
+| Bootstrap 4 (web interface) | MIT License |
+
+The firmware and software are open-source under the GPL v3. The hardware designs and documentation are licensed under CC BY-NC-SA 4.0 (non-commercial use only — commercial licensing available on request). Third-party libraries retain their own licences.
+
+The names **picoZ80**, **pico6502**, and **engineers@work** are trademarks of Philip Smart. See the [NOTICE](NOTICE) file for full attribution, trademark, and anti-passing-off terms.
+
+Full licence texts: [LICENSE](LICENSE) | [LICENSE-HARDWARE.txt](LICENSE-HARDWARE.txt) | [LICENSE-SOFTWARE.txt](LICENSE-SOFTWARE.txt)