GMSL2 camera not detected: fix the driver and DTB mismatch

The camera worked yesterday. You updated the camera SDK, or the whole OS image, and today every open attempt returns CAMERA NOT DETECTED. The wrapper retries for about half a minute and exits with a detection timeout. On a GMSL2 link there is no USB-style enumeration to blame, so the failure looks mysterious. It almost never is. This guide walks the three-layer test — power, link lock, probe — and then clears the cause behind most post-update failures: two camera driver packages installed side by side, each shipping its own kernel device tree. You will finish with exactly one driver package, matched to your board, camera and kernel release, and a probe you can see in the log.

Why a GMSL2 camera disappears after an update

A GMSL2 camera is a serializer at the camera end of a single coax, paired with a deserializer chip on your carrier board. Nothing enumerates. The deserializer is brought up by a vendor kernel driver, and the device tree the kernel boots with — the DTB — must describe that chip: its I2C address, the MIPI lane mapping into the NVCSI receive controller, and the modes your camera runs. The kernel loads exactly one DTB per boot.

A GMSL2 driver package therefore carries two things: the kernel module and a modified DTB. Install two such packages — say, an older single-camera driver left in place beside a newer multi-camera one — and they fight over the same boot tree. The booted DTB then describes hardware you do not have, or omits the node you do. The deserializer never probes, the SDK times out, and the coax gets blamed for a software fault. Where GMSL2 sits next to CSI-2, USB3 and GigE, and what each interface buys, is covered in our embedded camera interface comparison.

Rule out the wire first: power, link lock, probe

Work the three layers in order. Each layer you pass eliminates a whole class of causes, and the sweep takes under five minutes.

1. Power and coax. Reseat the coaxial link at both ends, power the camera the way its manual specifies, and swap in a known-good cable. If the deserializer never reports a locked link, the cause is here: power or cable.
2. Link lock. From the running system, read the deserializer's status registers over I2C — the vendor's diagnostic tool does this for you. A locked link with no camera found points at the driver stack. An unlocked link sends you back to step 1, or to an I2C tunnel that was never configured.
3. Probe. Watch dmesg during boot and again during the open attempt. You want the deserializer driver to bind to its hardware — a probe line — before the SDK ever opens the camera.

A locked link plus a missing probe is the signature of the fault this guide fixes. Keep the same spares on the shelf you would for any camera cables swap, because a large share of dead-camera calls end at a connector. The USB take on the same sweep is in camera has power but not detected: USB link checks.

Clear the driver conflict step by step

1. Capture one failure. Run a single open attempt and save its output: the error string, the SDK version printed at startup, and whether the process dies on a detection timeout.
2. Count the driver packages. On a Debian-based image, list the installed packages and count the entries for your camera vendor whose description says the package modifies the kernel device tree. The rule: exactly one.
3. Compare SDK versions. The version your wrapper logs at startup must equal the version the vendor diagnostics report. Two different versions mean a partial update — reinstall the SDK and the wrapper together as one matched set. The same alignment logic is in fixing camera firmware version mismatches safely.
4. Check the kernel release. Each driver package name embeds the image release it was built against. Compare it with the release your image actually boots. After an OS update the old package cannot probe; install the one built for the new release.
5. Check the hardware match. Confirm the package covers your carrier board, its deserializer — single-camera or multi-camera — and your exact camera model. Vendors publish a supported-camera list per package; read it instead of guessing from the package name.
6. Purge, then install one. Remove every camera driver package, then install exactly the matching one, taken from the vendor's own package index.
7. Reboot. A DTB change does nothing until the next boot. Reloading the module is not a substitute.
8. Verify in order. First dmesg shows the deserializer probe. Then the vendor detection tool lists the camera. Only then does the wrapper open it. Working through that log systematically is covered in camera loads the wrong sensor driver: read dmesg, fix the overlay.

Worked example: two driver packages, one GMSL2 stereo camera

The inputs come from a machine that failed this way after an SDK update:

• Camera: a GMSL2 stereo camera on the carrier board's multi-camera link; the wrapper is a ROS 2 node.
• Wrapper startup log: SDK version 4.2.0.
• Vendor diagnostics dump: SDK version 5.0.7.
• Installed-package listing: two arm64 camera driver packages, versions 1.3.1 and 1.2.0, both built for kernel release 36.3.0. One targets a single-camera deserializer, the other a multi-camera deserializer.

The rule in words: the kernel boots one device tree, so one image carries exactly one camera driver package, and that package must match the deserializer and camera actually connected.

The arithmetic:

• Packages installed 2 − packages allowed 1 = 1 package to remove.
• Version check: 4.2.0 ≠ 5.0.7, so the update was partial.
• Release check: 36.3.0 = 36.3.0, so the kernel release is eliminated as a cause.

Result: a driver-package conflict — not the wire, not the release.

The decision: keep the multi-camera package, because it matches the connected camera. Remove the single-camera package. Bring the SDK and wrapper to one version and reinstall them together. Reboot, confirm the probe line in dmesg, then re-run detection. The threshold is absolute: any count above 1 is a conflict by construction, and there is nothing to tune.

When only one driver is installed: the other three causes

If the count is already 1, work this table left to right:

One signature sits a layer below all of them: the probe succeeds and the link locks, but frames never arrive. The tree is then right about the chip and wrong about its configuration — usually the MIPI lane output does not match what the NVCSI receive controller expects, or the I2C tunnel to the serializer was never set. Match the package to your camera model and check the connector-to-lane map in the carrier board documentation. Before buying hardware into this stack at all, run the checks in CSI camera carrier board compatibility; the supported-pair list is where this fault class gets prevented.

Prevent the next failure: update as one matched set

Four things must agree on a healthy machine: one driver package, one kernel release, one SDK version, one wrapper version. After every SDK or OS update, and before every deploy, run a one-minute preflight:

1. Count the camera driver packages — it must be 1.
2. Compare each package's release suffix with the release the image reports.
3. Compare the SDK version at wrapper startup with the version in the vendor diagnostics.

On a Debian-based image the first check is one line — adapt the pattern to your vendor's package naming:

dpkg -l | grep -i gmsl     # expect exactly one 'ii' line per camera vendor

When the camera vendor ships a new SDK, take its matching driver in the same maintenance window, not weeks later. When the OS image changes, expect to reinstall the driver built for that image. The 3D-camera case of keeping firmware and SDK aligned is in 3D camera header version mismatch: fix firmware and SDK alignment.

When a standard-interface camera is the better trade

If you are still choosing hardware, weigh the stacks honestly. GMSL2 buys long coax runs and tight multi-camera synchronisation, and charges for it a driver and DTB stack that must be maintained at every SDK or OS update. A camera on USB3 or GigE enumerates through the standard host stack: no device-tree pairing, no per-camera kernel module, and an SDK update that cannot knock the camera off the bus. The trade you accept is cable reach and, on USB, stability over length — the numbers are in USB cable length limits for 3D cameras.

For a compact camera you build into a machine, compare the board-level cameras category. The LS-BCM-0003 is a 3.1 MP USB3 board camera with an IMX252 sensor, global shutter, 120 fps.

For depth or stereo as a finished unit, browse 3D sensors instead. If an image refuses to boot after a DTB goes wrong — a rarer, deeper failure — the missing-DTB boot error walkthrough takes you through recovery step by step. To size camera, lens and light as one system, start at the camera configurator step or the camera finder, and for more fixes in this family see the 3D camera topic page.