GVSP packets arrive but the player shows no image: debug it

You are bringing up a GigE Vision transmitter. Discovery works, the control channel answers, the acquisition start command goes through, and Wireshark shows a leader, data packets and a trailer for every frame with no decode errors. The host player still shows nothing: no image, no dropped-frame counter, no error counter, nothing. That exact combination is good news, because it narrows the fault to two places — the path between the wire and the receiver's UDP socket, or the frame validation the receiver runs before it counts anything. This guide gives you the checks in the order that separates them fastest, the leader fields a receiver validates, the payload arithmetic with worked numbers, and a baseline test against a known-good camera.

Why does Wireshark show clean GVSP packets but the player shows no image?

Wireshark taps the NIC before the operating system applies any filter, so clean GVSP packets on the wire prove the transmitter transmits, not that the receiver receives; counters stuck at zero mean the frames die between the socket and the SDK.

That capture point sits below the UDP socket layer the player listens on. The OS hands a datagram to the application only when its destination port matches a bound socket, and the SDK filters once more on the source address and stream channel it registered. A clean capture is necessary evidence, never sufficient.

Three things break delivery in practice. The device streams to a port the player never bound, most often through a byte-order mistake in the GVCP write. The destination address points at the wrong adapter on a multi-NIC host. Or the host firewall drops unsolicited inbound UDP while the capture keeps working.

Silent validation failures look identical from the outside. A receiver that rejects a frame on a leader mismatch discards it before the statistics stage, so even the error counters stay flat. Read zero counters as "nothing survived", not "nothing arrived".

What does a receiver check before it counts a frame?

Before a frame is counted, a receiver validates three things in order: that the packet arrived on its own UDP socket, that the leader declares the geometry it negotiated over GVCP, and that the data packet count matches the payload size. Rank your suspects the same way.

1. Destination mismatch — wrong port, wrong address, wrong adapter, firewall shut. This is the one cause that produces a completely silent receiver, counters and errors included, so test it first (next section).
2. Stream channel never armed — the receiver opens the stream channel over GVCP before the acquisition start command. If your transmitter starts streaming from a register write without that handshake, a strict receiver ignores the stream entirely. The standard test packet exists to prove this path end to end.
3. Leader geometry mismatch — width, height, pixel format or payload type disagreeing with the GVCP writes.
4. Payload type not a plain image — a player built for image streams silently ignores leaders it cannot render.
5. Frame and packet id anomalies — reused, skipped or restarting ids push the receiver into resend requests or straight to the discard bin; what genuine loss looks like once it gets through is the horizontal lines in live images symptom.
6. Nonzero status field — a packet flagged as damaged in its own header gets dropped whatever the decode says.

Causes 1 and 2 match your symptom exactly: no counters, no errors, nothing. Causes 3 to 6 usually leave a trace somewhere — a resend request on the control channel, an error register, a timeout message.

Which leader and trailer fields must match the GVCP settings?

Four values in each frame's leader must equal what your device wrote over GVCP: the payload type, the width, the height and the pixel format; the payload size register must equal width × height × bytes per pixel, exactly.

Every frame travels as one leader packet, one or more data packets and one trailer packet, all sharing a single frame id — the structure the open-source Aravis project documents. Expand the GVSP layer of the leader in your capture and compare against the GVCP writes earlier in the same capture:

• Payload format. An image leader uses format 0x01. A different value tells the receiver this is not a plain image frame, and an image-only player drops it without a word.
• Image payload block. The leader's image payload structure — GVSP_LEADER_PAYLOAD_IMAGE in the Aravis sources — carries the width, the height and the pixel format. Each must equal the GVCP value, including the pixel format's four-character code, character for character.
• Payload size. The size your device declared over GVCP must be exactly what the geometry works out to at your bytes per pixel; a Mono8 frame is 1 byte per pixel.
• Ids and trailer. Every packet's GigE Vision header carries the image number and the packet number. Data packet ids start at 1 and step by 1 with no gaps, and the trailer closes the frame. Until the trailer arrives, the receiver holds the frame against its timeout — the receiver-side view of that wait is the GigE Vision stream timeout guide.

A single mismatched byte is enough for a silent discard: the receiver knows what it negotiated, and a different answer is a broken frame, not an error event.

How do you prove where the frames stop, at the socket or in the parser?

Capture on the receiver host itself and list its listening UDP sockets while the player runs: a netstat or ss listing that shows no socket on your captured destination port proves the drop is below the application, before any parser.

