シリアル通信の問題¶

このガイドでは、kazunokoとOSECHIミューオン検出器間のシリアル通信に関する問題と解決方法を説明します。

シリアル通信とは¶

シリアル通信 は、USBケーブルを通じてコンピューターとデバイス間でデータを1ビットずつ順番に送受信する方式です。

PC ← → USB ← → OSECHI Detector
   (シリアル通信)

kazunoko は以下の設定でシリアル通信を行います。

設定	値
通信方式	RS-232
ボーレート	115200 bps
データビット	8
ストップビット	1
パリティ	None
フロー制御	None

ポート接続エラー¶

ポートが見つからない¶

Error: No suitable serial port found for OSECHI detector.

Available ports:
  (None found)

原因:

USBケーブルが接続されていない
デバイスが電源オフ
ドライバーがインストールされていない
デバイスが他のアプリケーションで使用中

対応方法¶

ステップ1: 物理接続を確認

# デバイスのLEDが点灯しているか確認
# → 点灯していない場合は電源をオン

ステップ2: ポートを手動で確認

# macOS / Linux
ls /dev/tty*

# Windows
mode

ステップ3: 利用可能なポートをリスト表示

# Pythonでポートをスキャン
python3 << 'EOF'
from serial.tools.list_ports import comports

for port in comports():
    print(f"Port: {port.device}")
    print(f"  Description: {port.description}")
    print(f"  HWID: {port.hwid}")
    print()
EOF

ステップ4: ドライバーをインストール

お使いのOS別にドライバーをインストールしてください。

macOS: 通常は自動認識（ドライバー不要）
Linux: sudo apt install python3-serial でドライバーを含むパッケージをインストール
Windows: デバイスマネージャーで認識されているか確認し、必要に応じてドライバーをダウンロード

ステップ5: ポートを指定して再試行

# ポートを明示的に指定
uv run kazunoko status --port /dev/ttyUSB0

# または別のポート
uv run kazunoko status --port /dev/ttyUSB1

パーミッションエラー¶

Error: Failed to open serial port /dev/ttyUSB0: Permission denied

原因:

ユーザーがシリアルポートにアクセスする権限がない。

対応方法（Linux）¶

# グループを確認
groups $USER

# dialout グループに属しているか確認
# → 属していない場合は追加
sudo usermod -a -G dialout $USER

# グループの変更を反映
newgrp dialout

# または、ログアウト/ログインして再度ログイン

対応方法（macOS）¶

# ポートの所有者を確認
ls -la /dev/ttyUSB*

# 必要に応じて所有者を変更
sudo chown $USER /dev/ttyUSB*

ポートがビジーの場合¶

Error: Failed to open serial port /dev/ttyUSB0: Device or resource busy

原因:

ポートが他のアプリケーション（別のkazunokoプロセス、シリアル監視ツールなど）で使用中。

対応方法¶

# どのプロセスがポートを使用しているか確認（Linux）
sudo lsof /dev/ttyUSB0

# プロセスを終了
kill <PID>

# または、デバイスの電源をオフにして再度オン

タイムアウトエラー¶

応答がない¶

Error: No response received within 0.1s timeout

原因:

デバイスの電源が入っていない
USB接続が不安定
ボーレート設定が間違っている
シリアル通信がハングアップしている

対応方法¶

ステップ1: デバイスの状態を確認

# デバイスのLEDが点灯しているか確認
# → LED が消えている場合は電源をオン

ステップ2: デバイスを再起動

# デバイスの電源を切る
# → 10秒待つ
# → 再度電源を入れる

ステップ3: タイムアウト時間を増やす

デバイスの初期化に時間がかかる場合、タイムアウト値を増やします。

# タイムアウトを 0.5 秒に延長
uv run kazunoko status --timeout 0.5

# または 1.0 秒
uv run kazunoko status --timeout 1.0

ステップ4: ケーブルを確認

# USB ケーブルを抜いて再度接続
# → 別の USB ポートを試す
# → 別のケーブルを試す

ステップ5: ログを確認

# ログファイルで詳細なエラーを確認
tail -20 ~/Library/Logs/kazunoko/kazunoko.json | jq .record.message

# デバッグレベルで実行
uv run kazunoko --level debug status 2> debug.log

タイムアウトが頻繁に発生¶

複数のコマンド実行中にタイムアウトが発生する場合：

# 1. デバイスの状態を確認
uv run kazunoko status --verbose

# 2. イベント読み込みを試す（スレッショルドを下げて）
uv run kazunoko read 10 --event-timeout 10.0

# 3. ログを分析
tail -50 ~/Library/Logs/kazunoko/kazunoko.json | \
  jq 'select(.record.level.name == "WARNING" or .record.level.name == "ERROR")'

一般的な原因:

