SharpKey マルチHIDインターフェース 開発者ガイド

概要

• Sharp MZ-2500 — SuperMZシリーズ
• Sharp MZ-2800 — 16ビットSuperMZ
• Sharp MZ-5500/5600/6500 — MZビジネスシリーズ
• Sharp X1 — X1シリーズパーソナルコンピュータ
• Sharp X68000 — 68000ベースパーソナルワークステーション
• NEC PC-9801 — NEC 98アーキテクチャ

---

前提条件

ソフトウェア前提条件

• ESP-IDF v4.4 — Espressif IoT Development Framework。ESP32ファミリーの公式開発フレームワークです。バージョン4.4が必要です。新しいバージョンではAPIに破壊的変更が導入される可能性があります。
• Python 3.8+ — IDFツールチェーンのビルドスクリプト、menuconfig、およびeFuseテーブルジェネレーターに必要です。
• Git — リポジトリのクローンおよびサブモジュール（arduino-esp32とesp_littlefs）の初期化に使用します。
• Docker — オプション。Espressif IDF Dockerイメージ（espressif/idf:v4.4）は事前設定されたビルド環境を提供し、CI/CDパイプラインや再現可能なビルドに便利です。
• LinuxまたはmacOS — 推奨ホストオペレーティングシステム。WindowsユーザーはIDFツールチェーンおよびシェルスクリプトとの完全な互換性のためにWSL2（Windows Subsystem for Linux 2）を使用してください。

ハードウェア前提条件

• SharpKey PCB — ESP-32S AI Thinkerモジュールを搭載した、SharpKeyプロジェクト用に設計されたカスタムPCB。
• PS/2キーボード — 有線キーボード入力テスト用。スキャンコードセット2を使用する標準的なPS/2キーボードに対応しています。
• Bluetooth HIDキーボード — オプション。ワイヤレスキーボードサポートのテスト用。BT Classic HIDおよびBLE HIDデバイスの両方に対応しています。
• USB-シリアルアダプター — ファームウェアの書き込みおよびシリアルモニターデバッグ用（Linuxでは通常/dev/ttyUSB0）。
• 対象ビンテージマシン — エンドツーエンドテスト用の対応ホストマシンのいずれか。

---

リポジトリ構成

SharpKey/
├── main/
│   ├── SharpKey.cpp              — Entry point, initialisation, FreeRTOS task creation
│   ├── MZ2528.cpp                — MZ-2500/2800 host interface (Core 1, timing-critical)
│   ├── MZ5665.cpp                — MZ-5500/5600/6500 host interface
│   ├── X1.cpp                    — Sharp X1 host interface
│   ├── X68K.cpp                  — Sharp X68000 host interface
│   ├── PC9801.cpp                — NEC PC-9801 host interface
│   ├── HID.cpp                   — HID device manager (multiplexes PS/2 and BT)
│   ├── BTHID.cpp                 — Bluetooth HID keyboard/mouse support
│   ├── BT.cpp                    — Low-level Bluetooth stack management
│   ├── WiFi.cpp                  — WiFi AP/Client, web server, OTA updates, REST API
│   ├── PS2KeyAdvanced.cpp        — PS/2 keyboard protocol (Scan Code Set 2)
│   ├── PS2Mouse.cpp              — PS/2 mouse protocol handler
│   ├── Mouse.cpp                 — Mouse protocol abstraction
│   ├── KeyInterface.cpp          — Virtual base class for host interfaces
│   ├── LED.cpp                   — Status LED control
│   ├── NVS.cpp                   — Non-Volatile Storage (config persistence)
│   ├── SWITCH.cpp                — Configuration switch (WiFi/BT mode)
│   ├── esp_efuse_custom_table.c  — Custom eFuse field definitions (generated)
│   ├── esp_efuse_custom_table.csv — eFuse field CSV source
│   ├── Kconfig.projbuild         — Menuconfig options (~310 lines)
│   ├── CMakeLists.txt            — Component registration
│   └── include/
│       ├── KeyInterface.h        — Base class definition
│       ├── MZ2528.h              — MZ key matrix mapping (165+ entries)
│       ├── MZ5665.h              — MZ-5600 series mappings
│       ├── X1.h                  — X1 key mappings
│       ├── X68K.h                — X68000 key mappings
│       ├── PC9801.h              — PC-9801 key mappings
│       ├── HID.h                 — HID manager header
│       ├── BTHID.h               — Bluetooth HID header
│       ├── BT.h                  — Bluetooth stack header
│       ├── PS2KeyAdvanced.h      — PS/2 keyboard header
│       ├── PS2KeyCode.h          — PS/2 key code definitions
│       ├── PS2KeyTable.h         — PS/2 key lookup tables
│       ├── WiFi.h                — WiFi and web server header
│       ├── LED.h                 — LED control header
│       ├── NVS.h                 — NVS storage header
│       ├── SWITCH.h              — Mode switch header
│       ├── Mouse.h               — Mouse abstraction header
│       ├── PS2Mouse.h            — PS/2 mouse header
│       └── esp_efuse_custom_table.h  (generated from CSV)
├── webserver/
│   ├── index.html                — Main web UI dashboard
│   ├── keymap.html               — Key mapping editor
│   ├── mouse.html                — Mouse settings page
│   ├── ota.html                  — OTA firmware upload page
│   ├── wifimanager.html          — WiFi configuration page
│   ├── version.txt               — Firmware version string
│   ├── css/                      — Bootstrap and custom stylesheets
│   ├── js/                       — jQuery, Bootstrap, keymap and OTA scripts
│   └── font-awesome/             — Icon fonts for web UI
├── components/
│   ├── arduino-esp32/            — Arduino compatibility layer (submodule, v2.0.3)
│   └── esp_littlefs/             — LittleFS filesystem driver (submodule, v1.3.1)
├── build_webfs.sh                — Web filesystem build script
├── sharpkey_partition_table.csv  — Flash partition layout
├── sdkconfig                     — Current build configuration
├── version.txt                   — Release version
└── CMakeLists.txt                — Top-level project CMake configuration

---

ソフトウェアアーキテクチャ

アーキテクチャ概要

• 入力レイヤー — PS/2キーボードおよびマウスプロトコル（PS2KeyAdvanced、PS2Mouse）とBluetooth HIDデバイス（BTHID、BT）を処理します。これらのコンポーネントはFreeRTOSスケジューラーおよびWiFi/BTスタックとともにCore 0で動作します。
• 処理レイヤー — HID抽象化レイヤー（HID.cpp）がPS/2およびBluetooth入力ソースを統合キーイベントストリームにマルチプレクスします。キーマッピングテーブルがHIDスキャンコードをホスト固有のマトリクスポジションに変換します。
• 出力レイヤー — ホスト固有のインターフェース実装（MZ2528、MZ5665、X1、X68K、PC9801）がマッピングされたキーイベントを各ビンテージマシンが期待する電気信号に変換します。これらはリアルタイム優先度でCore 1上で動作します。

┌─────────────────────────────────────────────────────────────────┐
│                        Input Layer (Core 0)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ PS2KeyAdvanced│  │  PS2Mouse    │  │  BTHID / BT          │  │
│  │ (Scan Code 2) │  │ (3-button)   │  │  (Classic + BLE)     │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬───────────┘  │
│         │                 │                      │              │
│  ┌──────┴─────────────────┴──────────────────────┴───────────┐  │
│  │                    HID.cpp (Multiplexer)                   │  │
│  └────────────────────────────┬──────────────────────────────┘  │
│                               │                                 │
├───────────────────────────────┼─────────────────────────────────┤
│                     Processing Layer                            │
│  ┌────────────────────────────┴──────────────────────────────┐  │
│  │              Key Mapping Tables (t_keyMap[])               │  │
│  │         PS/2 scan code → host matrix row/column            │  │
│  └────────────────────────────┬──────────────────────────────┘  │
│                               │                                 │
├───────────────────────────────┼─────────────────────────────────┤
│                       Output Layer (Core 1)                     │
│  ┌─────────┐ ┌─────────┐ ┌────┐ ┌──────┐ ┌────────┐          │
│  │ MZ2528  │ │ MZ5665  │ │ X1 │ │ X68K │ │ PC9801 │          │
│  └─────────┘ └─────────┘ └────┘ └──────┘ └────────┘          │
│         GPIO register writes → Host machine connector          │
└─────────────────────────────────────────────────────────────────┘

