Developers Guide¶

このガイドは、kazunokoを使用中に問題が発生した際に、自分で原因を特定して解決する方法を説明しています。

ユーザーが測定中のトラブル解決やデータ品質の確認を必要とするすべての方向けです。

このガイドの目的¶

❌ エラーメッセージが出たとき、何が起きているのかを理解する
📊 データが正しく取得できているか、品質を確認する方法
🔧 よくあるトラブルに対する実践的な対応方法
📝 ログファイルから問題の根本原因を特定する

ガイドの構成¶

基礎知識¶

エラーメッセージの読み方
エラーの種類と意味
コンソール出力の見方
よくあるエラーパターン
ログの基礎
ログレベルとは何か
ログファイルの場所と確認方法
JSON形式のログの読み方
デバイス状態の確認
デバイス情報の取得方法
デバイスが正常に動作しているか確認する
ファームウェアバージョンとの互換性

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

シリアル通信の問題
ポート接続エラー
タイムアウトエラー
デバイスが応答しない
イベント読み出しの問題
EventTimeout（イベントタイムアウト）
ProtocolError / ResponseError
イベントがスキップされている
データ品質の確認
イベント数が期待値と異なる
スレッショルド設定の検証
記録されたデータの統計分析

パフォーマンスとチューニング¶

パフォーマンスの問題
読み出し速度が遅い
CPU/メモリ使用率が高い
長時間測定での安定性
パラメータ調整
Poll countの意味と調整方法
タイムアウト値の最適化
イベント読み出し速度の向上

Advanced¶

デバッグモード
--level debug オプションの活用
詳細ログの有効化
開発者への問題報告
よくあるご質問
- Q&A形式の問題解決ガイド
- 実例付きのトラブルシューティング

クイックリファレンス¶

よくあるエラーと対応¶

エラー	原因	対応
ポートが見つからない	デバイスが接続されていない	USBケーブルを確認
Timeout	デバイスが応答していない	電源を再確認、リセットを試す
EventTimeout	イベントを受け取れていない	スレッショルドを下げる、poll_countを増やす
ResponseError	デバイスからの応答形式が不正	デバイスの再起動を試す

すぐに確認すべきこと¶

# 1. デバイスが接続されているか確認
uv run kazunoko status

# 2. ファームウェアバージョン確認
uv run kazunoko version

# 3. 少数のイベントで試す（モックモード）
uv run kazunoko read 5 --mock

# 4. 実デバイスで試す
uv run kazunoko read 5 --verbose

# 5. ログファイルを確認
# macOS: cat ~/Library/Logs/kazunoko/kazunoko.json
# Linux: cat ~/.local/share/kazunoko/logs/kazunoko.json

ログファイルの場所¶

各OSでのログファイルの保存場所：

macOS: ~/Library/Logs/kazunoko/kazunoko.json
Linux: ~/.local/share/kazunoko/logs/kazunoko.json
Windows: %APPDATA%\kazunoko\logs\kazunoko.json

ログファイルはJSON形式で保存され、タイムスタンプ、詳細なエラー情報、コンテキストメタデータが含まれています。

次のステップ¶

問題の種類に応じて、該当するセクションを参照してください：

最初に: エラーメッセージの読み方
デバイスの問題: シリアル通信の問題
データの問題: イベント読み出しの問題
パフォーマンス: パフォーマンスの問題
詳しく知りたい: ログの基礎

問題が解決しない場合¶

以下の情報を用意して、GitLabでissueを作成してください：

エラーメッセージ（スクリーンショット）
実行したコマンド
ログファイルの内容（--level debug で取得）
デバイス情報（kazunoko version の出力）
環境情報（OS、Pythonバージョン）

詳しくはデバッグモードを参照してください。