# WSL USB Identity Manager

*[English](README.md) | [日本語](README.ja.md)*

[usbipd-win](https://github.com/dorssel/usbipd-win) で USB デバイスを WSL に転送する環境で、
**どれがどの物理デバイスなのか**を確実に把握するためのツール。

> 要件は [docs/requirements.ja.md](docs/requirements.ja.md) を参照してください。

![デバイス一覧。シリアル番号を持たない CH340 が 2 個、それぞれの先の ESP32 で区別されている](docs/images/main-window.png)

*シリアル番号を持たない CH340 が 2 個。ケーブルの先のボードで区別されている。*

## 解決する問題

WSL への USB 転送は動きます。同じアダプタが 2 個以上になるまでは。

- **CH340 はシリアル番号を持ちません。** 3 個挿さっていても、USB 記述子には
  区別できる情報が存在しません。Windows が答えられるのは
  「どのポートに刺さっているか」までです。
- **BUSID は安定した名前ではありません。** `usbipd` の BUSID は
  `Hub_#NNNN` と `Port_#MMMM` の組であり、ハブ番号は Windows がハブを
  認識した順に振られます。ドックを後から接続すれば、その先のデバイスの
  BUSID は全部変わります。**同じ BUSID が別のデバイスを指すようになります。**
- **COM 番号も `/dev/ttyUSB*` も**同じ理由で動きます。
- **アダプタやプローブが名乗るのは自分自身で、その先にあるものではありません。**
  CH340 のシリアル番号は（あったとしても）アダプタのものであって、
  配線されたボードのものではありません。WCH-LinkE のシリアル番号はプローブのもので、
  デバッグピンのボードを載せ替えてもその番号は変わりません。

つまり「CH340 を Ubuntu に attach して」という指示が、現状のツールでは成立しません。

## 何を識別するのか

「このデバイス」と言うとき、普通は手前のアダプタではなく**ボード**を指しています。
1 本のケーブルの先には、最大で 3 つの別々のものがあります。

| | 例 | 識別手段 |
| --- | --- | --- |
| **Port** | BUSID、`COM8`、`/dev/ttyUSB2` | 物理トポロジパス — 永続化しない |
| **Transport** | CH340、CH343、WCH-LinkE | USB 記述子（シリアル番号がある場合） |
| **Target** | ESP32-S3、CH32X035 | **ボード自身に問い合わせる** |

**アダプタやプローブの先にある Target まで識別することが、本ツールの目的です。**
ネイティブ USB のボードは Transport と Target が同一なので、
シリアル番号だけで足ります。それ以外はボードに聞くしかありません。

### 現在対応している Target

| 系統 | 識別に使うもの |
| --- | --- |
| **ESP32 系**（CH340 / CP210x 等の裏） | eFuse MAC とチップ種別 |
| **CH32 RISC-V 系**（WCH-Link / WCH-LinkE の先） | 工場出荷時 UUID とチップ署名（[ch32rv](https://github.com/ch32-riscv-ug/ch32rv) 経由） |

それ以外（Arduino、RP2040、STM32、または不明なボードが繋がった生のアダプタ）は
**Transport までの識別に留まり**、そのことを隠さずに表示します。
系統の追加は、識別処理を足すだけで済む構造にします。

## できること

**共有と接続。** WSL がデバイスを受け取るには先に `usbipd` が共有している必要があるので、
各行で共有 → 接続 → 切り離し → 共有をやめる、を使う順に並べています。
共有には管理者権限が要ります。昇格を求めるのはその瞬間だけで、
アプリ自身は管理者権限なしで動きます。
共有の記録だけが残っている（共有したまま抜いた）デバイスも、共有をやめられます。

**識別。** 行の「未識別」を押すと、ボード自身に何なのかを尋ねます。
シリアル番号を持たないデバイスは、接続直後のまだ誰も使っていない数秒の間に自動で識別します。
これは切れますし、VID:PID 単位で除外もできます。
シリアル番号を申告するアダプタはこの自動識別の対象外なので、残りは一括識別で拾えます。

**自動接続。** 条件はボード ID / USB シリアル番号 / VID:PID / BUSID のいずれかでデバイスを指定し、
一致したデバイスは `usbipd` が共有した時点で WSL に渡されます。
切り替えはダイアログの奥ではなくツールバーに置いています。

意図的にやらないことが 2 つあります。**自動で共有はしません** —
管理者権限が要るので、自動処理が UAC を出すべきではないためです。
そして **接続するかどうかを決めるために識別もしません** —
ボード ID の条件は、別の理由で識別されるまで黙って待ちます。

## 方針

**「どこに接続されているか」**と**「それが何という物理デバイスなのか」**を分離します。

| | 例 | 扱い |
| --- | --- | --- |
| Runtime Connection | BUSID、COM 番号、`/dev/ttyUSB0`、Attach 状態 | 表示のみ。名前として使わない |
| USB Identity | VID/PID、USB シリアル、ポートパス | 毎回 Windows から取得 |
| Target Identity | 基板そのものから読んだ ID | 接続されている間だけ保持 |
| 前回までの情報 | 各デバイスが最後に持っていた名前とボード ID | 保存する。グレー表示で、判断には使わない |
| ユーザーが決めたこと | 自動 Attach の条件、触ってほしくない相手 | 保存する |

USB 記述子から特定できないものは、**接続先の基板そのものに問い合わせて**識別します。
これは [board-identify](https://github.com/tanakamasayuki/board-identify) が Linux 側で
到達したのと同じ結論です。

ただし問い合わせは対象を乱します。ESP32 の eFuse MAC を読めばファームウェアが再起動し、
WCH-Link に attach すればターゲットのコアが止まります。
そのため本ツールは**定期的な問い合わせを行いません**。
ボタンを押したとき、あるいは誰も使っていない接続直後の短い時間内にのみ実行します。

**識別結果は、デバイスを抜いた時点で破棄します。**
CH340 の先の基板が、抜かれている間に載せ替えられたかどうかを USB は教えてくれません。
覚えておけば、それは事実の顔をした推測になります。
抜いて挿し直せば、そのデバイスは再び未識別です。識別を押すか、接続直後の自動識別に任せてください。
未識別のものは未識別と表示されます。**別の機器かもしれない名前を出すことはありません。**

## スコープ

本ツールが受け持つのは Windows 側です。
デバイスの列挙、識別、`usbipd` の状態と操作、そして自動で WSL に接続する条件の管理。

**WSL 内部は管理しません。** udev ルールもデバイスノードの権限も
シンボリックリンクも、既存の Linux 側の仕組みに委ねます。
情報が取得できる場合に表示するだけで、変更は行いません。

## 動作要件

- Windows 10 / 11（x64）
- [usbipd-win](https://github.com/dorssel/usbipd-win) 5.x
- WSL 2
- WebView2 Runtime — Windows 11 には同梱。Windows 10 でも大多数の端末に導入済み

## インストール

[最新リリース](https://github.com/tanakamasayuki/wsl-usb-identity-manager/releases/latest) からインストーラまたはポータブル ZIP を取得してください。

| | |
| --- | --- |
| `wsl-usb-identity-manager_<version>_x64_setup.exe` | 現在のユーザーにインストール。管理者権限は不要 |
| `wsl-usb-identity-manager_<version>_x64_portable.zip` | 展開して実行。設定とログを実行ファイルの隣に置く |

**コード署名はしていません。** ダウンロードの実績が積み上がるまで、
初回起動時に Windows SmartScreen の警告が出ます。

## ドキュメント

各ドキュメントは英語版と日本語版があり、先頭で相互にリンクしています。

- [要件定義](docs/requirements.ja.md)
- [実測で確認した事実](docs/research-findings.ja.md) — 本設計の根拠となる測定値
- [識別ポリシー](docs/identification-policy.ja.md)
- [リリース手順](docs/release.ja.md) — 手元でのビルド方法も

## 関連プロジェクト

- [board-identify](https://github.com/tanakamasayuki/board-identify) — WSL 側の対応ツール。
  WSL 内に安定したシンボリックリンクを発行する
- [ch32rv](https://github.com/ch32-riscv-ug/ch32rv) — WCH-Link プローブの実装
- [usbipd-win](https://github.com/dorssel/usbipd-win) — 本ツールが操作する USB/IP ホスト

## ライセンス

MIT。[LICENSE](LICENSE) を参照。