GigE camera streaked frames on an embedded board: test the link first

Streaks across frames from a GigE camera on an embedded board look like a sensor or driver fault, and they rarely are. The same camera that streams cleanly into a desktop PC is telling you the sensor is fine. What breaks is throughput: the board's Ethernet path cannot carry the camera's data rate, UDP packets go missing, and every lost packet tears a band across the frame. Dropping the resolution to 640 × 480 hides the problem because the smaller stream fits the damaged link. This guide gives you the arithmetic that predicts streaks, a ten-minute iperf3 test that separates a healthy link from a starved one, and the fixes in the order that works: network driver, negotiated speed, cabling, switch path, and only then camera or SDK settings.

The streak is a lost packet, not a bad sensor

GigE Vision carries image data as UDP (User Datagram Protocol) datagrams, and UDP does not retransmit. When a datagram goes missing, the receiver asks the camera to resend it; at a low loss rate the resends quietly patch the gap, and at a high rate they cannot keep up. Every unrecovered gap lands in the image as a horizontal streak, a torn band or a run of shifted scanlines. That is the same packet-loss signature behind horizontal lines in live GigE images; the difference here is where the loss comes from.

The same hardware behaving differently on two hosts is the strongest clue you get. Run the camera into a laptop on the same cable for an hour. If the laptop's stream stays clean while the board's streaks, the sensor, the camera and the cable have all passed. Spend the rest of the session on the board's network path, and stop considering a camera swap.

Budget the camera's data rate first

Before you test anything, work out what the camera demands of the link. One multiplication does it:

Bytes per pixel: 1 for 8-bit mono, 1.5 for 12-bit mono, 2 for YUV422, 3 for RGB8. Set the headroom target at 20-30% of the link's measured rate, not its nominal rate.

Worked example: a 12 MP sensor at 4000 × 3000 pixels, 8-bit mono, 9 fps.

• Frame size: 4000 × 3000 = 12,000,000 px × 1 B = 12 MB × 8 = 96 Mbit.
• Stream rate: 96 Mbit × 9 fps = 864 Mbps.
• Margin on a healthy 940 Mbps link: (940 - 864) / 940 = 8%. That is under the 20-30% target, so this class of camera runs at the ceiling, and any throughput dip shows up as streaks before it shows as dropped frames.
• On a starved link at 350 Mbps, the same camera manages 350 / 96 = 3.6 fps without loss. Above that rate, packets fall off the link and the streaks return.

The LS-CMR-0053 sits exactly in this class: 12 MP on a 1/1.7" sensor over GigE, rated at 9 fps. If your stream lives within 10% of the link's ceiling, treat every driver and cable change as a throughput change and re-measure after each one.

Measure the link with iperf3 in UDP mode

iperf3 pushes a known UDP load through the link and reports what survived. Run the server on the board, so the traffic flows in the same direction as the camera's stream:

# on the embedded board: start the receiver and leave it running
iperf3 -s

# on the PC: 192.168.0.10 stands in for the board's address
iperf3 -c 192.168.0.10 -u -b 0 -l 16K -t 120 -i 1

The flags matter. -u tests UDP, which is what GigE Vision streams over. -b 0 removes iperf3's 1 Mbps default cap for UDP and lets the sender run at line rate; skip it and the test will read a flattering 1 Mbps. -l 16K sends 16 KB datagrams because the 8 KB default reads a few percent low.

-t 120 -i 1 runs for two minutes with a report each second, long enough to catch a marginal cable or a throttling driver. Read the receiver's closing summary: delivered throughput is what counts, not what the sender attempted. Run it a second time with the roles swapped to test the transmit path too; the receive run is the one that mirrors your streaks.

What healthy looks like, and why: gigabit Ethernet moves 1,000 Mbps at wire rate, framing and headers at 16 KB datagrams cost under 1%, and a healthy host stack sustains 940-950 Mbps. Treat 940 Mbps as the pass mark.

A small loss figure at a delivered rate near 950 Mbps is the receiver's stack running at its limit, not a cable fault, so judge delivered throughput first. Anything at 940 or better clears the network; below 900, find the cause before you touch the camera or the SDK.

Why 640 × 480 stops the streaks

The clean low-resolution frame is the diagnosis confirming itself. Run the budget arithmetic at 640 × 480, 8-bit mono, 30 fps: 640 × 480 = 307,200 px × 1 B = 307,200 B × 8 = 2,457,600 bit ≈ 2.46 Mbit per frame. At 30 fps that is 73.7 Mbps. Even a starved link at 350 Mbps carries that with (350 - 73.7) / 350 = 79% headroom, so nothing drops and the streaks vanish. The artefacts were throughput starvation, not sensor noise. Do not ship the reduced resolution as the fix — it caps your measurement resolution permanently. Restore the full frame only after the link passes the iperf3 test.

Likely causes in order of probability

