デバイス状態の確認

このガイドでは、OSECHIミューオン検出器の現在の状態を確認する方法を説明します。

測定を開始する前に、デバイスが正常に動作しているか、正しく設定されているかを確認することが重要です。

---

デバイス情報の確認

status コマンドでデバイス状態を表示

最も基本的な確認方法は、status コマンドです。

uv run kazunoko status

出力例:

┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ Key             ┃ Value              ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ status          │ ok                 │
│ mac_address     │ AA:BB:CC:DD:EE:FF  │
│ firmware        │ v1.5.0             │
│ uptime          │ 1234567 seconds    │
│ event_queue     │ 0 events           │
│ poll_count      │ 1000               │
│ deadtime        │ 500 microseconds   │
│ threshold_ch1   │ 280                │
│ threshold_ch2   │ 300                │
│ threshold_ch3   │ 290                │
└─────────────────┴────────────────────┘

各フィールドの意味は以下のとおりです。

フィールド	意味	正常な値
status	デバイスの状態	ok
mac_address	デバイスの識別番号	XX:XX:XX:XX:XX:XX 形式
firmware	ファームウェアバージョン	v1.x.x 以上
uptime	起動からの経過時間（秒）	任意の正の数値
event_queue	バッファに溜まっているイベント数	0 またはその付近
poll_count	ポーリング時の読み込み回数	1 ～ 65535
deadtime	チャネル間の最小読み込み間隔	0 ～ 1000 マイクロ秒
threshold_ch1,2,3	各チャネルのスレッショルド値	100 ～ 500

---

詳細表示モード（verbose）

より詳しい情報が必要な場合は、--verbose オプションを使用します。

uv run kazunoko status --verbose

このモードでは、以下の追加情報が表示されます。

• デバイスの接続ポート
• 読み込み時刻
• デバイスのログ情報
• リアルタイムクロック（RTC）の時刻

---

ステータスコード解釈

status: ok

デバイスが正常な状態です。

確認項目:

• ✓ event_queue がほぼ 0 なら正常
• ✓ firmware が最新版なら最適

status: error

デバイスが異常な状態です。

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

# リセット後、再度確認
uv run kazunoko status --verbose

よくある原因:

• デバイスのメモリバッファがいっぱい
• 通信エラーが発生した
• ファームウェアのバグ

---

ファームウェアバージョンの確認

デバイスのファームウェアバージョンを確認します。

uv run kazunoko version

出力例:

Device firmware:
  Version: v1.5.0
  Build date: 2024-01-15
  Commit: abc1234

Library version:
  kazunoko: 0.6.2

バージョン互換性

デバイスのファームウェアが古い場合、一部の機能が使用できないことがあります。

機能	必要なバージョン
基本的なイベント読み込み	v1.0.0 以上
RTC（リアルタイムクロック）同期	v1.2.0 以上
高速ポーリング（poll_count > 1000）	v1.3.0 以上
JSON形式レスポンス	v1.4.0 以上

---

MAC アドレスの確認

デバイスの一意な識別番号（MAC アドレス）を確認できます。

uv run kazunoko status | grep mac_address

用途:

• 複数のデバイスを区別する場合
• デバイスの識別情報をログに記録する場合
• 測定ノートに記録する場合

---

スレッショルド値の確認

各チャネルのスレッショルド値を確認します。

uv run kazunoko status --verbose

出力で確認する項目:

threshold_ch1   │ 280
threshold_ch2   │ 300
threshold_ch3   │ 290

スレッショルド値の意味

• 値が小さい → より敏感に反応 → イベント数が多い
• 値が大きい → 反応しにくい → イベント数が少ない

スレッショルド値が適切か確認する

# 現在の設定でイベント読み込みを試す
uv run kazunoko read 10 --event-timeout 5.0

# イベントが取得できたか確認
# → 取得できた：スレッショルド値は適切
# → タイムアウトが多い：スレッショルド値が高すぎる

スレッショルド値の調整方法は、パラメータ調整を参照してください。

---

poll_count（ポーリング数）の確認

poll_count は、デバイスのメモリバッファを読み込む詳細さを表します。

uv run kazunoko status | grep poll_count

意味:

poll_count	意味	イベント検出
小さい（例: 100）	バッファを少ない回数だけスキャン	✓ 高速だが取りこぼす可能性あり
中程度（例: 1000）	バッファを標準的にスキャン	✓ バランス型（推奨）
大きい（例: 65535）	バッファを徹底的にスキャン	✓ 遅いが確実

---

イベントキューの確認

バッファに待機中のイベント数を確認します。

uv run kazunoko status | grep event_queue

正常な値:

• event_queue: 0 events → バッファが空で正常
• event_queue: 1-5 events → わずかに溜まっているが正常
• event_queue: 10+ events → バッファが溜まり気味、読み込みを開始した方が良い

イベントキューが溜まっている場合

# イベントを読み込んでバッファをクリア
uv run kazunoko read 100

# 再度確認
uv run kazunoko status | grep event_queue
# → 0 events に戻ったか確認

---

デバイスが応答しない場合

status コマンドでタイムアウトが発生する場合は、デバイスに問題があります。

対応方法

# 1. タイムアウト時間を増やして再試行
uv run kazunoko status --timeout 2.0

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

# 3. 再度確認
uv run kazunoko status

# 4. それでも応答しない場合
# → ケーブルの接続を確認
# → 別のUSBポートを試す
# → 詳細ログを確認
tail -20 ~/Library/Logs/kazunoko/kazunoko.json

詳しくはエラーメッセージの読み方の「タイムアウトエラー」セクションを参照してください。

---

自動ヘルスチェック

スクリプトで自動的にデバイス状態をチェックできます。

from kazunoko import connect, Command

def check_device_health():
    """デバイスのヘルスチェック"""
    try:
        with connect() as device:
            cmd = Command(device)

            # 状態確認
            response = cmd.status()

            # ヘルスチェック
            assert response.status == "ok", "Device status is not ok"
            assert response.event_queue == 0, "Event queue is not empty"

            print(f"✓ Device is healthy")
            print(f"  - MAC: {response.mac_address}")
            print(f"  - Firmware: {response.firmware}")
            print(f"  - Uptime: {response.uptime} seconds")

            return True

    except AssertionError as e:
        print(f"✗ Device health check failed: {e}")
        return False
    except Exception as e:
        print(f"✗ Connection failed: {e}")
        return False

if __name__ == "__main__":
    if check_device_health():
        print("\nReady to start measurement")
    else:
        print("\nDevice needs troubleshooting")

---

複数デバイスの区別

複数のデバイスが接続されている場合、MAC アドレスで区別します。

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

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

# 結果を比較
# → MAC アドレスが異なるか確認

---

次のステップ

• シリアル通信の問題 - 接続エラーのトラブルシューティング
• パラメータ調整 - poll_count とスレッショルドの最適化
• エラーメッセージの読み方 - エラーが出た場合の対応