FreeRTOSタスクモデル

タスク	コア	優先度	スタック（バイト）	用途
mz25Interface	Core 1	25	4096	MZ-2500タイミングクリティカルGPIOループ（スピンロック保護）
mz28Interface	Core 1	MAX-1	2048	MZ-2800タイミングクリティカルGPIOループ
hidInterface	Core 0	0	4096	HID入力ポーリング（PS/2スキャン＋Bluetoothイベント）
WiFi/BTタスク	Core 0	各種	—	ESP-IDF管理システムタスク

KeyInterface基底クラス

KeyInterface (abstract base)
├── MZ2528     — Sharp MZ-2500 and MZ-2800
├── MZ5665     — Sharp MZ-5500, MZ-5600, MZ-6500
├── X1         — Sharp X1 series
├── X68K       — Sharp X68000
└── PC9801     — NEC PC-9801

• init() — GPIOピンの初期化、割り込みの設定、キーマトリクスのセットアップ、およびCore 1に固定されたFreeRTOSタスクの作成。ホスト検出後の起動時に一度だけ呼び出されます。
• mapKey(uint16_t scanCode, uint8_t keyState) — 受信したPS/2スキャンコード（修飾キーフラグ付き）をホストキーマトリクスにマッピング。このメソッドはt_keyMap[]テーブルでスキャンコードを検索し、keyMatrix[]配列の適切なビットをセットまたはクリアします。
• createKeyMapFile() — 再起動をまたいで永続化するため、現在のキーマッピングテーブルをNVSストレージにシリアライズ。Webインターフェースのキーマッピングエディターで使用されます。
• getKeyMapData() — Webインターフェース用にJSON構造として現在のキーマッピングデータを返します。
• suspend() — ホストインターフェースタスクを一時停止。WiFiとBluetoothモードの切り替え時やOTAアップデート中に使用されます。
• resume() — 一時停止されたホストインターフェースタスクを再開します。

ホスト検出

---

キーマッピングシステム

スキャンコードパイプライン

PS/2 Keyboard
    │
    ▼
PS2KeyAdvanced (Scan Code Set 2 → ASCII + modifier flags)
    │
    ▼
HID.cpp (multiplex with Bluetooth input)
    │
    ▼
KeyInterface::mapKey() (lookup in t_keyMap[] table)
    │
    ▼
keyMatrix[16] (set/clear matrix bits)
    │
    ▼
keyMatrixAsGPIO[16] (pre-shifted for GPIO registers)
    │
    ▼
GPIO.out_w1ts / GPIO.out_w1tc (atomic register writes to host)

マッピングテーブル構造

フィールド	型	説明
ps2KeyCode	uint8_t	PS2KeyAdvancedからのASCIIキーコード（スキャン結果の下位バイト）
ps2Ctrl	uint8_t	修飾キーフラグマスク（SHIFT、CTRL、ALT、CAPSなど）
keyboardModel	uint8_t	PS/2キーボードモデル識別子（0 = 全モデル）
machine	uint8_t	対象マシン（MZ_ALL、MZ_80B、MZ_2000、MZ_2500、MZ_2800）
MK_ROW1	uint8_t	Makeキー1：マトリクス行番号
MK_KEY1	uint8_t	Makeキー1：列ビットポジション
MK_ROW2	uint8_t	Makeキー2：マトリクス行番号（同時押しキー用）
MK_KEY2	uint8_t	Makeキー2：列ビットポジション
MK_ROW3	uint8_t	Makeキー3：マトリクス行番号（3キー同時押しコンボ用）
MK_KEY3	uint8_t	Makeキー3：列ビットポジション
BRK_ROW1	uint8_t	Breakキー1：リリースするマトリクス行
BRK_KEY1	uint8_t	Breakキー1：リリースする列ビット
BRK_ROW2	uint8_t	Breakキー2：リリースするマトリクス行
BRK_KEY2	uint8_t	Breakキー2：リリースする列ビット

行	キーグループ
0	F1, F2, F3, F4, F5, F6, F7, F8
1	F9, F10, KP_*, KP_+, KP_=, HELP, COPY, ARGO
2	CLR, HOME, INST, DEL, BS, 前行, ESC, SCROLL
3	BREAK, RIGHT, LEFT, DOWN, UP, RETURN, SPACE, TAB
4-7	アルファベットA-Z（4行に分散）
8-9	数字0-9、マイナス、キャレット、円記号、アットマーク
10	括弧、セミコロン、コロン、カンマ、ピリオド、スラッシュ、アンダースコア
11	CTRL, KANA, SHIFT（左）, LOCK, GRAPH, — , SHIFT（右）, —
12-13	テンキー0-9、KP_period、KP_comma、KP_minus、KP_enter
14-15	拡張ファンクションキー、追加特殊キー

対応キーボードモデル

モデルID	キーボード	備考
0	全機種/汎用	任意のPS/2キーボード用デフォルトマッピング
1	Wyse KB3926	Wyseターミナルキーボード、コンパクトレイアウト
2	OADG109	日本語109キーレイアウト（JIS）
3	Sanwa SKBL1	サンワサプライバックライトキーボード
4	Periboard 810	Perixxワイヤレス（PS/2アダプター付き）
5	Omoton K8508	コンパクトBluetoothキーボード
6	Dell KB212-B	標準Dell USBキーボード（PS/2アダプター付き）
7	Logitech K120	一般的なLogitech有線キーボード
8	Cherry G80	Cherryメカニカルキーボードシリーズ

ホストへのマトリクス出力

• keyMatrix[16] — 各要素がマトリクスの1行を表すuint8_t配列。各ビットが列に対応し、ビットセット＝キー押下、ビットクリア＝キーリリースです。
• keyMatrixAsGPIO[16] — 8列ビットがハードウェアが期待するGPIO出力ポジションにシフト済みの事前計算uint32_t配列。これにより、タイミングクリティカルな出力ループでのビットシフトが不要になります。

// Clear all column output bits
GPIO.out_w1tc = KDO_ALL_MASK;

// Set the bits for pressed keys in the selected row
GPIO.out_w1ts = keyMatrixAsGPIO[selectedRow];

---

新しいホストインターフェースの追加

電気的要件

Group	Signals	Default GPIOs	Direction	Description
KDO[7:0]	8 data lines	14, 15, 16, 17, 18, 19, 21, 22	Output	プライマリデータバス。既存のホストではESP32が駆動するキーマトリクスの列データを伝送します。アクティブローの規則：’1’ = キーリリース、’0’ = キー押下。サブマイクロ秒のアトミック書き込みのためにGPIO.out_w1ts / GPIO.out_w1tcに直接マッピングされます。
KDB[3:0]	4 address lines	23, 25, 26, 27	Input (default) / Output	既存ホストでの行選択入力（ホストが4ビット行番号を送信）。双方向バスが必要なホスト向けにreconfigADC2Ports()で出力として再構成可能です。X1インターフェースではループバック検出のために一時的に出力モードに設定されます。
RTSNI	1 strobe line	35	Input only	ホストからのアクティブローストローブ。GPIO 35はESP32の入力専用バンク（GPIO_IN1_REG、ビット3）にあります。MZ-2500/2800では行転送ストローブとして使用されます。他のホストでは未使用の場合があります（ケーブル上でHIGHまたはLOWに直接接続）。
MPXI	1 multiplex line	12	Input	ホストからのマルチプレクス/モード選択。MZマシンではMZ-2500とMZ-2800のタイミングを区別するために使用されます。新しいホストでは任意の目的に使用可能です。
KDI4	1 extra input	13	Input	補助データ入力。MZホストでは単一行モードとSTROBEALLモードの区別に使用されます。任意の目的に使用可能です。
PS/2 DATA	1 bidirectional	14	Bidirectional	PS/2キーボードデータライン（mini-DINコネクタに直接接続）。
PS/2 CLK	1 interrupt-capable	13	Bidirectional	PS/2キーボードクロックライン。Scan Code Set 2の受信のために割り込み対応が必要です。
PWRLED	1 output	25	Output	電源/ステータスLED。
WIFI_EN	1 input	34	Input only	WiFi有効化スイッチ（アクティブロー、GPIO 34は入力専用）。

