picoZ80 ユーザーマニュアル

picoZ80 ユーザーマニュアル

picoZ80 は、DIP-40 ソケット付きコンピューター用の Z80 CPU ドロップイン交換品です。ビンテージコンピューターの Z80 ソケットに直接接続することで、ホストボードに一切改造を加えることなく、拡張メモリ、仮想ペリフェラル、フロッピーおよび QuickDisk エミュレーション、ファイリングシステム、WiFi 経由のブラウザベースの管理インターフェースを提供します。
このマニュアルでは、物理ボード、初期セットアップ、ホストマシンへの接続、ウェブインターフェースの使用方法を説明します。アーキテクチャの詳細、設定リファレンス、開発情報についてはpicoZ80 テクニカルガイドを参照してください。

ボード概要

picoZ80 PCB は、標準的な 40 ピン DIP パッケージのフットプリント内に収まるように設計されています。40 本すべての DIP ピンがボードの裏面から突き出ており、実際の Z80 のピン配置と完全に一致しているため、ピンを曲げたりアダプターを使用したりすることなく、どの Z80 ソケットにも直接装着できます。
ボードの表面にはすべてのアクティブコンポーネントが搭載されています。ボードのほとんどの Z80 コンピューターの内部スペースよりも幅が狭く、ソケット上の高さは下に DIP-40 ソケットが取り付けられた標準的な IC のエンベロープ内に収まっています。

コネクタとインジケータ

picoZ80 ボードには以下のコネクタとインジケータがあります：
項目 説明
6 ピンデバッグヘッダー ボードの端に位置。RP2350 への SWD（シリアルワイヤデバッグ）アクセス、初期フラッシュ用の BOOTSEL とリセットライン、ESP32 のリセットを提供。下記のデバッグヘッダーのピン配置を参照。
USB ポート（Mini-B） USB 大容量ストレージ経由のファームウェアフラッシュ（初期フラッシュ）および ESP32 への USB-UART ブリッジ用の USB 接続。ボードリビジョン v2.3a 以降では ESP32 用の専用 USB ポートが追加で存在する場合もある。
SD カードスロット ESP32 が管理するフルサイズ SD カードスロット。config.json、ROM イメージ、ディスクイメージ、ファイリングシステムツリーを保持。

デバッグヘッダーのピン配置

6 ピンヘッダーは初期プログラミングとソースレベルデバッグのためのプライマリハードウェアインターフェースです。ピンはボード端マーカーに最も近い端のピン 1 から番号が付けられています。
ピン シグナル 機能
1 SWCLK シリアルワイヤデバッグクロック（ARM SWD）
2 SWDIO シリアルワイヤデバッグデータ（ARM SWD）
3 Reset RP2350 RP2350 のアクティブロウリセット。ロウにプルして RP2350 をリセット。
4 Reset ESP32 ESP32 のアクティブロウリセット。ロウにプルして ESP32 をリセット状態で保持。
5 GND グランド基準
6 BOOTSEL RP2350 ブートモード選択。電源投入/リセット中にロウを保持して USB 大容量ストレージモードに入る。

注：ピン 1、2、5 は SWD デバッグに使用（SWCLK、SWDIO、GND）。ピン 3 と 6 は初期フラッシュにのみ使用。ピン 4 は RP2350 の起動中に ESP32 が起動しないようにする必要がある場合に使用（例：初期 ESP32 ファームウェアプログラミング中）。

はじめに

picoZ80 ボードを初めてセットアップする際は、以下の手順を順番に実行します：
  1. USB 大容量ストレージモード（BOOTSEL）経由で RP2350 ブートローダーをフラッシュする。
  2. esptool 経由で ESP32 ファームウェアをフラッシュする。
  3. config.json と必要な ROM/ディスクイメージを含む SD カードを準備する。
  4. ホストコンピューターの Z80 ソケットに picoZ80 を取り付ける。
  5. 電源を入れ、picoZ80 ウェブインターフェースに接続し、必要に応じて設定する。

ステップ 1 — RP2350 ブートローダーをフラッシュする

RP2350 には物理的な BOOTSEL またはリセットボタンがありません。両方のシグナルは 6 ピンデバッグヘッダーで利用可能です。USB 大容量ストレージブートローダーに入るには：
  1. まだ picoZ80 をホストコンピューターに挿入しないでください — USB ケーブルでのみ PC に接続してください。
  2. ジャンパーまたはプローブを使用してピン 6（BOOTSEL）をロウに保持します。
  3. USB ポートに電源を供給します — RP2350 が起動を開始します。
  4. ボードが USB 大容量ストレージデバイスとして列挙された直後に BOOTSEL を解放します（リセット後に BOOTSEL を長く保持しすぎると RP2350 がフラッシュチップにアクセスできなくなります）。
  5. PC に RPI-RP2（または類似）とラベル付けされたドライブがマウントされます。
  6. Bootloader_<バージョン>.uf2 をマウントされたドライブにコピーします。RP2350 は自己フラッシュして自動的に再起動します。
ブートローダーをフラッシュした後、その後のすべての RP2350 ファームウェアアップデートはウェブ OTA ページ経由でワイヤレスで実行できます — 通常のファームウェアアップデートのためにデバッグヘッダーに再度触れる必要はありません。

ステップ 2 — ESP32 ファームウェアをフラッシュする

ESP32 ファームウェアは esptool を使用してフラッシュします。ボードリビジョン v2.3a 以降では、ESP32 は独自の USB ポートを持ちホスト PC 上で独立して表示されます。以前のリビジョン（v2.0〜v2.2）では、ESP32 は USB-UART ブリッジとして機能する RP2350 を通じてアクセスされます。
Python 環境をセットアップします（一度だけ）： 
python3 -m venv ./venv/
source ./venv/bin/activate
cd $HOME/esptool
次に 4 つすべての ESP32 ファームウェアコンポーネントをフラッシュします。OS が割り当てたデバイスノードに PORT を調整してください： 
PORT=/dev/ttyUSB0       # Linux — 必要に応じて調整

