MIPI camera driver install fails on a third-party carrier board

You mount a MIPI camera module on your compute module, run the camera vendor's install script, and it dies partway through. Rerunning it will not help, and neither will a fresh download: the script has already written kernel modules and pin configuration for one carrier layout — the reference board the module maker ships — and your carrier routes its CSI connector differently. This guide is for engineers bringing up a board-level camera on a third-party carrier board. You will pinpoint the step that failed, clean out the partial package, and pick one of the three fixes that work: a carrier-matched device tree overlay from your board vendor, an overlay you port yourself, or a USB3 board camera that takes CSI out of the project. The same logic applies on any compute-module platform whose camera hangs off a mezzanine CSI connector.

Why the install fails: the pinmux, not the package

The vendor script does three things in order. It installs a kernel package (arducam-nvidia-l4t-kernel in the case behind this guide), it drops tooling into /opt/arducam, and it writes device tree and pinmux configuration so the CSI lanes, the I2C bus and the camera power-enable lines match the reference carrier. The -m flag only selects the sensor: -m imx477 installs the IMX477 driver, while -m arducam_4lane installs a different sensor series altogether. The wrong flag is the first failure mode to rule out, because the fix is a cleanup and one rerun.

On a third-party carrier the third step breaks. Which CSI lanes reach the connector, where the enable lines sit, which I2C instance the camera hangs off: these are carrier design decisions. The script writes the reference board's answers, your board disagrees, and the configuration step fails before the sensor is ever probed.

So the decision up front: match the device tree to the carrier, not the script to the sensor. Everything below serves that decision.

What you need before you start

• Console or SSH access to the module, and the ability to reboot it.
• The exact carrier board model and its vendor's page, because the overlay is tied to that model, not to the camera.
• The camera module's sensor name and lane count (IMX477, 4-lane, in the worked case).
• Your platform release (JetPack 5.x in the worked case), since a carrier overlay is built for a specific release.
• The reference carrier's device tree source, if you plan to port the overlay yourself.

The CSI camera and carrier board compatibility guide lists what to settle before a module ever goes on a board you did not design.

Step 1: find where the install actually failed

Two commands split the failure into its three possible homes:

sudo dmesg | grep -i imx477
ls /dev/video*

1. The script errors during installation, no sensor name in dmesg, no video node: a package or pinmux configuration failure. Go to Step 2.
2. The install finished and the sensor name appears in dmesg, but no /dev/video node exists: the driver loaded but the device tree chain is incomplete. The sensor probes but no video node guide walks that chain.
3. A video node exists and frames come out black or torn: the install is not your problem. Start from the streaming failure guide, which covers power, clocks and runtime device tree issues.

Case 1 is the subject here, and nothing about it proves the sensor hardware is bad.

Step 2: remove the partial install, then retry once

1. Remove the half-installed kernel package: sudo dpkg --remove --force-remove-reinstreq arducam-nvidia-l4t-kernel.
2. Delete the tool folder: sudo rm -rf /opt/arducam.
3. Rerun install_full.sh once with the flag that matches your sensor — -m imx477 for the IMX477, a 12.3 MP sensor in this case.
4. Reboot when the script finishes.

On the reference carrier this is usually the whole fix. On a third-party carrier, expect the same error at the same step. One clean retry proves the point; the fifth rerun proves nothing new.

Step 3: one pass through the pin-configuration tool, then stop

The platform ships its own pin tool; here it starts with sudo /opt/nvidia/jetson-io/jetson-io.py. The menu sequence for this camera runs: Configure Jetson 24pin CSI Connector → Configure for compatible hardware → Camera IMX477-A and IMX219-C → Save pin changes → Save and reboot to reconfigure pins.

Watch the last item. In the case behind this guide the tool failed at Save and reboot to reconfigure pins, every time, including with the Camera IMX477 Dual variant. Some engineers also try the camera vendor's own copy of the tool; that attempt is covered in the FAQ below.

That error is the diagnosis, not another prompt to retry. The menus list sensor options; the save step writes the pin table; and the pin table encodes the reference carrier's routing. A menu option cannot change where your board's traces go.

Commit to the rule: one pass on a third-party carrier, and if the save step fails, the answer is a carrier-matched overlay, not a sixth menu combination.

Step 4: get a carrier-matched device tree overlay

