ORBIT-X — Ground-Based Educational CubeSat ADCS Simulator

ORBIT-X is an end-to-end, high-fidelity ground-based Attitude Determination and Control System (ADCS) educational software simulator for 3U CubeSats. Designed for aerospace engineering education, algorithm testing, and telemetry visualization, ORBIT-X provides deterministic Keplerian 2-body orbit propagation, 3D quaternion rigid-body dynamics, sensor noise modeling, complementary filter sensor fusion, quaternion PID attitude control, and a real-time React Mission Control dashboard. This is a ground-based educational simulator for modeling and learning, not software for a real satellite flight computer.

---

🏗️ Architecture Overview

                          ┌─────────────────────────────────────────┐
                          │         ORBIT-X ADCS PIPELINE           │
                          └─────────────────────────────────────────┘

 ┌────────────────────────────────┐                 ┌────────────────────────────────┐
 │     GROUND TRUTH SIMULATION    │                 │      REST / WEBSOCKET API      │
 │  (Unobservable Physics State)  │                 │     (FastAPI Telemetry Hub)    │
 └───────────────┬────────────────┘                 └───────────────▲────────────────┘
                 │                                                  │
                 ▼                                                  │
   ┌───────────────────────────┐                         ┌──────────┴──────────┐
   │   2-Body Keplerian Orbit   │                         │  10Hz Telemetry Stream│
   │  (Position, Velocity, v)  │                         │ & REST Control APIs │
   └─────────────┬─────────────┘                         └──────────▲──────────┘
                 │                                                  │
                 ▼                                                  │
   ┌───────────────────────────┐                         ┌──────────┴──────────┐
   │ Quaternion RK4 Dynamics   │                         │  Ground-Truth vs    │
   │  (Euler Rigid Body Kin)   │                         │  Estimated Error    │
   └─────────────┬─────────────┘                         └──────────▲──────────┘
                 │                                                  │
                 ▼                                                  │
 ┌────────────────────────────────┐                         ┌───────┴───────┐
 │   HARDWARE SENSOR SIMULATION   ├────────────────────────►│ Complementary │
 │ (IMU, Mag, Sun, Camera + Noise)│                         │ Sensor Fusion │
 └────────────────────────────────┘                         └───────┬───────┘
                                                                    │
                                                                    ▼
 ┌────────────────────────────────┐                         ┌───────────────┐
 │    REACTION WHEEL ACTUATOR     │◄────────────────────────┤ Quaternion PID│
 │  (Torque Bounds & Speed RPM)   │                         │  Controller   │
 └────────────────────────────────┘                         └───────────────┘

                 │                                                  │
                 └──────────────────► DASHBOARD ◄───────────────────┘
                                  (React + 3D Viewport)

---

⚡ Quickstart & Installation

Prerequisites

• Python 3.10+
• Node.js 18+ and npm

1. Backend Setup

# Create and activate virtual environment
python -m venv venv

# On Windows (PowerShell):
.\venv\Scripts\activate

# On Linux/macOS:
source venv/bin/activate

# Install dependencies
pip install numpy scipy astropy skyfield fastapi uvicorn websockets pytest pydantic httpx

2. Frontend Setup

cd frontend
npm install

---

🚀 Running the Application

Option A: Direct Backend Execution (FastAPI Server)

Starts the FastAPI telemetry server and serves the compiled Mission Control Dashboard at http://127.0.0.1:8000/:

python backend/api/main.py

Option B: Development Servers

1. Backend Server (Terminal 1):

   uvicorn backend.api.main:app --reload --port 8000

2. Frontend Dev Server (Terminal 2):

   cd frontend
   npm run dev

   Open http://localhost:5173 in your browser.

Option C: One-Click CLI Demo

python run_demo.py

---

🧪 Running the Pytest Suite

Execute the complete 34-test regression suite covering orbit mechanics, quaternion kinematics, $q \equiv -q$ double cover, PID stability, estimator recovery, and REST control endpoints:

python -m pytest backend/tests/

---

📸 Interface Preview

Note: Open http://127.0.0.1:8000/ after starting the server to launch the live React Mission Control Dashboard featuring 10Hz telemetry streaming, real-time charts, 3D satellite visualization, and full parameter control.

For technical limitations and mathematical approximations, see docs/limitations.md.