Board level camera image corrupted: check format and wiring

A camera module that hands back a JPEG the decoder refuses, or an RGB565 frame that lands on the storage smeared into diagonal stripes, rarely has a broken codec. The bytes leave the sensor intact and are then truncated, miscounted, mislabeled or bit-flipped between the die and the file. This guide is for engineers bringing up small camera modules on microcontroller and embedded boards. It gives the marker checks, the stride arithmetic, the wiring limits and a fix order, so you can name the failing layer in under an hour — and decide with evidence whether the module stays or goes.

Why does a saved JPEG from a board-level camera fail to decode?

In most cases the decoder is innocent: the byte stream it receives is truncated, mislabeled or bit-corrupted, so the first check is whether the file starts with the JPEG start marker FF D8 and ends with the end marker FF D9.

A JPEG file is a marker stream wrapped around compressed entropy data, and a decoder that gives up has hit one of three situations: the stream stops before the end marker, the bytes were never JPEG output, or bit errors scrambled the entropy data in transit. Open the saved file in a hex viewer and read two places.

• The first two bytes must read FF D8, the start-of-image marker. Absent, and the buffer never held JPEG at all — you are feeding raw pixels to a decoder, the host-side cousin of JPEG decode hangs on raw pixel data.
• The last two bytes must read FF D9, the end-of-image marker. Absent, and the stream was cut mid-entropy-data. That is truncation, and the buffer sizing below fixes it.

Both markers present and the image still fails? The damage sits inside the entropy data itself, which points at bit errors on the module bus. Corruption picked up after the camera — a network hop or a file rewrapped by an intermediate parser — leaves a different fingerprint, extraneous bytes ahead of a marker; that case is its own repair, covered in corrupt JPEG data with extraneous bytes before the marker.

Which failure is it: truncated stream, wrong format or bad wiring?

Test in this order: a missing FF D9 at the end of the file means truncation, no FF D8 at the start means a format mismatch, and corruption that moves when you flex the cable means wiring.

The order below is probability, not convenience. Each test takes one capture and one hex view.

1. Truncated stream — the most common. Buffers get sized from one lucky frame and stay silent until a busy scene produces a longer JPEG. Signature: the saved file is exactly as long as your allocation, and FF D9 is missing. Fix: the buffer sizing two sections down.
2. Format mismatch — the quiet bring-up failure. The sensor never left its power-up output mode, or the capture code declares one pixel format while the module delivers another. Signature: no FF D8, and the bytes look like plausible pixels. Read the output-format setting back over the control bus after writing it; a read-back mismatch closes this case in one pass. The wider habit — know what your bytes are before you process them — is the subject of image bytes vs pixel data.
3. Ribbon bit errors — the marginal hardware case. A grossly broken bus shows nothing at all, while a marginal one corrupts long frames first. Signature: the corruption pattern changes when you flex the cable, and damage grows with resolution. Fix: the ribbon section below.

For failures that turn out to be pipeline and driver problems rather than byte damage, the systems topic page collects the rest of the transport and format repairs.

Why is a saved RGB565 image smeared, sheared or folded back on itself?

A smear is a stride error: RGB565 stores 2 bytes per pixel, so a 320-pixel row occupies 640 bytes, and a writer that advances 320 bytes per row shifts every line until the frame shears and folds back on itself.

Stride is the byte distance from one row to the next, and every writer, converter and display must agree on it.

Worked example, a 320×240 RGB565 frame:

• bytes per row = 320 px × 2 B/px = 640 B
• full frame = 640 B × 240 rows = 153,600 B = 150 KiB
• a writer advancing 320 B per row consumes 320 B × 240 = 76,800 B, half the frame, and every saved row holds the left half of the intended one

Two quieter variants of the same error:

• Portrait and landscape swapped. A 240×320 allocation against a 320×240 capture holds the same 153,600 B, so nothing overflows; the geometry simply scrambles. Check width and height separately.
• Word-boundary padding. An interface that moves 32-bit words pads each row to a 4-byte boundary. 320 px needs none, since 640 B divides by 4, but a 321-px line is 642 B and pads to 644 B — every row after the first walks 2 bytes out of step, a diagonal tear that grows toward the bottom.

Raw-Bayer paths use the same arithmetic at 1 B/px for 8-bit output; what raw output is and is not is covered in CSI camera with no ISP.

Why do the colors look swapped or washed out when the geometry is right?

Wrong colors with correct geometry mean byte order: RGB565 and BGR565 pack red and blue into opposite ends of the same 16-bit word, so a channel swap turns red objects blue and a byte swap washes the whole frame into striped mush.

One test separates the two. Point the camera at something solidly red.

• It renders blue: channel order. The producer packed BGR565 where the consumer reads RGB565. Fix it in the conversion, or select the matching channel order on the sensor side if its settings offer one.
• The hue is right but banded and steppy: byte order. The two bytes of each 16-bit word travel out of sequence, so red bits land where blue bits were expected. Fix with a per-pixel byte swap in the conversion loop, or set the module output byte-order option — many modules expose one.

Uncompressed paths carry this failure; JPEG paths do not. A decoder emits pixels in a fixed channel order, so wrong colors on a decoded JPEG point at the decoder-to-display step, not at the camera. The display-side twin of this mismatch, grayscale appearing where color should be, is worked through in grayscale image display on composite video: fix the RGB565 mismatch.