• マトリクススキャンキーボード（最も一般的）— ホストが行アドレス（通常4-6ビット）を送信し、列データ（通常8ビット）を読み返します。これはKDB[3:0]を行入力、KDO[7:0]を列出力として直接マッピングされます。MZ-2500/2800、X1、PC-9801はすべてこのパターンを使用します。
• シリアルキーボード — 一部のホスト（例：特定のMSXマシン、初期のApple）はシリアルプロトコルを使用します。任意の単一GPIOをシリアルデータラインとして、別のGPIOをクロックとして使用できます。KDOまたはKDBラインは個別にアドレス指定できます。
• アクティブ出力キーボード — X68000のようなホストは、キーボードがマトリクスを提示するのではなく、キーダウン/キーアップスキャンコードを能動的に送信することを期待します。SharpKeyはこのモデルをサポートしています — X68KインターフェースはKDOラインをシリアルトランスミッタとして使用し、KDB入力は完全に無視します。
• 混合プロトコル — ホストがマトリクススキャンと追加の制御信号（例：CAPS LOCK LEDフィードバック、キーボードリセット）の両方を使用する場合、MPXI、KDI4、RTSNIラインを再利用できます。すべてのGPIO割り当てはKconfigで設定可能です。

1. ホストのサービスマニュアルから、またはオリジナルキーボードのリバースエンジニアリングによって、キーボードコネクタのピン配列を入手します。
2. どの信号が行選択（アドレス）で、どれが列データ（キー状態）で、どれが制御/ストローブ信号かを特定します。
3. ホスト信号を最も適切なSharpKey GPIOグループにマッピングします（出力にはKDO、入力にはKDB、ストローブおよび制御信号にはRTSNI/MPXI/KDI4）。
4. ホストがSharpKeyのアクティブハイと反対のアクティブロー信号を使用する場合（またはその逆）、ケーブルにインバータが必要な場合があります — ただしほとんどの場合、ソフトウェアで極性反転を処理できます。
5. ホストが5V出力ドライブを必要とし（SharpKeyの74HCT257経由の3.3Vでは不十分な場合）、ケーブルPCBまたはインラインアダプタにバッファIC（例：74HCT245）を追加します。
6. 電源とグランドが接続されていることを確認します。SharpKeyはキーボードコネクタで利用可能なホストの5V電源から給電するか、USBプログラミングポート経由で独立して給電できます。

ソフトウェア実装

ステップ1 — ヘッダーファイルの作成

• クラス宣言 — KeyInterfaceを継承
• マトリクスの次元 — ターゲットホストのキーボードマトリクスの行数と列数を定義
• 制御構造体（t_newHostControl）— キーマトリクス配列、GPIOビットマスク、モードフラグ、およびプロトコル固有の状態を保持
• キーマッピングテーブル（t_keyMap keyMap[]）— 各PS/2キーコード＋修飾キーの組み合わせを1つ以上のホストマトリクス行/列位置にマッピング。各エントリは最大3つの同時「make」キーと2つの「break」キーをエンコード可能
• PS/2制御フラグ — 修飾キーマッチング用の標準PS2CTRL_*定数（SHIFT、CTRL、ALT、CAPSなど）を使用
• マシンモデルタグ — ホストに異なるキーレイアウトのサブモデルがある場合、モデル定数を定義 （MZ2528.hのMZ_80B、MZ_2000、MZ_2500、MZ_2800に類似）

// NewHost.h — Header for a hypothetical new host interface
#ifndef NEWHOST_H
#define NEWHOST_H

#include "KeyInterface.h"
#include "NVS.h"
#include "LED.h"
#include "HID.h"
#include <vector>
#include <map>

class NewHost : public KeyInterface {

    // Constants
    #define NEWHOST_VERSION             1.00
    #define NEWHOST_KEYMAP_FILE         "NewHost_KeyMap.BIN"
    #define NEWHOST_MATRIX_ROWS         12       // Number of rows in the host key matrix
    #define NEWHOST_MATRIX_COLS         8        // Number of columns (bits per row)

    // PS/2 → Host mapping table dimensions
    #define PS2TBL_NEWHOST_MAXROWS      128      // Maximum entries in the mapping table
    #define PS2TBL_NEWHOST_MAX_MKROW    3        // Max simultaneous make keys per entry
    #define PS2TBL_NEWHOST_MAX_BRKROW   2        // Max simultaneous break keys per entry

    // Machine model tags (if the host has sub-models)
    #define NEWHOST_ALL                 0xFF
    #define NEWHOST_MODEL_A             0x01
    #define NEWHOST_MODEL_B             0x02

    // The PS/2 to host mapping table type (same structure as other interfaces)
    typedef struct {
        uint16_t    ps2KeyCode;                                  // PS/2 key code from PS2KeyAdvanced
        uint8_t     ps2Ctrl;                                     // Modifier flags (PS2CTRL_SHIFT, etc.)
        uint8_t     keyboardModel;                               // 0 = all keyboards, or specific model ID
        uint8_t     machine;                                     // NEWHOST_ALL or specific model
        struct {
            uint8_t row;
            uint8_t col;                                         // Bitmask: bit position in the row
        }           mk[PS2TBL_NEWHOST_MAX_MKROW];               // Make (key press) targets
        struct {
            uint8_t row;
            uint8_t col;
        }           brk[PS2TBL_NEWHOST_MAX_BRKROW];             // Break (key release) targets
    } t_newHostKeyMap;

    // Control structure holding all runtime state
    typedef struct {
        uint8_t     keyMatrix[NEWHOST_MATRIX_ROWS];              // Virtual key matrix (1 = released, 0 = pressed)
        uint32_t    keyMatrixAsGPIO[NEWHOST_MATRIX_ROWS];        // Pre-shifted GPIO bitmasks for atomic writes
        uint8_t     strobeAll;                                   // AND of all rows (used by some protocols)
        uint32_t    strobeAllAsGPIO;
        bool        noKeyPressed;
    } t_newHostControl;

    public:
        // Constructors matching the KeyInterface pattern
                     NewHost(void) : KeyInterface() {};
                     NewHost(uint32_t ifMode, NVS *hdlNVS, LED *hdlLED, HID *hdlHID, const char *fsPath);
                     NewHost(NVS *hdlNVS, HID *hdlHID);
                    ~NewHost();

        // Overridden virtual methods
        void         init(uint32_t ifMode, NVS *hdlNVS, LED *hdlLED, HID *hdlHID);
        void         init(NVS *hdlNVS, HID *hdlHID);
        IRAM_ATTR uint32_t mapKey(uint16_t scanCode);

        // Key map file I/O (for web interface persistence)
        bool         createKeyMapFile(std::fstream &outFile);
        bool         getKeyMapData(std::vector<uint32_t>& dataArray, int *row, bool start);
        void         getKeyMapHeaders(std::vector<std::string>& headerList);
        std::string  getKeyMapFileName(void);

        // FreeRTOS task functions — static so they can be passed to xTaskCreatePinnedToCore
        static void IRAM_ATTR hostInterfaceTask(void *pvParameters);
        static void           hidInterface(void *pvParameters);

    private:
        t_newHostControl      hostCtrl;
        TaskHandle_t          TaskHostIF = NULL;
        TaskHandle_t          TaskHIDIF  = NULL;
        portMUX_TYPE          hostMux    = portMUX_INITIALIZER_UNLOCKED;
};

// ─── Key Mapping Table ──────────────────────────────────────────────────────
// Each row maps one PS/2 key (+ optional modifier) to host matrix position(s).
// Fields: ps2KeyCode, ps2Ctrl, kbModel, machine,
//         mk[0].row, mk[0].col, mk[1].row, mk[1].col, mk[2].row, mk[2].col,
//         brk[0].row, brk[0].col, brk[1].row, brk[1].col
//
// Example: map PS/2 'A' (0x1C) to host row 4, column bit 0
static const t_newHostKeyMap newHostKeyMap[] = {
    { PS2_KEY_A,     PS2CTRL_NONE, 0, NEWHOST_ALL, {{4,0x01},{0,0},{0,0}}, {{4,0x01},{0,0}} },
    { PS2_KEY_B,     PS2CTRL_NONE, 0, NEWHOST_ALL, {{4,0x02},{0,0},{0,0}}, {{4,0x02},{0,0}} },
    { PS2_KEY_ENTER, PS2CTRL_NONE, 0, NEWHOST_ALL, {{3,0x04},{0,0},{0,0}}, {{3,0x04},{0,0}} },
    // ... complete mapping for all host keys ...
};

#endif // NEWHOST_H

ステップ2 — ソースファイルの作成

