Raspberry Pi Zero 2 W を USBキーボード(HID)化＋Bluetoothキーボード併用で開発する環境構築ガイド

---

## なぜ「USB OTG ガジェット(HID)」と「Bluetoothキーボード」を同時に使うのか？

- **Raspberry Pi Zero 2 W** を **USB OTG ガジェットモード**で「HIDキーボード」にすると、**ターゲットPC** は Pi を「USBキーボード」としてしか認識しなくなります。  
- その状態では Pi の USBポートは **"デバイス側"** として使われており、**PiにUSBキーボードやマウスを差し込む**ことはできません。  
- しかし、Pi 上で HID関連のコードを編集・実行したり、OSを操作したりという **“開発・セットアップ作業”** も同時に行いたい場合が多いです。  

この問題を解決するため、**Pi Zero 2 W が Bluetoothホストになり、外部のBluetoothキーボードを受け入れる**ようにすれば、**Piへの入力手段を確保**しつつ、**同時に USBケーブル越しにターゲットPCへHIDキーボード入力を送る**ことが可能になります。

---

## ポイント: 「Bluetoothキーボードを使えるようになる前」に通常のUSBキーボードでセットアップ

1. **最初は Pi をUSBホストモードで使い、普通のUSBキーボードを挿して操作**  
   - なぜなら、Bluetoothキーボードのペアリング設定を行うには、Pi上でのコマンド操作やGUI操作が必要。  
   - その操作をするために、一時的にUSBキーボード（またはSSH）でPiに入力できる状態を作るのが最も簡単。

2. **Bluetoothキーボード設定完了 → USBホストは不要**  
   - 一度 Bluetoothキーボードがペアリングされれば、Pi 側でいつでもキーボード入力を受け取れるように。  
   - その後は、**USBポートをデバイスモードに切り替え**、**Pi がターゲットPCに「HIDキーボード」として接続**していても問題なく開発できる。

---

## 構成イメージ

```mermaid
flowchart LR
    subgraph Raspberry Pi Zero 2 W
       B[1 USB ホストモード<br>一時的に普通のUSBキーボードで操作 → BT設定]
       C["2 USB デバイスモード(HID)<br>ターゲットPCへ<br>キーボードエミュレート"]
       D[Bluetoothホスト<br>外部BTキーボード<br>でPiを操作]
    end
    A[通常USB<br>キーボード] --初期セットアップ--> B
    D <--ペアリング--> BTK[Bluetooth<br>キーボード]
    C --> PC[ターゲットPC<br>USBホスト]
```

- **最初**: PiをUSBホストモード + 通常USBキーボード でセットアップ  
- **Bluetoothキーボード** をペアリング  
- **本番**: PiをUSBデバイスモード(HID) でターゲットPCに挿し、Pi上の操作はBluetoothキーボードで行う  

---

## ステップ1: Raspberry Pi OS のインストール & 初回起動

1. **microSD への OS 書き込み**  
   - Raspberry Pi Imager 等で **Raspberry Pi OS (Lite でも可)** を書き込む。  
   - SSHやWi-Fiの初期設定を仕込んでもOK。  
2. **初回起動 → aptアップデート**  
   - `sudo apt-get update && sudo apt-get upgrade -y`  
3. **Pi をUSBホストモードで使えるようにする**  
   - Pi Zero 2 W でUSBホストを使う場合、**OTGアダプタ**を介してフルサイズUSBキーボードを接続。  
   - モデルによっては `/boot/config.txt` に `dtoverlay=dwc2` を入れたりするが、Pi Zeroではたいてい自動的にホスト化できる場合もある（必要に応じて調べてください）。  
4. **通常USBキーボードを挿してコンソール操作可能になったら OK**  

---

## ステップ2: Bluetoothキーボードのセットアップ

1. **bluetoothctl (CLI) の利用**  
   - `sudo bluetoothctl`  
   - `power on`, `agent on`, `default-agent`, `scan on` …などでペアリング。  
   - `pair XX:XX:XX:XX:XX:XX`, `trust XX:XX:XX:XX:XX:XX`, `connect XX:XX:XX:XX:XX:XX`  
2. **GUI(デスクトップ版) の場合**  
   - 右上Bluetoothアイコン → “Add Device” → デバイス名選択 → ペアリング。  
3. **動作確認**  
   - ペアリング完了後、Bluetoothキーボードから文字を打ってみて、Pi のターミナルに反映されることを確認。  
4. **不要になったら、通常USBキーボードを外す**  
   - 以後はBluetoothキーボードだけで Pi の操作が可能。  

---

## ステップ3: USB OTG ガジェット(HID) 設定

### 3-1. config.txt / cmdline.txt の編集