# 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

注：初期フラッシュが完了したら、その後のすべての ESP32 ファームウェアアップデートは OTA ウェブページ（ota-esp32.htm）経由で実行できます。

ステップ 3 — SD カードを準備する

SD カードは picoZ80 のプライマリストレージメディアです。設定ファイル、ROM イメージ、ディスクイメージ、ファイリングシステムディレクトリを保持します。
フォーマット要件：
  • FAT32 ファイルシステム。
  • FAT32 がサポートする任意の容量（信頼性の高いフォーマットには通常 32GB 以下を推奨）。
最低限必要なファイル：
  • SD カードのルートにある config.json — メイン設定ファイル。最小限の例については基本設定を参照。
  • webfs/ ディレクトリ — ESP32 ウェブインターフェースのアセット。プロジェクトリポジトリの webfs/ ディレクトリの内容を SD カードのルートにコピーしてください。
オプションだが推奨されるディレクトリ：
ディレクトリ 内容
MZF/ ファイリングシステム経由で読み込む MZF 形式プログラムファイル
ROM/ config.json が参照する ROM イメージ
DSK/ WD1773 エミュレーション用フロッピーディスクイメージ（DSK 形式）
QD/ QuickDisk エミュレーション用 QuickDisk イメージ
TZFS/ TranZPUter ファイリングシステムツリー
RFS/ ROM ファイリングシステムプログラムツリー
picoZ80 が動作したら、SD カードはウェブファイルマネージャーを通じて完全に管理できます — カードを物理的に取り外すことなく、ブラウザから ROM イメージのアップロード、`config.json` の編集、ディレクトリの作成が可能です。

ステップ 4 — ホストコンピューターに取り付ける

安全第一：picoZ80 を取り付けまたは取り外す前に、必ずホストコンピューターの電源を切ってプラグを抜いてください。ボードは内部で 3.3V で動作しますが、DIP-40 ピンは適切なインターフェース回路を通じて 5V ホストバスに接続されています。ただし電源が入っている状態でボードを挿入または取り外してはいけません。
取り付け手順：
  1. ホストコンピューターの電源を切り、静電気を放電します。
  2. DIP-40 ソケットから既存の Z80 CPU チップを取り外します。ピンを曲げないようにチップエクストラクターツールの使用を推奨します。
  3. picoZ80 の SD カードスロットに SD カードを挿入します。
  4. picoZ80 を Z80 ソケットに位置合わせし、picoZ80 のピン 1（ドットまたはノッチで示されている）がソケットのピン 1（IC アウトライン シルクスクリーンのノッチに隣接して示されている）と一致することを確認します。
  5. picoZ80 をソケットに静かに均等に押し込みます。40 本すべてのピンが装着されていることを確認してください。無理に押し込まないでください — 抵抗を感じたら取り外してピンの位置を確認してください。
  6. ホストコンピューターの電源を入れます。
新しいファームウェアのインストール後の初回電源投入時、ESP32 はアクセスポイントモードで起動し、picoZ80 という名前の WiFi ネットワークをブロードキャストします。このネットワークに接続してウェブインターフェースにアクセスし、初期 WiFi 設定を完了してください。

注：picoZ80 は Z80 ソケットの VCC ピンの 5V 供給から電源を取ります。オンボードのバックコンバーターがすべてのボードコンポーネントに 3.3V を供給します。ホストコンピューターの 5V 供給が少なくとも 500mA を供給できることを確認してください — picoZ80 はピーク負荷（WiFi アクティブで RP2350 が 300MHz）で最大 400mA を消費する可能性があります。

WiFi セットアップ

WiFi 接続には、PCB 上のアンテナ整合回路の実装と WiFi 対応ファームウェアが必要です。詳細は下記の無線規制に関する注意事項を参照してください。NCM のみのファームウェアを使用している場合は、このセクションをスキップし、USB NCM 接続をご使用ください。
picoZ80 ESP32 コプロセッサが WiFi 接続を提供します。初回起動時（または WiFi 資格情報が保存されていない場合）、ESP32 はアクセスポイント（AP）モードで起動し、ブラウザでアクセスしてホームネットワーク設定を構成できます。

アクセスポイントモードでの接続

  1. スマートフォン、タブレット、またはノートパソコンで WiFi 設定を開き、picoZ80 という名前のネットワーク（または AP モードでの config.json の esp32.wifi.ssid フィールドで設定されたもの）を探します。
  2. picoZ80 ネットワークに接続します。デフォルトの AP パスワードは pZ80pZ80 です（変更されている場合はファームウェアのリリースノートを確認してください）。
  3. ブラウザを開いて http://192.168.4.1 に移動します — これはデフォルトの AP モード IP アドレスです。picoZ80 ウェブインターフェースが表示されます。
  4. WiFi マネージャーページに移動して、ホームネットワークの SSID とパスワードを入力します。
  5. Save & Connect をクリックします。ESP32 が再起動してホームネットワークにクライアントとして接続します。

クライアント（ステーション）モード

クライアントモードに設定されると、ESP32 はホーム WiFi ネットワークに参加し、ダッシュボードページに表示された IP アドレスで到達可能になります。`config.json` に固定 IP を設定した場合（アクセスの容易さのために推奨）、直接移動してください： 
http://192.168.1.192
設定した IP アドレスに置き換えてください。DHCP を使用している場合は、ルーターの DHCP クライアントリストから割り当てられたアドレスを確認してください。
ウェブインターフェースはブラウザで完全に動作します。追加のソフトウェアは不要です。picoZ80 ウェブサーバーはポート 80 で動作します。

