Jam-proof GPS-denied navigation for attritable drones: optical flow + offline map geo-registration + EKF fusion + barometric altitude.

Name note: JamBoy = GPS jam + Game Boy-era pun. Nothing to do with historical golf caddie slang.

JamBoy is a navigation layer, not a targeting or weapons system. It is sim-validated on synthetic data; it is not flight-certified.

Given a downward camera, pre-loaded GeoTIFF maps, IMU rates, and barometer altitude, JamBoy estimates local position and velocity without GPS:

1. Lucas–Kanade optical flow with gyro de-rotation → ground velocity
2. ORB (optional SIFT) + RANSAC homography against tiled maps → absolute geo fix
3. 6-state EKF fusion with baro altitude
4. State machine: Cruise → DeadReckon → Terminal (stub) → Abort
5. MAVLink out: VISION_POSITION_ESTIMATE (preferred) or reposition fallback

Global shutter is strongly preferred; rolling shutter is supported with fallback modes.

Requires Python 3.10+.

python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -e ".[dev]"

CPU runtime only (no CUDA wheels):

pip install -r requirements.txt
pip install -e ".[dev]"

Optional GPU acceleration (CuPy / PyTorch):

pip install -r requirements-gpu.txt
# or: pip install -e ".[gpu,dev]"

export PYTHONPATH=src   # Windows: $env:PYTHONPATH = "src"
python scripts/generate_dummy_data.py
pytest -q
python scripts/run_simulation.py --cpu --profile
python scripts/validate_sim.py

One-shot helper (CUDA if available, else CPU):

bash scripts/run_sim_confident.sh

Realism / vibration data:

python scripts/generate_dummy_data.py --realism
python scripts/run_simulation.py --cpu --profile --realism

Pass criteria and metrics: docs/REQUIREMENTS.md, docs/SIM_TEST_GUIDE.md.

python scripts/calibrate_camera_imu.py --camera 0
# Set mavlink.sim_mode: false for a real FC
python scripts/main_navigator.py --config config/pi5_pixhawk.yaml

Details: docs/ARCHITECTURE.md · Roadmap: docs/ROADMAP.md

Any CUDA host works. Use your own SSH endpoint from your cloud provider dashboard — do not commit hostnames, ports, or keys.

ssh root@<POD_IP> -p <PORT> -i ~/.ssh/<your_key>
cd /workspace/JamBoy   # or your clone path
source .venv/bin/activate
export PYTHONPATH=src CUDA_VISIBLE_DEVICES=0
pip install -e ".[gpu,dev]"
bash scripts/run_sim_confident.sh

JamBoy is research / simulation software for GPS-denied navigation experiments. It does not provide targeting, ROE, or kinetic autonomy. Validate on your own hardware before flight. Use in accordance with applicable law and export controls.

See CONTRIBUTING.md. Security reports: SECURITY.md.

MIT — Copyright (c) 2026 Fratres-X AI