1. **`/boot/config.txt`** に:
   ```txt
   dtoverlay=dwc2
   ```
2. **`/boot/cmdline.txt`** の `rootwait` の後ろに:
   ```txt
   modules-load=dwc2,libcomposite
   ```
3. 再起動

### 3-2. HIDガジェットの有効化スクリプト (例)

```bash
sudo modprobe libcomposite
cd /sys/kernel/config/usb_gadget
sudo mkdir mykeyboard
cd mykeyboard

# ベンダーID, プロダクトID 等
echo 0x1d6b > idVendor
echo 0x0104 > idProduct
echo 0x0200 > bcdUSB
echo 0x0100 > bcdDevice

mkdir strings/0x409
echo "1234567890" > strings/0x409/serialnumber
echo "MyPiVendor"  > strings/0x409/manufacturer
echo "MyPiKeyboard" > strings/0x409/product

mkdir configs/c.1
mkdir configs/c.1/strings/0x409
echo "Config 1: Keyboard" > configs/c.1/strings/0x409/configuration
echo 120 > configs/c.1/MaxPower

mkdir functions/hid.usb0
echo 1 > functions/hid.usb0/protocol
echo 1 > functions/hid.usb0/subclass
echo 8 > functions/hid.usb0/report_length
cat /home/pi/keyboard_report.desc > functions/hid.usb0/report_desc

ln -s functions/hid.usb0 configs/c.1/
echo "20200000.usb" > UDC
```

- これを実行後、**Pi Zero 2 W の「データ用MicroUSBポート」** をターゲットPCに挿せば、**PCに“USBキーボード”** として認識される。  

---

## ステップ4: 開発フロー

1. **Pi → PC (USB) : HIDキーボード**  
   - Pythonなどで `/dev/hidg0` に書き込む → ターゲットPCにキー入力が注入される。  
2. **Bluetoothキーボード → Pi**  
   - Pi 上でコマンドを打ってスクリプトを実行したり、編集したり。  
   - これにより、**Pi がUSBデバイスモードであっても**、Pi上の操作手段を失わない。  

---

## まとめ

1. **最初に通常USBキーボードでBluetooth設定**  
   - ここが最大のハマりどころ。Bluetoothキーボードを使うにはセットアップが必要だが、そのセットアップ自体にキーボード入力が要る、というジレンマ。  
   - 一時的にPiをUSBホスト化し、普通のUSBキーボードを挿して設定を済ませよう。

2. **Bluetoothキーボード が使えたら、USBポートをデバイスモード(HIDガジェット)に**  
   - ターゲットPCに対し、Piが「仮想キーボード」として動作。  
   - 開発者はBluetoothキーボードでPiを操作し、HIDコードを書く・実行する。

3. **これで「Pi上で開発しながらターゲットPCにキーストロークを注入する」**環境が完成  
   - SSH不要でスタンドアロンに近いかたちで利用できる点が大きなメリット。

---

## よくある質問 (FAQ)

- **Q1. USBホストモードとデバイスモードをどう切り替える？**  
  - `dwc2` の設定やケーブル(OTGアダプタ)次第で、Piがホストになるかデバイスになるかが変わる。  
  - Pi Zero 2 W は標準では「OTGケーブル」でホスト化が可能、「普通のMicro USBケーブル」でPCと繋ぐとデバイス化…など物理接続でも変わる。  

- **Q2. bluetoothctl は GUI？**  
  - **いいえ**、CUI (コマンドライン) ツールです。 デスクトップ版ならBluetoothアイコン(アプレット)でも設定できる。  

- **Q3. 消費電力は？**  
  - Pi Zero 2 W がWi-Fi + Bluetooth同時稼働すると多少電力を食うが、大抵はPCのUSBポート給電でも動く。心配ならセルフパワーUSBハブや5Vアダプタで電源を確保。  

- **Q4. HIDレポートデスクリプタがわからない**  
  - これはUSB HIDの仕様。最小限のキーボード用デスクリプタを使えばOK。例として `keyboard_report.desc` を用意して書き込む手順が多い。  

---

## 最終チェック

- **全体構成**：問題なし。「最初に通常USBキーボード→BT設定→USBデバイスモードへ切り替え」の流れが明確。  
- **用語**：表記ゆれや誤字は修正済み。  
- **追加説明**：Bluetoothキーボードが使えるようになる前のジレンマがしっかり解説されている。  

---

## 参考リンク

- [Raspberry Pi公式ドキュメント](https://www.raspberrypi.com/documentation/)  
- [bluez / bluetoothctl (Linux向けBluetooth実装)](https://www.bluez.org/)  
- [過去の記事: HIDガジェット化の前編・後編](前編後編のURLなど)

---

以上