satx

SATx - Satellite Detection, Tracking, and Transmission System

Python Version License: MIT Docker Tests Documentation PyTorch TensorFlow

A complete automated system for detecting, tracking, decoding transmissions from satellites passing overhead. SATx leverages SDR hardware, GNU Radio, and machine learning to provide end-to-end satellite observation capabilities with 100% operational reliability.

🖥️ Web Dashboard

SATx features a modern, professional web interface for real-time monitoring and control:

### Main Dashboard ![SATx Dashboard](https://github.com/user-attachments/assets/ad76e38f-5783-43c9-84dd-6153bb9b6f16) ### Satellite Tracking ![Satellite Tracking](https://github.com/user-attachments/assets/1c93a5be-c36b-40bd-a79a-6b32feb20bee) ### Analytics View ![Analytics](https://github.com/user-attachments/assets/2eed5fce-dc17-4fef-ad96-c65c1af90c58)

Dashboard Features:

Access the dashboard at http://localhost:8080 after starting the web server.

Table of Contents

Features

🚀 New to SATx? Check out the Quick Start Guide to get up and running in minutes!

System Status

System Status Operational Readiness

Current Status: Production Ready

For detailed system status and reports, see the Critical Requirements Document.

ML and AI Capabilities

SATx uses deep learning for advanced signal processing:

Models are trained on both synthetic and real satellite signals, achieving high accuracy in various conditions.

Supported Frameworks

Quick Start

For a complete turnkey installation with ML training:

# Clone and setup everything automatically
git clone https://github.com/Artifact-Virtual/satx.git
cd SATx
./setup.sh

The setup script will:

Manual Setup

  1. Install dependencies: 
    pip install -r requirements.txt

  2. Configure your station: Edit configs/station.ini with your location coordinates

  3. Fetch latest TLEs: 
    python scripts/fetch_tles.py
  4. Predict upcoming passes: 
    python scripts/predict_passes.py
  5. Run automated observation: 
    python scripts/scheduler.py

ML Training Setup

To train or retrain the signal detection models:

# Prepare training data
python scripts/prepare_training_data.py

# Download additional data from SatNOGS
python scripts/download_satnogs_data.py

# Train the model
python models/model_v1/train.py

Hardware Requirements

Minimum Setup ($50-100)

Professional Setup ($800+)

See the Critical Requirements Document for detailed hardware specifications and budget breakdowns.

Software Requirements

Core Dependencies

Optional Dependencies

Supported Operating Systems

Installation

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

Native Installation

# Install system dependencies
sudo apt-get update
sudo apt-get install python3 python3-pip git docker.io

# Clone repository
git clone https://github.com/Artifact-Virtual/satx.git
cd SATx

# Install Python dependencies
pip install -r requirements.txt

# Run setup script
./setup.sh

Configuration

Station Configuration

Edit configs/station.ini:

[station]
name = My Ground Station
latitude = 40.7128
longitude = -74.0060
altitude = 100
device = rtl=0
sample_rate = 2400000
frequency = 437800000

SDR Configuration

Configure SDR devices in configs/sdr.ini:

[sdr]
device_type = rtl
device_args = rtl=0
sample_rate = 2400000
gain = 40
bias_tee = true

ML Configuration

Configure ML models in configs/ml.ini:

[ml]
model_path = models/model_v1/
batch_size = 32
threshold = 0.8
use_gpu = true

Usage

Basic Operation

# Start the complete system
python scripts/scheduler.py

# Monitor via web interface
# Open http://localhost:5000 in your browser

Command Line Tools

# Fetch TLE data
python scripts/fetch_tles.py

# Predict passes
python scripts/predict_passes.py --lat 40.7128 --lon -74.0060

# Process recording
python scripts/process_recording.py recording.iq

# Run tests
python tests/run_all_tests.py

Web Interface

Start the web dashboard:

python3 web/app.py

The modern web dashboard provides:

Access at: http://localhost:8080

Features:

🔍 Spectrum Scanner

Scan frequency bands to discover active signals:

# Scan all configured bands
python3 scripts/spectrum_scanner.py

# Scan specific band (137-138 MHz)
python3 scripts/spectrum_scanner.py --band 137.0-138.0

# Save results to file
python3 scripts/spectrum_scanner.py --output scan_results.json

Features:

🕵️ Ghost Mode - Privacy Protection

Enable bulletproof privacy and operational security:

# Enable maximum privacy (bulletproof)
python3 scripts/ghost_mode.py --enable --level maximum

# Enable high privacy
python3 scripts/ghost_mode.py --enable --level high

# Enable standard privacy
python3 scripts/ghost_mode.py --enable --level standard

# Check status
python3 scripts/ghost_mode.py --status

# Clean all traces
python3 scripts/ghost_mode.py --clean

# Disable ghost mode
python3 scripts/ghost_mode.py --disable

Privacy Levels:

Ghost Mode Features:

Use Cases:

Testing

Run comprehensive system tests:

# Run all tests with detailed reporting
python tests/run_all_tests.py

# Run specific test categories
python -m pytest tests/unit/ -v
python -m pytest tests/integration/ -v
python -m pytest tests/e2e/ -v

# Generate coverage report
python -m pytest --cov=satx --cov-report=html

Test Results

All tests generate comprehensive HTML and JSON reports in tests/reports/.

Project Structure

SATx/
├── scripts/                    # Core automation scripts
│   ├── fetch_tles.py          # TLE data fetching
│   ├── predict_passes.py      # Orbital pass prediction
│   ├── process_recording.py   # Signal processing with ML
│   ├── scheduler.py           # Automated observation scheduler
│   ├── prepare_training_data.py # ML training data preparation
│   └── test_system.py         # Comprehensive system testing
├── configs/                   # Station and service configurations
│   └── station.ini           # Station location and settings
├── data/                      # Data storage
│   └── tles/                 # TLE orbital data
├── decoders/                  # Signal decoders and flowgraphs
│   └── grc_flowgraphs/       # GNU Radio flowgraphs
├── models/                    # ML models for signal detection
│   └── model_v1/            # Current model version
├── services/                  # Docker services
│   ├── ml/                   # ML processing service
│   └── sdr/                  # SDR processing service
├── tests/                     # Comprehensive test suite
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   ├── e2e/                  # End-to-end tests
│   └── reports/              # Test reports and results
├── web/                      # Dashboard UI
├── docs/                     # Documentation
│   └── critical_requirements.md # Hardware requirements
├── transmit/                 # Transmission capabilities
├── recordings/               # Recorded I/Q data (gitignored)
├── logs/                     # Operation logs and candidates
├── docker-compose.yml        # Docker orchestration
├── requirements.txt          # Python dependencies
├── setup.sh                  # Automated setup script
└── README.md                 # This file

API Reference

Core Modules

Configuration Files

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Fork and clone the repository
git clone https://github.com/your-username/satx.git
cd SATx

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python tests/run_all_tests.py

Code Standards

License

This project is licensed under the MIT License - see the LICENSE file for details.

Resources

Official Documentation

External Resources

Community

SATx - Bridging the gap between amateur satellite observation and professional signal intelligence.

This site is open source. Improve this page.