// NewHost.cpp — Implementation of a new host interface
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "driver/gpio.h"
#include "soc/gpio_struct.h"
#include "soc/gpio_reg.h"
#include "NewHost.h"

#define MAINTAG "NewHost"

// ─── Constructor (with hardware) ────────────────────────────────────────────
NewHost::NewHost(uint32_t ifMode, NVS *hdlNVS, LED *hdlLED, HID *hdlHID, const char *fsPath)
{
    init(ifMode, hdlNVS, hdlLED, hdlHID);
}

// ─── Constructor (without hardware, for WiFi probing) ───────────────────────
NewHost::NewHost(NVS *hdlNVS, HID *hdlHID)
{
    init(hdlNVS, hdlHID);
}

// ─── Destructor ─────────────────────────────────────────────────────────────
NewHost::~NewHost() { }

// ─── init() with hardware ───────────────────────────────────────────────────
// ホストが検出された際に呼び出されます。GPIOを設定しFreeRTOSタスクを起動します。
void NewHost::init(uint32_t ifMode, NVS *hdlNVS, LED *hdlLED, HID *hdlHID)
{
    // 制御変数を初期化します（キーマトリクスを全キーリリース状態に）。
    init(hdlNVS, hdlHID);

    // 基底クラスのinitを呼び出します（NVS、LED、HIDハンドルを格納し、LEDを点灯）。
    KeyInterface::init(getClassName(__PRETTY_FUNCTION__), hdlNVS, hdlLED, hdlHID, ifMode);

    // ── GPIO設定 ──────────────────────────────────────────────────────
    // 基底クラスKeyInterface::reconfigADC2Ports()はすでにKDB[3:0]を入力、
    // KDI4/MPXIを入力、RTSNIを入力として設定しています。
    // ここではホスト固有のGPIO要件を設定します：
    gpio_config_t io_conf = {};

    // KDO[7:0]を出力として設定（ESP32が直接駆動）
    io_conf.intr_type    = GPIO_INTR_DISABLE;
    io_conf.mode         = GPIO_MODE_OUTPUT;
    io_conf.pull_down_en = GPIO_PULLDOWN_DISABLE;
    io_conf.pull_up_en   = GPIO_PULLUP_DISABLE;
    for(int pin : {CONFIG_HOST_KDO0, CONFIG_HOST_KDO1, CONFIG_HOST_KDO2, CONFIG_HOST_KDO3,
                   CONFIG_HOST_KDO4, CONFIG_HOST_KDO5, CONFIG_HOST_KDO6, CONFIG_HOST_KDO7})
    {
        io_conf.pin_bit_mask = (1ULL << pin);
        gpio_config(&io_conf);
    }

    // すべてのKDO出力をHIGHに設定（全キーリリース）
    GPIO.out_w1ts = (1 << CONFIG_HOST_KDO7) | (1 << CONFIG_HOST_KDO6) |
                    (1 << CONFIG_HOST_KDO5) | (1 << CONFIG_HOST_KDO4) |
                    (1 << CONFIG_HOST_KDO3) | (1 << CONFIG_HOST_KDO2) |
                    (1 << CONFIG_HOST_KDO1) | (1 << CONFIG_HOST_KDO0);

    // ── FreeRTOSタスクの作成 ──────────────────────────────────────────
    // ホストインターフェースタスクをCore 1で実行（タイミングクリティカル）
    ESP_LOGW(MAINTAG, "Starting NewHost interface thread on Core 1...");
    ::xTaskCreatePinnedToCore(&NewHost::hostInterfaceTask, "newHostIf",
                              4096, this, 25, &this->TaskHostIF, 1);
    vTaskDelay(500);

    // HID入力ポーリングタスクをCore 0で実行
    ESP_LOGW(MAINTAG, "Starting HID interface thread on Core 0...");
    ::xTaskCreatePinnedToCore(&NewHost::hidInterface, "hidIf",
                              4096, this, 0, &this->TaskHIDIF, 0);
}

// ─── init() without hardware (WiFiパラメータプローブ用) ──────────────────────
void NewHost::init(NVS *hdlNVS, HID *hdlHID)
{
    // キーマトリクスを全キーリリース状態に初期化
    hostCtrl.strobeAll       = 0xFF;
    hostCtrl.strobeAllAsGPIO = 0x00000000;
    hostCtrl.noKeyPressed    = true;
    for(int i = 0; i < NEWHOST_MATRIX_ROWS; i++)
    {
        hostCtrl.keyMatrix[i]       = 0xFF;         // 全キーリリース
        hostCtrl.keyMatrixAsGPIO[i] = 0x00000000;   // クリアするGPIOビットなし
    }

    // 基底クラスのinitを呼び出し（ハードウェアなし）
    KeyInterface::init(getClassName(__PRETTY_FUNCTION__), hdlNVS, hdlHID);
}

// ─── mapKey() — PS/2スキャンコードをホストマトリクスに変換 ───────────────────
// Core 0のHIDインターフェースタスクから呼び出されます。共有の
// keyMatrix/keyMatrixAsGPIO配列に書き込む際はスピンロックを使用する必要があります。
IRAM_ATTR uint32_t NewHost::mapKey(uint16_t scanCode)
{
    uint8_t  keyCode  = scanCode & 0xFF;
    uint8_t  ctrlKeys = (scanCode >> 8) & 0xFF;
    bool     isBreak  = (ctrlKeys & PS2_BREAK) ? true : false;

    // マッピングテーブルを検索
    for(int idx = 0; idx < sizeof(newHostKeyMap)/sizeof(newHostKeyMap[0]); idx++)
    {
        if(newHostKeyMap[idx].ps2KeyCode == keyCode)
        {
            // マトリクスにキーを適用
            portENTER_CRITICAL(&hostMux);
            for(int mk = 0; mk < PS2TBL_NEWHOST_MAX_MKROW; mk++)
            {
                uint8_t row = newHostKeyMap[idx].mk[mk].row;
                uint8_t col = newHostKeyMap[idx].mk[mk].col;
                if(col == 0) break;

                if(isBreak)
                    hostCtrl.keyMatrix[row] |= col;    // ビットセット = キーリリース
                else
                    hostCtrl.keyMatrix[row] &= ~col;   // ビットクリア = キー押下
            }
            // strobeAllを再計算（全行のAND）
            hostCtrl.strobeAll = 0xFF;
            for(int r = 0; r < NEWHOST_MATRIX_ROWS; r++)
                hostCtrl.strobeAll &= hostCtrl.keyMatrix[r];
            portEXIT_CRITICAL(&hostMux);
            break;
        }
    }
    return(0);
}

// ─── hostInterfaceTask() — Core 1タイミングクリティカルループ ─────────────────
// メインのホスト側プロトコルハンドラです。Core 1でタイトループとして実行され、
// ホストの行選択ストローブに列データで応答します。
// 確定的な実行タイミングのために関数を命令RAMに保持するためIRAM_ATTRでマークします。
void IRAM_ATTR NewHost::hostInterfaceTask(void *pvParameters)
{
    NewHost *pThis = (NewHost *)pvParameters;

    // KDO出力ライン用のGPIOビットマスクを事前計算
    const uint32_t KDO_ALL_MASK = (1 << CONFIG_HOST_KDO7) | (1 << CONFIG_HOST_KDO6) |
                                  (1 << CONFIG_HOST_KDO5) | (1 << CONFIG_HOST_KDO4) |
                                  (1 << CONFIG_HOST_KDO3) | (1 << CONFIG_HOST_KDO2) |
                                  (1 << CONFIG_HOST_KDO1) | (1 << CONFIG_HOST_KDO0);

    // 各列ビットのGPIOマスクをビットごとに事前計算
    const uint32_t colGPIO[8] = {
        (1 << CONFIG_HOST_KDO0), (1 << CONFIG_HOST_KDO1),
        (1 << CONFIG_HOST_KDO2), (1 << CONFIG_HOST_KDO3),
        (1 << CONFIG_HOST_KDO4), (1 << CONFIG_HOST_KDO5),
        (1 << CONFIG_HOST_KDO6), (1 << CONFIG_HOST_KDO7)
    };

    while(true)
    {
        // ── サスペンド要求の確認（WiFiモード切替に必要）─────────────────
        pThis->yield(0);

        // ── ホストプロトコルをここに実装 ──────────────────────────────
        // 例：マトリクススキャンプロトコル（MZ-2500と同様）
        //
        // 1. ホストからのストローブ信号を待つ
        //    while((REG_READ(GPIO_IN1_REG) & RTSNI_MASK) == 0) { }
        //
        // 2. KDB[3:0]から行番号を読み取る
        //    uint32_t gpioIn = REG_READ(GPIO_IN_REG);
        //    uint8_t row = ((gpioIn >> CONFIG_HOST_KDB3) & 1) << 3 |
        //                  ((gpioIn >> CONFIG_HOST_KDB2) & 1) << 2 |
        //                  ((gpioIn >> CONFIG_HOST_KDB1) & 1) << 1 |
        //                  ((gpioIn >> CONFIG_HOST_KDB0) & 1);
        //
        // 3. すべてのKDOをHIGH（非アクティブ）に設定し、押下キービットをクリア
        //    GPIO.out_w1ts = KDO_ALL_MASK;
        //    uint8_t rowData = pThis->hostCtrl.keyMatrix[row];
        //    uint32_t clearMask = 0;
        //    for(int b = 0; b < 8; b++)
        //        if(!(rowData & (1 << b)))  clearMask |= colGPIO[b];
        //    GPIO.out_w1tc = clearMask;
        //
        // 4. ストローブのデアサートを待つ（ホストがデータをラッチ）
        //    while((REG_READ(GPIO_IN1_REG) & RTSNI_MASK) != 0) { }
        //
        // シリアル出力ホスト（X68000のような）の場合、ループは代わりに
        // 保留中のキーイベントを確認し、KDOライン上でビットバンギングにより
        // スキャンコードを送信します。

        vTaskDelay(1);  // プレースホルダー — 実際のプロトコル実装時に削除
    }
}