1. Leave the player waiting for frames, then list the bound UDP sockets on the receiving host — netstat -ano -p udp on Windows, ss -ulnp on Linux. Note the port number.
2. Read the UDP destination port off your captured GVSP packets. The two numbers must match exactly; a mismatch means the OS discards the stream before the player ever sees a datagram.
3. Decode the port value you wrote. GVCP fields are big-endian: a destination port of 50010 leaves the device as the bytes C3 5A. Written in reverse order, the value reads 5A C3 — that is 23235, a perfectly formed port nobody listens on. Check your register-write code's byte lanes against the write command's data field in the capture.
4. On a multi-NIC host, compare the packets' destination IP with the host's own addresses (ipconfig on Windows, ip addr on Linux). The stream must land on the adapter whose address the receiver registered; the SDK filters on it even when the OS itself would deliver. The same one-address-per-port discipline the assign cameras to ports reliably guide describes for multi-camera rigs applies here.
5. Add a firewall rule for the player's inbound UDP port. Both Windows and Linux firewalls drop unsolicited inbound datagrams silently, and neither touches the capture, which mimics a destination mismatch perfectly.
6. If socket, port, address and firewall all agree, rerun and watch the player's counters. Still flat means the frames now reach the parser and die in validation — go back to the leader fields above.

How much bandwidth and how many packets does one frame need?

A 2448 × 2048 Mono8 frame carries 5,013,504 bytes, which needs 560 data packets at a 9000-byte packet size and 40.1 Mbit per frame, so a gigabit link sustains roughly 23 fps and a 30 fps request truncates every frame.

The arithmetic in full, for a 5 MP transmitter at a 9000-byte packet size:

• Payload. 2448 × 2048 = 5,013,504 pixels; Mono8 carries 1 byte per pixel, so the frame payload is 5,013,504 bytes.
• Packets. IPv4 (20 bytes), UDP (8) and the GVSP common header (8) take roughly 36 bytes per data packet, so each carries about 8,964 image bytes: 5,013,504 ÷ 8,964 = 559.35, rounding up to 560. Read one real data packet's payload length in your capture to confirm the true header cost of your implementation.
• Bandwidth. 5,013,504 bytes × 8 = 40,108,032 bit ≈ 40.1 Mbit per frame. A gigabit link moves about 950 Mbit/s once framing overhead is paid, so the ceiling is 950 ÷ 40.1 ≈ 23.7 — call it 23 fps sustained, and less once resends need headroom. A 30 fps geometry truncates frames; the trailer never arrives, and the receiver may again count nothing.

The same division is your payload-size check: whatever the geometry works out to is what the payload size register must say, and the packet count the trailer implies must match it. Jumbo frames raise the payload share of every Ethernet frame, which is why packet size belongs to the set-up before acquisition, and a packet size the path cannot carry kills the stream entirely — that failure seen from the camera side is the MTU auto-negotiation fix.

How do you test a transmitter against a known-good receiver?

Put a working production camera from the shop on the same cable, NIC and host, capture its stream, and diff your leader against it field by field; if the player displays the reference camera, every receiver-side suspicion is settled at once.

Any current camera from the area scan cameras range makes a clean reference signal on the bench:

Run the reference camera through the same player on the same port and capture it. A working display clears the receiver stack in one move, and the capture becomes your golden sample: leader format, width, height, pixel format, packet size behaviour, id sequences. Diff your transmitter's leader against it byte by byte; the first differing byte is the bug.

A second, independent parser helps as much as the golden sample. An open-source receiver such as Aravis speaks the same protocol and fails differently from your player, so agreement between two receivers isolates transmitter faults fast.

Keep the bench fixed while you swap devices: a single known-good RJ45 camera data cable with a locking stud:

For the capture host, ordinary desktop ports carry a small bench, but a purpose-built NIC keeps the reference camera and the transmitter on separate, PoE-capable sockets:

If the rig grows to several cameras or tighter timing, that is where dedicated frame grabbers earn their slot. The same selection logic applies to acquisition hardware of any kind, and this GigE Vision acquisition hardware selection guide walks the trade-offs.

Which fix matches which symptom?

Zero counters with clean packets points at the destination port, address or firewall; counters that stay flat after the socket checks pass point at leader fields; resends arriving on the control channel point at packet id gaps or payload truncation.

Prevention is six habits that take minutes to add to your bring-up script:

• Capture on the receiving adapter every session.
• Diff the leader against the GVCP writes after each firmware change.
• Keep the test-packet handshake in the bring-up script.
• Compute the payload size from the geometry, never from a constant.
• Step the frame id once per frame; start data packet ids at 1.
• Open the firewall port before the first stream attempt.

When the transmitter displays against the reference camera, point the bench at production hardware: the camera finder filters by interface and resolution, the configurator pairs a camera with the rest of the chain, and the systems topic page collects the receiver-side guides — read the blank-image pipeline probe next, for the case where frames arrive but pixels stay dark. A build question that fits no form goes through /contact/.