Camera device tree overlay CSI mapping troubleshooting

A camera driver can load successfully while no camera appears in the capture interface. Loading registers driver code; it does not prove that the sensor has power, answers on its control bus, or connects through a valid CSI capture graph. This troubleshooting procedure is for embedded-vision integrations where an overlay enables no camera, removes previously working cameras, or assumes a different carrier layout. Start with the supported board configuration, then trace each connection from sensor to receiver.

1. Separate module loading from camera detection

Treat camera initialization as a chain of separate milestones. Each milestone narrows the next test:

Record which milestone actually fails. A loaded module without a sensor probe points toward device description, matching, or control-bus initialization. A successful probe followed by capture timeouts shifts attention toward routing, clocks, and mode settings.

If the driver package and board release are not a supported combination, resolve that before adapting an overlay. The guide to driver and device-tree package mismatches covers that earlier compatibility boundary.

2. Restore a baseline and identify the active tree

Before changing anything else, preserve the last working boot configuration and its recovery procedure. Use the board vendor's documented method to disable the suspect overlay and restart the system. Verify whether previously working cameras return.

That comparison is useful evidence. If removing one overlay restores other cameras, the overlay likely changes shared resources or camera graph definitions. It does not, by itself, identify which property conflicts.

Check the tree the kernel actually received, not just the overlay file stored on disk. Depending on the platform, firmware, a bootloader, or another boot stage may select and combine device-tree files.

Useful read-only checks include:

• uname -r to record the running kernel release.
• The board's documented boot configuration to identify selected device-tree files and overlays.
• /sys/firmware/devicetree/base or /proc/device-tree, where available, to inspect the active tree.
• dmesg to locate sensor probe, deferred-probe, regulator, clock, and receiver messages.

On systems with the device-tree compiler installed, this command prints the active tree as text without editing it:

dtc -I fs -O dts /sys/firmware/devicetree/base

Preserve the output for comparison. A file present in the boot directory is not proof that its changes became active.

3. Validate sensor nodes, control buses, and power first

Find the intended sensor node in the active tree. Compare its compatible string, enabled status, parent bus, address, and resource references with the supported board documentation and driver binding.

Check these items in order:

1. Node enabled: Confirm that the sensor and required parent controllers are enabled. An enabled child cannot compensate for a disabled bus controller.
2. Driver matching: Confirm that the compatible string matches the supported driver binding. Loading a module manually does not create a missing device-tree device.
3. Control-bus route: Trace the physical connector to its I2C controller and any intervening multiplexer channel. Software bus numbering may differ from schematic labels.
4. Address convention: Confirm the address format required by the binding. A data sheet may display an address differently from the seven-bit address normally used in an I2C device-tree node.
5. Power and control signals: Verify regulator references, enable sequencing, reset polarity, and power-down polarity against the schematic.
6. Clock supply: Check the documented clock source, required rate, and whether the driver controls it during probing.

Use existing driver logs and vendor-supported diagnostics before issuing direct bus transactions. Indiscriminate scans or register writes can interfere with devices sharing the bus.

For a sensor that never acknowledges or fails identification, follow the sensor probe and I2C failure checks. CSI lane changes will not repair an unpowered sensor or an incorrect control-bus address.

4. Trace the physical CSI path into the capture graph

Once the sensor probes, trace its data path from the schematic into the active device tree. CSI describes the image-data interface; I2C describes a separate control path. Either can fail independently.

Build a mapping sheet rather than guessing from connector labels:

A connector marked with a particular number does not necessarily map to the same numbered controller or capture channel. Some platforms also require coordinated settings in several camera-related nodes.

Follow each endpoint reference through the graph and verify that it terminates at the intended peer. Check both sides according to the platform binding. Property names and numbering conventions vary, so do not transplant example values from another carrier.

Use media-ctl -p, where supported, to inspect the registered media topology. Use v4l2-ctl --list-devices to inspect capture-device registration. A media graph can be incomplete even when the sensor's control-bus initialization succeeded.

The CSI camera and carrier compatibility checklist explains the hardware evidence to collect before choosing an overlay.

5. Look for single-camera and multi-camera conflicts

An overlay intended for multiple sensors may modify more than the additional sensor nodes. It can change shared controller status, graph endpoints, capture-channel assignments, clocks, regulators, or multiplexer definitions.

Compare the active tree with and without the overlay. Focus first on nodes serving cameras that previously worked. Look for disabled nodes, replaced endpoint references, duplicated channel assignments, and shared resources redirected to another path.

