共通API & バッチ処理（_BasicDevice）
すべてのデバイスクラスで共通して利用可能な基本通信コア関数、およびバッチ同期送信に関する仕様です。
search()、connect()、disconnect()、および同期ブロックを伴う命令（blocking=Trueが設定された各関数やend_batch(blocking=True)など）は、通知受信用コールバック関数の中から直接呼び出すことはできません。呼び出した場合、デッドロック防止のため内部で検知され、RuntimeError が発生します。
1. デバイス通信・制御関数
search()
Bluetoothを使用して周囲のハードウェアをスキャンし、一致したデバイスリストを返します。
| 引数名 | 要求される型 | 数値の範囲 / 選択肢 | 備考 |
|---|---|---|---|
| timeout | int / float | 0 以上の任意の数値 | 0を指定すると最初に見つかるまでスキャン（最大10秒）。 |
| device_name | str / None | 任意の文字列 | ハードウェア名フィルタ（部分一致） |
| device_mac | str / None | 任意の文字列 | MACアドレスによるフィルタ |
| card_color | int / None | 任意の整数（アプリ用カラー定数に対応） | Connection Cardの色定数フィルタ。指定された値は内部で型変換され、フィルタリングに使用されます。 |
| card_serial | int / str / None | 0 〜 9999 | "0049" などの文字列も指定可能。範囲外は無視（フィルタ対象外）されます。 |
connect()
指定されたConnection Cardのフィルタなどに基づいてハードウェアを検索し、接続を確立します。
| 引数名 | 要求される型 | 数値の範囲 / 選択肢 | 備考 |
|---|---|---|---|
| device | オブジェクト / None | search() の返り値 | Noneの場合は自動で検索を実行。 |
| device_notification_delay | int / float (四捨五入) | 0 または 15 〜 1000 | 自動通知の間隔（ミリ秒）。範囲外指定はValueError。 |
light_color()
デバイスのボタンライトの色、明るさ、および点滅パターンを設定します。
| 引数名 | 要求される型 | 数値の範囲 / 選択肢 | 備考 |
|---|---|---|---|
| color | int (厳格) | 0 〜 10 (App準拠のLegoColor定数) | アプリ位置合わせ用定数（0:NOCOLOR 〜 10:AZURE）が対象です。-1などの指定外の数値はValueErrorになります。 |
| pattern | int (厳格) | 0 〜 5 (LightPattern定数) | 0:常灯, 1:ブレス, 2:パルス, 3:短点滅, 4:長点滅, 5:2回点滅 |
| intensity | int / float (四捨五入) | 0 〜 100 (%) | 明るさの割合。 |
beep()
ハードウェアで指定されたビープ音パターンを再生します。
| 引数名 | 要求される型 | 数値の範囲 / 選択肢 | 備考 |
|---|---|---|---|
| pattern | int (厳格) | 0 〜 3 (SoundPattern定数) | 0:単音, 1:2連続, 2:3連続, 3:メロディ変更 |
| frequency | int / float (四捨五入) | 0 〜 2700 (Hz) | 周波数。範囲外はValueError。 |
| count | int (厳格) | 1 〜 255 (回) | 全体の再生リピート回数。 |
stop_beep()
現在ハードウェア側で鳴っている継続的なビープ音を即座に緊急停止させます。
device_uuid()
ハードウェアに固有の一意識別番号（UUID）を同期リクエストし、レスポンスオブジェクトを返します。返り値の .uuid プロパティから8バイトのバイト配列を取得可能です。
program_flow_notification()
ハードウェアに対してプログラムの「開始」または「停止」を通知します。これにより、デバイス内部の多くの設定値が初期リセットされます。
- 引数 action には、定数 le.PROGRAM_ACTION_START (0) または le.PROGRAM_ACTION_STOP (1) を指定します。
info()
接続中ハードウェアの技術的なメタ情報・バージョン構造を同期リクエストして取得します。返されるオブジェクトからは以下のプロパティを参照可能です。
- rpcMajor / rpcMinor / rpcBuild : RPC通信プロトコルのバージョン
- firmwareMajor / firmwareMinor / firmwareBuild : ファームウェアのバージョン
- bootloaderMajor / bootloaderMinor / bootloaderBuild : ブートローダのバージョン
- maxPacketSize : 1パケットあたりの最大MTU通信サイズ（バイト）
- productGroupDevice : ハードウェアのプロダクトグループID
2. 全デバイス共通の「システム状態監視プロパティ」
すべてのデバイスインスタンスは、ハードウェアのハブ本体から配信される共通のシステムステータスプロパティを保持しています。
接続が確立され、最初の通知を受信するまでは各プロパティ内部の値は float('nan') で初期化されています。
info_device プロパティ (InfoDeviceNotification)
| プロパティ名 | データ型 | 有効レンジ / 選択肢 | 内容説明 |
|---|---|---|---|
| batteryLevel | uint8 | 0 〜 100 (%) | ハブ本体のバッテリー残量パーセンテージ。 |
| UsbPowerState | uint8 | 0 または 1 | USB給電状態（0: 未接続、1: 接続中）。 （UsbPowerState定数に対応） |
button プロパティ (ButtonStateNotification)
| プロパティ名 | データ型 | 有効レンジ / 選択肢 | 内容説明 |
|---|---|---|---|
| state | uint8 | 0 または 1 | ハブ本体にある物理ボタンのリアルタイムな押下状態（0: 離されている、1: 押されている）。 （ButtonState定数に対応） |
3. バッチ（同時同期送信）制御関数とコード例
複数の個別コマンドをバラバラに送るのではなく、1つのBLEパケットに詰め込んで「ほぼ完全に同時」に駆動開始させるための命令です。
begin_batch()
バッチモードを有効化し、以降に発行されるモーターコマンドを送信バッファに蓄積します。
end_batch()
蓄積されたすべてのバッチコマンドを一括送信し、バッチモードを終了します。
batch()
with device.batch(): の形式でバッチを自動制御するためのコンテキストマネージャです。
cancel_batch()
送信パケットを送信せずに現在のバッチ内容をすべてクリア（キャンセル）します。戻り値として、破棄（未送信のままキャンセル）されたコマンドの総数（int）を返します。
バッチ処理サンプルコード
パターンA: 標準呼び出し (begin_batch / end_batch)
import legoeducation as le doublemotor = le.DoubleMotor() doublemotor.connect(card_color=le.LEGO_COLOR_RED) doublemotor.begin_batch() doublemotor.motor_run(motor=le.MOTOR_LEFT, speed=60) doublemotor.motor_run(motor=le.MOTOR_RIGHT, speed=20) doublemotor.end_batch(blocking=True)
パターンB: コンテキストマネージャ (with 構文)
import legoeducation as le doublemotor = le.DoubleMotor() doublemotor.connect(card_color=le.LEGO_COLOR_BLUE) with doublemotor.batch(blocking=True): doublemotor.motor_run(motor=le.MOTOR_LEFT, speed=40) doublemotor.motor_run(motor=le.MOTOR_RIGHT, speed=40)