luxonis-device-setup

name	luxonis-device-setup
description	Get Luxonis OAK hardware working for development and write setup notes. Use for first setup, USB/PoE, oakctl or DepthAI discovery, or a camera that is not found.

Luxonis Device Setup

Get OAK hardware working so later development can use it. This can happen before any app exists. Do not start a product interview. Questions or camera advice → luxonis. Build or change an app → luxonis-app. oakctl install and AGENTS.md → luxonis-workspace.

Done when

A host-connected or standalone path streams real camera or app data, and docs/device.md holds setup notes for the next session (unless the user asked for a report-only check). Notes may describe several units. Blocked means the failing layer, the evidence, and one next action. Hardware fault (orange LED, boot failure, suspected calibration) goes to [e-mail].

1. Current facts

Never invent DepthAI APIs from memory. DepthAI v3 only.

Best source first: the Luxonis MCP tools (surfaced names vary by host), then the exact example or doc source they return, then https://docs.luxonis.com/llms.txt, then observed behavior; memory is only for general reasoning. For oakctl commands and flags, the installed oakctl --help outranks docs and MCP: the local version (possibly older or beta) defines what is possible here, so work from it and suggest an oakctl update when it lacks something current docs describe. If observed host or device behavior contradicts docs or MCP, trust the observation and note the conflict. If offline, work from oakctl --help and local examples and name which facts are unverified.

oakctl is required on this host (udev, inspect, future host config). If AGENTS.md is missing, or oakctl is missing, name luxonis-workspace and follow it, then continue hardware proof. Do not copy its procedure.

2. Inspect before changing

Read docs/device.md when present as notes, not ground truth. Also read a legacy root DEVICE.md if present; write new notes to docs/device.md. Cabling, IPs, and which unit is on the desk can change. Run scripts/luxonis_doctor.py --format json for non-destructive host facts. Trust live state over the file.

• RVC2 runs a DepthAI pipeline on a connected host and does not appear in oakctl. Empty oakctl list does not mean no device.
• RVC4 may be host-connected DepthAI or a standalone OAK App.
• Prefer DepthAI discovery for first contact; it sees both families.

Discover what is attached. Several units is normal; record them. Pin an id, address, or serial only for this command (open, flash, adopt, oakctl -d). Do not treat that pin as the only legal device for this folder.

Ask which physical camera only when a privileged or mutating action would be ambiguous. Serialize probes; never run competing processes against one device.

3. Get a development path working

Stop at the highest layer proven by direct observation: discovered, reachable, or ready (real frame or message). Device metadata is not proof that a pipeline or OAK App runs. Prove the path the user cares about; if they did not specify, prove what is present. Two cameras means two notes, not a forced winner.

Host-connected DepthAI

Use an isolated environment:

1. Supported Python and importable DepthAI v3.
2. The device for this check opens from this host with exclusive access.
3. A minimal known-good pipeline streams one real frame or structured message.
4. The probe closes cleanly and the device remains available.

Standalone OAK 4

1. The device for this check is RVC4.
2. Current oakctl commands and version are known.
3. The device can be selected non-interactively for this command.
4. Authentication and host/device networking required by the path are available.
5. A minimal known-good OAK App traverses the required build/run path, or an existing app proves that path without mutating unrelated state.

4. Troubleshoot one readiness layer

Keep one verification command stable while changing one supported cause: interpreter and DepthAI version; USB permissions, power, cable, or speed; PoE power, routing, DHCP/link-local, VPN, or firewall; factory versus managed OAK 4; exclusive access; authentication or clock.

Confirm current USB, PoE, and discovery details from docs. Useful starting hints: Linux USB RVC2 may appear as Movidius 03e7:2485; a red LED on OAK 4 often means insufficient PoE power.

5. Write setup notes

Create or update docs/device.md from assets/DEVICE.template.md unless the user requested a report-only check or there is no project workspace. Include host facts, each unit seen, last proving command per path, and open issues. Preserve still-valid notes; replace stale facts with live evidence. A blocked session should still leave notes about what failed.

Guardrails

• Ask before sudo/admin changes, firmware/OS updates, flashing, factory reset, Hub adoption, global pip, persistent networking, or deploying over an unrelated running app.
• Never compile DepthAI from source.
• Do not pretend a sandbox, VM, or WSL environment has USB or broadcast access it does not have.
• Never run competing probes against one device.