SharpKey Multi-HID Interface ファームウェアガイド

概要

resourcefulな日本のユーザー（classicpc.org、またはYoukan）と8bity.czのMartinは、一般的なPS/2またはUSB PCキーボードを変換してキーボードなしのSharpマシンで動作するインターフェースを開発しました。X1とX68000については概して完璧に動作し、プロフェッショナルな小型ケースに収められています。しかしMZ-2500のインターフェースにはいくつかの問題があります。特に利用可能な設計はST開発ボードに基づいており、ファームウェアはクローズドソースです。秋葉原での販売用にプロフェッショナルなアダプタとして作られましたが、現在は入手できないようです。私の場合、Webで入手できるMZ-2500インターフェースの開発バージョン（少なくとも私が組み立てたバージョン）は気まぐれで、MZ-2800では動作しません（一部の日本のコンタクトで確認）。改修中のMZ-2500/MZ-2800マシン（すべてキーボードなし）を完成させるために信頼性の高い動作ユニットが必要なため、他の選択肢を検討する必要がありました。
現在2台のMZ-2500マシンを改修中で、1台を保持予定です。またMZ-2800も改修中です。YoukanのDevelopmentボードベースのインターフェースの限界を考慮して、8bity.czのMartinが使用したKM24の小型ケースデバイスという物理的な形式を使用して独自の設計を行うことにしました。最初は、Sato Kyouchiの非常に信頼性の高いX1インターフェースに使用されているRenesas R8Cプロセッサを検討し、サポートハードウェアを追加して2 in 1デバイス（PS/2 → X1/MZ-2500/2800）を作成することを望んでいました。R8Cは素晴らしい小型MCUで作業とプログラムが容易ですが、この要件ではパフォーマンスの問題がありました。20MHzでも割り込みへの応答に1uSかかります。これはほとんどのアプリケーション（PS/2やX1キーボードプロトコルを含む）には問題ありませんが、MZ-2500には遅すぎました。

MZ-2500 キーボードプロトコル

ハードウェアインターフェースは、シールドされた8ピンミニDINソケットとプラグを使用した7つの信号、5VとGNDで構成されています。

動作モードは主に2つあります。キー押下を待機している間に使用するすべて（STROBEALL）のキーテストモードと、押されたキーの位置を特定するためにすべての行を手動スキャンするモードです。

キーデータ取得のプロトコルは以下の通りです：

1. RTSNがアクティブHIGHになり1.08usアクティブ状態を維持します。STROBEALLでキーを検出した後の最初のRTSN期間は1.08usアクティブHIGH、660nsインアクティブLOWです。その後は均一に660nsアクティブHIGH、680nsインアクティブLOWです。
2. メインボードはキーボードにスキャン行を送信し、RTSNの立ち上がりエッジから160ns後に有効になります。
3. スキャン行はKD[3:0]から残りの920nsでキーボードによって読み取られます。KD4の状態（または状態変化）はRTSNの立ち上がりエッジに先行します。
4. KD4がサンプリングされ、LOWの場合は列ごとのすべてのキーの論理ANDが設定され、HIGHの場合は選択された行の実際の列が設定されます。
5. RTSNの立ち下がりエッジで、MPXは320nsHIGHになり、MPXの立ち上がりエッジから20ns後にKD[3:0]上に上位ニブルが出力されます。データはMPXがLOWになるまでの残り300ns以内に読み取られます。MPXがLOWになると下位ニブルが同じ320nsタイミングで出力されます。320ns後にRTSNが再び立ち上がります。
6. 上記はキーが押されている間繰り返されます。
7. キーが押されていない場合はSTROBEALLモードに切り替えます。

STROBEALLモードのプロトコルは以下の通りです：

1. STROBEALLモード中、KD4はLOWに保持されており、18.996msから198.83msの間で変化する20nsのグリッチを除いて状態は変化しません。このグリッチはハードウェアの見落としのように見えます。
2. STROBEALLモード中、RTSNは均一な期間（660nsアクティブHIGH、660nsアクティブLOW）を持ちます。行は無視されます（意味のない定数値4を繰り返し続けます）。
3. KD4がサンプリングされます。
4. RTSNの立ち下がりエッジで、MPXは320nsHIGHになり、上位ニブルが出力されます。MPXがLOWになると下位ニブルが出力されます。320ns後にRTSNが再び立ち上がります。
5. キーが押されている場合はキーデータ取得モードに切り替え、そうでなければ上記をループで繰り返します。

信号は以下のロジックアナライザ図で可視化できます：

非アクティブ中、メインボードのゲートアレイはSTROBEALLコマンドを送信します。これはKD4がLOWであることで認識されます。

