DEV Community: 宛涵

USBPcap and usbmon debugging: what to collect before blaming firmware

宛涵 — Tue, 23 Jun 2026 07:16:50 +0000

USB bugs are easy to describe badly.

The device is not detected.
The HID report is wrong.
The endpoint stalls.
It works on one machine but not another.
The firmware team says the host is wrong.
The host team says the firmware is wrong.

The fastest way out is to collect evidence at the USB transfer level.

On Windows, that often means USBPcap. On Linux, that often means usbmon. The capture alone is only the beginning; the useful work is turning that capture into a readable explanation.

Start with the failure mode

Before capturing, write down the exact failure.

Examples:

Device never enumerates
Configuration is selected but interface does not start
HID input report length is unexpected
Bulk IN endpoint stops responding
CDC device opens but no data arrives
Mass Storage command times out
UVC camera exposes descriptors but preview fails

Different failures require different evidence.

Capture enumeration first

If the device is not recognized correctly, capture from plug-in through configuration.

Look for:

reset
device descriptor request
configuration descriptor request
string descriptor requests
set address
set configuration
interface and endpoint descriptors
class-specific descriptors

Enumeration bugs often hide in descriptors, not payload data.

Read descriptors like a contract

Descriptors tell the host what the device claims to be.

Check:

bDeviceClass / bInterfaceClass
idVendor / idProduct
bcdUSB
configuration count
interface count
endpoint address and direction
endpoint transfer type
wMaxPacketSize
polling interval
HID report descriptor
CDC class descriptors
UVC class descriptors

If the descriptor contract is wrong, the host may behave correctly while the product still fails.

Separate control, interrupt, bulk, and isochronous traffic

Not every transfer means the same thing.

Control transfers often explain setup and class requests.

Interrupt transfers often matter for HID devices.

Bulk transfers often matter for CDC, storage, vendor protocols, and firmware update flows.

Isochronous transfers often matter for cameras, audio, and real-time media.

A readable timeline should keep these categories visible.

Check setup packets before payloads

For control transfers, inspect the setup packet:

bmRequestType
bRequest
wValue
wIndex
wLength

A single wrong wIndex or request direction can explain a failure that looks like a payload problem.

Compare good vs bad hosts

If the device works on one machine and fails on another, capture both.

Compare:

descriptor requests
selected configuration
class driver behavior
endpoint polling interval
transfer sizes
timeout patterns
stall/clear-feature sequences

Do not assume the host with the failure is the only interesting one. The working host is your baseline.

Avoid overclaiming from software captures

USBPcap and usbmon are software-side evidence. They are very useful, but they are not a replacement for a hardware analyzer when the question is electrical timing, signal integrity, low-level bus errors, or power behavior.

Use software captures for:

enumeration logic
descriptors
class requests
transfer sequence
payload inspection
host/device protocol behavior

Use hardware tools when you need electrical truth.

What to send to firmware or support

A useful USB debugging handoff should include:

OS and kernel/build version
Device VID/PID
Firmware version
Capture source: USBPcap or usbmon
Failure mode
Enumeration summary
Descriptor notes
Endpoint involved
Transfer timeline
Relevant setup packets
Payload examples if safe
What changed between good and bad runs

That is much better than “USB does not work”.

Where Bus Scope fits

You can capture USB evidence with USBPcap, usbmon, Wireshark, and scripts. The hard part is making the session readable enough for firmware, hardware, and support teams to discuss the same evidence.

I build Bus Scope for that workflow. It is a local desktop USB diagnostics workbench for inspecting USBPcap or usbmon evidence, descriptors, endpoints, HID reports, payloads, sessions, filters, and exportable support notes.

It is not a professional hardware analyzer replacement for electrical timing or signal integrity. It is for daily software-side USB debugging and handoff.

Disclosure: I build Bus Scope.

Quick checklist

[ ] Define the exact failure mode
[ ] Capture from plug-in if enumeration matters
[ ] Save descriptors
[ ] Inspect setup packets
[ ] Separate transfer types
[ ] Compare good and bad hosts
[ ] Document OS, firmware, VID/PID
[ ] Export a readable handoff

How to prepare a PCAP for vendor support without leaking the whole capture

宛涵 — Tue, 23 Jun 2026 07:02:13 +0000

Packet captures are useful because they are specific. They are risky for the same reason.

A raw PCAP can contain:

