Common questions and answers about Heimdall.
Heimdall is an AI-powered platform for real-time localization of radio transmissions using distributed WebSDR receivers. It uses machine learning to analyze radio signals from multiple receivers and triangulate the source location with uncertainty estimates.
In Norse mythology, Heimdall is the all-seeing guardian of Bifrost who can see and hear across all realms. Similarly, our system “sees” radio transmissions across a distributed network of receivers.
Yes! Heimdall is open source under a Creative Commons Non-Commercial license. You can use it freely for personal, educational, and amateur radio purposes.
No, the CC Non-Commercial license prohibits commercial use. For commercial licensing, please contact the project maintainer.
See the Quick Start Guide for a 5-minute installation process. You’ll need Docker and 8GB of RAM.
Minimum:
Recommended:
Not required! The system is designed to be accessible. However, familiarity with radio concepts helps understand the results.
No! The ML models are pre-trained and ready to use. ML expertise is only needed if you want to retrain models or modify the architecture.
Target accuracy is ±30m (68% confidence interval). Actual accuracy depends on:
Real-time inference latency is <500ms from signal reception to location prediction.
Currently configured for:
The system can be adapted to other bands by retraining models with appropriate data.
Minimum: 3 receivers (for triangulation) Recommended: 5-7 receivers (for better accuracy) Current setup: 7 receivers in Northwestern Italy
Yes! Edit WEBSDRS.md to add your receiver configuration. You’ll need:
See the Contributing Guidelines for detailed instructions. Quick steps:
Backend:
ML Pipeline:
Frontend:
Deployment:
# Backend tests
make test
# Frontend tests
cd frontend && pnpm test
# E2E tests
cd frontend && pnpm test:e2e
See Development Guide for details.
Open an issue on GitHub Issues with:
The system will fetch IQ data from all active WebSDR receivers simultaneously.
Uncertainty represents the confidence in the predicted location. It’s displayed as an ellipse on the map:
Factors affecting uncertainty:
For development/testing, yes - use mock data. For production localization, you need access to real WebSDR receivers.
Supervised learning approach:
Accumulate many samples to train accurate models.
Training data includes 10% synthetic signals (5% single-tone beacons, 5% dual-tone DTMF) alongside 90% voice signals to ensure the model generalizes well and doesn’t overfit to voice-only patterns.
Rationale:
To adjust the distribution:
Edit services/training/src/data/iq_generator.py lines 470-498 (single sample) and 734-778 (batch generation).
Impact on model performance:
See Training Documentation for details.
# Check Docker is running
docker ps
# Restart all services
docker-compose down -v
docker-compose up -d
# Check logs
docker-compose logs -f
# Wait 30 seconds for services to initialize
sleep 30 && make health-check
# Check individual services
docker-compose ps
docker-compose logs <service-name>
# Find conflicting process
lsof -i :5432 # Replace with your port
# Stop conflicting service or change port in .env
# Verify PostgreSQL is running
docker-compose ps postgres
# Test connection
psql -h localhost -U heimdall_user -d heimdall
cd frontend
# Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install
# Rebuild
pnpm build
See Architecture Guide for details.
TimescaleDB is optimized for time-series data:
Perfect for radio signal measurements over time.
Benefits:
Models are trained in PyTorch, then exported to ONNX for inference.
Yes! For development and small-scale deployments, use docker-compose:
docker-compose -f docker-compose.prod.yml up -d
For production at scale, Kubernetes is recommended for auto-scaling, self-healing, and orchestration.
The first inference loads the ONNX model into memory. Subsequent inferences are much faster (<500ms) due to:
Depends on usage:
Recommendation: 50GB for active development/production.
Local deployment:
No data is sent externally. Everything stays on your infrastructure.
Yes, all data is stored locally:
Use standard backup/deletion tools.
Yes! The CC Non-Commercial license allows modifications for non-commercial purposes.
Yes, under the same CC Non-Commercial license. Credit the original project.
The license prohibits commercial use. For commercial licensing, contact the maintainer.