// ─── hidInterface() — Core 0 HID入力ポーリング ──────────────────────────────
void NewHost::hidInterface(void *pvParameters)
{
    NewHost *pThis = (NewHost *)pvParameters;

    while(true)
    {
        // PS/2またはBluetoothキーイベントをポーリング
        uint16_t scanCode = pThis->hid->read();
        if(scanCode > 0)
        {
            pThis->mapKey(scanCode);
        }
        vTaskDelay(1);
    }
}

ステップ3 — ビルドシステムへの登録

set(COMPONENT_SRCS SharpKey.cpp NVS.cpp LED.cpp SWITCH.cpp KeyInterface.cpp
    MZ2528.cpp X1.cpp X68K.cpp Mouse.cpp MZ5665.cpp PC9801.cpp
    HID.cpp WiFi.cpp PS2KeyAdvanced.cpp PS2Mouse.cpp BT.cpp BTHID.cpp
    esp_efuse_custom_table.c
    NewHost.cpp)
set(COMPONENT_ADD_INCLUDEDIRS "." "include")
register_component()

// In getHostType(), after existing detection cases:

// Check for NewHost — describe the electrical signature
// e.g., KDI4 = high, MPXI = high, RTSNI = low, KDB[3:0] = 1100
if(tKDI4 == 1 && tMPXI == 1 && tRTSNI == 0 &&
   tKDB3 == 1 && tKDB2 == 1 && tKDB1 == 0 && tKDB0 == 0 &&
   eFuseInvalid == false &&
   (sharpkeyEfuses.disableRestrictions == true || sharpkeyEfuses.enableNewHost == true))
{
    ifMode = 12345;  // 新しいホスト用のユニークなID番号を選択
}

#include "NewHost.h"    // SharpKey.cppの先頭に追加

// setup()内のswitch(ifMode)ブロック：
case 12345:
{
    ESP_LOGW(SETUPTAG, "Detected NewHost.");
    keyIf = new NewHost(ifMode, &nvs, led, hid, LITTLEFS_DEFAULT_PATH);
    break;
}

ステップ4 — Kconfigオプションの追加（任意）

// In Kconfig.projbuild, under the "Host Interface" menu:
config ENABLE_NEWHOST
    bool "Enable NewHost support"
    default true
    help
        Enable support for the NewHost retro computer interface.

ステップ5 — ビルドとテスト

1. idf.py menuconfigを実行し、新しいホストのKconfigオプションが表示され正しく設定されていることを確認します。
2. ビルド：idf.py build
3. ESP32にフラッシュ：idf.py -p /dev/ttyUSB0 flash
4. カスタムケーブルを使用してSharpKeyを新しいホストに接続します。
5. シリアル出力を監視：idf.py -p /dev/ttyUSB0 monitor — ホスト検出が正しいifMode値を表示することを確認します。
6. menuconfigでCONFIG_DEBUG_SERIALを有効にして、詳細なキーイベントログを出力します。各PS/2スキャンコード、修飾キー状態、および結果のホストマトリクス行/列が表示されるはずです。
7. CONFIG_DEBUG_DISABLE_KDOを使用して、検出とキーマッピングロジックを単独でテストしている間、ホストへの出力を無効にします。
8. キーマッピングが確認できたら、出力を有効にしてホストコンピュータがキーストロークを正しく受け付けることを検証します。

作成/変更するファイルの要約

Action	File	What to do
作成	main/include/NewHost.h	クラス宣言、キーマッピングテーブル、定数
作成	main/NewHost.cpp	init()、mapKey()、hostInterfaceTask()、hidInterface()
変更	main/CMakeLists.txt	NewHost.cppをCOMPONENT_SRCSに追加
変更	main/SharpKey.cpp	#include "NewHost.h"の追加、getHostType()の検出ロジック、setup()のswitchブロックへのインスタンス化
変更	main/Kconfig.projbuild	（任意）GPIOピンと機能有効化オプションの追加
変更	main/esp_efuse_custom_table.csv	（任意）機能セキュリティeFuseビットの追加
作成	ホストケーブル	SharpKeyコネクタからターゲットホストのキーボードコネクタへの物理配線

---

キーマップの更新

Webインターフェース経由

• ソート可能なグリッドにすべてのエントリが表示された現在のキーマッピングテーブルの参照
• PS/2キーを選択し、1つ以上のホストマトリクスポジションに割り当て
• 修飾キー要件の設定（マッピングをアクティブにするためにSHIFT、CTRL、ALTを保持する必要あり）
• キーボードモデル固有のオーバーライドの設定
• NVSへの変更保存（再起動やファームウェア更新をまたいで保持）
• NVSキーマッピングデータをクリアして工場出荷時のデフォルトにリセット

ソースコード経由

// Map PS/2 'A' key (ASCII 0x61) to MZ matrix row 4, column bit 0
// No modifiers required, all keyboard models, all MZ machines
{ 0x61, 0x00, 0, MZ_ALL,
  4, 0x01,    // Make key 1: row 4, bit 0
  0, 0x00,    // Make key 2: unused
  0, 0x00,    // Make key 3: unused
  4, 0x01,    // Break key 1: row 4, bit 0
  0, 0x00     // Break key 2: unused
},

// Map PS/2 SHIFT+'a' to MZ SHIFT + 'A' (two simultaneous make keys)
{ 0x61, PS2CTRL_SHIFT, 0, MZ_ALL,
  11, 0x04,   // Make key 1: row 11 (SHIFT), bit 2
  4,  0x01,   // Make key 2: row 4 ('A'), bit 0
  0,  0x00,   // Make key 3: unused
  11, 0x04,   // Break key 1: release SHIFT
  4,  0x01    // Break key 2: release 'A'
},

フラグ	値	説明
PS2CTRL_SHIFT	0x01	Shiftキーを保持する必要あり
PS2CTRL_CTRL	0x02	Ctrlキーを保持する必要あり
PS2CTRL_CAPS	0x04	Caps Lockがアクティブである必要あり
PS2CTRL_ALT	0x08	Altキーを保持する必要あり
PS2CTRL_ALTGR	0x10	AltGr（右Alt）を保持する必要あり
PS2CTRL_GUI	0x20	Windows/Superキーを保持する必要あり
PS2CTRL_FUNC	0x40	Functionキーを保持する必要あり
PS2CTRL_EXACT	0x80	修飾キーの完全一致が必要（追加の修飾キー不可）

新しいキーボードモデルの追加