STROBEALLでキーが押されたことが検出されると、KD4がHIGHになり、メインボードがキーを特定し始めます。Row 11から始まります（特殊キーCTRL、SHIFT、LOCK、KANA、GRAPHを含む）。

Row 11のスキャンはスイッチバウンスに対応するためだと思われる約30usの間行われます。

Row 11の調査後、Row 12（日本語変換キーを含む）に切り替わります。Row 12は約50usの間スキャンされます。

Row 11と12の調査後、Row 0から順次スキャンが開始されます。

順次スキャンは押されたキー（この場合はRow 4 Column 3の’C’）を見つけるまで続きます。キーバウンスを判定するために同じ行が600us以上スキャンされます。

MZ-2500が使用するハードウェアは以下の2つの回路で確認できます。

この回路図はキーボード回路を表しており、ゲートアレイと双方向バッファで構成されています。

この回路図はメインユニット回路を表しており、Z-80B PIOに接続されたゲートアレイで構成されています。ゲートアレイはRow番号（0〜13）を送出し、キーボードから2ニブルで8ビットのデータブロックを受け取ります。

MZ-2800 キーボードプロトコル

MZ-2800はMZ-2500の後継機であり、8ビットZ80ベースのMZ-2500モードと16ビット80286モードが組み込まれています。MZ-2500と同様に、キーボードハードウェアインターフェースは7つの信号、5VとGNDで構成されていますが、旧式のAMP 9ピンUSBスタイルコネクタを使用しています。

MZ-2800マザーボードには標準的な9ピンヘッダがあり、AMP ソケットが取り付けられた娘基板に接続されています。ヴィンテージ機器を改造することを避けたいため代替品を探し（現在開発中で証明後にここに掲載します）、AMPコネクタと同じサイズのD-Subを使用した解決策を見つけました。これにより、オリジナルのMZ-2800キーボードを入手できた場合でも素早くAMPコネクタに戻せます。

信号の概要は以下のテーブルに示します。物理的にはMZ-2500と同一です。

MZ-2800のプロトコルはMZ-2500と同じ物理的な信号を共有しますが、主にタイミングが異なります。

STROBEALLとキーデータ取得の両モードの主要プロトコルは以下の通りです：

1. RTSNがアクティブHIGHになり、メインボードがキーボードにスキャン行を送信します。
2. KD4をサンプリングする前にRTSNがアクティブになってから少なくとも200ns待ちます。
3. ROWを読み取る前に少なくとも650ns待ちます。
4. スキャン行がKD[3:0]から読み取られます。
5. KD4がサンプリングされます。
6. RTSNがインアクティブLOWになるのを待ちます。
7. MPX = HIGHの場合、上位ニブルが出力されます。MPX = LOWの場合、下位ニブルが出力されます。MPXはMZ-2500と同じ期間（640ns、320nsアクティブHIGH、320nsLOW）を持ちます。
8. 上記が繰り返されます。

STROBEALLモード。メインボードはKD4をLOWに保持してキー押下を待機しています。

キーが押されると、KD4がHIGHになり、メインボードは列データを取得するために有効な行番号の送信を開始します。

RTSNがアクティブになってから行データが利用可能になるまでのタイミング遅延。

上の画像で順次スキャンが確認できます。

スキャンが押されたキー（’C’ - Row 4 Column 3）の行に達すると、デバウンスのために同じ行が100usの間読み取られます。

キーが押し続けられると、スキャンが2回目に押されたキーに到達すると300us以上スキャンします（上記の例ではキー’A’が押されています）。

キーが押されてから離される瞬間までの完全なサイクル。

MZ-2800キーボードとMZ-2500キーボードの違いの一つは14番目の行の追加です。MZ-2500モードのMZ-2800ではRow 14はスキャンされず、MZ-2800モードの場合にのみスキャンされます。

MZ-2800が使用するハードウェアは以下の2つの回路で確認できます。

この回路図はキーボード回路を表しており、ゲートアレイと双方向バッファで構成されています。

この回路図はメインユニット回路を表しており、Z-80B PIOに接続されたゲートアレイで構成されています。Row番号（MZ-2500モードでは0〜13、MZ-2800モードでは0〜14）を送出し、2ニブルで8ビットのデータを受け取ります。

ESP-32S AI Thinker

回路図

PCB

設計した回路のプロトタイプを作成してその制御ソフトウェアの大部分を書いた後、PCBの設計に取り掛かりました。KM24ケースに収まるように小型でなければならず、コンポーネントの数とサイズを考えると、PCBの両面を使用する必要がありました。