USB NCM 接続（WiFi 不要）
ボードが NCM ファームウェア（sdkconfig.mode_ncm_only または sdkconfig.mode_wifi_and_ncm）でビルドされている場合、ESP32 USB ポートをホストコンピューターに接続すると仮想 Ethernet アダプターが表示されます。picoZ80 の内蔵 DHCP サーバーがホストに自動的に IP アドレスを割り当てるため、手動のネットワーク設定は不要です。
  1. ホストコンピューターから picoZ80 の ESP32 USB ポートに USB ケーブルを接続します。
  2. ホスト OS が新しいネットワークアダプターを検出するまで数秒待ちます。
  3. ウェブブラウザを開いて http://192.168.7.1 にアクセスします。
  4. picoZ80 ダッシュボードページが表示されます。
このモードでは、設定の編集、ファームウェア更新、ファイル管理、ペルソナ選択など、すべてのウェブインターフェース機能に完全にアクセスできます。WiFi アンテナや無線部品は不要です。

ウェブインターフェース

picoZ80 ウェブインターフェースは ESP32 が提供する 8 ページの Bootstrap 4 アプリケーションです。すべてのページは各ページ上部のナビゲーションバーからアクセスできます。ウェブアセットは SD カードの webfs/ ディレクトリに保存されており、ファームウェアとは独立して更新できます。

ダッシュボード（index.htm）

ダッシュボードはウェブインターフェースのホームページです。リアルタイムのシステム情報を表示し、picoZ80 の状態の概要を提供します。
ダッシュボードに表示される情報：
  • ファームウェアバージョン — 現在動作している RP2350 ファームウェアのバージョンとビルド日付。
  • ESP32 バージョン — ESP32 コプロセッサのファームウェアバージョン。
  • アクティブパーティション — 現在アクティブな 2 つのファームウェアスロット（1 または 2）のどちら。
  • アクティブペルソナ — 現在読み込まれているマシンペルソナ（例：MZ-700、MZ-80A）。
  • RP2350 クロック — MHz 単位の現在の CPU 周波数。
  • PSRAM クロック — 現在の PSRAM SPI クロック周波数。
  • WiFi ステータス / ネットワークステータス — WiFi モードではモード（AP またはクライアント）、SSID、割り当てられた IP アドレスが表示されます。NCM のみモードでは「ネットワーク設定」として USB NCM ネットワークの状態が表示されます。
  • WiFi RSSI（WiFi モードのみ — NCM のみモードでは非表示） — 3 秒ごとに自動更新される受信信号強度インジケーター（dBm）。色分け表示：緑（−50 dBm 以上、優良）、青（−70 dBm 以上、良好）、オレンジ（−80 dBm 以上、普通）、赤（−80 dBm 未満、弱い）。picoZ80 は低 RF 放射設計のため、金属製コンピューターケース内に収納されルーターから離れた場所に設置される場合があります。このインジケーターを参考にホストの位置やアンテナを調整して最良の受信状態を得てください。
  • WiFi TX Power（WiFi モードのみ — NCM のみモードでは非表示） — 現在の送信電力（dBm）。こちらもリアルタイム更新されます。WiFi マネージャーページの TX Power 設定適用後の実効値を表示します。
  • SD カード — SD カードが存在するかどうかとファイルシステムのマウント状態。
  • アップタイム — 最終再起動からの経過時間。
ダッシュボードには RP2350 を再起動するボタンと、完全な再起動なしで SD カードから設定を再読み込みするボタンもあります。

コンフィグエディタ（config.htm）

コンフィグエディタページは SD カードに保存されている config.json ファイルのブラウザ内エディタを提供します。エディタにはシンタックスハイライトと基本的な JSON バリデーションが含まれています。
設定を編集するには：
  1. コンフィグエディタページに移動します。
  2. 現在の config.json がエディタに自動的に読み込まれます。
  3. 変更を加えます。エディタはシンタックスエラーを赤でハイライトします。
  4. Save をクリックして更新されたファイルを SD カードに書き戻します。
  5. Apply（または再起動）をクリックして新しい設定を適用します。RP2350 は起動時に設定を読み取り、最小化してフラッシュに保存します — その後の起動では SD カードがない場合はフラッシュのコピーを使用します。
メモリマップ、ROM イメージ、I/O マップへの変更は次の RP2350 リセット時に有効になります。esp32.wifi ブロックの WiFi 設定への変更は次の ESP32 再起動時に有効になります。

注：コンフィグエディタは SD カードのファイルを直接操作します。大幅な変更を加える前に、動作する config.json のバックアップコピーを PC に保存しておくことをお勧めします。

GUI 設定（configgui.htm）

GUI 設定ページは、JSON Config Editor のグラフィカルな代替手段を提供します。すべての設定がラベル付き入力フィールド、ドロップダウン、編集可能なテーブルとして 4 つのタブに整理されています：
  • RP2350 グローバル — 両パーティションに適用されるコア電圧、CPU 周波数、PSRAM 周波数のグローバル設定。
  • パーティション 1 / パーティション 2 — パーティションごとのメモリマップ（アドレス、サイズ、タイプ、ウェイトステート、バンク、ROM ファイル）、I/O ポートマップ、ドライバー設定。各セクションに行の追加・削除ボタン付き。
  • ESP32 — WiFi SSID、パスワード、IP アドレス、ネットマスク、モード（AP/Client）、DHCP、TX パワー設定。
Save Configuration で config.json に保存（以前のバージョンは自動バックアップ）し、RP2350 設定を自動的に再読み込みします。Reload は SD カードから現在の config.json を再読み込みし、未保存の変更を破棄します。GUI で対応できない高度な編集には Config Editor をご使用ください。

ファイルマネージャー（filemanager.htm）