1. Ask the carrier board vendor first. Give them the carrier model, the sensor (IMX477), the lane count and your platform release, and ask for a camera overlay plus its flashing instructions. In the case behind this guide this was the only remaining path: the board vendor has to supply the correct device tree. If your platform boots but the camera DTBs never load, the driver and device tree mismatch guide covers that stage.
2. Port the overlay yourself if the vendor has nothing. Start from the reference carrier's camera device tree source and keep the sensor node: its I2C address, mode table and lane assignment stay. Change what is carrier-specific: the CSI node references, the I2C bus instance and the pinmux block for the enable and reset lines. The I2C probe failure guide shows what a half-finished port looks like in dmesg, and the device tree CSI mapping guide maps which node belongs to which connector.

The platform release notes document the same edit pattern for co-located sensors: disable the sensor DTSI you are not using and enable the one you are, in the carrier board's main DTS. On the reference board that is a two-line change; on your carrier, the pinmux around it is the real work.

Worked example: pin budget for the 24-pin CSI connector

Inputs, with their sources:

• 24 pins on the camera connector — the pin tool's own menu calls it Configure Jetson 24pin CSI Connector (from the failed install).
• Configuration A: one 4-lane camera, the lane count the install targeted (4 data lanes plus one clock lane).
• Configuration B: two 2-lane cameras, the Camera IMX477 Dual menu option (2 data lanes plus one clock lane each).
• MIPI D-PHY lanes are differential pairs: 2 pins per lane, clock lane included.
• One shared I2C bus: 2 pins.
• One enable line per camera: 1 pin each (a module with a separate reset line adds 1 pin per camera).

Rule in words: a configuration fits only if the pins it must reserve stay within the connector. Reserved pins = 2 × (data lanes + 1 clock lane) + 2 (I2C) + control lines.

Configuration A, one 4-lane camera: data 4 × 2 = 8 pins; clock 1 × 2 = 2 pins; CSI subtotal 10. Add I2C 2 and one enable 1: reserved = 10 + 2 + 1 = 13 pins, leaving 24 − 13 = 11 pins for power and ground.

Configuration B, two 2-lane cameras: data 2 cameras × 2 lanes × 2 pins = 8 pins; clocks 2 × 2 = 4 pins; CSI subtotal 12. Add shared I2C 2 and two enables 2: reserved = 12 + 2 + 2 = 16 pins, leaving 8.

Result: both configurations fit inside 24 pins, so pin count is not what killed the save step. The threshold works the other way too: any configuration whose reserved count exceeds 24 is impossible for every overlay, and this two-line calculation rules it out before you ask the vendor for it. What the save step actually hit is position mismatch — the tool drives pins where the reference board routes them — and only a carrier-matched pin table fixes that.

The third fix: sidestep CSI with a USB3 board camera

If the carrier vendor publishes no overlay for your sensor and release, and the schedule cannot absorb a device tree port, remove CSI from the problem. A USB3 board-level camera enumerates through the standard host controller: no carrier-specific overlay, no pinmux, no reflash. You give up MIPI's direct sensor-to-SoC path and its latency edge, and in exchange the camera works on any carrier with a USB3 port.

For presence checks, code reading and pick-and-place location at modest frame rates, that trade is usually the affordable one. The board-level camera selection guide covers the resolution, shutter and mount decisions; the same logic applies when USB3 is the interface.

USB3 board cameras from the catalog that fit this route:

The LS-BCM-0003 is the motion pick: a 3.1 MP USB3 board-level camera on an IMX252, 1/1.8" global shutter, 120 fps. The MV-CB060-10UM-B suits builds where you handle the optics: a 6 MP mono bare board, IMX178, 1/1.8", rolling shutter, USB3. The LS-BCM-0047 covers color work at lower resolution: 1.3 MP, 1/2.7", C-mount, global shutter, USB3.0. Filter the full range in the camera finder by interface, resolution and mount.

Verify the camera, then judge the stream

After the carrier overlay is flashed and the module reboots:

1. dmesg shows the sensor driver probing on the I2C bus your overlay assigns — the right driver, not a sibling sensor's.
2. /dev/video* lists a node.
3. A capture returns frames that are not black, and the image changes when you wave a hand in front of the lens.

Three failure modes live past this point, and each has its own guide: a black preview with a probed sensor is the CSID lane0 FIFO overflow case; a sibling driver binding is the wrong sensor driver case; a probe that fails only at certain lane counts is the 2-lane vs 4-lane mode case.

Prevention is a purchasing question. Before the next carrier order, ask the vendor in writing: do you publish camera overlays for this sensor, and for which platform releases? Treat "it works with the reference kit" as not an answer. The board camera evaluation checklist and the interface compatibility guide both put this question where it belongs, before the hardware arrives.

If the carrier vendor has no overlay, choose a camera that does not need one. Browse the board-level cameras category, and when you want the overlay question answered for your exact carrier, reach us through the contact page — free expert support with every order.