luxonis-device-setup

Luxonis デバイスのセットアップ

後続の開発で使えるように、OAK ハードウェアを動作させます。アプリがまだ存在しない段階でも実施できます。製品に関するヒアリングは始めないでください。質問やカメラに関するアドバイスは luxonis へ。アプリのビルドや変更は luxonis-app へ。oakctl のインストールと AGENTS.md については luxonis-workspace へ。

完了条件

ホスト接続またはスタンドアロンの経路で、実際のカメラまたはアプリのデータをストリーミングでき、次のセッションに向けたセットアップメモが docs/device.md に記録されていること（ユーザーがレポートのみの確認を依頼した場合を除きます）。メモには複数のユニットを記載できます。ブロック中の場合は、失敗しているレイヤー、証拠、次のアクションを1つ記載します。ハードウェアの故障（オレンジ色の LED、起動失敗、キャリブレーションの問題が疑われる場合）は [email protected] に連絡してください。

1. 現在の事実

DepthAI API を記憶だけで作り上げないでください。DepthAI v3 のみを使用します。

まず最初に、Luxonis MCP ツール（ホストによって表示される名前は異なります）を確認します。次に、それらが返す正確なサンプルまたはドキュメントのソース、続いて https://docs.luxonis.com/llms.txt、最後に実際に観察された動作を確認します。記憶は一般的な推論にのみ使用してください。oakctl のコマンドとフラグについては、インストール済みの oakctl --help をドキュメントや MCP より優先します。この環境で可能なことはローカルのバージョン（古い場合やベータ版の場合があります）によって決まるため、そこから作業し、現在のドキュメントに記載されている機能がなければ oakctl の更新を提案してください。ホストまたはデバイスで観察された動作がドキュメントや MCP と矛盾する場合は、観察結果を優先し、矛盾を記録してください。オフラインの場合は、oakctl --help とローカルのサンプルを使って作業し、未検証の事実を明示してください。

このホストでは oakctl が必須です（udev、inspect、今後のホスト設定に必要です）。AGENTS.md がない場合、または oakctl がない場合は、luxonis-workspace を指定してその手順に従い、その後ハードウェアの動作確認を続けてください。その手順をコピーしないでください。

2. 変更前に確認する

docs/device.md がある場合は、事実ではなくメモとして読みます。ルートに旧式の DEVICE.md がある場合も読み、新しいメモは docs/device.md に記録してください。ケーブル、IP アドレス、机の上にあるユニットは変わることがあります。変更を加えないホスト情報を取得するには scripts/luxonis_doctor.py --format json を実行してください。ファイルよりも現在の状態を優先します。

• RVC2 は接続されたホスト上で DepthAI パイプラインを実行し、oakctl には表示されません。oakctl list が空でも、デバイスがないとは限りません。
• RVC4 は、ホストに接続して DepthAI を使用することも、スタンドアロンの OAK App として動作することもあります。
• 最初に接続を確認する際は、DepthAI の検出を優先してください。どちらのファミリーも検出できます。

接続されているデバイスを検出します。複数のユニットがあるのは通常のことなので、記録してください。ID、アドレス、またはシリアル番号を固定するのはこのコマンドのみです（open、flash、adopt、oakctl -d）。その指定を、このフォルダーで使用できる唯一のデバイスとして扱わないでください。

権限が必要な操作や変更を加える操作で、対象が曖昧な場合に限り、どの物理カメラを使うか確認してください。プローブは順番に実行し、1台のデバイスに対して複数のプロセスを同時に実行しないでください。

3. 開発経路を動作させる

直接観察で確認できた最上位のレイヤー（検出済み、到達可能、または準備完了（実フレームまたはメッセージ））で止めます。デバイスのメタデータは、パイプラインや OAK App が動作する証明にはなりません。ユーザーが必要とする経路を確認してください。指定がない場合は、存在するものを確認します。カメラが2台ある場合は、無理に1台を選ばず、2台分のメモを残してください。

ホスト接続型の DepthAI

分離された環境を使用します。

1. サポートされている Python と、インポート可能な DepthAI v3 があること。
2. この確認対象のデバイスを、このホストから排他的に開けること。
3. 最小限の既知正常なパイプラインで、実際のフレームまたは構造化メッセージを1つストリーミングできること。
4. プローブが正常に終了し、デバイスを引き続き使用できること。

スタンドアロン OAK 4

1. この確認対象のデバイスが RVC4 であること。
2. 現在の oakctl コマンドとバージョンがわかっていること。
3. このコマンドで、デバイスを対話なしで選択できること。
4. この経路に必要な認証とホスト／デバイス間のネットワークが利用可能であること。
5. 既知正常な最小限の OAK App が必要なビルド／実行経路を通ること。または、無関係な状態に変更を加えずに、既存のアプリでその経路を確認できること。

4. 準備状態の各レイヤーをトラブルシューティングする

検証コマンドは固定したまま、サポートされている原因を1つずつ変更します。対象は、インタープリターと DepthAI のバージョン、USB のアクセス許可・電源・ケーブル・速度、PoE の電源・ルーティング・DHCP／リンクローカル・ VPN・ファイアウォール、工場出荷時の状態か管理対象の OAK 4 か、排他的アクセス、認証または時刻です。

USB、PoE、検出に関する最新情報はドキュメントで確認してください。参考となる情報：Linux の USB RVC2 は Movidius 03e7:2485 として表示される場合があります。OAK 4 の赤い LED は、多くの場合 PoE の電力不足を示します。

5. セットアップメモを作成する

ユーザーがレポートのみの確認を依頼した場合、またはプロジェクトのワークスペースがない場合を除き、 assets/DEVICE.template.md を基に docs/device.md を作成または更新してください。ホストの情報、検出された各ユニット、 各接続経路で最後に成功を確認したコマンド、未解決の問題を記載します。現在も有効なメモは残し、古くなった情報は実際の確認結果で置き換えます。処理がブロックされた場合も、何が失敗したかをメモに残してください。

ガードレール

• sudo／管理者権限での変更、ファームウェア／OS の更新、書き込み、工場出荷時設定へのリセット、Hub への登録、 グローバルな pip の使用、永続的なネットワーク設定、または無関係な実行中アプリへのデプロイを行う前に確認してください。
• DepthAI をソースからコンパイルしないでください。
• サンドボックス、VM、または WSL 環境に、実際にはない USB アクセスやブロードキャストアクセスがあるかのように扱わないでください。
• 1台のデバイスに対して、競合するプローブを同時に実行しないでください。