How to Bring Up a Custom MIPI CSI-2 Sensor on an SBC
Choosing an SBC for a custom MIPI CSI-2 sensor is a compatibility decision, not a connector-count decision. The board must match the sensor's lane count and link rate, clock mode, electrical wiring, power sequence, and control bus. Its BSP must also expose the CSI-2 receiver, D-PHY or SerDes, sensor driver, media-controller graph, and a usable capture node.
For a radar front end or another non-standard sensor, the safest sequence is:
- freeze the sensor and electrical requirements;
- select a board with a documented CSI-2 receive path;
- verify the kernel and device-tree support;
- bring up the sensor as a V4L2 sub-device;
- configure the media graph and capture frames before adding AI or recording.
A MIPI connector proves that a physical interface exists. It does not prove that an arbitrary sensor will enumerate or stream.
1. Choose the Receiver Before the Board
Start with the sensor datasheet and write down the complete output contract:
| Sensor requirement | What the board must provide |
|---|---|
| Number of data lanes | The same lane count, with the required lane mapping and polarity |
| Per-lane data rate | A receiver and PCB path rated for the required link rate |
| Clock mode | Continuous or discontinuous clock support in the receiver and driver |
| Pixel format | A compatible media-bus format, such as a RAW Bayer or YUV format |
| Resolution and frame rate | A supported mode in the sensor driver, receiver, ISP, and capture node |
| Sensor control | I2C or SPI access, reset and power-down GPIOs, and required regulators |
| External clock | The required MCLK frequency and a stable clock source |
| Processing path | RAW capture, ISP, or a downstream application that can consume the format |
The practical choice is the board with the shortest verified path from the sensor to a userspace video node. A board with more theoretical bandwidth can still be a worse choice if its BSP hides the receiver or lacks a sensor-driver pattern.
The Linux media subsystem models many camera systems as a graph of sub-devices and video nodes. The kernel's V4L2 sub-device documentation describes the sensor and receiver components that make up that graph. The Media Controller API documentation explains how links and pads expose the topology to userspace.
2. Freeze the Hardware Contract
Before editing a device tree, confirm the physical design.
Lanes and link rate
Record the number of data lanes, the clock lane, lane order, lane polarity, and the actual sensor mode. A four-lane connector is not a four-lane working design if only two lanes are routed, the lane order is swapped, or the sensor registers still select a two-lane mode.
Do not assume that a property named link-frequencies has identical units or semantics in every driver. Confirm whether the target driver interprets it as a per-lane rate, a pixel-link rate, or another driver-specific value.
Clock and power
The sensor's external clock must match its PLL requirements. Use the exact frequency from the sensor datasheet; 24 MHz is common, but it is not universal. Also verify:
- analog, digital, and I/O supply rails;
- regulator enable order and settling time;
- reset and power-down GPIO polarity;
- I2C or SPI voltage levels and address;
- FPC orientation, differential-pair routing, impedance, and reference plane;
- thermal and mechanical conditions that can change the link.
If the sensor cannot complete power-up or its PLL cannot lock, a correct V4L2 command will not repair the hardware.
ISP and output format
Decide whether the sensor produces RAW Bayer, YUV, or another format. A RAW stream may need an ISP before an application can display or encode it. A YUV stream may bypass part of that path but still require an exact media-bus format and stride. Keep the sensor output, receiver input, ISP output, and /dev/videoN format consistent.
3. Check BSP and Driver Readiness
Before selecting a board, inspect its kernel or vendor BSP for four layers:
- the CSI-2 receiver and D-PHY or SerDes driver;
- the sensor driver or a close reference driver;
- device-tree bindings for lanes, clocks, endpoints, and regulators;
- the ISP, DMA, and video-node path that delivers frames to userspace.
The sensor driver normally probes over I2C, reads a chip ID, registers a V4L2 sub-device, advertises supported pad formats and frame sizes, and programs the sensor registers when streaming starts. If no driver exists, adapting an upstream sensor driver pattern is usually more predictable than starting from an arbitrary capture example, but the register tables and mode timings remain sensor-specific.
Vendor examples are useful evidence of a software path, not proof of portability. NVIDIA's Camera Software Development Solution is one example of a platform-specific integration model. Its device-tree properties, driver names, and userspace framework cannot be copied to another board without checking the target BSP.
4. Describe the Sensor and Receiver in the Device Tree
The exact binding is platform-specific, but a sensor endpoint normally needs to describe the control bus, clock, power controls, and the remote CSI-2 endpoint. A conceptual fragment looks like this:
sensor@10 {
compatible = "vendor,sensor-name";
reg = <0x10>;
clocks = <&clock_provider SENSOR_XCLK>;
clock-names = "xclk";
reset-gpios = <&gpio SENSOR_RESET GPIO_ACTIVE_LOW>;
port {
sensor_out: endpoint {
remote-endpoint = <&csi_rx_in>;
data-lanes = <1 2>;
clock-lanes = <0>;
link-frequencies = /bits/ 64 <456000000>;
};
};
};
Treat this as a shape of the contract, not a drop-in binding. The compatible string, clock name, endpoint properties, lane numbering, and frequency units must come from the target driver's binding. Enable the CSI receiver, D-PHY, clocks, regulators, and any required ISP or DMA nodes in the board support package.
After changing the device tree or overlay, rebuild the correct image, reboot, and check the probe and link messages before trying a high-level application.
5. Bring Up the Media Graph in Small Steps
Use a staged sequence so a failure has a narrow cause.
Step 1: Confirm the control bus
Use the board's documented I2C bus and confirm that the sensor responds at the expected address. A response does not prove that the sensor is powered correctly or that the driver can stream, but no response makes later media debugging premature.
Step 2: Confirm probe and link-up
Load the driver or overlay and inspect dmesg. Look for the sensor chip ID, clock and regulator errors, CSI-PHY link state, lane or settle-time errors, and failed endpoint binding.
Step 3: Inspect the topology
The media controller should expose a path similar to:
sensor sub-device -> CSI-2 receiver -> ISP or DMA -> /dev/videoN
Print the topology with the tools supplied by the target distribution:
media-ctl -d /dev/media0 --print-topology
The entity names and pad numbers are board-specific. Do not copy the numbers from another platform.
Step 4: Set formats from the sensor outward
Set the sensor pad format, enable the required links, and then set the receiver and downstream format. A generic example is:
media-ctl -d /dev/media0 \
--set-v4l2 "'sensor 1-0010':0 [fmt:SRGGB10_1X10/1920x1080 field:none]"
The entity name, bus code, resolution, and pad index must match the actual graph. If the sensor advertises a RAW 10-bit format but the capture node expects YUYV, the pipeline will fail or produce unusable data.
Step 5: Capture a bounded sample
Once the graph is configured, capture a small number of frames:
v4l2-ctl -d /dev/video0 \
--set-fmt-video=width=1920,height=1080,pixelformat=RG10 \
--stream-mmap --stream-count=10 --stream-to=frame.raw
Use a pixel format accepted by the actual video node. For a higher-level application, use the board's supported GStreamer, libcamera, or vendor framework after raw capture is stable.
6. Validate the Whole Pipeline
Successful frame capture is the first milestone, not the final result. Validate:
- the delivered frame size and frame rate;
- pixel format, bit depth, stride, and byte order;
- frame-start and frame-end behavior;
- dropped frames, CRC errors, and timestamp jitter;
- CPU, memory, DMA, and ISP load;
- reconnect and power-cycle behavior;
- downstream conversion, inference, encoding, or storage.
For a radar or other non-camera sensor, also validate the application meaning of each frame. A V4L2 node can deliver bytes while the application still misinterprets line packing, coordinate order, timing, or metadata.
Do not add RKNN or another AI runtime until capture and format validation pass. If the stream will feed a model, then validate model preprocessing and inference separately. The existing RKNN compatibility checklist covers that later gate; it does not replace CSI bring-up.
7. Platform Routing For This Use Case
YY3588: primary worked example
The youyeetoo YY3588 Wiki documents two MIPI CSI D-PHY inputs, configurable as one four-lane path or two two-lane paths. Its CSI guide documents the CSI1 and CSI2 board connections and warns that the camera must be connected to the correct CSI interface rather than a DSI interface.
This makes YY3588 a defensible worked example for checking board-level CSI wiring and a documented Android camera path. It does not prove that an arbitrary radar front end will work without a sensor driver, device-tree work, clock and power validation, and the correct BSP. Public documentation also does not provide a controlled Linux custom-sensor throughput result for this guide.
YY3568: conditional alternative
The YY3568 Wiki lists CSI camera support and provides Android and Ubuntu camera examples, plus OpenCV and RTSP development paths. It can be a lower-compute alternative when its documented software path and workload fit the project. Current availability, pricing, and custom-sensor validation remain unverified here.
R1: pending candidate
The R1 Wiki shows a two-CSI camera path and an Android CameraX example. The current project evidence does not establish the relevant hardware-version boundary or a complete Linux custom-sensor path, so R1 remains a candidate for follow-up rather than a recommendation in this article.
8. Failure Matrix
| Symptom | First checks |
|---|---|
| Sensor missing from I2C | Power rails, reset/PWDN state, I2C bus, address, voltage level |
| Driver probes but no media link | Endpoint references, lane mapping, clock lane, D-PHY/SerDes enablement |
| PHY reports settle or CRC errors | MCLK, link frequency, lane polarity, signal integrity, settle-time settings |
| Video node exists but stream fails | Pad formats, link enablement, resolution, frame interval, ISP/DMA path |
| Frames arrive with wrong colors or shape | Bus code, bit depth, byte order, stride, Bayer order, conversion stage |
| Stream works briefly then fails | Thermal state, clock stability, power sequencing, buffer pressure, cable integrity |
| Capture works but application fails | Userspace format negotiation, buffer type, metadata, timestamps, and downstream assumptions |
Change one layer at a time. Do not compensate for a device-tree lane mismatch by changing userspace pixel formats.
9. Acceptance Checklist
Before calling a custom sensor integration ready for the next development stage, record:
- sensor part number, mode, lane count, lane rate, clock mode, and output format;
- board revision, connector, lane mapping, MCLK, regulators, and GPIO polarity;
- OS, kernel, BSP, sensor-driver revision, and device-tree commit;
- I2C probe and chip-ID evidence;
- media topology and negotiated pad formats;
- capture-node format, frame count, sustained frame rate, and dropped-frame count;
- representative power-cycle, reconnect, and thermal observations;
- any remaining RAW/ISP, inference, recording, or application work.
The decision is then concrete: the board either passes the documented sensor mode, or the next blocker is named. "The SBC has a CSI connector" is not an acceptance result.
Frequently Asked Questions
Is a four-lane CSI-2 connector enough for a four-lane sensor?
No. The PCB routing, lane mapping, receiver configuration, sensor registers, clock mode, driver, and downstream format must all agree.
Can I use v4l2-ctl without writing a sensor driver?
Only when the sensor is already supported and the board exposes a working sub-device. v4l2-ctl configures and captures an existing pipeline; it does not replace the sensor driver or device-tree binding.
Should I choose the board with the highest camera bandwidth?
Choose the board with the most complete, verified path for the sensor and workload. Bandwidth matters, but driver maturity, clocks, power control, ISP behavior, and maintenance usually decide bring-up risk.
Does the YY3588 CSI interface guarantee support for a custom radar front end?
No. The YY3588 documentation proves the board interfaces and documented camera path. A custom radar front end still needs compatible electrical signaling, a driver, device-tree configuration, and application-level format validation.