API Guide¶
kazunokoライブラリのPython APIを使用して、OSECHI検出器と通信する方法を解説します。
APIの構成¶
kazunokoのAPIは3つのレイヤーで構成されています。
1. 接続層 - デバイスへの接続管理¶
connect()- 推奨される接続方法PortDevice- シリアルデバイスの実装detect_port()- ポート自動検出
用途: デバイスとのシリアル通信接続を確立
from kazunoko import connect
with connect() as device:
print("Connected!")
2. コマンド層 - 高レベルなデバイス操作¶
Command- デバイスコマンド実行- 14個のメソッド：status, version, threshold, led, など
- 直感的なAPIですべてのデバイスコマンドをカバー
用途: デバイスコマンドを簡潔に実行
from kazunoko import connect, Command
with connect() as device:
cmd = Command(device)
response = cmd.status()
print(response.version)
3. プロトコル層 - 低レベルな通信¶
DeviceProtocol- 通信インターフェイス定義send_command()- コマンド送信receive_response()- レスポンス受信query()- 送受信の一括操作
用途: カスタムコマンド送信や詳細な制御
with connect() as device:
response = device.query("CUSTOM_COMMAND")
ユースケース別ガイド¶
基本的なステータス確認¶
デバイスの状態を確認する、もっとも一般的な使い方です。
from kazunoko import connect, Command
with connect() as device:
cmd = Command(device)
status = cmd.status()
print(f"Version: {status.version}")
print(f"Poll Count: {status.poll_count}")
詳細は Command クラス を参照してください。
デバイス設定変更¶
スレッショルドやポーリング回数、デッドタイム（不感時間）などを設定します。
from kazunoko import connect, Command
with connect() as device:
cmd = Command(device)
# 単一チャネルのスレッショルド設定
cmd.threshold(1, 300)
# 複数チャネルを一度に設定
cmd.thresholds({1: 300, 2: 350, 3: 320})
# 1回あたりのポーリング回数
cmd.poll_count(100)
検出データの読み込み¶
デバイスからのイベントの検出データを受け取る場合は、
Command.readを使用します。
from kazunoko import connect, Command
with connect() as device:
cmd = Command(device)
# 単一のイベント読み込み
event = cmd.read()
print(f"Signal: {event.signal1}")
# 複数イベントの処理
for i in range(100):
event = cmd.read()
# イベント処理...
低レベルなコマンド送信¶
カスタムコマンドや特殊な操作が必要な場合は
DeviceProtocol.queryを使用します。
from kazunoko import connect
with connect() as device:
# 直接コマンド送信
response = device.query("YOUR_CUSTOM_COMMAND")
print(response.model_dump())
詳細は DeviceProtocol を参照してください。
エラーハンドリング¶
kazunokoのすべてのエラーは階層化された例外（exception）で処理できます。
from kazunoko import connect, Command
from kazunoko.exceptions import (
DeviceError,
ResponseTimeout,
KazunokoError,
)
try:
with connect() as device:
cmd = Command(device)
response = cmd.status()
except DeviceError as e:
print(f"Connection failed: {e}")
except ResponseTimeout:
print("Device did not respond")
except KazunokoError as e:
print(f"Other kazunoko error: {e}")
詳細は エラーハンドリング を参照してください。
テストとモック¶
実デバイスなしでテストできます。
from kazunoko import MockDevice, Command
# モックデバイスを作成
mock = MockDevice()
with mock:
cmd = Command(mock)
response = cmd.status()
# 実デバイスと同じように動作
Response オブジェクト¶
すべてのコマンドは Response オブジェクトを返します。
ドット記法でアクセス¶
response = cmd.status()
print(response.version) # "1.10.1"
print(response.poll_count) # 100
print(response.type) # "response"
辞書アクセス¶
data = response.model_dump()
print(data) # すべてのフィールドを辞書で取得
JSON 変換¶
import json
json_str = json.dumps(response.model_dump())
API リファレンス¶
Command クラス メソッド一覧¶
情報取得:
help()- 利用可能なコマンド一覧status()- デバイス状態確認version()- ファームウェアのバージョンuptime()- デバイスの稼働時間mac_address()- デバイスのMACアドレスbuffer_stats()- イベントバッファーの統計情報
設定:
poll_count(count)- 検出時のポーリング回数deadtime(milliseconds)- 意図的なデッドタイム設定threshold(channel, value)- 単一チャンネルのスレッショルド設定thresholds(dict)- 複数チャネルのスレッショルド設定time(unixtime)- デバイスの時刻設定reset()- デバイスの設定をリセット
制御:
led(channel, state)- デバイスのLED制御
データ:
read()- 検出イベント読み込み
詳細は Command クラス を参照してください。
接続設定¶
デフォルト接続¶
from kazunoko import connect
# ポート自動検出、デフォルト設定
device = connect()
カスタム設定¶
from kazunoko import PortDevice
# タイムアウトを長くする
device = PortDevice(
port="/dev/ttyUSB0",
baudrate=115200,
timeout=2.0 # 2秒
)
詳細は Connection を参照してください。
次のステップ¶
- まず読むべき: Connection ドキュメント - デバイス接続方法
- 次に読むべき: Command クラス - コマンド実行方法
- その後: エラーハンドリング - 本番コード向け
- 必要に応じて: DeviceProtocol - 低レベル操作
よくある質問¶
Q: CommandクラスとPortDeviceの違いは？¶
A: Commandクラスは高レベルなAPIで、通常はこちらをこれします。PortDeviceはより低レベルなAPIで、カスタム操作が必要な場合に使用します。
Q: どのポート設定を使えばいい？¶
A: デフォルト設定を使い、複数デバイス接続時は明示的にポート指定してください。
Q: タイムアウトエラーが出た場合は？¶
A: ポート接続を確認し、タイムアウト時間を長くしてみてください（例: timeout=2.0）
Q: 複数デバイスを同時に操作できる？¶
A: はい。複数の connect() で異なるポートに接続できます。
device1 = connect("/dev/ttyUSB0")
device2 = connect("/dev/ttyUSB1")