ファイルマネージャーは SD カードの内容のブラウザベースビューを提供します。ディレクトリのナビゲート、新しいファイルのアップロード（ROM イメージ、ディスクイメージ、MZF プログラムファイル）、既存ファイルの PC へのダウンロード、新しいディレクトリの作成、ファイルとディレクトリの削除が可能です。
ファイルマネージャーの一般的なタスク：
  • ROM イメージのアップロード — ROM/ ディレクトリに移動し、アップロードボタンを使用して PC から ROM ファイルを転送。
  • ディスクイメージのアップロード — DSK/（フロッピー）または QD/（QuickDisk）に移動してイメージファイルをアップロード。読み込み後、現在のディスクイメージファイル名がアクションメニューの各フロッピーおよび QD スロットの横に表示され、クイックリファレンスとして確認できます。
  • MZF プログラムのアップロード — MZF/ または関連するファイリングシステムディレクトリに移動して MZF ファイルをアップロード。
  • config.json のバックアップ — config.json の横のダウンロードアイコンをクリックして PC にコピーを保存。
ファイル操作は ESP32 経由で SD カードに直接実行されます。大きなファイルのアップロードはファイルサイズと WiFi 信号品質によっては数秒かかる場合があります。

ペルソナ選択（personality.htm）

ペルソナ選択ページでは、picoZ80 がホストコンピューターに提示するマシンペルソナを選択できます。異なるペルソナは設定から異なるメモリマップ、ROM イメージ、仮想ドライバーバインディングを読み込みます。
現在サポートされている Sharp MZ ペルソナ：
  • MZ-700 — バンク切り替え、仮想ビデオ、キーボード I/O、WD1773 フロッピーエミュレーション、QuickDisk エミュレーション、ROM ファイリングシステムを含むフル MZ-700 ペルソナ。SD カードの読み書きアクセスを持つ CP/M v2.23（48K）、SA-1510 BASIC、Microsoft BASIC v4.7 を含む。
  • MZ-80A — MZ-80A ペルソナ（開発中）。
  • MZ-80B — MZ-80B ペルソナ（開発中）。
  • MZ-800 — MZ-800 ペルソナ（開発中）。
ペルソナを切り替えると、ホストを再起動せずにアクティブなメモリマップと読み込まれた ROM イメージが変更されます。picoZ80 は新しいペルソナの設定に合わせてメモリバンクを再初期化し、ホストは次の Z80 バストランザクション時に新しいメモリレイアウトを認識します。

ファームウェアアップデート（OTA）

RP2350 と ESP32 の両方のファームウェアは、デバッグヘッダーへの物理的なアクセスなしにウェブインターフェースから無線（OTA）でアップデートできます。

RP2350 OTA アップデート（ota-rp2350.htm）
  1. ビルドスクリプトを使用して RP2350 ファームウェアをビルドします — 出力バイナリはバージョンスタンプ付きのファイル名（例：BaseZ80_v3.009.bin）で fw/bin/ に入ります。
  2. http://<デバイス IP>/ota-rp2350.htm に移動します。
  3. どのパーティションスロットを更新するか選択します（スロット 1 またはスロット 2）。現在アクティブなスロットはダッシュボードに表示されます — アップデートが失敗した場合に既存のファームウェアを使用可能な状態に保つため、非アクティブスロットを更新することをお勧めします。2 つのオプションチェックボックスが利用可能です：Clear App Config はターゲットスロットの ROM イメージと設定データを消去し、Clear Flash Header はパーティションテーブルをファクトリーデフォルトにリセットします — 互換性のない設定スキーマを持つファームウェアバージョンにアップグレードする際に使用してください。
  4. Choose File をクリックし、.bin ファイルを選択して Upload をクリックします。
  5. アップロードと確認が完了するのを待ちます。ページには成功が確認され、新しいパーティションが利用可能として表示されます。
  6. 新しいファームウェアを有効化するには、同じページのパーティション選択セクションに移動し、新しく更新されたスロットを選択して Set Active & Reboot をクリックします。RP2350 が新しいファームウェアで再起動します。
アプリケーションパーティションは非標準のフラッシュアドレスに存在するため、純粋なバイナリ形式（UF2 ではなく）を使用します。ブートローダーは新しいパーティションを有効化する前にイメージのチェックサムを確認します — 確認に失敗した場合は既存のアクティブスロットが使用され続けます。
ビルドシステムは 4 つのファームウェアバリアントを生成します：標準（デバッグシェルなし）と DBGSH（ICE デバッガー付き）× 2 パーティション。DBGSH バリアントは INCLUDE_DBGSH コンパイル定義で制御されます。ICE デバッグシェルを使用するには DBGSH バリアントのファームウェアをフラッシュしてください。

ESP32 OTA アップデート（ota-esp32.htm）
  1. ESP32 ファームウェアをビルドします — 出力バイナリは esp32/build/tzpuPico_esp32.bin です。
  2. http://<デバイス IP>/ota-esp32.htm に移動します。
  3. Choose File をクリックし、.bin ファイルを選択して Upload をクリックします。
  4. ESP32 は成功したアップロード後に自動的に新しいファームウェアで再起動します。
OTA ページは SD カードの webfs/ ディレクトリに保存されたウェブインターフェースアセットを更新する FilePack アーカイブも受け付けます。これにより ESP32 ファームウェアバイナリとは独立してウェブ UI を更新できます。

WiFi マネージャー（wifimanager.htm）