1. スキャンコードの特定 — 新しいキーボードを接続し、menuconfigでCONFIG_DEBUG_SERIALを有効にします。シリアルモニターが各キー押下の生スキャンコードデータを出力します。非標準のスキャンコードを生成するキーをメモしてください。
2. モデルIDの割り当て — 次に利用可能なモデル番号を選択し、PS2KeyTable.hに定数として定義します。
3. モデル固有エントリの追加 — ホストインターフェースヘッダー（例：MZ2528.h）に、汎用マッピングと異なるキーについて、新しいモデルIDをkeyboardModelフィールドに持つt_keyMap[]エントリを追加します。
4. 徹底的なテスト — すべてのキーがホストマシンで正しい出力を生成することを確認します。修飾キー、特殊文字、およびキーボードレイアウト固有のキーに特に注意してください。
5. Webインターフェースの更新 — ユーザーが手動で選択できるよう、webserver/keymap.htmlのキーボードモデルドロップダウンに新しいモデル名を追加します。

---

GPIOピン設定

PS/2インターフェース

信号	GPIO	方向	用途
PS2_DATA	14	双方向	PS/2キーボードデータライン（オープンコレクタ）
PS2_CLK	13	双方向	PS/2キーボードクロックライン（割り込み駆動）

ホストインターフェース — 行選択（ホストからの入力）

信号	GPIO	方向	用途
KDB0	23	入力	行選択ビット0（ホストスキャン中にアクティブ）
KDB1	25	入力	行選択ビット1
KDB2	26	入力	行選択ビット2
KDB3	27	入力	行選択ビット3

ホストインターフェース — スキャンデータ（74HCT257経由でホストに出力）

信号	GPIO	方向	用途
KDO0	14	出力	マトリクス列データビット0
KDO1	15	出力	マトリクス列データビット1
KDO2	16	出力	マトリクス列データビット2
KDO3	17	出力	マトリクス列データビット3
KDO4	18	出力	マトリクス列データビット4
KDO5	19	出力	マトリクス列データビット5
KDO6	21	出力	マトリクス列データビット6
KDO7	22	出力	マトリクス列データビット7

制御信号

信号	GPIO	方向	用途
RTSNI	35	入力	ホストからの行ストローブ（アクティブロー、GPIO_IN1_REG経由で読み取り）
MPXI	12	入力	マルチプレクス選択（ホスト読み取りサイクル中にアクティブ）
KDI4	13	入力	追加キーボードデータ入力ライン
PWRLED	25	出力	電源/ステータスLEDインジケーター
WIFI_EN	34	入力	WiFi有効化スイッチ（アクティブロー、入力専用GPIO）

ADC2/WiFi GPIOの競合

ADC2 GPIOs: 0, 2, 4, 12, 13, 14, 15, 25, 26, 27

---

MZ-2500/2800プロトコル

MZ-2500タイミング

1. ホストがKDB0-KDB3に行アドレス（0-13）を駆動
2. ホストがRTSNをLOWにアサート（約600ns）
3. SharpKeyがKDB0-KDB3から行アドレスを読み取り
4. SharpKeyが対応する列データをKDO0-KDO7に提示
5. ホストが列データを読み取り
6. ホストがRTSNをHIGHにデアサート
7. SharpKeyが列データ出力をクリア

MZ-2800タイミング

• 最大優先度でCore 1上で動作する
• IRAM_ATTRを使用してすべてのコードを命令RAMに保持する（フラッシュキャッシュミスなし）
• 共有データアクセスにportMUX_TYPEスピンロックを使用する（mutexではなく）
• GPIO.out_w1ts、GPIO.out_w1tc、およびREG_READ(GPIO_IN1_REG)を介してGPIOレジスタに直接アクセスする
• ホットループ内でFreeRTOS API呼び出しを行わない（vTaskDelayなし、xSemaphoreTakeなし）
• 事前計算されたkeyMatrixAsGPIO[]を使用してストローブウィンドウ中のビットシフトを排除する

// Simplified MZ-2800 hot loop (IRAM_ATTR, Core 1)
void IRAM_ATTR MZ2528::mz28InterfaceTask(void *pvParameters) {
    while (1) {
        // Wait for RTSN strobe (active low)
        while (REG_READ(GPIO_IN1_REG) & RTSNI_MASK) { }

        // Read row address from KDB0-KDB3
        uint32_t gpioIn = REG_READ(GPIO_IN_REG);
        uint8_t row = (gpioIn >> KDB_SHIFT) & 0x0F;

        // Present column data
        GPIO.out_w1tc = KDO_ALL_MASK;          // Clear all columns
        GPIO.out_w1ts = keyMatrixAsGPIO[row];   // Set pressed keys

        // Wait for RTSN deassert
        while (!(REG_READ(GPIO_IN1_REG) & RTSNI_MASK)) { }

        // Clear outputs
        GPIO.out_w1tc = KDO_ALL_MASK;
    }
}

---

Bluetooth統合

アーキテクチャ

• BT.cpp — GAP（Generic Access Profile）イベント処理、SDP（Service Discovery Protocol）登録、およびHIDデバイスコールバックを含む低レベルBluetoothスタックを管理します。ESP-IDF BluetoothコントローラーおよびBluedroidホストスタックの初期化を処理します。
• BTHID.cpp — 高レベルのBluetooth HIDインターフェースを提供します。BluetoothキーボードおよびマウスからのHIDレポートをPS/2パスで使用されるのと同じスキャンコードフォーマットに変換し、パイプラインの残りの部分（HID.cpp、mapKey）が同一に処理できるようにします。

ペアリングプロセス

1. ボンディングされたデバイスが接続されていない場合、SharpKeyが検出可能モードに入ります
2. ステータスLEDが8Hzで点滅し、ペアリングモードがアクティブであることを示します
3. キーボードがHIDホストをスキャンしてペアリングを開始します
4. PINが要求された場合、デフォルトPINは"1234"です
5. ペアリングが成功すると、デバイスボンドがNVSに保存されます
6. LEDが常時点灯に切り替わり、デバイスが接続されたことを示します
7. デバイスが接続されない場合、60秒後にペアリングウィンドウが閉じます

HIDマルチプレクシング

• PS/2が優先 — データ/クロックラインでPS/2キーボードが検出された場合、Bluetoothスキャンは無効化され、すべての入力はPS/2ソースから取得されます。
• Bluetoothフォールバック — ブート時にPS/2キーボードが検出されない場合、Bluetoothが初期化され、Bluetooth HIDソースから入力が取得されます。
• ホットプラグ検出 — Bluetoothがアクティブな状態でブート後にPS/2キーボードが接続された場合、システムはPS/2入力に切り替わります。ただし、ESP-IDFスタックの制限により、Bluetoothへの切り替えには再起動が必要です。
• マウス入力 — PS/2およびBluetoothマウスはキーボード入力とは独立してマルチプレクスされます。両方を同時にアクティブにできます。

---

WiFiとWebインターフェース

WiFiモード

• アクセスポイントモード（デフォルト） — SharpKeyが独自のWiFiネットワークを作成します。デフォルトSSID：sharpkey、デフォルトパスワード：sharpkey。ラップトップまたはスマートフォンからこのネットワークに接続し、http://192.168.4.1にアクセスしてWebインターフェースを使用します。このモードは既存のネットワークインフラストラクチャなしで動作します。
• ステーションクライアントモード — SharpKeyがクライアントとして既存のWiFiネットワークに接続します。SSIDとパスワードはwifimanager.htmlページまたはmenuconfigを通じて設定されます。SharpKeyはDHCPを通じてIPアドレスを取得します。このモードでは同じネットワーク上の任意のデバイスからアクセスできます。

Webサーバーエンドポイント

エンドポイント	メソッド	用途
/index.html	GET	メインダッシュボード — ファームウェアバージョン、ホストタイプ、WiFiステータス、接続デバイスを表示
/keymap.html	GET	キーマッピングエディター — PS/2からホストキーへの変換のビジュアルエディター
/mouse.html	GET	マウス設定 — 感度、加速度、ボタンマッピング
/ota.html	GET	OTAファームウェアアップロードページ — ドラッグアンドドロップでのファームウェアバイナリアップロード
/wifimanager.html	GET	WiFi設定 — APとクライアントモードの切り替え、SSID/パスワードの設定
/version.txt	GET	ファームウェアバージョン文字列（プレーンテキスト）
/api/update	POST	OTAファームウェアアップロードエンドポイント — バイナリファームウェアデータを受信

Webファイルシステム

