Unified configuration and shared libraries for RETINA

[jonnyspicer]

Summary

Implement a unified configuration system and shared libraries across all RETINA modules to eliminate duplicate configuration and code, ensuring consistency across the project.

Problem

Duplicate Configuration

Currently, each RETINA module maintains its own configuration:

• tar1090-node/.env - Receiver location, adsb.lol settings
• blah2-arm/config/config.yml - Full YAML config with location, frequency, etc.
• adsb2dd/.env - Port and server settings
• synthetic-adsb/.env - Transmitter location, frequency, radar positions
• 3lips/.env - Radar URLs, map center

Issues:

• Same values (lat/lon/alt, frequency, ports) duplicated across 5+ files
• Easy to get configurations out of sync
• Changing receiver location requires editing multiple files
• Hard to maintain consistency across deployments
• Error-prone manual updates

Duplicate Geometry Code

The same geometry functions are duplicated across multiple repositories:

lla2ecef() implementations found in:

• adsb2dd/src/node/geometry.js (JavaScript)
• blah2-arm/api/bistatic.js (JavaScript)
• 3lips/event/RETINAsolver/Geometry.py (Python)
• retina-geolocator/lib/Geometry.py (Python)
• 3lips-telemetry-solver/event/algorithm/geometry/Geometry.py (Python)
• RETINAsolver/Geometry.py (Python)

Additional duplicated functions:

• norm() - Vector magnitude calculation
• ft2m() - Feet to meters conversion
• ecef2lla() - ECEF to lat/lon/alt conversion
• Bistatic delay/Doppler calculations

All implementations are mathematically equivalent (WGS84 ellipsoid model) but maintained separately.

Proposed Solutions

1. Unified Configuration System

Create a unified configuration system with three components:

Root Configuration File

Single /retina/.env file containing all shared configuration:

# Location
RECEIVER_LAT=-34.9192
RECEIVER_LON=138.6027
RECEIVER_ALT=110
TX_LAT=-34.9810
TX_LON=138.7081
TX_ALT=750

# Radio
FC_HZ=204640000
BANDWIDTH_HZ=2000000

# Ports
TAR1090_PORT=8504
ADSB2DD_PORT=49155
BLAH2_WEB_PORT=49152

Configuration Generator

Python script generate-configs.py that auto-generates service-specific configs:

• Reads from root .env
• Generates tar1090-node/.env
• Generates blah2-arm/config/config.yml
• Generates adsb2dd/.env
• Generates synthetic-adsb/.env
• Generates 3lips/.env

Documentation

• UNIFIED-CONFIG.md - Usage guide
• MIGRATION-EXAMPLE.md - Migration steps from current setup

2. Shared Geometry Libraries

Create language-specific shared libraries:

JavaScript Library: @retina/geometry

retina/
└── packages/
    └── geometry-js/
        ├── package.json
        ├── index.js
        └── test.js

Consumers:

• adsb2dd - Replace src/node/geometry.js
• blah2-arm/api - Replace api/bistatic.js
• tar1090-node - Use for any geometry needs

Python Library: retina_geometry

retina/
└── packages/
    └── geometry-py/
        ├── setup.py
        ├── retina_geometry/
        │   ├── __init__.py
        │   └── geometry.py
        └── tests/

Consumers:

• 3lips/event/RETINAsolver - Import instead of local Geometry.py
• retina-geolocator - Import instead of local lib/Geometry.py
• 3lips-telemetry-solver - Import instead of local module

Benefits

Unified Configuration

✅ Single source of truth - All configuration in one place
✅ Consistency - No conflicting values between services
✅ Easy updates - Change receiver location once, affects all services
✅ Version control - Track all config changes in one file
✅ Deployment - Copy one file to configure entire system

Shared Libraries

✅ Single source of truth - One implementation per language
✅ Easier maintenance - Fix bugs once, affects all projects
✅ Consistent results - Identical calculations across services
✅ Unit tested - Shared test suite validates correctness
✅ Versioned - Track changes and ensure compatibility

Example Use Case

Current Workflow ❌

To change receiver location from Adelaide to Melbourne:

1. Edit tar1090-node/.env → Change LAT/LON
2. Edit blah2-arm/config/config.yml → Change location.rx.latitude/longitude
3. Edit synthetic-adsb/.env → Update RADARS JSON
4. Edit 3lips/.env → Change MAP_CENTER_LAT/LON
5. Restart all services individually

Total: 4-5 files edited, 5 commands

Proposed Workflow ✅

nano .env  # Change RECEIVER_LAT/LON once
./generate-configs.py
docker compose restart

Total: 1 file edited, 2 commands

Implementation

Configuration System

Files to create:

• /retina/.env.example - Configuration template
• /retina/generate-configs.py - Config generator script
• /retina/UNIFIED-CONFIG.md - Documentation
• /retina/MIGRATION-EXAMPLE.md - Migration guide

Files to update:

• Each service's .gitignore to ignore auto-generated configs
• README files to reference unified config
• Deployment scripts to use unified config

Shared Libraries

Phase 1: Create shared packages

• Extract and test JavaScript implementation from adsb2dd
• Extract and test Python implementation from 3lips
• Publish as internal packages

Phase 2: Migrate consumers

• Update each service to use shared library
• Remove duplicate geometry.js/Geometry.py files
• Update imports and dependencies

Phase 3: Documentation

• Add geometry library docs to UNIFIED-CONFIG.md
• Update README files with import instructions

Migration Path

1. Create unified config system in parallel
2. Create shared geometry libraries
3. Test with synthetic-adsb (simplest)
4. Migrate each service one-by-one
5. Update deployment docs
6. Remove old config files and duplicate code