1. Stale NIC driver or kernel on the board. Test: iperf3 lands at 300-400 Mbps while a laptop on the same cable passes at 940. Fix: install the board vendor's current kernel and Ethernet driver, then retest. This is the most common cause on ARM boards, and a driver update alone has repeatedly moved UDP throughput from a few hundred Mbps to line rate.
2. Link negotiated down to 100 Mbps. Test: iperf3 sits at 90-95 Mbps and the host's link-state tool reports 100. Fix: reseat or replace the cable, try another port, and force 1 Gbps on the local end.
3. Marginal cable or connector. Test: swap in a known-good shielded camera cable and rerun. Fix: a drag-chain-rated cable with screw locks, kept short — featured below. 1000BASE-T is specified to 100 m on Cat5e or better, but a machine harness needs shielding and strain relief more than length.
4. Switch port or shared uplink. Test: connect the camera straight to the board and rerun. Fix: one dedicated port per camera; where cameras must share an uplink, divide the budget first.
5. CPU starved of interrupt time. Test: watch softirq CPU load during the run and during capture; a board that cannot keep up at line rate drops packets inside the kernel. Fix: stop competing processes, pin the camera's interrupt to its own core, and update to a driver with receive offloads.
6. Every test passes and the streaks persist. The loss is happening after the NIC, in receive software — the next section.

Fixes that hold

Start with the driver and kernel: it is the highest-yield fix on an embedded board, and it changes no hardware. After every update, rerun the two-minute iperf3 test, because driver regressions are common enough to deserve the re-check.

Keep the path direct. One camera on one port beats any switch. When several cameras share a host, plan the ports and uplinks before you mount anything — the GigE camera network planning guide covers the layout.

Then the cable. Office patch leads fail in machines at the latch and the shield. A drag-chain-rated GigE cable with screw locks, such as the 3 m LS-CBL-0199, holds its shielding and strain relief where a patch lead cannot; compare camera data cables by length and flex rating before ordering.

When the board itself cannot be rescued, change the host side. In a vision controller or any host with a free full-height PCIe slot, a dual-port PoE NIC such as the MV-GE2002P puts two proven gigabit ports in the path, powers the cameras over their data cables, and takes the onboard Ethernet out of the equation. The frame grabbers category and the accessories finder filter the options by port count.

There is also a platform escape hatch: if the Ethernet stack still cannot hold 900 Mbps after a driver update and the pixel budget cannot shrink, change interfaces. A USB3 camera bypasses the board's Ethernet path entirely, and the ARM board for USB3 camera acquisition guide covers what to check before committing to that route.

When the link passes and the streaks remain

Then the packets are being lost after the NIC. Three receive-side causes cover most of what is left.

First, SDK receive buffers too few or too small. Raise the buffer count before tuning anything else, because a full queue forces the driver to drop frames. Second, work inside the frame callback: converting or detecting in place of the handoff stalls the queue. Copy the buffer and hand it to another thread, the way the camera callback buffer copy guide shows. Third, packet size set beyond what the path supports. Set it to the largest size the camera, any switch and the host MTU all accept, and set it before acquisition starts — the packet size before acquisition guide walks the order.

To pin the loss to acquisition time rather than later processing, save a raw frame sequence straight from the SDK and inspect the saved frames. Streaks already present there happened during acquisition, and nothing downstream can repair them. If the SDK reports buffer-overflow errors while iperf3 passes, the host is holding frames too long; the GigE camera buffer overflow troubleshooting guide walks that receive-side path step by step.

Keep it fixed

• Budget every new camera before ordering: pixels × bytes per pixel × fps × 8, with 20-30% of the measured link rate spare.
• Rerun the two-minute iperf3 test, both directions, after every OS, kernel or driver update.
• One camera per port, and no shared uplink without a written budget.
• Shielded, screw-locked camera cable, strain-relieved, kept short inside the machine.
• Check negotiated link speed after any cable or port change; the fall to 100 Mbps stays silent until the streaks return.
• Keep packet size consistent across camera, switch and host MTU.

The decision

• iperf3 at 940 Mbps or better: the network is proven, so fix streaks in software — buffer count, callback work, packet size.
• iperf3 at 300-400 Mbps: update the board's kernel and Ethernet driver, retest, and leave the camera alone.
• iperf3 at 90-95 Mbps: reseat or replace the cable, try another port, force 1 Gbps.
• Link passes but the camera's budget leaves under 20% headroom: cut fps to measured rate ÷ frame size, shrink the region of interest, or move the camera to USB3.
• Same camera clean on a laptop: the camera is exonerated; spend the budget on cabling and driver time, not a replacement.

If you are specifying hardware rather than rescuing a board, browse the area scan cameras range, filter it in the camera finder, or configure a system and let the picker size the link. For a board that refuses to cooperate, contact us with three numbers — the receive rate, the loss figure and the camera's fps — and we will tell you which side to fix. The rest of the acquisition pipeline, from trigger to transfer, is collected on the systems topic page.