venus/axiom-nmea/debug/README.md

Debug Scripts

This directory contains debugging and analysis tools for reverse-engineering the Raymarine LightHouse network protocol. These scripts are used to discover field mappings, locate sensor data, and understand the protobuf structure.

Protocol Analysis

protobuf_decoder.py

Full protobuf decoder with documented field mappings. Parses the nested protobuf structure and extracts sensor data (GPS, wind, depth, tanks, batteries, temperature).

python protobuf_decoder.py -i 198.18.5.5
python protobuf_decoder.py --pcap capture.pcap

protobuf_parser.py

Low-level protobuf wire format parser without schema. Decodes the nested message structure to understand the protocol.

raymarine_decoder.py

Standalone Raymarine decoder that extracts sensor data from multicast packets. Outputs human-readable or JSON format.

python raymarine_decoder.py -i 198.18.5.5
python raymarine_decoder.py -i 198.18.5.5 --json
python raymarine_decoder.py --pcap raymarine_sample.pcap

packet_debug.py

Dumps raw protobuf field structure from multicast packets. Shows all top-level fields, nested structures, and decoded values.

python packet_debug.py -i 198.18.5.5

field_debugger.py

Interactive field mapper that displays all protobuf fields in a columnar format. Useful for correlating field values with real-world sensor readings.

python field_debugger.py -i 192.168.1.100           # Live capture
python field_debugger.py --pcap capture.pcap        # From file
python field_debugger.py --pcap capture.pcap -n 5   # Show 5 snapshots

field_mapping.py

Documents the discovered field structure and validates against captured data. Shows the relationship between protobuf fields and sensor values.

analyze_structure.py

Analyzes packet header structure and protobuf nesting patterns. Groups packets by size and examines common headers.

Sensor Finders

These scripts search for specific sensor values within the protobuf stream.

find_cog_sog.py

Searches all protobuf fields for values matching expected COG (Course Over Ground) and SOG (Speed Over Ground) ranges.

python find_cog_sog.py -i 198.18.5.5 --cog-min 0 --cog-max 359 --sog-min 0 --sog-max 0.5
python find_cog_sog.py -i 198.18.5.5 --show-all   # Show ALL numeric fields
python find_cog_sog.py -i 198.18.5.5 -f 2         # Filter to field 2 only

wind_finder.py

Searches for wind speed and direction values in captured packets. Expects wind speed in m/s (7-12) and direction in radians (1.0-1.7).

find_twd.py

Searches for True Wind Direction values in a specific degree range (e.g., 69-73 degrees).

find_twd_precise.py

Precise TWD finder with tighter tolerance for exact value matching.

find_twd_hdg.py

Finds both TWD and Heading offsets using known reference values.

find_heading_vs_twd.py

Correlates heading and TWD candidates. At anchor pointing into wind, heading and TWD should be within ~50 degrees.

find_consistent_heading.py

Finds offsets that show consistent heading-like values across multiple pcap files.

pressure_finder.py

Locates barometric pressure data by searching for values matching a known pressure reading.

python pressure_finder.py -i YOUR_INTERFACE_IP -p 1021  # Known pressure in mbar

battery_finder.py

Scans all multicast groups for values matching expected battery voltages (12V, 24V systems).

python battery_finder.py -i 198.18.5.5 -t 10
python battery_finder.py -i 198.18.5.5 -v   # Verbose mode

tank_finder.py

Scans multicast groups for values matching expected tank level percentages.

Field-Specific Debug Tools

battery_debug.py

Dumps raw protobuf entries to find battery data fields. Supports deep nesting analysis (e.g., Field 14.3.4 for engine battery).

python battery_debug.py -i 198.18.5.5 -t 5
python battery_debug.py -i 198.18.5.5 -f 14   # Focus on Field 14

tank_debug.py

Dumps raw Field 16 entries to discover tank IDs and status values.

debug_wind.py

Examines actual packet bytes at known wind data offsets.

debug_decode.py

Simulates the wind extraction logic and shows packet size distribution.

debug_field13.py

Debugs Field 13 (Wind/Navigation) extraction across different packet sizes.

watch_field.py

Monitors a specific protobuf field path across incoming packets.

python watch_field.py -i 192.168.1.100 --field 7.1    # Watch depth
python watch_field.py --pcap capture.pcap --field 13.4  # Watch TWD

Offset Comparison Tools

compare_offsets.py

Compares old fixed-byte offsets vs protobuf field-based offsets for wind direction.

compare_heading_both_pcaps.py

Compares heading and TWD candidates between two different pcap files to validate consistency.

check_006b.py

Thoroughly checks offset 0x006b across all packets of various sizes.

Usage Notes

Most scripts require either:

• -i, --interface - The IP address of the interface connected to the Raymarine network
• --pcap - Path to a captured pcap file for offline analysis

Common multicast groups:

• 226.192.206.102:2565 - Primary sensor data
• 226.192.206.98:2561 - Navigation sensors
• 239.2.1.1:2154 - Additional sensor data (tanks, engines)

Data Formats

• Angles are stored in radians (multiply by 57.2958 for degrees)
• Speeds are stored in m/s (multiply by 1.94384 for knots)
• Depth is stored in meters
• Temperature is stored in Kelvin (subtract 273.15 for Celsius)