Two devices can use the same I2C address on separate isolated multiplexer channels. That does not mean they can share the same address on one unisolated bus segment. Document the entire route before diagnosing an address collision.

Do not assume that deleting the second sensor node converts a multi-camera overlay into a valid single-camera configuration. Other references may still expect both sensors or assign the remaining sensor to the wrong receiver.

Ask the board and camera vendors for a supported single-camera configuration, or an adaptation reviewed against the carrier schematic. Preserve working camera definitions unless the documented integration requires changing them.

6. Check mode settings and estimate the data budget

After control-bus probing and topology checks pass, verify the selected sensor mode. Compare active dimensions, frame rate, transmitted bit depth, lane count, and documented link-frequency settings across the sensor driver and receiver configuration.

A payload estimate provides a useful consistency check:

For a hypothetical uncompressed mode with 1280 × 800 active pixels, 10 bits per pixel, and 60 frames per second:

The active image payload is therefore about 614.4 Mbit/s, or 307.2 Mbit/s per lane across two lanes. Actual link requirements include packet overhead and mode timing. Receiver limits must come from the platform documentation.

Do not copy that estimate directly into a clock or link-frequency property. Device-tree properties may describe different clock domains or use different conventions. Follow the binding and the supported mode table.

If a documented low-rate mode works but a higher-rate mode fails, investigate timing, supported receiver limits, and physical signal quality before changing unrelated sensor addresses.

7. Verify the repair with controlled tests

Change one documented configuration item at a time. Reboot when required by the supported overlay workflow, then repeat the same checks.

A practical verification sequence is:

1. Confirm the expected active-tree changes.
2. Confirm successful sensor probing without unresolved resource dependencies.
3. Inspect the media graph and capture-device registration.
4. Capture using an explicitly supported mode.
5. Repeat acquisition after a complete power cycle.
6. Reconnect other cameras individually and repeat the test.

For example, capture 300 frames at a requested 30 frames per second. The nominal image interval is 1 / 30 = 0.0333 seconds, and the acquisition period is approximately 10 seconds, excluding startup and software overhead. Check frame counts, timestamps, image content, and receiver errors rather than relying only on a preview window.

Do not treat a changed device-node number as a missing camera. Identify devices through supported metadata and topology. The guide to multiple-camera device-path conflicts covers persistent identification for a different interface when your system also includes USB cameras.

8. Decide whether CSI remains the right integration path

Repairing the supported CSI configuration is usually preferable when the application depends on the embedded receiver, compact wiring, or an established sensor pipeline. Replacing it with an external camera changes the acquisition architecture and requires separate validation.

If carrier-specific software maintenance is unacceptable, evaluate area scan cameras through the camera finder. An external camera interface can avoid the CSI device-tree integration, but it introduces its own driver, throughput, power, and application requirements.

Consider LS-CMR-0166 only as an alternative acquisition architecture, not a replacement CSI sensor module. Check host software support and the required imaging performance before selecting it.

Review cables using the accessory finder. Match connectors, routing, and interface requirements rather than assuming an existing flex cable can be adapted.

The LS-CBL-0219 is a USB3.0 camera cable for high-flex, drag-chain use. Verify connector compatibility separately before ordering.

Neither product changes a CSI overlay or repairs a carrier-board lane assignment.

9. Prepare the support package and prevent recurrence

Before requesting an overlay adaptation, assemble a concise evidence package:

• Board identity and revision: Different revisions may route resources differently.
• Supported software release and kernel: Record the complete versions, not just the major release.
• Camera and connector identification: Include the connected port and cable orientation.
• Official package origin: Obtain drivers, firmware, and documentation from the manufacturer or its distributors.
• Active-tree comparison: Include the working baseline and failing configuration.
• Boot and probe logs: Preserve the earliest relevant failure, not only the final capture error.
• Topology mapping sheet: Show the control-bus route, CSI lanes, receiver, and capture channel.
• Reproduction sequence: State which cameras work before and after applying the overlay.

Keep the validated overlay, supported package versions, and rollback instructions together. Recheck them after board-support updates rather than assuming a previously generated overlay remains compatible.

For help evaluating an external-camera alternative, send the imaging requirements and host-interface constraints through application support. If that architecture fits, start the camera system configurator; for carrier-specific CSI changes, request the supported configuration from the board and camera vendors.