このページは WiFi が有効な場合（sdkconfig.mode_wifi_only または sdkconfig.mode_wifi_and_ncm）にのみ表示されます。NCM のみモードではこのページはナビゲーションに表示されません — USB NCM 経由でネットワーク接続が自動的に提供されるため、ユーザー設定は不要です。
WiFi マネージャーページで ESP32 のネットワーク設定を構成します。ここで行われた変更は ESP32 の NVS（不揮発性ストレージ）に保存され、次の再起動時に有効になります。
利用可能な設定：
  • WiFi モード — アクセスポイント（picoZ80 が独自のネットワークを作成する）またはクライアント（picoZ80 が既存のネットワークに参加する）。
  • SSID — 作成する（AP モード）または参加する（クライアントモード）ネットワーク名。
  • パスワード — WiFi パスフレーズ。
  • IP アドレス / ネットマスク / ゲートウェイ — クライアントモード用の固定 IP 設定（一貫したアクセスのために推奨）。
  • DHCP — ルーターからアドレスを自動的に取得するには有効にする；固定 IP 設定を使用するには無効にする。
  • TX Power — WiFi 送信電力（0.25 dBm 単位、範囲 8〜84、すなわち 2〜21 dBm）。0 に設定するとリージョン固有のデフォルト値を使用します。picoZ80 PCB は最小限の RF 放射を目指して設計されているため、金属製コンピューターケース内に設置するとルーターへの信号が弱くなる場合があります。TX Power を上げると消費電力がわずかに増加しますが接続性が向上します。下げると多数の WiFi デバイスがある環境での干渉を低減できます。現在の RSSI と実効 TX Power はダッシュボードおよびこのページで 3 秒ごとにライブ更新されます。
保存後、Reboot ESP32 をクリックして新しい設定を適用します。ESP32 が再起動して新しい設定で接続します。クライアントモードの接続に失敗した場合（SSID またはパスワードが間違っている場合）、ESP32 はタイムアウト後にアクセスポイントモードにフォールバックし、再接続して設定を修正できます。

基本設定

すべての picoZ80 の動作は SD カードの config.json で制御されます。以下は Sharp MZ-700 の最小限の動作設定です。すべてのオプションの詳細な説明についてはテクニカルガイド — 設定リファレンスを参照してください。 
{
  "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": []
      }
    ]
  }
}
この例は以下をマッピングします：
  • 0x0000 – 0x0FFF — PSRAM バンク 0 に SD カードの /ROM/mz700.rom から読み込まれた 4KB ROM。
  • 0x1000 – 0xCFFF — PSRAM バンク 0 の 48KB RAM（読み書き、ゼロウェイト状態）。
  • 0xD000 – 0xFFFF — 物理ホストハードウェア（VRAM および I/O レジスタ）にパススルー、2 ウェイト状態と T1 同期を有効化。

ICE（デバッグシェル）

picoZ80 には、Z80 CPU エミュレーションのリアルタイム検査と制御のための組み込みインタラクティブデバッグシェル（ICE — インサーキットエミュレーター）が含まれています。
接続方法：デバッグシェルは USB の 2 番目のシリアルポートで利用できます。picoZ80 を USB 接続すると、ホストコンピューターに 2 つのシリアルポートが表示されます — 1 つ目は標準デバッグログ出力、2 つ目がデバッグシェルです。任意のターミナルエミュレーターで 115200 baud、8N1 で接続してください。接続するとプロンプト dbg> が表示されます。
主な機能：
  • レジスター検査 — regs で全 Z80 レジスター、フラグ、サイクルカウントを表示。
  • メモリダンプ — dm p 0000 100 でアドレス 0x0000 から 256 バイトを物理バス経由でダンプ。dm v 0000 100 で仮想 PSRAM を直接読み取り。
  • ブレークポイント — bp E800 で 0xE800 にブレークポイントを設定。最大 8 個。bl で一覧表示、bc * で全クリア。
  • シングルステップ — hold で CPU を一時停止し、step で 1 命令ずつ実行。前後のレジスタ状態を表示。
  • 実行トレース — trace on で全実行命令を記録。trace dump 20 で最後の 20 命令をディスアセンブリ付きで表示。
  • ディスアセンブリ — dis v E800 20 で 0xE800 から 32 命令をディスアセンブル。
  • I/O アクセス — in D8 でポート 0xD8 を読み取り。out D8 03 でポート 0xD8 に 0x03 を書き込み。
  • システム情報 — status で CPU 周波数、PSRAM クロック、エミュレーション速度、稼働時間を表示。drivers でアクティブなドライバーを一覧表示。
プロンプトで help と入力すると簡易サマリーが表示されます。