製造に出た完成した回路基板。

組み立て済みインターフェース

以下の写真は完成した、組み立て済みで動作するインターフェースを示しています。

インターフェースの上側。2mmピンヘッダなどのオプションコンポーネントがインストールされています。8ピンプログラミングインターフェースは必要ですが、9ピンMZ2500インターフェースヘッダはケーブルを基板に直接はんだ付けできます。通常の使用では必要ありません（DTR/RTS なしのUARTを使用する場合を除く）。

インターフェースの裏側。ESP32がほとんどのスペースを占めています。

KM-24ケース内への設置。タイトな収まりです。

ピンヘッダを使用することで、あらかじめ作られた8ピンミニDINケーブルを切り離せます（例えばMZ-2800ケーブルへの変更や、X1などの別のマシン用のファームウェア開発のため）。X1はGND、5V、1本の双方向ピンのみが必要なのでうまく機能します。

プログラミングハーネス。汎用のUSBからTTL UARTアダプタ、現在のキーマトリクスを出力するためのオプションのOLEDディスプレイ、インターフェースに接続するための2mmヘッダで構成されています。

完成品。MZ-2500で使用する準備が整いました。MZ-2800についてはインターフェースは動作しますが、奇妙なAMP 9ピンソケットはもはや入手できないため、非破壊的な解決策（例えばMZ-2800のソケットを8ピンミニDINに変更するなど）を考える必要があります。

開発中のMZ-2500に接続されたインターフェース。OLEDスクリーンは仮想キーマトリクスを表示するために使用されています。

MZ-2500に接続された完成したインターフェース。

組み立て済みMZ-2800インターフェース

先に示したようにMZ-2800はMZ-2500と同じハードウェアインターフェースを持つようですが、プロトコルとそのタイミングが異なります。MZ-2800はまた異なるキーボードプラグとソケットを使用しています。MZ-2500で選択された8ピンミニDINの代わりに、Sharpはより頑丈にするためにチャンキーなAMP 9ピンD-Subプラグとソケットを選択しました。残念ながら9ピン AMP D-SubはDodoの運命をたどり、少なくともすべての主要なベンダーやebayからはもはや入手できません。代替品の調達が必要でした。改造は選択肢ではありませんでした。

MZ-2800は9ピンAMPソケットを使用していますがもはや入手できないため、代替品を見つける必要がありました。JST XH2.50mm 9ウェイでメインボードの9ピンヘッダ（CN1）を交換することが解決策でした。これはAMPのコネクタのスペードターミナルがJSTの角型ピンターミナルに合うため、元のAMPソケットとも引き続き機能します。

様々なパーツカタログを調べると、3Mが製造する互換ソケットとプラグが見つかりました（10120-6000Lプラグと10220-5212PLソケット）。これらはMZ-2800のケーシングに取り付けるために正確なサイズの20ピンデバイスです。ソケットはJH 9ピンヘッダソケットに配線され、アセンブリがオリジナルと交換できるようになりました。

ソケットはケースに完璧に収まります。新しいソケットがネジ付きであったため、2つのネジでケースの壁に固定するだけの簡単な作業でした。

ケース外部のソケット。インターフェースとプラグを作成するだけです。

MZ25KEYインターフェース、短いリボンケーブル、IDCプラグを使用して、MZ-2800インターフェースが最終的に組み立てられました。インターフェースにロードされたファームウェアはMZ-2800固有のものです。

インターフェースの裏側。

蛇の頭を持つ一つ目のマウス？

テスト中。PS/2キーボードをインターフェースに接続し、インターフェースをMZ-2800に接続します。

完成！

ファームウェア

ファームウェアはgcc(++)、git、CMake、NinjaからなるEspressif IDBビルドシステムで書かれています。ビルドシステムはWindows、Linux、macOSで動作しますが、この場合はLinuxを使用しました。PS/2ライブラリはもともとArduino用に書かれていたため、Arduino互換コンポーネントがインストールされています。ファームウェアはCとC++の混合で書かれており、C++が主要な言語です。

ファームウェアのインストール

gitクローンを使用してソフトウェアリポジトリをコンピュータに取得します。

git clone https://git.eaw.app/eaw/mz25key.git

ビルドシステムのインストール

Espressif IDBビルドシステムを作成するには、Espressifのガイドに従ってください：

