Depth camera detected but frame get hangs: Jetson USB fixes

The depth camera shows up on the bus, the SDK finds it, the pipeline builds without an error — and then your program sits inside the frame fetch forever, a call such as video.get() that never comes back until you kill it by hand. That combination rules out most detection and driver problems and points at the USB transfer path on the host: throughput, current, link speed, or a mismatched SDK and OS image. It is one step past the camera that is detected but shows no image, where the fetch returns empty frames instead of hanging. Work through the five-minute tests below in order; the test that changes the behaviour names the cause, and each fix sits at the end of its own section.

What detected but hanging actually means

Enumeration and streaming are two different jobs on one cable. Enumeration is control transfers: small packets, milliwatt-level current, no bandwidth commitment. Streaming opens bulk transfers that move megabytes every second at close to the port's full current, sustained for the whole run. A hang therefore means the control path works while the data path never completes — which is why re-plugging, reinstalling a driver or hunting a detection fault rarely helps. The camera is there; its frames just never finish arriving. Four causes cover most cases: the host cannot sustain the stream, the port cannot deliver full current, the link fell back to USB 2.0, or the SDK and the board image are out of step.

Split the causes in five minutes

Run these in order and stop when one changes the behaviour.

1. Time-box the fetch. Call it with a 5-second timeout if your SDK's fetch accepts one, and count consecutive timeouts. Ten in a row while lsusb still lists the device means the transfer queue is dead, not that the camera vanished.
2. Shed the load. Drop to one mono stream at half resolution and 15 fps. If frames arrive, your full stream set outruns the link; go to the throughput section.
3. Watch the kernel log (dmesg in a second terminal) as the streams open. Transfer errors, resets or device-gone lines mean link or power trouble; a clean log with continuing timeouts points at host buffers or the software stack.
4. Read the negotiated speed from the same log or your system's USB tree: 5,000 Mb/s is USB 3.0, 480 Mb/s is a USB 2.0 fallback that cannot carry a stereo set.
5. Try a plain USB webcam on the same port in a simple viewer. If that hangs too, the host software stack is the patient; if it streams, your camera's transfers are the problem.
6. Meter the power. Put an inline USB power meter between camera and cable and read it exactly when the streams open. A draw that jumps and collapses, or a port that re-enumerates mid-run, is starvation.

Cause 1: the host cannot sustain the stream

Size the stream before you tune anything.

Worked example, a 1080p stereo head: two mono streams at 1920 × 1080 and 30 fps, 8 bit per pixel, plus a 16-bit depth map at the same resolution and rate.

• One mono stream: 1920 × 1080 × 30 × 1 B = 62,208,000 B/s ≈ 498 Mb/s
• The 16-bit depth map: 1920 × 1080 × 30 × 2 B = 124,416,000 B/s ≈ 995 Mb/s
• Total: 498 + 498 + 995 = 1,991 Mb/s ≈ 2 Gb/s

USB 3.0's 5 Gb/s line rate loses 20% to 8b/10b encoding and roughly another 20% to bulk overhead, so a healthy link moves about 3.2 Gb/s (≈400 MB/s). The example set fits with around 1.2 Gb/s of margin. A USB 2.0 link offers 480 Mb/s at the line and about 280 Mb/s (≈35 MB/s) in practice: the full set overshoots by roughly 1.7 Gb/s, and one mono stream alone exceeds it by 218 Mb/s. On a fallen-back link the queue never drains and the fetch waits forever.

Bandwidth is only half the story. The kernel also caps how much memory the USB device filesystem may pin for in-flight transfers, and images for small ARM boards start that ceiling low. Size it from your largest frame: the example depth frame is 1920 × 1080 × 2 B = 4,147,200 B ≈ 4.1 MB, so five in-flight frames need 20.7 MB before your SDK's own queues are counted. Raise the ceiling in the USB module options, set it persistently so it survives reboot, and check the running value before you retest. The same sizing drives two USB3 cameras streaming at full resolution.

The fixes, in the order that pays:

• Move the camera to a root port on the board for the first test; hubs come back only as powered ones.
• Raise the transfer-memory ceiling and make the setting persistent.
• Raise the SDK's transfer-queue count or size if its configuration exposes one.
• Shed streams you do not use: an RGB preview nobody inspects costs as much as a depth map.

Cause 2: the port cannot deliver full current