コマンドリファレンス
ICE の全コマンドセットを以下に示します。すべてのアドレスおよびデータ値は 0x プレフィックスなしの 16 進数で入力します。
コマンド パラメータ 説明
help — 利用可能な全コマンドのサマリーを表示。
regs — Z80 レジスターセットの完全ダンプ：メインレジスター（AF、BC、DE、HL）、裏レジスター（AF’、BC’、DE’、HL’）、インデックスレジスター（IX、IY）、スタック・プログラムカウンター（SP、PC）、割り込み状態（I、R、IM、IFF1、IFF2）、デコードされたフラグ（S、Z、H、P/V、N、C）、HALT ライン状態、MEMPTR、累積 T サイクルカウント。
dm [p|f|v|r] <addr> [len] メモリを 16 進および ASCII でダンプ。4 つのモード：p（物理）は Z80 バス経由で実ハードウェアを動作させて読み取り、f（フェッチ）はフェッチ（M1）サイクルで物理バスから読み取り、v（仮想）はバスアクティビティなしで PSRAM を直接読み取り、r（RP2350）はマイクロコントローラー自身のアドレス空間（Flash、SRAM、ペリフェラル）を読み取り。addr は開始アドレス、len はバイト数（デフォルト 256）。
dis [p|v] [addr] [count] Z80 マシンコードをディスアセンブル。p は物理バスからオペコードを読み取り、v は仮想 PSRAM から（デフォルト）。addr のデフォルトは現在の PC。count は命令数（デフォルト 16）。現在の PC は > で表示。
asm [addr] addr（デフォルト：現在の PC）からインタラクティブ Z80 アセンブラーを起動。Z80 ニーモニックを 1 行ずつ入力。アセンブルされたバイトは仮想 PSRAM に書き込まれ、アドレスが自動的に進みます。db、dw/defw ディレクティブをサポート。空行または . で終了。
memmap [block] SRAM メモリブロックポインターテーブルを表示。各エントリにブロック番号、Z80 アドレス範囲、メモリタイプ（PHYSICAL、RAM、ROM、FUNC）、バンク番号、PSRAM オフセットを表示。block 指定時はその 512 バイトブロックのみ表示。
memptr [addr] 指定アドレスの PSRAM memPtr/memioPtr テーブルを表示。ハンドラー関数ポインターと属性を表示。
iomap [port] I/O ポートハンドラーテーブルを表示。各エントリにポートアドレス、ハンドラー関数、方向（読み取り/書き込み/両方）を表示。port 指定時はそのポートのみ表示。
status — システムステータス概要：RP2350 CPU 周波数、PSRAM SPI クロック、ホスト Z80 クロック、エミュレーション速度比、空き SRAM、稼働時間。
ver — ファームウェアバージョン、ビルド日、Flash パーティションレイアウト（アドレス、サイズ、チェックサム、アクティブフラグ）、著者、ライセンスを表示。
drivers — アクティブなマシンペルソナドライバーとサブインターフェースの一覧。初期化状態を表示。
hold — Z80 CPU エミュレーションを一時停止。Core 1 は現在の命令を完了してフェッチを停止。ホールドが確認されるまでシェルは待機。out などの実行状態を変更するコマンドの前に必要。
release — ホールドされた地点から Z80 CPU エミュレーションを再開。ブレークポイントはアクティブなまま。
go — 実行を続行（release と同じ）。ブレークポイントにヒットすると CPU は再び自動的にホールド。
cont — go のエイリアス。現在のホールドポイントから実行を続行。ブレークポイントはアクティブなまま。
step [n] 1 命令（または n 命令）をシングルステップ実行。各ステップで実行前のレジスター状態、16 進バイト付きディスアセンブル命令、実行後のレジスター状態を表示。先に CPU をホールドする必要あり。マルチステップ中にブレークポイントにヒットすると早期に停止。
bp <addr> 指定 Z80 アドレスにブレークポイントを設定。最大 8 個同時にアクティブ可能。オペコードフェッチ中に PC がブレークポイントアドレスに一致すると、CPU は自動的にホールドされヒットが報告される。重複アドレスは拒否。
bc <n|*> ブレークポイントスロット n（0〜7）をクリア、または全ブレークポイントをクリア（*）。
bl — アクティブなブレークポイントの一覧（スロット番号とアドレスを表示）。
wm [p|v] <addr> <byte> [byte]... メモリにバイトを書き込み。p = 物理 Z80 バス、v = 仮想 PSRAM、省略時は自動（メモリマップに従う）。複数バイトはスペース区切りで指定。物理/マップ書き込み時は CPU を自動ホールド。
fill [p|v] <addr> <len> [w|d] <val> メモリを定数値で充填。p = 物理、v = 仮想、省略時は自動。デフォルトは 8 ビット、w = 16 ビット、d = 32 ビット（リトルエンディアン）。必要に応じて CPU を自動ホールド。
in <port> Z80 I/O ポートを読み取り。実際の IORQ+RD バスサイクルを駆動し、読み取ったバイトを表示。
out <port> <byte> Z80 I/O ポートにバイトを書き込み。先に CPU をホールドする必要あり。実際の IORQ+WR バスサイクルを駆動。
trace <on|off|dump [n]|clear|rt|byte> 実行トレースの制御。on で全実行命令を 512 エントリのリングバッファに記録（PC、オペコード、フラグ）。off で記録を無効化。dump で最後の n エントリをディスアセンブリとデコードフラグ付きで表示（デフォルト：全件）。clear でバッファをリセット。rt でリアルタイムトレース出力。byte でバイトレベルトレース。
set <reg|flags|memmap|memptr|iomap> Z80 レジスター、フラグ、メモリマップ、PSRAM memPtr、I/O マップエントリを実行時に変更。設定をリロードせずにメモリ/IO 構成をホットパッチ可能。
hist [n] コマンド履歴を表示。最後の n エントリを表示（デフォルト：全件）。履歴は ESP32 NVS に保存されセッション間で保持。
savehst — コマンド履歴を ESP32 NVS に即座に強制保存。
fdctrace <on|off|dump> FDC I/O トレースログの有効/無効切替。dump でリングバッファから最後の 64 回の操作をダンプ。WD1773 レジスターへの全アクセスを 64 エントリのリングバッファに記録。パラメータなしで現在の状態を表示。
qdtrace <on|off|dump> Quick Disk I/O トレースログの有効/無効切替。dump でリングバッファから最後の 64 回の操作をダンプ。パラメータなしで現在の状態を表示。
piodbg [clear] 全 3 PIO ブロック（PIO 0、PIO 1、PIO 2）の RP2350 PIO ハードウェア診断を表示。FDEBUG スティッキーエラーフラグ、FSTAT、FIFO レベル、ステートマシンごとのプログラムカウンター、GPIO 出力イネーブル状態、GPIO ピンレベルを表示。clear で FDEBUG スティッキーフラグをリセット。
load <p|v> <file> <addr> [len] [ofs] ESP32 SD カードからファイルを Z80 メモリにロード。p = 物理バス書き込み、v = 仮想 PSRAM バンク 0。file は ESP32 上の /sdcard/ 相対パス。addr は Z80 開始アドレス、len はバイト数（最大 1MB、省略時はファイル全体）、ofs はファイルオフセット（オプション）。物理書き込み時は CPU を自動ホールド。PSRAM バンク 63 をスクラッチバッファとして使用。
dir [path] ESP32 SD カード上のファイルを一覧表示。オプションのパスは /sdcard/ からの相対パス。
save <p|pf|v> <file> <addr> <len> Z80 メモリを ESP32 SD カード上のファイルに保存。p = 物理バス読み取り、pf = 物理フェッチ（M1）、v = 仮想 PSRAM バンク 0。file は /sdcard/ 相対パス。addr は Z80 開始アドレス、len は保存バイト数（最大 64KB）。物理読み取り時は CPU を自動ホールド。物理読み取り中は定期的に DRAM リフレッシュを実行。
cmp [f] <phys> <virt> <len> 物理バスメモリと仮想 PSRAM を比較。f でフェッチ（M1）サイクルを使用。不一致をアドレスと値で報告。
copy <pv|fp|vp> <src> <len> <dst> 物理メモリと仮想メモリ間でコピー。pv = 物理読み取り→仮想、fp = 物理フェッチ→仮想、vp = 仮想→物理書き込み。CPU を自動ホールド。
memtest <addr> <len> [pattern] 物理メモリを 3 パスでテスト：書き込み＋読み取り、書き込み＋フェッチ、インターリーブ。デフォルトパターン：昇順バイト。パスごとにエラーを報告。
verify <on|off> 全オペコードフェッチ検証の切り替え。オン時は全フェッチを readPhysicalMem で検証（速度約 50% 低下）。オフ（デフォルト）時は 0x00/0xFF オペコードのみチェック。
fwait <0-4> M1（オペコードフェッチ）サイクルに追加ウェイトステートを強制。0 = オフ（デフォルト）。タイミング依存のコードのデバッグに有用。パラメータなしで現在の設定を表示。
iowait <0-8> I/O 読み書きサイクルに追加ウェイトステートを強制。0 = オフ（デフォルト）。応答の遅いペリフェラルの診断用。パラメータなしで現在の設定を表示。
corrupt [clear] 検出されたフェッチ破損を表示（PC、フェッチされたオペコード、検証されたオペコード）。clear でログをリセット。
echo [on|off] 文字エコーの切り替えまたは設定。オン（デフォルト）では入力文字がターミナルにエコーバック。
reset — Z80 CPU の即座の強制リセット。エミュレーションはリセットベクター（通常 0x0000）から再開。
一般的なデバッグワークフロー：
  1. 2 番目の USB シリアルポートにターミナルを接続（115200、8N1）。
  2. hold — CPU を一時停止。
  3. regs — 現在のレジスター状態を検査。
  4. dis v — 現在の PC でコードをディスアセンブル。
  5. bp E800 — ブレークポイントを設定。
  6. go — 実行を再開。0xE800 に到達すると CPU が停止。
  7. step 5 — ブレークポイントから 5 命令をシングルステップ。
  8. dm v D000 80 — VRAM の内容を検査。
  9. trace on / go / trace dump 50 — 実行履歴をトレースしてレビュー。

