From e19a22fce692a6bc3484d20fb48ad56b00e73fc1 Mon Sep 17 00:00:00 2001 From: Philip Smart Date: Sun, 29 Mar 2026 23:59:43 +0100 Subject: [PATCH] Added README --- README.ja.md | 319 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 319 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 638 insertions(+) create mode 100644 README.ja.md create mode 100644 README.md diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 0000000..a85b4e0 --- /dev/null +++ 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** — 自動バージョンインクリメントに使用 + +### ディレクトリ構成 + +``` +/ +├── 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 /projects +cd /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 +./get_and_build_sdk.sh +``` + +### ステップ 4 — RP2350 ファームウェアのビルド + +```bash +cd + +# 標準リリースビルド（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 /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_.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:///ota-rp2350.htm` にアクセスし、`.bin` ファイルをアップロード +- **ESP32** — `http:///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) diff --git a/README.md b/README.md new file mode 100644 index 0000000..92032d3 --- /dev/null +++ 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 + +``` +/ +├── 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 /projects +cd /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 +./get_and_build_sdk.sh +``` + +### Step 4 — Build the RP2350 Firmware + +```bash +cd + +# 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 /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_.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:///ota-rp2350.htm`, upload the `.bin` file +- **ESP32** — navigate to `http:///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)