USB 3.0 guarantees up to 900 mA at 5 V per port — 4.5 W. USB 2.0 manages 500 mA (2.5 W). Enumeration sits in the milliwatt range, so the camera powers up and lists fine everywhere. Streaming drives two or three sensors plus an illuminator toward the unit-load ceiling, and that is when a marginal rail shows itself. The classic trap is the bus-powered hub: one 900 mA intake, a couple of hundred milliamps budgeted for the hub itself, and every downstream port shares the rest. Two cameras on such a hub get less than half the budget each, at the exact moment they need the most.

Meter it: an inline USB power meter between camera and cable, read at stream start. A draw that spikes and collapses, or a port that drops off the bus and re-enumerates, is power starvation, not bandwidth. The camera that disconnects when the IR stream starts is the same fault with a different symptom.

Fix it with supply, not settings: a powered hub on its own wall adapter or a desktop-class host port, camera on the hub's first port, measured total at or below about 80% of the intake so inrush has margin. For a fixed station, take the hub off the shared bench rail; the enclosed power supplies range covers 12 / 24 / 48 V duty for cameras, lights and controllers.

Cause 3: the link fell back to USB 2.0

The negotiated speed settles this in seconds. The kernel log lists device speed at enumeration: 5,000 Mb/s is USB 3.0, 480 Mb/s is USB 2.0. From the numbers above, a 480 Mb/s link cannot carry even one 1080p mono stream, so the fetch will hang no matter what the software does.

Fallbacks are almost always physical: a cable longer than about 3 m, an unshielded or damaged cable, a passive extension or adapter, a front-panel port behind a hub chip, a connector not fully seated. USB 3.0 holds its full link rate for roughly 3 m of good cable; past that, expect exactly this symptom. The camera that enumerates as USB 2.0 on a USB 3.0 port and the extension cable that fails only when the depth stream records walk the same diagnosis.

Swap in a short, shielded USB 3.0 cable straight into the board before touching software — keep a spare camera data cable on the bench for exactly this test. For a mount that moves, the LS-CBL-0219 is a 3 m USB3.0 camera cable, high-flex and rated for drag chains.

Cause 4: the SDK and the board image are out of step

If the plain-webcam test hung too, the software stack is the patient. Two patterns account for most of it: a demo app that streams only after its missing runtime libraries are installed, and a board whose camera starts only after the OS image is cleanly reflashed or the SDK rebuilt against the image revision it expects. Version skew fails quietly — the device enumerates, the pipeline builds, and the stream never starts, which is precisely a forever-hanging fetch.

Update the SDK and the image together rather than one at a time: install the SDK build listed for your image revision, add the runtime libraries that build calls out, and reflash when the installed image no longer matches. Prefer a clean rebuild to a stacked upgrade. The Jetson SDK rebuild walk-through and the driver-stack rebuild after a firmware update cover the mechanics.

Match your test result to the fix

When the camera itself is at fault

Close the loop before condemning hardware: second known-good host of a different chipset family, short shielded cable, direct root port, matched SDK and image, other devices streaming happily on that port. If the same hang reproduces there, the camera's transfer hardware is failing under streaming load and no USB setting will change that. Replace the unit or re-spec it for the mount. Two depth cameras from our range cover replacement duty well.

For a full re-specification rather than a one-unit swap, start from the range card below and match the sensing type to the task: projected structured light for close-range geometry, time of flight for longer-range volume work.

Prevention

• Give the depth camera a root port in fixed builds; where you must hub, use a powered hub and put the camera on its first port.
• Keep the cable run under 3 m, shielded, and drag-chain rated where the rig moves.
• Set the transfer-memory ceiling once, persistently, sized above your queue depth — not per login shell.
• Ship the time-boxed fetch: a timeout counter and a re-enumeration counter in the production logs catch this in a day instead of a month.
• Budget before adding cameras. The multi-camera bandwidth and power budget and the hub frame-rate loss guides carry the worked arithmetic.
• If the host is a small dev-class module and the duty is industrial, moving the stack onto fanless industrial mini PCs built for sustained camera duty removes the shared-rail limits at the hardware level.

Where to go next

If the table leaves you between rows, send us the kernel log, the stream set (resolution, frame rate, bits per pixel) and the meter reading — contact the applications team and we will read it with you. To re-specify the camera side, the 3D camera finder filters by sensing type and resolution, and the configurator starts at the camera step: configure a vision system. The neighbouring depth-camera guides sit on the 3D topic page.