HardwareLink is a fully interactive satellite link simulator where RF performance, link quality, and throughput emerge naturally from realistic hardware physics — not lookup tables.
Every degradation in the RF chain (phased-array steering loss, LNA thermal drift, PA compression, oscillator drift, polarization degradation, pointing jitter, power bus limits, T/R module faults) visibly cascades through the link budget into BER, adaptive modulation, packet loss, retransmissions, and goodput — with full root-cause traceability.
- NASA Blue Marble + Night Lights dual-texture Earth with realistic day/night cycle
- Sun position computed from simulation UTC timestamp (solar declination + hour angle)
- Atmospheric rim glow and wireframe overlay
- Full orbit controls — rotate, zoom, and pan from anywhere on the viewport
- SGP4 propagation of actual Starlink TLEs (NORAD 44713) with sub-second precision
- Live TLE fetch from CelesTrak with automatic fallback to embedded TLE
- Color-coded orbit trails: 🟢 green (>500 Mbps) / 🟡 yellow (50–500 Mbps) / 🔴 red (<50 Mbps)
Phased array, RF front-end, power amplifier, oscillator, polarization, pointing/attitude, power bus, compute scheduling, thermal model, and fault injection — all interdependent
- Glassmorphism design with multi-layer glass cards, gradient accents, and custom scrollbars
- Framer Motion animations — smooth entrance transitions, animated segmented controls, hover effects
- Collapsible cards — Ground Station and Time Mode cards show compact summaries by default, expand on hover/click
- Dynamic ground station — search any city or enter lat/lon coordinates; 3D label and beam update instantly
- Historical mode — simulate any past date/time with UTC conversion display
Every dB of SNR penalty traces back to a specific hardware subsystem
Individual packet events with HARQ retransmissions, jitter, and loss
Waterfall chart showing each subsystem's dB impact on SNR with dominant cause identification
Play/pause/scrub through satellite passes at 1×–50× speed with gradient progress bar
┌─────────────────────────────────────────────────────────┐
│ FRONTEND (React 19) │
│ ┌────────────┐ ┌────────────┐ ┌──────────┐ ┌────────┐ │
│ │ 3D Globe │ │ Overview │ │ Packet │ │ Root │ │
│ │ + Beam │ │ Gauges │ │ Sniffer │ │ Cause │ │
│ └─────┬──────┘ └─────┬──────┘ └────┬─────┘ └───┬────┘ │
│ └──────────────┴─────────────┴───────────┘ │
│ │ │
│ fetch /api/simulate │
└──────────────────────────┬──────────────────────────────┘
│ JSON (700+ frames, full telemetry)
┌──────────────────────────┴──────────────────────────────┐
│ BACKEND (FastAPI) │
│ ┌────────────┐ ┌────────────┐ ┌───────────────────┐ │
│ │ SGP4 │ │ 10-Block │ │ Link Budget + │ │
│ │ Orbit │──│ Hardware │──│ Packet Sim + │ │
│ │ Engine │ │ Model │ │ Causal Waterfall │ │
│ └────────────┘ └────────────┘ └───────────────────┘ │
└─────────────────────────────────────────────────────────┘
| Tool | Version |
|---|---|
| Python | 3.12+ |
| Node.js | 18+ |
| npm | 9+ |
git clone https://github.com/sandman-sh/HardwareLink.git
cd HardwareLinkcd backend
pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reloadAPI server starts at http://localhost:8000 — Swagger docs at /docs
cd frontend
npm install
npm run devOpen http://localhost:5173 in your browser.
Most satellite simulators parameterise link quality as a simple function of elevation angle. HardwareLink runs a physics loop every simulated second across 10 interdependent subsystem blocks:
SGP4 orbit
│
▼
┌─────────────────────────────────────────────────────────┐
│ HARDWARE MODEL (per second) │
│ │
│ Phased Array ──► Scan loss (cos^1.5 θ) │
│ RF Front-End ──► LNA NF + gain (temp-dependent) │
│ Power Amplifier ──► Backoff / compression │
│ Oscillator ──► Frequency drift (temp-dependent) │
│ Polarization ──► Cross-pol isolation vs scan angle │
│ Pointing ──► Attitude jitter + beam pointing loss │
│ Power Bus ──► Battery SOC, solar gen, load shedding │
│ Compute ──► DSP load, beam scheduling delay │
│ Thermal ──► Lumped-capacity heat model │
│ Faults ──► Failed T/R modules, degraded solar cells │
│ │
│ All subsystems feed into ──► EIRP + Noise Floor │
└──────────────────────┬──────────────────────────────────┘
│
▼
Link Budget ──► SNR ──► AMC ──► BER
│
▼ ▼
Packet Sim ──► Loss, Jitter, Retransmissions
│
▼
Causal Waterfall ──► Dominant hardware cause
Example causality chain:
Satellite steers to low-elevation user → scan angle increases → PA draws more power → temperature rises → LNA noise figure increases + PA enters compression + oscillator drifts → EIRP drops + noise floor rises → SNR degrades → AMC falls from 64QAM to QPSK → packet errors increase → HARQ retransmissions spike → throughput drops 4×
Root Cause tab shows: "Scan Loss: 8.2 dB (DOMINANT)"
- Engine: SGP4 (via
sgp4Python package) - Frame transforms: TEME → ECEF → ENU (Bowring geodetic)
- Outputs: Elevation, azimuth, slant range, Doppler shift (Ku-band 12 GHz)
- Element pattern: cos^1.5(θ) roll-off
- Max scan: ~65° from boresight
- Scan loss: Up to 20 dB at extreme angles
- LNA noise figure: 1.2 dB nominal, +0.015 dB/°C above 40°C
- LNA gain: 35 dB nominal, −0.02 dB/°C above 40°C
- Filter insertion loss: 0.5 dB + Doppler band-edge penalty
- Nominal backoff: 3 dB (linear region)
- Temperature effect: Backoff decreases → compression increases
- Power throttle: 3 dB penalty when battery SOC < 20%
- Drift model: Parabolic temperature dependence (0.01·ΔT + 0.001·ΔT²) ppm
- Effect: Frequency error → implementation loss on SNR
- Boresight: 25 dB cross-pol isolation
- Scan angle: Isolation degrades as 25 − 15·sin²(θ) dB
- Effect: Polarization mismatch loss on receive power
- Jitter: Gaussian random + random walk bias
- 3 dB beamwidth: ~2° (Starlink phased array)
- Pointing loss: 12·(error/beamwidth)² dB (Gaussian beam)
- Battery: 2500 Wh, tracks SOC based on net power
- Solar: Up to 2800 W, varies with orbit sun angle
- Bus voltage: 28 V nominal, droops under heavy load
- Load shedding: PA power reduced when SOC < 20%
- DSP load: Increases with beam steering + modulation complexity
- Beam scheduling delay: Increases when DSP > 85% utilization
- Effect: Adds to packet jitter
- Type: First-order lumped capacity (200 J/°C)
- Cooling: Radiative at 1.2 W/°C above −20°C ambient
- Effect: Drives PA, LNA, and oscillator degradation
- T/R modules: 0–15 randomly failed out of 1024 per pass
- Solar cells: 0–5% random degradation
- Effect: Reduced array gain + reduced power generation
- Path loss: Friis free-space + 1/sin(el) atmospheric model
- Doppler tracking: 0.1% residual error → SNR penalty
- Tx: 10 dBW + 35 dBi antenna = 45 dBW EIRP (nominal)
- Rx: 33 dBi ground terminal, temperature-adjusted noise floor
| SNR Threshold | Modulation | MCS | Spectral Eff. | Max Goodput |
|---|---|---|---|---|
| < 2 dB | Outage | 0 | — | 0 Mbps |
| 2–5 dB | BPSK | 1 | 0.5 b/s/Hz | 101 Mbps |
| 5–10 dB | QPSK | 2 | 1.5 b/s/Hz | 304 Mbps |
| 10–15 dB | 16QAM | 4 | 3.0 b/s/Hz | 608 Mbps |
| 15–20 dB | 64QAM | 6 | 4.5 b/s/Hz | 1000 Mbps |
| > 20 dB | 256QAM | 8 | 6.0 b/s/Hz | 1215 Mbps |
- HARQ: Up to 3 retransmission attempts per packet
- Jitter sources: Oscillator drift, DSP scheduling, Doppler rate
- Per-packet output: Sequence #, status (OK/LOST/RETX), latency, jitter, hardware cause
- Ground-station sniffer view: 12 sampled packets per second for trace inspection
| Tab | Purpose |
|---|---|
| Overview | Throughput, elevation, SNR, modulation, array loss, temperature gauges + throughput timeline chart |
| Subsystems | Deep inspection of all 10 hardware subsystem blocks with green/amber/red status indicators |
| Packets | Ground-station packet sniffer: per-packet seq, status, latency, jitter, and hardware failure cause |
| Root Cause | Waterfall bar chart ranking each subsystem's dB impact on SNR — identifies the dominant degradation source |
The 3D globe uses a custom GLSL shader that blends NASA Blue Marble (day) and Earth Night Lights textures based on the sun's position:
- Sun direction is computed from the simulation's UTC timestamp using simplified solar declination and hour angle formulas
- Smooth terminator — gradual transition from day to night using
smoothstepblending - City lights — Night side reveals glowing city lights from the NASA night texture
- Atmospheric glow — Subtle rim lighting and outer halo for realism
- When running a historical simulation, the Earth shows the exact sun position for that date/time
0 STARLINK-30477
1 57912U 23146X 24099.49439401 .00006757 00000+0 51475-3 0 9997
2 57912 43.0018 157.5807 0001420 272.5369 87.5310 15.02537576 31746
Ground Station: Configurable — default Seattle, WA (47.6062°N, 122.3321°W). Search any city or enter coordinates directly.
HardwareLink/
├── backend/
│ ├── app/
│ │ ├── main.py # FastAPI app + CORS + geocoding
│ │ ├── models/simulation.py # Pydantic schemas (90+ fields per frame)
│ │ ├── simulation/
│ │ │ ├── orbit.py # SGP4 + coordinate transforms
│ │ │ ├── hardware.py # 10-block hardware model
│ │ │ ├── link_budget.py # EIRP → SNR → AMC → causal waterfall
│ │ │ └── packet_sim.py # Per-packet HARQ + jitter simulation
│ │ ├── routers/simulate.py # POST /api/simulate endpoint
│ │ └── utils/
│ ├── requirements.txt
│ └── run.py
├── frontend/
│ ├── src/
│ │ ├── App.tsx # Layout, API, playback, tab system
│ │ ├── App.css # Glassmorphism styles & animations
│ │ ├── index.css # Design tokens, scrollbar, slider
│ │ ├── scenes/
│ │ │ ├── Earth.tsx # Day/night GLSL shader globe
│ │ │ └── SatelliteScene.tsx # Satellite, beam, trail, GS marker
│ │ ├── components/
│ │ │ ├── LocationSearch.tsx # Collapsible ground station picker
│ │ │ ├── HistorySearch.tsx # Collapsible time mode selector
│ │ │ ├── TelemetryPanel.tsx # Overview gauges + throughput chart
│ │ │ ├── SubsystemPanel.tsx # Deep hardware inspection view
│ │ │ ├── PacketSniffer.tsx # Ground-station packet trace
│ │ │ └── CausalTrace.tsx # Root cause waterfall chart
│ │ └── main.tsx
│ ├── vite.config.ts
│ ├── tailwind.config.mjs
│ └── package.json
├── docs/
│ └── screenshots/ # UI screenshots for README
├── README.md
└── .gitignore
| Layer | Technology |
|---|---|
| Backend | Python 3.12, FastAPI, Uvicorn |
| Simulation | sgp4, NumPy, SciPy, Pandas |
| Frontend | React 19, TypeScript, Vite |
| 3D | Three.js, @react-three/fiber, @react-three/drei |
| UI | Tailwind CSS, Framer Motion, Recharts, Lucide Icons |
| Fonts | Inter (UI), JetBrains Mono (telemetry) |
MIT