トラブルシューティング

ホストコンピューターが起動しない

  • 向きを確認する — picoZ80 のピン 1 がソケットのピン 1 と一致していることを確認してください。ボードを逆に挿入すると picoZ80 とホストコンピューターの両方が損傷します。
  • 装着を確認する — picoZ80 を取り外して再挿入し、40 本すべてのピンが完全に装着されてボードの下に折れ曲がっていないことを確認してください。
  • SD カードを確認する — config.json がないか壊れている場合、ファームウェアは以前にキャッシュされたフラッシュ設定を使用しようとします。有効な設定が存在しない場合、RP2350 はメモリマップを初期化せず、ホストはオープンバスを認識します。
  • ファームウェアがフラッシュされていることを確認する — picoZ80 を USB で接続し（ホストに挿入せずに）、ボードが PC で列挙されることを確認してください。
  • ホストの電源供給を確認する — picoZ80 は 5V レールから最大 400mA を消費する可能性があります。一部のビンテージコンピューターは電源供給が不安定です。マルチメーターで負荷下の 5V レール電圧を確認してください。

ウェブインターフェースに接続できない

  • WiFi モードを確認する — 初回起動またはファクトリーリセット後、ESP32 は AP モードで起動します。最初に picoZ80 WiFi ネットワークに接続し、http://192.168.4.1 に移動してください。
  • 設定された IP アドレスを確認する — 固定 IP でクライアントモードが設定されている場合、IP がネットワークサブネットと一致していることを確認してください。
  • SD カードが存在することを確認する — SD カードの webfs/ にあるウェブアセットが必要です。SD カードがないとウェブサーバーはページを提供できません。
  • webfs ディレクトリを確認する — SD カードに webfs/ ディレクトリが存在し、プロジェクトリポジトリの HTML/CSS/JS ファイルが含まれていることを確認してください。
  • WiFi のファクトリーリセット — 資格情報が失われた場合は、ESP32 ファームウェアを再フラッシュして NVS 設定をクリアし、新しく始めてください。

SD カードが認識されない

  • SD カードが FAT32 でフォーマットされていることを確認してください。NTFS、exFAT、FAT16 はサポートされていません。
  • 別の SD カードを試してください — 一部の大容量または高速カードは ESP32 SPI SD インターフェースとの互換性に問題がある場合があります。
  • 32GB までのカードは十分にサポートされています。非常に大きなカード（32GB 超）は特別なフォーマットが必要な場合があります。
  • SD カードを再装着してください — 取り外して再挿入してよい接触を確保してください。