1. python v3.7以降がインストールされていることを確認してください。インストールしたら「update-alternatives」を使用して最新バージョンをプライマリインタープリタとして選択します（一部のLinuxインストールでは古い汎用バージョンのPython 2.7がデフォルトになっています）。
2. このガイドを使用してEspressifリポジトリをインストールします。「git clone」に「-b v4.4」フラグを使用してv4.4をインストールするか、クローン後に「git checkout」を使用してください。Arduino互換モジュールサポートにはv4.4が必要です。
3. このガイドを使用してEspressif Arduino互換モジュールサポートをインストールします。

ファームウェアのコンパイル

gitからリポジトリを取得してEspressif IDBをインストールした後、プロジェクトを設定する必要があります。KConfigファイル「sdkconfig」はファームウェアに含まれていますが、一部のオプションを変更したい場合があります。これは次のコマンドで実行できます：

idf.py menuconfig

これにより、以下に示す一連のメニューが表示されます。

ルート画面ではEspressif IDBインストール、コンパイラ、ESP32、FreeRTOSの設定など様々な側面を設定できます。多くの設定を変更できますが、インターフェースについては「MZ25Key設定」オプションを選択してください。

PS/2キーボードインターフェース、MZ-2500/2800インターフェース、WiFi、デバッグオプションを設定できます。

PS/2設定では、インターフェースに使用するGPIOピンを設定できます。独自のボードを構築して異なるGPIOを使用した場合を除いて、変更する必要はありません。

PS/2メニューで選択するもう一つのオプションはキーボードマッピングのタイプです。現在のところWyse KB-3926キーボード用のマッピングのみがあります。

MZ-2500/2800インターフェースメニューでは、ターゲットマシン（MZ-2500またはMZ-2800）を選択し、ストローブ入力、スキャンデータ出力、RTSN/KDI4入力に使用するGPIOを設定できます。

WiFiメニュー（現在進行中）では、Wifiモジュールを有効にしてさまざまなデフォルトパラメータを設定できます。

デバッグメニューではさまざまなデバッグ補助を有効にできます。接続されている場合OLEDスクリーンはリアルタイムデータを出力するのに役立ちます。テスト用にインターフェースのさまざまなコンポーネントを無効にすることもできます。ESP32はデフォルトでシリアルポートからテキストメッセージを出力するため、USB to TTL UARTアダプタがプログラミングコネクタに接続されている場合、これらのメッセージを確認できます。

OLEDタイプを設定する必要があります。ハードウェアはI2Cインターフェースに対応し、解像度は128x64ピクセルです。

設定が完了したら、次のコマンドでテストビルドを実行します：

idf.py build

すべてが成功したら、USB to TTL UARTアダプタをコンピュータに接続して、mz25keyインターフェースのプログラミングコネクタに接続します。配線は以下の通りです：

/devでttyUSB*デバイスを探してUSB to TTL UARTアダプタのdevポートを取得します。通常は/dev/ttyUSB0です。次のコマンドでフルビルド、フラッシュ、モニタリングを実行します：

idf.py -p /dev/ttyUSB0 build flash monitor

システムはファームウェアをコンパイルし、mz25keyインターフェースにフラッシュして、出力されるメッセージを確認できるようにUARTモニタを実行します。例：

使用方法

キーボードはキーボードですよね？正確にはそうではありません。特に1つのキーボードが別のキーボードのふりをしている場合は！

PS/2キーボードはMZ-2500/MZ-2800の出現から数年後にIBM PCまたは互換機のために作られました。また私がアクセスできるキーボードは日本語PS/2ユニットではないため、いくつかの日本語固有のキーが欠けています。これにはマッピングが必要です。PS/2キーボードの未使用のキーを選択して、MZ-2500/MZ-2800キーボードの日本語キーのふりをさせます。

MZ-2500/MZ-2800マシンはオフィスクリーム色であるため、過去にWyseキーボードを使用した経験からWyse KB-3926クリームモデルをMZに最も合わせるために選択しました。MZ-2500、MZ-2800、Wyse KB-3926キーボードは以下に示されており、PS/2キーをMZ-2500キーにマッピングするマッピングテーブルも以下に示されています。

オリジナルのSharp MZ-2500キーボード。

オリジナルのSharp MZ-2800キーボード。

Wyse KB-3926 PS/2キーボード。

マッピングテーブル

* = MZ-2800では日本語で表記。

その他のキーはPS/2キーボードの記号通りです。Num Lockキーはテンキーを数値とカーソル機能の間で切り替えます。

MZ-2500はMZ-2000とMZ-80Bをエミュレートでき、各マシンにはわずかに異なるマッピングがあります。MZ-2500キーボードがどのようにこれを処理したかは不明ですが、メインユニットのゲートアレイがモデルモードスイッチに応じてその場でマッピングを実行していると推測しています。これに対応するために、マッピングテーブルのコンポーネントとしてマシンモデルを追加しました。通常、キーはすべてのモデルに割り当てられますが、差異が発生した場合はそのモデルに応じてタグ付けされます。この機能を呼び出すには、使用したいマッピングのマシンに応じたキーの組み合わせを押す必要があります：

