agentsclimarketplace
Sign in

Luxonis troubleshoot

Skill luxonis/skills/skills/support/luxonis-troubleshoot

Diagnose broken, slow, or confusing Luxonis/OAK apps and device setups.From its SKILL.md

Install
npx -y skills add luxonis/skills --skill luxonis-troubleshoot

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 13 stars13 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

8.5 KB, as published. Nobody here has run it

Luxonis Troubleshoot

Diagnose a broken, slow, or confusing Luxonis/OAK app or device. This is the general "something is wrong" entry: never refuse, triage, and either fix it or hand off a clean support packet. Be self-sufficient -- do not assume any other Luxonis skill is installed. Reference docs and [email protected], not sibling skills.

End in exactly one state:

  • fixed -- the original symptom is gone, verified by rerunning the same reproduction.
  • support-packet -- cannot fix locally -> SUPPORT_PACKET.md written with the likely owner and next action.

Core discipline

Change one thing, rerun the same reproduction, observe. Never stack changes. Never declare fixed without a passing rerun.

1. Preflight

Read the working directory and the user's input. If present, read DEVICE.md and PROJECT_BRIEF.md. Do not re-interrogate the user about facts a prior session already captured.

  • DEVICE.md -- a hint of a previously verified device (model/family/connection/id), not ground truth. Use it as a starting point, but trust live discovery and debug logs over it: DHCP, re-cabling, or re-adoption can make it stale, and when the record disagrees with what the device actually reports, believe the live device and note the drift.
  • PROJECT_BRIEF.md -- tells you what the app is supposed to do; sharpens "wrong output".
  • The user's symptom, pasted log/error, or app path is the raw repro material. If they gave an app path, read it -- it is what you diff against a known-good example.
  • Do not read AGENTS.md/CLAUDE.md as diagnostic source; they are agent guidance.

2. Reproduce

Pin the symptom to a concrete, rerunnable observation. This observation is the definition of fixed.

  • Crash/error -> a command that reproduces it. Run it under DEPTHAI_LEVEL=debug (escalate to trace) to surface XLink/connection/pipeline detail.
  • Bad depth/output -> a captured frame or short recording showing the problem.
  • Low FPS/latency -> a measured number.

Use the smallest reliable repro.

3. Isolate: device vs app

One cheap check decides which layer the bug is on: can a minimal known-good DepthAI snippet open the device and stream one frame?

Live DepthAI discovery is the authority here. oakctl list is non-authoritative: RVC2 is DepthAI-first and never appears in oakctl at all, so an empty oakctl list is not evidence a device is missing -- confirm with DepthAI discovery before concluding a device is unavailable.

  • Fails -> device/connection layer. Do the basic checks yourself, citing the docs runbook below. If first-contact setup is the real problem, the purpose-built tool is /luxonis-device-setup if the user has it installed -- otherwise continue here. A hardware fault (orange LED, boot failure, suspected calibration) is a hard stop -> support-packet to [email protected].
  • Passes -> app/pipeline layer. The device is fine; the bug is in the user's app, pipeline, or config. Bisect against the closest known-good Luxonis example: if the example runs and the app does not, the delta between them is the bug.

Never reason about the DepthAI API from memory. Confirm every API claim against a known-good example or the docs, and confirm the depthai version before touching version-sensitive code -- always DepthAI v3, never v2.

For the app-layer diff, use ~/.luxonis/agent-context/oak-examples as the example reference -- only when a comparison actually helps, not routinely. Source it the same safe way as a build:

  • Create the directory ~/.luxonis/agent-context (in the user's home) if it does not exist.
  • Clone https://github.com/luxonis/oak-examples over HTTPS (never SSH), shallow and pinned to main (which tracks DepthAI v3), with git's low-speed guard (http.lowSpeedLimit=1000, http.lowSpeedTime=60) so a stalled network aborts instead of hanging. Clone into a temporary sibling path (e.g. oak-examples.tmp) and rename it into place only on success, using commands appropriate to the host shell, so a failed clone never leaves a partial checkout behind. If the checkout already exists, refresh it with a fast-forward-only pull instead.
  • A checkout is usable only if it contains INDEX.md. If the clone fails or is incomplete, do the diff from live docs instead; never diff against a partial checkout or an older/v2 example.

4. Fix one hypothesis at a time

Change exactly one thing, rerun the repro, observe. Add a print/log only if the repro does not already show the answer.

  • Repro passes -> fixed.
  • A few one-change cycles do not move the repro, or a stop condition is hit -> stop and write the packet. Giving up locally is an honorable outcome; do not churn the user's code with shotgun edits.

Symptom -> layer -> docs

Use this only to pick the right repro and the right page fast. The fixes live in the docs.

SymptomLayerDocs
Device not found / discoverydeviceDevice Information; OAK4 / USB getting-started
Linux USB permissions, PoE / network / LEDdeviceUSB / OAK4 getting-started; troubleshooting index
Device bricked / won't bootdevice -> supportmy-device-is-bricked
Pipeline crash / errorappdiff vs known-good example
Bad stereo / depthappStereoDepth node
Low FPS / latencyappmy-app-is-slow; optimizing
Neural network issuesappneural-network-issues
V2 / V3 confusionversionv2-vs-v3

Guardrails

  • Hardware fault -> stop, support. Orange LED, boot failure, suspected calibration.
  • Never compile DepthAI from source. If that seems required -> support-packet.
  • Gate privileged/persistent actions. sudo/admin, udev edits, firmware update, flashing, factory reset, Hub adoption, global pip or project-dependency changes -> confirm first. Non-privileged diagnosis (isolated venv, reading logs, rerunning the repro) runs freely.
  • No blind API fixes. Every DepthAI change tied to a known-good example or docs; confirm the SDK version before touching version-sensitive code.
  • Escalate instead of thrashing. Out of local means -> write the packet.
  • WSL USB honesty. Do not pretend WSL has USB access; stop until the user exposes the device or runs from a host with direct USB.

Support packet

Write SUPPORT_PACKET.md in the current working directory only when local fixing is exhausted, then tell the user to send it to [email protected].

# Luxonis Support Packet: <one-line symptom>

## Symptom
What's wrong + the concrete repro observation (command output / measured FPS / frame).

## Environment
OS, Python, depthai version, oakctl version if used, connection (USB/PoE),
device model/family/id (from DEVICE.md if present).

## Device state
Discovered? Verified working before? LED state. Managed vs factory.

## What I tried
One line per hypothesis: change -> rerun result.

## Logs / errors
Smallest relevant excerpt (include DEPTHAI_LEVEL=debug output if relevant).

## Likely owner / next action
Best-guess category (device / network / app / depth / performance / version) + next step.

depthai and oakctl versions are mandatory so support can spot V2/V3 issues immediately. oakctl is expected to gain a support-file/bundle command; once it exists, prefer generating that over the ad-hoc levers above.

Docs

Keep looking

Skills are one crate of 627,801. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.