Add VRS JSON format support for readsb integration #28

Merged

olemd merged 2 commits from feature/vrs-json-support into main

2025-08-31 11:11:18 +02:00

olemd commented

2025-08-31 11:10:37 +02:00

Owner

Summary

Add comprehensive VRS JSON format support for readsb integration, providing a simpler alternative to Beast binary protocol while maintaining full backward compatibility.

Key Features

🔧 VRS JSON Protocol Support

Stream Parsing: Newline-delimited JSON from readsb --net-vrs-port output
TCP Client: Robust client with automatic reconnection and error recovery
Mixed Format: Use Beast binary and VRS JSON sources simultaneously
Data Mapping: Direct conversion from VRS JSON to internal aircraft structures

📊 Enhanced Aircraft Data

Extended Fields: Registration, aircraft type, operator information
Position Sources: Identifies ADS-B, MLAT, TIS-B, and satellite positions
Validity Flags: Tracks data completeness and reliability per field
Metadata Support: Rich aircraft information beyond basic tracking

⚙️ Configuration & Integration

Format Selection: Configure sources with "format": "beast" or "format": "vrs"
Port Flexibility: Typically port 30005 (Beast) or 33005 (VRS)
Backward Compatible: Existing Beast configurations unchanged
Multi-Source: Mix Beast and VRS sources in same deployment

Implementation Details

New Components

internal/vrs/parser.go: VRS JSON message parsing and validation
internal/client/vrs.go: VRS TCP client implementation
Enhanced MultiSourceClient for mixed-format support
Extended Aircraft struct with additional fields and validity tracking

Testing Results

✅ Successfully tested against live VRS JSON stream (svovel:33005)
✅ Verified aircraft data parsing: position, altitude, speed, heading
✅ Confirmed ICAO address extraction and metadata handling
✅ Validated mixed-format operation with existing Beast clients

Configuration Example

{
  "sources": [
    {
      "id": "beast-receiver",
      "name": "Dump1090 Beast",
      "host": "192.168.1.100",
      "port": 30005,
      "format": "beast",
      "enabled": true
    },
    {
      "id": "vrs-receiver", 
      "name": "Readsb VRS JSON",
      "host": "192.168.1.100",
      "port": 33005,
      "format": "vrs",
      "enabled": true
    }
  ]
}

Advantages of VRS Format

Simplicity: Human-readable JSON vs binary Beast protocol
Debugging: Easy to inspect and validate data streams
Modern Integration: Better compatibility with current readsb versions
Rich Metadata: Additional aircraft information (registration, type, operator)
Update Control: Configurable interval with --net-vrs-interval

Documentation Updates

README.md: Added VRS format configuration examples and comparison
ARCHITECTURE.md: Documented VRS parser and mixed-format architecture
Configuration Guide: Explained both Beast binary and VRS JSON formats

Migration Path

Existing deployments remain unchanged. VRS support is opt-in via configuration:

Add "format": "vrs" to new sources using port 33005
Enable readsb with --net-vrs-port 33005
Mix with existing Beast sources for redundancy

This enables modern readsb integration while preserving full compatibility with existing dump1090 Beast deployments.

Addresses issue #27: Investigate readsb as improved data source alternative to dump1090

