FAQ¶
このページではkazunokoを使用する際に想定される質問と回答をまとめました。
各回答は簡潔に記載しています。
詳細は関連ページを参照してください。
インストール¶
インストール方法は？¶
git clone https://gitlab.com/osechi/kazunoko.git
cd kazunoko
uv sync
関連ページ
Pythonのバージョン要件は？¶
Python 3.10以上が必要です。
関連ページ
対応OSは？¶
macOS、Linux、Windowsで動作します。動作確認はmacOSとLinuxが中心です。
デバイス接続¶
デバイスが見つかりません¶
- USBケーブルを確認
ls /dev/tty*でポートを確認--portオプションで明示的に指定
関連ページ
Permission deniedエラー（Linux）¶
sudo usermod -a -G dialout $USER
newgrp dialout
関連ページ
USBハブ経由で接続できますか？¶
可能ですが、直接接続を推奨します。ハブ経由では--timeoutを増やしてください。
イベント読み込み¶
イベントが取得できません¶
スレッショルド値を下げてください。
kazunoko measure "1:250;2:250;3:250" 10
関連ページ
読み込み速度が遅いです¶
--poll-countを小さくするか、--event-timeoutを短縮してください。
関連ページ
イベントがスキップされます¶
スレッショルドを下げるか、--poll-countを増やしてください。
関連ページ
「Malformed event data」エラー¶
USBケーブルを接続し直すか、デバイスをリセットしてください。
kazunoko reset
関連ページ
パラメーター設定¶
poll_countとは？¶
デバイスのメモリーバッファーをスキャンする回数です。値が小さいと高速ですが取りこぼしやすく、大きいと遅いものの確実です。
関連ページ
最適なスレッショルド値は？¶
環境によって異なります。スレッショルドスキャンで探してください。
関連ページ
データ保存¶
ファイルに保存するには？¶
リダイレクトを使用します。
kazunoko read 1000 > events.jsonl
kazunoko read 1000 --format csv > events.csv
関連ページ
イベント数が指定した数と異なります¶
一部のイベントがタイムアウトでスキップされています。--verboseで統計を確認できます。
関連ページ
ログとデバッグ¶
ログファイルはどこにありますか？¶
| OS | パス |
|---|---|
| macOS | ~/Library/Logs/kazunoko/kazunoko.json |
| Linux | ~/.local/share/kazunoko/logs/kazunoko.json |
関連ページ
デバッグモードを有効化するには？¶
kazunoko --level debug read 100
関連ページ
Python API¶
Pythonスクリプトで使用できますか？¶
from kazunoko import connect, Reader
with connect() as device:
reader = Reader(device)
for event in reader.stream_by_count(100):
print(event.model_dump_json())
関連ページ
エラーハンドリングは？¶
stream_by_count()やstream_by_time()は内部でエラーをハンドリングし、スキップします。統計はreader.statsで確認できます。
関連ページ
その他¶
複数のデバイスを同時に接続できますか？¶
可能です。--portオプションで各デバイスを指定してください。
kazunoko read 100 --port /dev/ttyUSB0 > device1.jsonl &
kazunoko read 100 --port /dev/ttyUSB1 > device2.jsonl &
モックデバイスで試すことはできますか？¶
kazunoko read 100 --mock
kazunoko measure "1:300;2:300;3:300" 100 --mock
関連ページ
バグを報告するには？¶
デバッグログを添付してGitLab Issuesで報告してください。
kazunoko --level debug read 10 2> debug.log
関連ページ
機能リクエストを提案するには？¶
関連ページ
クイックリファレンス¶
よくあるエラーと対応¶
| エラー | 原因 | 対応 |
|---|---|---|
| ポートが見つからない | デバイス未接続 | USBケーブルを確認 |
| Timeout | デバイス無応答 | 電源を再確認、リセット |
| EventTimeout | イベント未受信 | スレッショルドを下げる |
| ResponseError | 応答形式不正 | デバイスを再起動 |
すぐに確認すべきこと¶
# デバイス接続確認
kazunoko status
# バージョン確認
kazunoko version
# デバイスリセット
kazunoko reset
# デバッグログ出力
kazunoko --level debug read 10 2> debug.log