ROM イメージが読み込まれない

  • config.json のファイルパスが SD カード上のファイルの場所と完全に一致していることを確認してください（パスは大文字小文字を区別します）。
  • ROM イメージファイルが SD カードに存在することを確認してください — ファイルマネージャーを使用して期待される場所を参照してください。
  • fileofs 値を確認してください — 不正なオフセットはゴミデータを ROM バンクに読み込みます。
  • メモリマップエントリの size フィールドが ROM イメージファイルより大きくないことを確認してください。サイズが大きすぎるマッピングは未定義データでパディングされます。

ボードが予期せずリセットまたはリブートする

  • picoZ80 にはハードウェアウォッチドッグタイマーがあり、起動中または通常動作中にファームウェアがハングした場合に自動的に RP2350 をリセットします。ボードが繰り返しリブートする場合、起動ステージが時間内に完了しないためウォッチドッグがトリガーされています。
  • SD カードを確認する — config.json が存在しないか破損している場合、設定解析中に起動シーケンスが停止する可能性があります。
  • WiFi 設定を確認する — ESP32 が接続を確立できない場合、RP2350 と ESP32 間の SPI ハンドシェイクがタイムアウトし、ウォッチドッグがトリガーされる可能性があります。
  • SWD デバッグを使用する — デバッグプローブを接続し、ウォッチドッグスクラッチレジスタ（watchdog_hw->scratch[5] 〜 scratch[7]）を検査します。scratch[6] の起動進捗コードはウォッチドッグが発火する前にファームウェアがどのステージに達したかを示し、scratch[0–3] は最後の 4 回のリセット試行の履歴を保持します。
  • 永続ログを確認する — ファームウェアは plogf() を使用して PSRAM の最後の 4KB に起動クリティカルなメッセージを書き込みます。これらのメッセージはウォッチドッグリセット後も残り、次の正常起動時にデバッグコンソールにダンプされ、リセット前に何が起こったかを明らかにします。

OTA アップデートが失敗する

  • RP2350 OTA アップデートには .bin ファイル（.uf2 ではなく）をアップロードしていることを確認してください。
  • 動作しているファームウェアを保存するために、非アクティブスロットにアップロードしていることを確認してください。
  • OTA アップデートが失敗するか起動しないパーティションになった場合、ブートローダーは以前のアクティブスロットを動作させ続けます — アップロードプロセスを繰り返してください。
  • ESP32 OTA の失敗については、デバッグヘッダーの USB 接続を使用して esptool 経由で再フラッシュしてください。

参考サイト

リソース リンク
picoZ80 プロジェクトページ /picoz80/
picoZ80 テクニカルガイド /picoz80-technicalguide/
pico6502 プロジェクトページ /pico6502/
RP2350 データシート datasheets.raspberrypi.com
Pico SDK ドキュメント raspberrypi.github.io/pico-sdk-doxygen
ESP32-S3 技術リファレンス docs.espressif.com
X（Twitter）プロジェクトプレビュー engineerswork1

FCC / RED 無線規制に関する注意事項

本デバイスは 2.4 GHz ISM バンドで送信する ESP32-S3-PICO-1 無線モジュールを搭載しており、WiFi ファームウェアがインストールされている場合、世界各国の無線周波数規制（米国の FCC Part 15 Subpart C、欧州連合の無線機器指令 2014/53/EU を含む）において意図的放射器に該当します。
出荷時の構成
picoZ80 ボードは FCC（米国）または RED（EU）の意図的放射器認証を取得していません。出荷時には、WiFi アンテナ整合部品が未実装で、ESP32 ファームウェアは NCM Only 構成（sdkconfig.mode_ncm_only）でビルドされています。この構成では WiFi 無線は完全に無効化され、ESP32-S3 アンテナ整合回路の部品は PCB 上に実装されていません。高周波エネルギーの放射が発生しないため、デバイスは意図的放射器に該当せず、FCC、CE/RED、または同等の認証は不要です。規制上の認可なしに販売、配布、または贈与が可能です。
WiFi の追加
エンドユーザーはアンテナ整合回路を実装し、WiFi 対応ファームウェア（sdkconfig.mode_wifi_only または sdkconfig.mode_wifi_and_ncm）をフラッシュすることで、個人使用、実験、または教育目的で WiFi を使用できます。WiFi を有効にすると、デバイスは意図的放射器となり、以下のルールが適用されます：
ESP32-S3-PICO-1 モジュール自体は既存の規制認証（FCC、CE など）を取得していますが、そのモジュールレベルの認証は、モジュールを組み込んだ完成品に自動的に適用されるものではありません。事前認証モジュールの免除規定は、個人の趣味愛好家が個人使用、実験、または教育目的で少数のデバイスを製作する場合に、個別の機器認可を取得せずに行うことを許可するものです。
重要な制限事項
  • WiFi ファームウェアを搭載したデバイスは、完成品が独自にテストされ、該当する管轄区域で機器認可（例：FCC ID、認定機関による CE マーキング評価）を取得しない限り、第三者への販売、販売の申し出、贈与、またはその他の方法での配布を行ってはなりません。
  • 個人使用のために WiFi を有効にして少数を製作することは、趣味愛好家および実験使用の規定（例：FCC § 15.23）に基づき、デバイスが有害な干渉を引き起こさない限り、一般的に許可されています。
  • WiFi を有効にした商業販売には、完全な製品レベルの FCC/RED（または同等の）認証が必要です。
  • 規制要件は国によって異なります。米国外の製作者は、適用される規則について自国の無線周波数当局に確認してください。
製作者の責任
本設計に基づいて製作されたデバイスが、管轄区域内の適用されるすべての無線周波数規制に準拠することは、製作者の単独の責任です。著者は本設計を個人使用、教育、および趣味愛好家向けに提供しており、本設計から製作されたデバイスが商業的配布の規制要件を満たすことについて、いかなる表明も行いません。