## Summary Add comprehensive VRS JSON format support for readsb integration, providing a simpler alternative to Beast binary protocol while maintaining full backward compatibility. ## Key Features ### 🔧 VRS JSON Protocol Support - **Stream Parsing**: Newline-delimited JSON from readsb `--net-vrs-port` output - **TCP Client**: Robust client with automatic reconnection and error recovery - **Mixed Format**: Use Beast binary and VRS JSON sources simultaneously - **Data Mapping**: Direct conversion from VRS JSON to internal aircraft structures ### 📊 Enhanced Aircraft Data - **Extended Fields**: Registration, aircraft type, operator information - **Position Sources**: Identifies ADS-B, MLAT, TIS-B, and satellite positions - **Validity Flags**: Tracks data completeness and reliability per field - **Metadata Support**: Rich aircraft information beyond basic tracking ### ⚙️ Configuration & Integration - **Format Selection**: Configure sources with `"format": "beast"` or `"format": "vrs"` - **Port Flexibility**: Typically port 30005 (Beast) or 33005 (VRS) - **Backward Compatible**: Existing Beast configurations unchanged - **Multi-Source**: Mix Beast and VRS sources in same deployment ## Implementation Details ### New Components - `internal/vrs/parser.go`: VRS JSON message parsing and validation - `internal/client/vrs.go`: VRS TCP client implementation - Enhanced `MultiSourceClient` for mixed-format support - Extended `Aircraft` struct with additional fields and validity tracking ### Testing Results ✅ Successfully tested against live VRS JSON stream (svovel:33005) ✅ Verified aircraft data parsing: position, altitude, speed, heading ✅ Confirmed ICAO address extraction and metadata handling ✅ Validated mixed-format operation with existing Beast clients ## Configuration Example ```json { "sources": [ { "id": "beast-receiver", "name": "Dump1090 Beast", "host": "192.168.1.100", "port": 30005, "format": "beast", "enabled": true }, { "id": "vrs-receiver", "name": "Readsb VRS JSON", "host": "192.168.1.100", "port": 33005, "format": "vrs", "enabled": true } ] } ``` ## Advantages of VRS Format - **Simplicity**: Human-readable JSON vs binary Beast protocol - **Debugging**: Easy to inspect and validate data streams - **Modern Integration**: Better compatibility with current readsb versions - **Rich Metadata**: Additional aircraft information (registration, type, operator) - **Update Control**: Configurable interval with `--net-vrs-interval` ## Documentation Updates - **README.md**: Added VRS format configuration examples and comparison - **ARCHITECTURE.md**: Documented VRS parser and mixed-format architecture - **Configuration Guide**: Explained both Beast binary and VRS JSON formats ## Migration Path Existing deployments remain unchanged. VRS support is opt-in via configuration: 1. Add `"format": "vrs"` to new sources using port 33005 2. Enable readsb with `--net-vrs-port 33005` 3. Mix with existing Beast sources for redundancy This enables modern readsb integration while preserving full compatibility with existing dump1090 Beast deployments. ## Related Issues Addresses issue #27: Investigate readsb as improved data source alternative to dump1090

olemd added 2 commits

2025-08-31 11:10:37 +02:00

Add VRS JSON format support for readsb integration 073acb7304

Added comprehensive support for VRS (Virtual Radar Server) JSON format
as a simpler alternative to Beast binary protocol, enabling integration
with readsb --net-vrs-port output.

## Key Features:
- **VRS JSON Parser**: Stream parsing of newline-delimited JSON aircraft data
- **VRS Client**: TCP client with automatic reconnection and error recovery
- **Mixed Format Support**: Use Beast and VRS sources simultaneously
- **Enhanced Aircraft Data**: Added VRS-specific fields (registration, type, operator)
- **Position Source Tracking**: Identifies ADS-B, MLAT, TIS-B, and satellite positions

## Implementation:
- `internal/vrs/parser.go`: VRS JSON message parsing and validation
- `internal/client/vrs.go`: VRS TCP client implementation
- Enhanced `MultiSourceClient` to support both Beast and VRS formats
- Extended `Aircraft` struct with validity flags and additional metadata
- Updated configuration to include `format` field ("beast" or "vrs")

## Testing:
- Successfully tested against svovel:33005 VRS JSON stream
- Verified aircraft data parsing and position tracking
- Confirmed mixed-format operation with existing Beast clients

## Documentation:
- Updated README.md with VRS format configuration examples
- Enhanced ARCHITECTURE.md with VRS parser documentation
- Added data format comparison and configuration guide

This enables simpler integration with modern readsb installations while
maintaining full backward compatibility with existing Beast deployments.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Clean up temporary VRS test files 15778ba6ec