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

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

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

Tip

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

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

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

  • USBケーブルを抜き差しすると、デバイス名が変わることがある（とくにmacOS）

  • 複数のUSBデバイスが接続されている場合、どれが検出器かわからない

  • 間違ったポートを指定すると、データ収集が失敗する

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

📋 基本的な使い方#

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

haniwers-v1 port list

出力例（macOS）:

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）:

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

出力例（Windows）:

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: 接続テスト#

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

成功時の出力:

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検出器がデータを送信している

  • データ形式が有効

  • データ収集を開始できる

よくあるテスト結果#

✓ 成功#
✓ Port test successful (response in 1.23s)

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

✗ タイムアウト#
✗ 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ケーブルが破損していないか確認

✗ 無効なデータ#
✗ Received data but format is invalid
  Error type: invalid_data
  Data sample: ???garbage???

対処:

  1. DAQ設定でボーレートを確認

  2. 検出器を抜き差ししてみる

  3. 実際にOSECHI検出器であるか確認

✗ 権限エラー#
✗ Permission denied
  Error type: permission

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

対処:

  • sudoで実行（一時的）

  • dialout/uucpグループに自分を追加（恒久的）

✗ ポートビジー#
✗ Port is already in use
  Error type: port_busy

対処:

  1. ポートを使用している他のプログラムを閉じる

  2. 別のhaniwersプロセスが実行中でないか確認

  3. 必要に応じて再起動

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

実際のセッション例：

# 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）

  • 接続問題を早期に発見できます

ポートパスを保存#

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

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

または環境変数で：

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

複数の検出器#

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

  • それぞれ異なるデバイスパスに接続されます

  • port listで表示される説明やメーカー情報で区別できます

  • 各ポートを個別にテストします

デバッグ#

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

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グループに追加する必要があるかもしれません：

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

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

Windows#

  • ポートはCOM3、COM4などとして表示されます

  • COM1とCOM2は通常予約されています

  • ポート番号が不明な場合は、デバイスマネージャーで確認

  • 通常、権限の問題はありません

🔗 関連ドキュメント#

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

目次