# ポート管理：デバイスの接続確認

データ収集（DAQ）を開始する前に、OSECHI検出器が正しいシリアルポートに接続されているかを確認する必要があります。`haniwers-v1 port`コマンドは、この作業を簡単にします。

:::{tip}
**はじめての方へ**: ポート名は環境によって変わります（`/dev/ttyUSB0`、`COM3`など）。測定の前に必ず`port list`と`port test`で接続を確認しましょう。
:::

---

## 🤔 なぜポート管理が必要なのか？

シリアルポートのデバイスパス（例：`/dev/ttyUSB0`や`COM3`）は、以下の理由で変化することがあります：

- USBケーブルを抜き差しすると、デバイス名が変わることがある（とくにmacOS）
- 複数のUSBデバイスが接続されている場合、どれが検出器かわからない
- 間違ったポートを指定すると、データ収集が失敗する

`port`コマンドを使えば、**測定を始める前に正しいポートを特定**できます。

---

## 📋 基本的な使い方

### ステップ1: 利用可能なポートを一覧表示

```bash
haniwers-v1 port list
```

**出力例（macOS）**:

```text
INFO     | Found 2 ports
INFO     | Port0: /dev/cu.Bluetooth-Incoming-Port - n/a
INFO     | Port1: /dev/cu.usbserial-140 - USB Serial (Silicon Labs)
INFO     | Please use '/dev/cu.usbserial-140' as your device path
```

**出力例（Linux）**:

```text
INFO     | Found 1 port
INFO     | Port0: /dev/ttyUSB0 - USB Serial (FTDI)
INFO     | Please use '/dev/ttyUSB0' as your device path
```

**出力例（Windows）**:

```text
INFO     | Found 1 port
INFO     | Port0: COM3 - USB Serial Port (Prolific)
INFO     | Please use 'COM3' as your device path
```

#### 見るべきポイント

🔍 **OSECHI検出器のポートの特徴**：

- 説明に「USB Serial」または「UART」が含まれている
- メーカーが「Silicon Labs」、「FTDI」、「Prolific」のいずれか
- macOS: `/dev/cu.usbserial-*`
- Linux: `/dev/ttyUSB0`または`/dev/ttyACM0`
- Windows: `COM3`以上

:::{tip}
コマンドが自動的に推奨ポートを表示します！
:::

#### トラブルシューティング

❌ **「No ports found」**

- USBケーブルが接続されているか確認
- 別のUSBポートを試す
- PCを再起動してみる

❌ **「Permission denied」**（Linux/macOS）

- `sudo`で実行: `sudo haniwers-v1 port list`
- または、ユーザーを`dialout`/`uucp`グループに追加（恒久的な解決策）

### ステップ2: 接続テスト

```bash
# デバイスパスを置き換えてください
haniwers-v1 port test /dev/cu.usbserial-140
```

**成功時の出力**:

```text
Testing connection to /dev/cu.usbserial-140...

✓ Port test successful (response in 1.23s)
  Data sample: 2 0 0 936 27.37 100594.35 41.43

✓ Data format valid
  - Event counts: top=2, mid=0, btm=0
  - Temperature: 27.37°C
  - Pressure: 100594.35 Pa
  - Humidity: 41.43%

✓ This port is ready for data acquisition!
```

#### 結果の見方

**成功した場合**、以下が表示されます：

- ✓ 応答時間（5秒未満が正常）
- ✓ データサンプル行
- ✓ 解析された値（温度、気圧など）
- ✓ 確認メッセージ

**これは以下を意味します**：

- ポートが正しく動作している
- OSECHI検出器がデータを送信している
- データ形式が有効
- データ収集を開始できる

#### よくあるテスト結果

##### ✓ 成功

```text
✓ Port test successful (response in 1.23s)
```

**対処**: このポートでデータ収集を開始してください！

##### ✗ タイムアウト

```text
✗ No data received within 5 seconds
  Error type: timeout

Possible causes:
  - Device is not an OSECHI detector
  - Detector is not powered on
  - Wrong baud rate (check DAQ config)
```

**対処**:

1. 検出器の電源を確認
2. `port list`から別のポートを試す
3. USBケーブルが破損していないか確認

##### ✗ 無効なデータ

```text
✗ Received data but format is invalid
  Error type: invalid_data
  Data sample: ???garbage???
```

**対処**:

1. DAQ設定でボーレートを確認
2. 検出器を抜き差ししてみる
3. 実際にOSECHI検出器であるか確認

##### ✗ 権限エラー

```text
✗ Permission denied
  Error type: permission

On Linux/macOS, try:
  sudo haniwers-v1 port test /dev/ttyUSB0
```