1. build_webfs.shスクリプトがwebserver/からHTMLファイルをステージングディレクトリwebfs/にコピーします。
2. CSS、JavaScript、およびフォントファイルはフラッシュ使用量の削減と圧縮配信のために、コピー時にgzip圧縮されます。
3. CMakeビルドシステムがesp_littlefsコンポーネントを使用してwebfs/ディレクトリからLittleFSパーティションイメージを作成します。
4. パーティションイメージは書き込み時にfilesysパーティション（640KB、タイプspiffs）に書き込まれます。
5. 実行時にESP32がLittleFSパーティションをマウントし、ファイルを直接配信します。圧縮ファイルはContent-Encoding: gzipヘッダー付きで配信されるため、ブラウザが透過的に解凍します。

---

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

パーティション構成

# Name,     Type,  SubType,  Offset,   Size
otadata,    data,  ota,      0x9000,   0x2000
nvs,        data,  nvs,      ,         0x4000
phy_init,   data,  phy,      ,         0x1000
ota_0,      app,   ota_0,    ,         0x1A0000
ota_1,      app,   ota_1,    ,         0x1A0000
filesys,    data,  spiffs,   ,         0xA0000

パーティション	サイズ	用途
otadata	8 KB	OTA選択データ（どのパーティションからブートするか）
nvs	16 KB	不揮発性ストレージ（キーマッピング、WiFi設定、BTボンド）
phy_init	4 KB	PHYキャリブレーションデータ（WiFi/BT無線）
ota_0	1.625 MB	アプリケーションパーティションA
ota_1	1.625 MB	アプリケーションパーティションB
filesys	640 KB	LittleFS Webファイルシステム

アップデートプロセス

1. アップロード — ファームウェアバイナリは/ota.htmlWebページ（ドラッグアンドドロップ）を通じて、または/api/updateエンドポイントにバイナリをPOSTしてアップロードされます。
2. ヘッダー検証 — アップロードされたバイナリの最初のバイトがESP_APP_DESC_MAGIC_WORDヘッダーでチェックされ、有効なESP32アプリケーションイメージであることを確認します。
3. バージョンチェック — アプリケーションヘッダーのファームウェアバージョン文字列が実行中のバージョンと比較されます。eFuse設定で明示的にオーバーライドされない限り、ダウングレードは防止されます。
4. フラッシュへのストリーミング — バイナリデータは現在非アクティブなOTAパーティションにストリーミングされます（ota_0が動作中の場合、データはota_1に書き込まれ、その逆も同様）。これにより、更新が完了するまで実行中のファームウェアが保持されます。
5. アクティブパーティションの切り替え — 書き込みと検証が成功した後、次回の再起動時に新しく書き込まれたパーティションからブートするようOTAデータパーティションが更新されます。
6. 自動再起動 — ESP32が自動的に新しいファームウェアで再起動します。新しいファームウェアが起動に失敗した場合（例：初期init中にクラッシュ）、ブートローダーは設定可能なタイムアウト後に前のパーティションにロールバックします。

---

eFuseカスタムフィールド

識別フィールド

フィールド	ビット範囲	サイズ（ビット）	用途
HARDWARE_REVISION	56-71	16	SharpKey PCBのハードウェアリビジョン番号
SERIAL_NO	72-87	16	このユニットの一意なシリアル番号
DISABLE_RESTRICTIONS	88	1	セットすると、すべての機能制限を無効化
RESERVED1	89-95	7	将来のフラグビット用に予約
BUILD_DATE	160-183	24	24ビット値としてエンコードされたビルド日

機能セキュリティビット

ビット	フィールド名	用途
8	ENABLE_BT	Bluetoothキーボード/マウスサポートの有効化
9	ENABLE_MZ5665	MZ-5500/5600/6500ホストインターフェースの有効化
10	ENABLE_PC9801	NEC PC-9801ホストインターフェースの有効化
11	ENABLE_MOUSE	マウスサポート（PS/2およびBluetooth）の有効化
12	ENABLE_X68000	Sharp X68000ホストインターフェースの有効化
13	ENABLE_X1	Sharp X1ホストインターフェースの有効化
14	ENABLE_MZ2800	Sharp MZ-2800ホストインターフェースの有効化
15	ENABLE_MZ2500	Sharp MZ-2500ホストインターフェースの有効化

---

ビルド環境

ネイティブビルドセットアップ

# Install prerequisites (Ubuntu/Debian)
sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv \
    cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

# Clone ESP-IDF v4.4
mkdir -p ~/esp
cd ~/esp
git clone -b v4.4 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf

# Install toolchain and tools
./install.sh

# Set up environment variables (run in each new terminal session)
. ./export.sh

クローンとビルド

# Clone the repository
git clone https://git.eaw.app/eaw/SharpKey.git
cd SharpKey

# Initialise submodules (arduino-esp32 and esp_littlefs)
git submodule update --init --recursive

# Configure build options (select target, GPIO pins, features)
idf.py menuconfig

# Build the web filesystem (compress CSS/JS/fonts, create LittleFS image)
./build_webfs.sh

# Compile the firmware
idf.py build

# Flash to ESP32 (connect via USB-to-serial adapter)
idf.py -p /dev/ttyUSB0 flash

# Open serial monitor for debug output
idf.py -p /dev/ttyUSB0 monitor

Menuconfigオプション

• Build Target — ファームウェアバリアントの選択：
  • SHARPKEY — 完全なマルチホストビルド（MZ-2500、MZ-2800、MZ-5600、X1、X68000、PC-9801）
  • MZ25KEY_MZ2500 — MZ-2500専用のシングルターゲットビルド
  • MZ25KEY_MZ2800 — MZ-2800専用のシングルターゲットビルド
• Feature Security — eFuseベースの機能ロックの有効化（プログラムされたeFuseビットに基づいて利用可能なホストインターフェースと機能を制限）。
• PS2 Keyboard — PS/2のDATAおよびCLKライン用GPIOピン割り当て。
• Host Interface — 以下のGPIOピン割り当て：
  • KDB0-KDB3（ホストからの行選択入力）
  • KDO0-KDO7（ホストへの列データ出力）
  • RTSNI（行ストローブ入力）
  • MPXI（マルチプレクス選択入力）
  • KDI4（追加データ入力）
• Mouse UART — ホストへのマウスシリアル出力用にソフトウェアビットバンギングとハードウェアUARTの選択。
• WiFi — WiFiの有効/無効、デフォルトSSIDとパスワード、チャンネル番号、最大同時接続数の設定。
• Debug Options — シリアルデバッグ出力の有効化、およびハードウェア隔離テスト用の個別GPIOグループの無効化（KDB、KDO、RTSNI、MPXI、KDIの無効化）。
• Power LED — ステータスLED用GPIOピン割り当て。

Dockerビルド

# Simple Docker build
docker run --rm -v $(pwd):/project -w /project espressif/idf:v4.4 idf.py build

# Jenkins sibling container build (host path mapping)
docker run --rm \
    -v "${hostWorkspace}:${workspace}" \
    -w "${workspace}" \
    espressif/idf:v4.4 \
    idf.py build

---

継続的インテグレーション

Jenkinsパイプライン概要

1. Checkout — ワークスペースのクリーン、GiteaからのSharpKeyリポジトリのクローン、およびすべてのGitサブモジュール（arduino-esp32とesp_littlefs）の初期化。
2. Determine Version — リポジトリからversion.txtを読み取り。前回のコミットからバージョンが変更されていない場合、最新のGiteaリリースタグからバージョン番号を自動インクリメント。
3. Build Web Filesystem — build_webfs.shを実行してWebインターフェースアセットをwebfs/ステージングディレクトリにコピーおよび圧縮。
4. Generate eFuse Table — IDF Dockerコンテナ内でefuse_table_gen.pyを実行し、CSVソースからesp_efuse_custom_table.cおよび.hを生成。
5. Build Firmware — IDF Dockerコンテナ内でidf.py buildを使用してファームウェアをコンパイル。
6. Package Release — 3つのリリースアーカイブを作成：FW（ファームウェアバイナリ）、FilePack（Webファイルシステムイメージ）、FlashPack（完全なフラッシュイメージ）。
7. Create Gitea Release — バージョン番号でタグ付けした新しいGiteaリリースにリリース成果物をアップロード。

Webhook設定

• Webhook URL — https://<jenkins-host>/generic-webhook-trigger/invoke?token=sharpkey-build-trigger
• Token — sharpkey-build-trigger
• Content Type — application/json
• Branch Filter — refs/heads/mainまたはrefs/heads/masterへのプッシュでのみトリガー。フィーチャーブランチ、タグ、およびその他のrefへのプッシュは無視されます。