電源投入時のデフォルトマッピングはMZ-2500に設定されています。

PS/2キーボードはMZ-2500/MZ-2800の電源が入った状態でインターフェースに接続/切断でき、インターフェースもMZ-2500/MZ-2800から切断できます。AMS1117-3.3のリザーバコンデンサは、キーボードが接続されたときの急激な電圧降下に対応するために必要以上に大きくなっています。ソフトウェアは毎秒キーボードの存在を確認し、取り外された場合はキーボードが再接続されることを見越して再初期化と確認を実行します。

Dockerによるビルド

# Install Docker if not already present
sudo apt update && sudo apt install -y docker.io
sudo systemctl enable docker && sudo systemctl start docker

# Clone the repository
git clone https://git.eaw.app/eaw/SharpKey.git
cd SharpKey
git submodule update --init --recursive

# Build the web filesystem
chmod +x build_webfs.sh && ./build_webfs.sh

# Build the firmware using the ESP-IDF v4.4 Docker container
docker run --rm -v $PWD:/project -w /project espressif/idf:v4.4 idf.py build

# Build output:
#   build/main.bin                         - Firmware binary (for OTA update)
#   build/filesys.bin                      - Web filesystem image (for OTA update)
#   build/bootloader/bootloader.bin        - Bootloader
#   build/partition_table/partition-table.bin - Partition table
#   build/ota_data_initial.bin             - OTA data partition

# Flash and monitor (requires USB device access)
docker run --rm --privileged \
    --volume /dev:/dev --volume /sys:/sys:ro --volume /dev/bus/usb:/dev/bus/usb \
    -v $PWD:/project -w /project \
    espressif/idf:v4.4 \
    idf.py -p /dev/ttyUSB0 build flash monitor

# Add to ~/.bashrc or ~/.zshrc
alias idf44='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:v4.4 idf.py "$@"'

# Then use:
idf44 build
idf44 menuconfig
idf44 -p /dev/ttyUSB0 flash monitor

継続的インテグレーション（Jenkins）

1. Giteaリポジトリのmasterブランチにコードをプッシュします。
2. Giteaがwebhook（HTTP通知）をJenkinsサーバーに送信します。
3. Jenkinsがリポジトリをクローンし、gitサブモジュールを初期化します。
4. JenkinsがWebファイルシステムをビルドします（build_webfs.shを実行）。
5. Jenkinsがファームウェアをビルドします（ESP-IDF Dockerコンテナを起動し、idf.py buildを実行）。
6. Jenkinsが3つのリリース成果物をパッケージ化します：
   • SharpKey-FW-v*.bin.gz — Webインターフェース経由のOTAアップデート用ファームウェアバイナリ
   • SharpKey-FilePack-v*.bin.gz — OTAアップデート用Webファイルシステムイメージ
   • SharpKey-FlashPack-v*.tar.gz — esptool経由の新規書き込み用完全フラッシュイメージ（ブートローダー + パーティションテーブル + ファームウェア + ファイルシステム）
7. JenkinsがGitea Releaseを作成し、成果物をダウンロード可能なアセットとして添付します。
8. Jenkinsがメールを送信し、成功または失敗を報告します。

# Pull the ESP-IDF Docker image on the build server
docker pull espressif/idf:v4.4

volumes:
  - /srv/jenkins/data:/var/jenkins_home
  - /var/run/docker.sock:/var/run/docker.sock    # Required for ESP-IDF sibling container

1. Checkout: リポジトリをクローンし、gitサブモジュール（arduino-esp32、esp_littlefs）を初期化します。
2. Determine Version: version.txtを読み取るか、最新のGiteaリリースタグから自動インクリメントします。
3. Build Web Filesystem: build_webfs.shを実行し、HTML、CSS、JavaScriptをWebファイルシステムにパッケージ化します。
4. Build Firmware: espressif/idf:v4.4 Dockerコンテナを起動し、idf.py buildを実行します。
5. Package Release: バージョン付きのファームウェア、ファイルシステム、フラッシュパックのtarballを作成します。
6. Create Gitea Release: Giteaにタグ付きリリースを作成し、すべての成果物をアップロードします。

• Target URL: http://your-server:8080/generic-webhook-trigger/invoke?token=sharpkey-build-trigger
• Content Type: application/json
• Trigger On: Push Events

WiFi

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