スレッショルド値が高すぎてイベント検出できない
poll_count が小さすぎてデータを取りこぼしている
USB ハブ経由の接続（直接接続を推奨）
EMI/ノイズによる通信エラー

ケーブル接続の問題¶

ケーブル接続の確認チェックリスト¶

□ USB ケーブルがしっかり差し込まれているか
□ デバイスの電源が入っているか（LED を確認）
□ PC が USB デバイスを認識しているか
□ ドライバーがインストールされているか
□ 別の USB ポートを試したか
□ 別のケーブルを試したか
□ USB ハブではなく PC に直接接続しているか

ケーブルテスト¶

# 接続状態をリアルタイム監視
while true; do
  echo "Testing connection..."
  uv run kazunoko status --timeout 2.0 && echo "✓ Connected" || echo "✗ Failed"
  sleep 2
done

USB ハブの問題¶

USB ハブ経由で接続する場合、電力不足や信号品質の低下が発生することがあります。

推奨事項¶

✓ 推奨: USB 機器を PC に直接接続
✗ 非推奨: USB ハブ経由の接続
✗ 非推奨: 電力供給なしの USB ハブ

USB ハブ経由で接続する場合:

# より長いタイムアウトを設定
uv run kazunoko read 100 --timeout 1.0 --event-timeout 10.0

# または、電力供給付きの USB ハブを使用

デバイスが応答しない（ハングアップ）¶

症状¶

デバイスが接続されているが、コマンドに応答しない

原因¶

デバイスのソフトウェアが異常状態に陥った
メモリリークまたはバッファオーバーフロー
ファームウェアバグ

対応方法¶

ステップ1: 強制リセット（推奨）

# デバイスをリセット
uv run kazunoko reset

# リセット後、状態を確認
uv run kazunoko status --verbose

ステップ2: 電源再投入

# デバイスの電源を完全に切る
# → 30秒待つ
# → 再度電源を入れる

# 接続を再テスト
uv run kazunoko status

ステップ3: ドライバーの再ロード（Linux）

# ドライバーをアンロード
sudo modprobe -r usbserial

# ドライバーを再ロード
sudo modprobe usbserial

# デバイスを再接続
uv run kazunoko status

ノイズと通信エラー¶

症状¶

不規則にタイムアウトが発生する
データが破損して到着することがある

原因¶

電磁干渉（EMI）
ノイズなしの USB ケーブルではない
電源ケーブルの近くにシリアルケーブルがある

対応方法¶

# 1. ケーブルの配置を見直す
#    - 電源コードから離す
#    - その他の電子機器から離す

# 2. シールド付きケーブルを使用
#    - USB フェライトコアを使用することも有効

# 3. 設定を調整
#    - タイムアウト値を増やす
#    - poll_count を増やす

設定例:

# ノイズが多い環境向け
uv run kazunoko read 100 \
  --timeout 0.5 \
  --event-timeout 10.0 \
  --poll-count 65535

複数デバイスの接続¶

複数の OSECHI デバイスを同時に接続する場合：

# デバイス 1 を確認
uv run kazunoko status --port /dev/ttyUSB0

# デバイス 2 を確認
uv run kazunoko status --port /dev/ttyUSB1

# デバイス 1 からイベントを読む
uv run kazunoko read 100 --port /dev/ttyUSB0 > device1.jsonl

# デバイス 2 からイベントを読む
uv run kazunoko read 100 --port /dev/ttyUSB1 > device2.jsonl

ポート番号の確認¶

# 複数デバイスのポートを一覧表示
python3 << 'EOF'
from serial.tools.list_ports import comports

for port in comports():
    print(f"Port: {port.device}")
    print(f"  Description: {port.description}")
    print()
EOF

シリアル通信のデバッグ¶

ログレベルを上げて詳細なログを取得¶

# DEBUG レベルで実行
uv run kazunoko --level debug status 2> debug.log

# ログファイルを確認
cat debug.log | grep -i "serial\|port\|communication"

JSON ログから通信情報を抽出¶

# タイムスタンプと通信内容を表示
tail ~/Library/Logs/kazunoko/kazunoko.json | \
  jq '{time: .record.time.repr, message: .record.message, level: .record.level.name}'

# エラーレベルのみ表示
tail ~/Library/Logs/kazunoko/kazunoko.json | \
  jq 'select(.record.level.name == "ERROR")'

シリアルポート通信を監視¶

Linux では minicom や screen でシリアル通信を監視できます。

# minicom でシリアルポートを監視
minicom -D /dev/ttyUSB0

# または screen を使用
screen /dev/ttyUSB0 115200

次のステップ¶

デバイス状態の確認 - デバイスが正常に動作しているか確認
イベント読み出しの問題 - イベント読み込みがうまくいかない場合
エラーメッセージの読み方 - エラーメッセージの詳細な解釈
ログの基礎 - ログの見方と活用方法