internal IP addresses
hostnames
credentials or tokens in cleartext protocols
cookies
DNS queries
customer traffic unrelated to the bug
proprietary endpoints
timing information
enough context to reveal network architecture

Before sending a capture to a vendor, support team, customer, or public issue, treat it like evidence that needs minimization.

The goal is not to make the file pretty. The goal is to preserve the packets needed to reproduce or explain the issue while removing everything that does not belong in the handoff.

Start with the question

Do not edit a PCAP until you know what the receiver needs to answer.

Examples:

Why does TLS negotiation fail after ServerHello?
Why does this device retransmit every request?
Why does the API return 400 only for this payload?
Why does the camera stream freeze after PLAY?
Why does DNS resolve differently on this subnet?

That question tells you which packets matter.

Keep a read-only original

Always preserve the original capture.

Recommended structure:

case-1234/
  original/
    customer-capture-raw.pcapng
  working/
    filtered-draft.pcapng
  handoff/
    vendor-handoff-v1.pcapng
    notes.md

Never overwrite the original file. If a later question appears, you may need to rebuild the handoff from the untouched source.

Reduce the time window

The easiest safe reduction is time.

If the failure happens between 10:42:13 and 10:42:18, the vendor probably does not need a 45-minute capture.

Keep:

a small lead-in before the failure
the failure itself
enough aftermath to show retries, resets, or recovery

Remove unrelated browsing, background sync, update checks, and other noise.

Filter by conversation, not just protocol

Protocol filters are often too broad.

Instead of “all HTTP” or “all DNS”, narrow to:

client IP
server IP
port
stream/conversation
device MAC
transaction ID
request path if visible

A narrow conversation makes review faster and reduces accidental disclosure.

Redact identifiers deliberately

Common fields to inspect before sharing:

IP addresses
MAC addresses
Hostnames
DNS queries
HTTP headers
URLs and query strings
Cookies
Authorization headers
Email addresses
Usernames
Device serial numbers
Payload strings

Redaction should be intentional. Replacing every IP with nonsense can destroy routing evidence. Leaving every internal hostname can leak environment details.

A good rule:

preserve structure needed for diagnosis
remove identities not needed for diagnosis
document what changed

Repair checksums when rewriting

If you modify packet bytes, addresses, or headers, checksums may no longer match.

Some tools ignore bad checksums. Some analysis tools and test harnesses do not.

After editing, check:

IP header checksum
TCP checksum
UDP checksum
transport length fields
capture file format validity

If the file is meant for replay, testing, or regression fixtures, checksum correctness matters more.

Add a short handoff note

Do not send a PCAP alone.

Include a note like:

Case: login request fails after TLS renegotiation
Original capture retained internally: yes
Shared file time window: 10:42:10-10:42:22 UTC
Included hosts: client 10.0.0.15, api.example.internal
Redactions: client IP anonymized, hostname shortened, cookies removed
Checksums repaired: yes
Expected symptom: server closes connection after packet 184
Question for vendor: is this close_notify behavior expected?

That note prevents the receiver from reverse-engineering your intent.

Validate the final file

Before sending:

[ ] Opens in Wireshark/tshark
[ ] Contains the failure
[ ] Does not contain unrelated traffic
[ ] Redactions are documented
[ ] Checksums are valid if needed
[ ] File size is reasonable
[ ] Receiver knows what question to answer

Where PCAP Surgery fits

You can do parts of this with Wireshark, editcap, text notes, and scripts. The problem is that safe support handoff is a workflow, not one command.

I build PCAP Surgery for that workflow: review, trim, redact, repair checksums, and export focused PCAP/PCAPNG files from a local desktop workbench.

It is not a live packet sniffer, IDS, VPN, or traffic generator. It is for preparing packet evidence that can be safely handed to another person.

Disclosure: I build PCAP Surgery.

Minimal handoff checklist

[ ] Define the support question
[ ] Preserve the original capture
[ ] Trim the time window
[ ] Keep only relevant conversations
[ ] Redact sensitive identifiers
[ ] Repair checksums if rewriting
[ ] Export a focused PCAP/PCAPNG
[ ] Send a short note with the file

RTSP black screen troubleshooting: what to check when VLC works but your VMS does not

宛涵 — Tue, 23 Jun 2026 07:01:48 +0000

An IP camera stream failure is rarely just “RTSP does not work”. The useful question is more specific:

Did RTSP authentication succeed?
Did DESCRIBE return the SDP you expected?
Did SETUP choose TCP interleaved or UDP RTP?
Is media arriving after PLAY?
Are RTP sequence numbers continuous?
Does the codec profile match what the client can decode?
Is ONVIF handing the VMS a different URI than the one you tested in VLC?