Can a short-pitch ribbon really corrupt digital image data?

Yes: a parallel camera bus clocks an 8- or 10-bit data word on every pixel cycle at a few tens of megahertz, and one flipped bit on a marginal ribbon lands mid-frame, where the JPEG decoder reports it as a decode error.

The bus between module and host carries the data lines, a pixel clock, frame and line syncs, a master clock into the module, and a slow control pair. The data lines toggle on every pixel cycle and carry the video; the control pair runs four orders of magnitude slower and misreads loudly, stopping capture rather than damaging frames. That speed difference is why video lines corrupt silently and controls never do.

Keep the parallel video bus at board length: about 10 cm of ribbon is the practical ceiling at these clock rates. Beyond that, crosstalk between adjacent wires and reflections at the connectors flip single bits — invisible as a wrong pixel in a preview, fatal in the middle of a JPEG entropy stream.

The test that convicts or acquits the cable takes a minute: capture while you gently flex the ribbon near each connector. A pattern that moves is the cable. Then work up the cost ladder.

1. Reseat both ends, square and fully home. Short-pitch connectors sit at slight angles after a bench session, and half a millimetre of offset is enough.
2. Shorten the ribbon, or move the module onto the host board.
3. Drop the pixel clock one step and retest. A frame that survives slower confirms a margin problem, not a fix.

The same physics shows up on USB runs as image damage rather than a clean disconnection; that drill is in USB camera signal integrity.

Why does the image break only at larger resolutions or on busy scenes?

Because both multiply the byte count: a 320×240 RGB565 frame moves 153,600 bytes against 38,400 at 160×120, and a JPEG of a busy scene runs longer than the same frame on a flat one, so an undersized buffer truncates only then.

JPEG output is scene-dependent by design: the compressor spends more bytes on detail. A buffer sized from a flat test card is sized from the cheapest frame the camera will ever produce.

Worked example, a truncation you can predict:

• buffer allocated: 48 KiB = 48 × 1024 B = 49,152 B
• a busy 640×480 scene at a high quality setting needs roughly 60,000 B
• the stream stops dead at 49,152 B; the final bytes are entropy data, not FF D9; the decoder reports a failure
• the signature: the saved size equals the allocation exactly. That one equality convicts truncation.

The sizing rule that ends the class: reserve the uncompressed frame size and cap the quality setting mid-range. At 640×480 RGB565 that reserve is 640 × 480 × 2 B/px = 614,400 B, about 600 KiB. With the quality setting capped, no realistic scene produces a JPEG that overruns a full-frame reserve.

The resolution link is the same arithmetic: 160×120 to 320×240 is a fourfold jump in bytes per frame, so a marginal buffer, cable or clock passes the small frame and fails the large one. A module that runs clean at small sizes and breaks blocky above them is a size problem first and a hardware problem second.

How do you fix it, fastest test first?

Work the six steps below in order; each takes minutes, and each either fixes the image or names the guilty layer before you rewrite anything a second time.

1. Capture small. Save a 160×120 frame twice. Failing here means setup — go to step 3. Passing here while the full-size frame fails means size or wiring — continue in order.
2. Hex the file. FF D8 first, FF D9 last. Missing FF D9 is truncation: go to step 4. No FF D8 is a format mismatch: go to step 3.
3. Match the format end to end. Read the sensor output-format setting back over the control bus, rewrite it and read again. Confirm the pixel format the capture code declares matches what the module delivers, then recompute the stride: width × 2 B/px for RGB565, padded to the word boundary the interface moves.
4. Size the buffer for the worst frame. Reserve the uncompressed frame size, 614,400 B at 640×480 RGB565, and cap the quality setting mid-range.
5. Convict or acquit the cable. Power down, reseat both ribbon ends square, shorten the video bus toward 10 cm or drop the pixel clock one step, then capture while flexing the ribbon. A moving pattern was the cable; a stable one points back to the software.
6. Prove it twice. Repeat the original failing capture twice in a row: decoding, geometry and colors all correct, twice. Then make the FF D8 and FF D9 check a permanent line in the save path, so any future corruption arrives named and measured instead of silent.

When is it time to change the camera instead of the code?

Change the camera when the corruption survives a reseated, shortened ribbon and reappears on a second host: that points at marginal hardware inside the module, where your remaining hours are better spent on a standardized interface than on another driver patch.

A standardized industrial transport moves framing, packetization and error reporting into a maintained driver stack, so a failing cable announces itself as a dropped or flagged frame instead of silent corruption. For embedded machines that still want bare-board mechanics, USB3 and GigE board-level cameras mount on the same standoffs as the modules they replace.

The LS-BCM-0003 streams 3.1 MP frames at 120 fps over USB3 on an IMX252 global-shutter sensor.

The LS-BCM-0020 covers the GigE route with a 6.3 MP IMX178 rolling-shutter sensor at 18 fps.

Off the ribbon, put the run on cable built for machines rather than breadboard jumpers: high-flex, drag-chain-rated, positively locked at the camera end.

Before ordering, settle the questions that survive a camera swap — host interface, mounting, driver support — in camera module interface compatibility, and compare the candidates in board level camera selection for embedded vision machines. The board-level cameras category and the camera finder filter by interface and shutter, the camera configurator steps through the host interface first, and the cables category lists lengths and locking styles for the run.