**対処**:

- `sudo`で実行（一時的）
- `dialout`/`uucp`グループに自分を追加（恒久的）

##### ✗ ポートビジー

```text
✗ Port is already in use
  Error type: port_busy
```

**対処**:

1. ポートを使用している他のプログラムを閉じる
2. 別のhaniwersプロセスが実行中でないか確認
3. 必要に応じて再起動

---

## 🔄 完全なワークフロー例

実際のセッション例：

```bash
# 1. 利用可能なポートを探す
$ haniwers-v1 port list
INFO     | Found 2 ports
INFO     | Port0: /dev/cu.Bluetooth-Incoming-Port - n/a
INFO     | Port1: /dev/cu.usbserial-140 - USB Serial (Silicon Labs)
INFO     | Please use '/dev/cu.usbserial-140' as your device path

# 2. 接続をテスト
$ haniwers-v1 port test /dev/cu.usbserial-140
Testing connection to /dev/cu.usbserial-140...
✓ Port test successful (response in 1.23s)
✓ This port is ready for data acquisition!

# 3. 確認したポートでデータ収集を開始
$ haniwers-v1 daq
# (hnw.tomlでdevice.port=/dev/cu.usbserial-140に設定されていることを確認)
```

---

## 💡 ヒントとベストプラクティス

### 測定セッションの前に毎回実行

データ収集を開始する前に、必ず`port list`と`port test`を実行してください：

- ポートは変化する可能性があります（とくにmacOS）
- USBポートが再割り当てされることがあります（とくにWindows）
- 接続問題を早期に発見できます

### ポートパスを保存

正しいポートを見つけたら、設定ファイルに保存しておきましょう：

```toml
# hnw.toml
[device]
port = "/dev/cu.usbserial-140"
```

または環境変数で：

```bash
# .env.haniwersに追加
echo "HANIWERS_DEVICE_PORT=/dev/cu.usbserial-140" >> .env.haniwers
```

### 複数の検出器

複数のOSECHI検出器がある場合：

- それぞれ異なるデバイスパスに接続されます
- `port list`で表示される説明やメーカー情報で区別できます
- 各ポートを個別にテストします

### デバッグ

より詳細な出力が必要な場合は、`--log-level DEBUG`を追加：

```bash
haniwers-v1 port list --log-level DEBUG
haniwers-v1 port test /dev/ttyUSB0 --log-level DEBUG
```

---

## 📖 サマリーチートシート

| コマンド | 目的 | いつ使うか |
|---------|------|-----------|
| `port list` | すべての利用可能なポートを表示 | 最初のステップ、常に |
| `port test <device>` | 通信をテスト | データ収集の前 |

**典型的なワークフロー**: `list` → `test` → `daq`

---

## ❓ よくある質問

**Q: どのポートがOSECHI検出器ですか？**

A: 説明に「USB Serial」または「UART」があるものを探してください。`port list`コマンドが自動的に推奨します。

**Q: ある日は動作するのに、次の日は動作しません**

A: ポートパスが変更された可能性があります。常に最初に`port list`を実行してください。

**Q: テストステップをスキップできますか？**

A: できますが、テストを実行すると接続問題を早期に発見でき、時間を節約できます。

**Q: テストがタイムアウトしたら？**

A: 電源を確認、別のポートを試す、USBケーブルを確認してください。

---

## 🖥️ プラットフォーム固有の注意事項

### macOS

- ポートは`/dev/cu.*`と`/dev/tty.*`として表示されます
- `cu.*`バージョンを使用してください（`tty.*`ではありません）
- USB再接続時にポートパスが変更される可能性があります
- 通常、特別な権限は不要です

### Linux

- ポートは`/dev/ttyUSB*`または`/dev/ttyACM*`として表示されます
- ユーザーを`dialout`グループに追加する必要があるかもしれません：

  ```bash
  sudo usermod -a -G dialout $USER
  # ログアウトしてログインし直す
  ```

- または各コマンドで`sudo`を使用（一時的）

### Windows

- ポートは`COM3`、`COM4`などとして表示されます
- COM1とCOM2は通常予約されています
- ポート番号が不明な場合は、デバイスマネージャーで確認
- 通常、権限の問題はありません

---

## 🔗 関連ドキュメント

- [設定ファイルの作成](./config.md): ポート設定の保存方法
- [データ収集（DAQ）](./daq.md): ポート確認後のデータ収集手順
- [トラブルシューティング](./data-quality.md): データ品質とノイズ対処

---

**最終更新**: 2025-10-21
**機能バージョン**: 007-port-cli (v1.0.0)