When a camera plays in VLC but not in an NVR/VMS, the failure is usually in the gap between “the stream exists” and “this client can negotiate, receive, and decode it reliably”.

Start with the exact URI

Do not compare two different tests.

Write down the full RTSP URL used by each client:

rtsp://user:pass@camera.local:554/path

Check for differences in:

profile path
channel number
stream subtype
query parameters
username/password encoding
transport settings
ONVIF-generated URI vs manually copied URI

Many cameras expose multiple profiles. VLC may be opening the main stream while the VMS is using a substream, or vice versa.

Check the RTSP control flow

A normal session usually looks like this:

OPTIONS
DESCRIBE
SETUP video
SETUP audio (optional)
PLAY
TEARDOWN

Useful failure patterns:

401 loop

Authentication is not being accepted. Check digest/basic auth, clock drift on some devices, special characters in passwords, and whether the VMS encodes credentials differently.

DESCRIBE succeeds, SETUP fails

The client can read metadata but cannot negotiate media transport. Check UDP/TCP mode, client ports, firewall/NAT, and multicast settings.

PLAY succeeds, black screen

The control session succeeded, but media or decoding failed. Now inspect RTP and codec details.

Read the SDP instead of guessing

The DESCRIBE response should return SDP similar to:

m=video 0 RTP/AVP 96
a=rtpmap:96 H264/90000
a=control:trackID=1
a=fmtp:96 packetization-mode=1; profile-level-id=...

Check:

codec: H.264, H.265, MJPEG
payload type
control attribute
SPS/PPS availability for H.264
profile-level-id compatibility
audio track that may confuse weaker clients

A stream can be valid but still use a profile or packetization mode the receiving system handles poorly.

Verify RTP actually arrives

If RTSP SETUP selected UDP, confirm that RTP packets arrive on the negotiated ports.

Symptoms of blocked media:

RTSP commands return 200 OK
PLAY succeeds
no RTP packets arrive
no RTCP receiver reports
client shows black screen or timeout

This often means firewall, NAT, VLAN, routing, or client port negotiation is the real issue.

If TCP interleaved works but UDP does not, you have a transport path problem, not necessarily a camera problem.

Inspect RTP continuity

When packets arrive but playback freezes or breaks, look for:

sequence gaps
timestamp jumps
marker bit behavior
payload type changes
RTCP sender reports
jitter patterns

A few packet losses may be tolerable. Repeated gaps around keyframes can make a stream look like a decode failure.

ONVIF handoff can hide the real URI

Many VMS products discover cameras through ONVIF, then request stream URIs from the device.

That URI may not match the one you tested manually.

Compare:

ONVIF profile token
returned media URI
transport protocol requested by ONVIF client
main/sub stream selection
authentication behavior after handoff

If VLC uses a hand-written URI and the VMS uses an ONVIF URI, you have not tested the same thing yet.

What to hand to support

A useful report should include:

Camera model / firmware
Client name and version
RTSP URL path (without password)
Transport mode: TCP or UDP
RTSP request/response summary
SDP video/audio details
RTP arrival status
Packet loss or sequence gap notes
Codec profile notes
Exact failure symptom

That is much more actionable than “camera does not play”.

Where RTSP Inspector fits

You can do parts of this manually with VLC logs, Wireshark, ONVIF tools, and packet captures. The hard part is turning those pieces into a compact handoff that a camera vendor, installer, or VMS support team can understand.

I build RTSP Inspector for that workflow. It is a local desktop tool for RTSP, RTP, RTCP, SDP, ONVIF handoff, packet loss, and codec-readiness diagnostics. It is not a VMS, NVR, surveillance recorder, or media player; it is meant to explain why a stream does or does not work.

A practical workflow is:

Reproduce the failure with the same URI the client uses.
Capture RTSP control messages and SDP.
Confirm transport mode and media arrival.
Inspect RTP/RTCP evidence.
Export a report for support handoff.

Disclosure: I build RTSP Inspector.

Quick checklist

[ ] Same RTSP URI in both clients
[ ] Authentication result known
[ ] DESCRIBE response saved
[ ] SDP codec/profile inspected
[ ] SETUP transport mode known
[ ] RTP arrival confirmed
[ ] RTP sequence gaps checked
[ ] ONVIF media URI compared
[ ] Report prepared for support