Debugging

LibOSDP has extensive debugging and diagnostics built in to help narrow down issues without requiring a back-and-forth exchange. The default logging level is sane for everyday operation — don't generate verbose logs proactively unless you're actively investigating a problem.

A Note on Log Files ​

When reporting an issue, attach the full log from osdp_cp_setup() to the point of failure. Even if you think you know the cause, retain the very first few log lines — they contain the LibOSDP version and PD connection topology.

When creating a GitHub issue, attach the log file or post it on a paste service such as pastebin.com and include the link.

Log Level ​

LibOSDP supports different logging levels, with LOG_DEBUG being the most verbose. When asking for help, set the log level to LOG_DEBUG.

Call osdp_logger_init()beforeosdp_cp/pd_setup():

osdp_logger_init("osdp::cp", LOG_DEBUG, uart_puts);

Any log messages other than DEBUG and INFO should be treated as out-of-ordinary events requiring attention.

Packet Trace Builds ​

The most verbose debugging mode: all bytes on the wire are captured and saved to a .pcap file that can be inspected with WireShark. Useful for low-level protocol issues.

To enable packet trace:

mkdir build-pt && cd build-pt
cmake -DOPT_OSDP_PACKET_TRACE=on ..
make

During CP/PD setup, set the PD info flag OSDP_FLAG_CAPTURE_PACKETS. When your application runs, LibOSDP will produce a .pcap file in the current directory containing all decoded packets.

Data Trace Builds ​

When secure channel is working but you're seeing a command-level failure, data trace dumps the decrypted messages instead of the encrypted wire data.

To enable data trace:

mkdir build-dt && cd build-dt
cmake -DOPT_OSDP_DATA_TRACE=on ..
make

During CP/PD setup, set the PD info flag OSDP_FLAG_CAPTURE_PACKETS. LibOSDP will produce a .pcap file with decrypted packet content.

Note: Running both packet trace and data trace simultaneously is seldom useful and makes it harder to locate relevant information.

WireShark Payload Dissector ​

To view captured packets, set up WireShark with a custom protocol dissector (one-time setup):

mkdir -p $HOME/.local/lib/wireshark/plugins
cp path/to/libosdp/misc/osdp_dissector.lua $HOME/.local/lib/wireshark/plugins/

Windows: Copy osdp_dissector.lua to %APPDATA%\Wireshark\plugins

Restart WireShark if it is running. Then navigate to:

Preferences → Protocols → DLT_USER → Encapsulations Table → Edit

Click + to add a new row with:

DLT: User 15 (DLT=162)
Payload Dissector: osdp
Header size: 0
Trailer size: 0

Open the .pcap files via File → Open. Here is an example of what you can expect to see:

Tip: The trace builds above capture traffic from inside your own LibOSDP application. To watch and decode OSDP traffic on the bus directly — live, and without the Wireshark dissector setup — Osprio Capture is a graphical OSDP protocol analyzer for RS-485.