バージョン管理

• トリガーコミットでversion.txtが変更されている場合、ファイルに指定されたバージョンがそのままリリースに使用されます。
• version.txtが変更されていない場合、パイプラインはGitea APIに最新のリリースタグを照会し、マイナーバージョン番号を自動インクリメントします。
• マイナーバージョンは100でロールオーバーします：バージョン1.99は2.00にインクリメントされます（メジャーバージョンが1増加、マイナーが00にリセット）。
• バージョン文字列はファームウェアバイナリヘッダーに埋め込まれ、Webインターフェースで表示するためにwebserver/version.txtにも書き込まれます。

リリース成果物

成果物	内容	使用ケース
SharpKey-FW-vX.XX.bin.gz	ファームウェアアプリケーションバイナリ	Webインターフェース経由のOTAアップデート（ota_0/ota_1に書き込み）
SharpKey-FilePack-vX.XX.bin.gz	LittleFS Webファイルシステムイメージ	Webインターフェースのみの OTAアップデート（filesysに書き込み）
SharpKey-FlashPack-vX.XX.tar.gz	完全なフラッシュイメージ：ブートローダー、パーティションテーブル、OTAデータ、ファームウェア、ファイルシステム	esptool（シリアル）による初期書き込み

# Extract and flash the FlashPack
tar xzf SharpKey-FlashPack-v1.05.tar.gz
esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 \
    write_flash --flash_mode dio --flash_size 4MB \
    0x1000 bootloader.bin \
    0x8000 partition-table.bin \
    0x9000 ota_data_initial.bin \
    0x10000 sharpkey.bin \
    0x3A0000 filesys.bin

パイプライン設定

変数	用途
GITEA_URL	Giteaインスタンスのベース URL（例：https://git.eaw.app）
REPO_URL	SharpKeyリポジトリの完全なクローンURL
GITEA_TOKEN	リリースの作成とアセットのアップロード用APIトークン
GITEA_OWNER	リポジトリオーナー（例：”eaw”）
GITEA_REPO	リポジトリ名（例：”SharpKey”）
IDF_DOCKER	ESP-IDF Dockerイメージタグ（例：”espressif/idf:v4.4”）

// Groovy path mapping
def hostWorkspace = workspace.replace('/var/jenkins_home', '/srv/jenkins/data')

// The IDF container mounts the host path, not the Jenkins container path
docker run --rm \
    -v "${hostWorkspace}:${workspace}" \
    -w "${workspace}" \
    espressif/idf:v4.4 \
    idf.py build

eFuseテーブル生成

# Run inside the IDF Docker container
python /opt/esp/idf/components/efuse/efuse_table_gen.py \
    --idf_target esp32 \
    /opt/esp/idf/components/efuse/esp32/esp_efuse_table.csv \
    main/esp_efuse_custom_table.csv

---

デバッグ

シリアルモニター

idf.py -p /dev/ttyUSB0 monitor

• 受信したPS/2スキャンコード（生データおよびデコード済み）
• キーマッピング検索（どのテーブルエントリが一致したか）
• マトリクス状態変更（各キー押下/リリースの行と列）
• Bluetoothペアリングイベントおよび HIDレポート
• WiFi接続状態の変化
• ブート時のホスト検出結果
• NVS読み書き操作

GPIOデバッグフラグ

Kconfigオプション	効果
DEBUG_DISABLE_KDB	ホスト行選択入力（KDB0-KDB3）の無効化。インターフェースタスクは行アドレスを読み取りません。
DEBUG_DISABLE_KDO	ホストデータ出力（KDO0-KDO7）の無効化。ホストに列データが駆動されません。
DEBUG_DISABLE_RTSNI	行ストローブ入力（RTSNI）の無効化。インターフェースタスクはストローブ信号を待ちません。
DEBUG_DISABLE_MPXI	マルチプレクス選択入力（MPXI）の無効化。
DEBUG_DISABLE_KDI	追加データ入力（KDI4）の無効化。

よくある問題

• ADC2/WiFi GPIOの競合 — GPIO 0、2、4、12、13、14、15、25、26、27はADC2ペリフェラルと共有されており、WiFiがアクティブな間はデジタルI/Oに使用できません。reconfigADC2Ports()メソッドがこれを自動的に処理しますが、これらのピンに新しいGPIO割り当てを追加する場合は、WiFi初期化後に再設定されることを確認してください。
• eFuseファイルが見つからない — esp_efuse_custom_table.hが見つからずビルドが失敗する場合、CSVソースファイル（main/esp_efuse_custom_table.csv）がコミットされていることを確認し、メインビルドの前にefuse_table_gen.pyが実行されることを確認してください。CIではこれは個別のパイプラインステージです。ローカルビルドではidf.py buildがこれを自動的に処理するはずですが、初回ビルドでは手動実行が必要な場合があります。
• サブモジュールエラー — arduino-esp32またはesp_littlefsコンポーネントが見つからないことに関連するビルドエラーは、Gitサブモジュールが初期化されていないことを示しています。git submodule update --init --recursiveを実行して解決してください。
• MZ-2500/2800でのタイミング問題 — ホストマシンがキー押下を認識しない、またはランダムな文字が表示される場合、以下を確認してください：
  • インターフェースタスクがCore 1に固定されていること（xTaskCreatePinnedToCore(..., 1)）
  • タスク関数がIRAM_ATTRでマークされていること
  • portMUX_TYPEスピンロックが使用されていること（FreeRTOS mutexではなく）
  • ホットループ内でFreeRTOS API呼び出しが行われていないこと
  • GPIOレジスタアクセスが使用されていること（オーバーヘッドが追加されるgpio_set_level()ではなく）
• WiFi/Bluetoothモード切り替え — ESP-IDFのWiFiとBluetoothスタックは共存できません。モード切り替えには完全な再起動が必要です。切り替え後にファームウェアがハングする場合、esp_restart()を呼び出す前にモード選択がNVSに保存されていることを確認してください。
• Webファイルシステムが見つからない — Webインターフェースが404エラーを返す場合、ビルド前にbuild_webfs.shが実行されていること、およびfilesysパーティションが書き込まれていることを確認してください。FilePack OTAイメージを個別にアップロードして、Webファイルシステムのみを更新できます。
• PS/2キーボードが検出されない — DATA（GPIO 14）とCLK（GPIO 13）ラインが正しく接続されていることを確認してください。PS/2クロックラインは割り込み駆動です — 他のペリフェラルによって割り込みがマスクされていないか確認してください。スキャンコードが受信されているかどうかを確認するためにシリアルデバッグを有効にしてください。

---

参考サイト

• ESP-IDFプログラミングガイド（v4.4） — https://docs.espressif.com/projects/esp-idf/en/v4.4/
  FreeRTOS、GPIO、WiFi、Bluetooth、NVS、OTA、およびパーティションテーブルのドキュメントを含む、ESP-IDFフレームワークの完全なAPIリファレンスおよびプログラミングガイド。
• SharpKeyリポジトリ — https://git.eaw.app/eaw/SharpKey
  SharpKeyプロジェクトのソースコード、イシュー、リリース、およびCI/CDパイプライン。
• PS/2プロトコルリファレンス — PS/2キーボードプロトコルは、11ビットシリアルフレーム（1スタートビット、8データビット、1パリティビット、1ストップビット）を使用するスキャンコードセット2を使用します。クロックは10-16.7kHzでキーボードによって駆動されます。PS2KeyAdvancedライブラリは拡張キー（E0プレフィックス）、ブレイクコード（F0プレフィックス）、およびポーズ/ブレイクシーケンスを含むすべてのプロトコル詳細を処理します。
• ESP32テクニカルリファレンスマニュアル — GPIOレジスタ（GPIO_OUT_REG、GPIO_OUT_W1TS_REG、GPIO_OUT_W1TC_REG、GPIO_IN_REG、GPIO_IN1_REG）、割り込みマトリクス、およびWiFiとのADC2競合を含むペリフェラル割り当てをカバーするEspressifのハードウェアリファレンス。
• FreeRTOSリファレンス — ESP32デュアルコアアプリケーション向けのタスク作成、スピンロック（portMUX_TYPE）、コアピニング（xTaskCreatePinnedToCore）、およびIRAM_ATTR使用法。
• GNU General Public License v3 — SharpKeyはGPL v3の下でリリースされています。すべての派生著作物は同じライセンス条件を維持する必要があります。

---

---

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