Satellite RF Observatory

An experimental laboratory for building falsifiable RF observations from capabilities that are actually available in the current session.

The project began as a satellite-identification prototype. The experiments in this repository changed the question:

Given a finite time budget and live Internet-accessible RF capabilities, can we freeze one prospective physical experiment whose positive and negative outcomes are interpretable?

Targets, frequencies, endpoints and even the phenomenon under test may emerge only after capability qualification. A satellite is one possible model, not a required starting point.

This is research software. It is not an operational monitoring platform, a signal-identification service or evidence that any transmitter has been identified.

Current direction

The supported research surface is experiments/live_instrument. It contains two deliberately different branches:

Branch	Starting point	What it tests
SatNOGS	model-conditioned published measurements	whether clause-driven continuity and corroboration survive source revocation and TTL expiry
KiwiSDR	targetless live IQ	whether a shared or intervened RF structure is distinguishable under explicit temporal, transform and causal controls

The two branches share only the primitives that survived both:

• evaluation by contract clause, not one global health label;
• atomic receipts;
• event time and TTL;
• transform ledger;
• causal lineage;
• separation of physical decisions from descriptive/software errors;
• artifact hashing with zero RF persistence.

These are not promoted to a general framework. Each experiment must continue to justify them.

Latest checkpoint

Gate F2.5 removed server waterfall (W/F) and ext_api from the causal gate for same-Kiwi multichannel qualification. Its intended path is:

frozen affordances
  -> direct simultaneous SND reference + perturbed attempt
  -> two IQ streams
  -> local in-memory STFT/PSD
  -> targetless feature + witness
  -> per-channel retune qualification
  -> immutable plan
  -> one prospective A1/B/A2 confirmation
  -> one outcome

The first and only live F2.5 execution ended correctly as QUALIFICATION_INCOMPLETE: all six /status requests succeeded, but the frozen center policy expected a bandwidth field that the responses did not contain. No SND channel was attempted, no IQ was acquired and NO_MULTI_CHANNEL_CAPABILITY was therefore forbidden. See GATE_F2_5_OUTCOME_1.md.

That failure is useful: removing W/F was not enough while information formerly learned from its handshake was still required before the direct SND probe.

What can be claimed

Receipts may support narrow statements such as:

• a measurement satisfied a named clause before its TTL expired;
• two SND streams were simultaneous and independently sequenced;
• a feature behaved consistently with being upstream of a per-channel DDC;
• an observation was unavailable, unresolved, not detectable or not evaluated.

They do not automatically support:

• transmitter or satellite identity;
• external-RF origin;
• common physical cause;
• geolocation or TDoA;
• absence of a phenomenon when detectability was not established;
• multichannel unavailability when a second channel was never attempted.

Quick start: offline verification

Python 3.11 or 3.12 is recommended.

python -m venv .venv

# Linux/macOS
source .venv/bin/activate

# Windows PowerShell
# .venv\Scripts\Activate.ps1

python -m pip install -r requirements-live-instrument.txt
python -m pytest experiments/live_instrument/tests -q

The test suite is offline. It uses deterministic fixtures and synthetic IQ; it does not contact SatNOGS, KiwiSDR or any other remote service.

Live execution policy

Live runners are disposable experiment materializations, not daemons.

• Never run them as part of installation, import, tests or CI.
• Freeze candidates, order, transforms, thresholds, retry budget and stop condition before network access.
• Use only public capabilities and respect receiver-owner access limits.
• Retry only pre-freeze software/transport failures allowed by the frozen plan.
• After plan freeze: zero retry, endpoint change, frequency change, threshold change or second confirmation window.
• Hash ephemeral RF artifacts before analysis and destruction; persist only strict JSON receipts and hashes.

Every new live session requires explicit authorization. The repository's documented outcomes must remain unchanged after the fact; fixes belong to a new gate and a new commit.

Repository map

experiments/live_instrument/
  models.py                 strict receipts, clause and JSON boundary
  orbital_kernel.py         stateless Skyfield geometry/Doppler kernel
  satnogs_probe.py          model-conditioned published artifacts
  satnogs_failover.py       clause-driven continuity/corroboration failover
  kiwi_probe.py             targetless dual-Kiwi capture and in-session nulls
  kiwi_prospective.py       discovery/prediction/confirmation separation
  kiwi_gate_e.py            detectability and qualification experiments
  kiwi_gate_f2*.py          capability-first and same-Kiwi DDC interventions
  tests/                     offline deterministic test suite
  CHECKPOINT_*.md            checkpoint evidence
  GATE_*.md                  frozen plans, outcomes and postmortems

analysis/, collectors/, processors/, trackers/
  original offline satellite-first prototype

api/, workers/, core/, receivers/
  legacy architecture retained for reference; not the supported path

For mechanisms and state semantics, read README_TECHNICAL.md. For the next bounded work, read ROADMAP.md.

Original proof of concept

The image records the original product exploration. Its labels, confidence, locations and events are demonstration output, not validated telemetry or satellite identifications. No supported frontend is currently included.

Legacy offline prototype

The original SDR-to-disk and satellite-candidate code remains available through gray_system_main.py. It is exploratory and is not the validated output of the live-instrument gates. In particular:

• encryption and secure export are not implemented;
• metadata-scrubbed captures are incompatible with the current reader;
• Doppler proximity is candidate ranking, not identification;
• old API, Redis, PostgreSQL and frontend documents are historical.

Legal and ethical use

Use this repository only for lawful education, amateur-radio experimentation, spectrum research and signals you are authorized to receive and process. It does not transmit, jam, decrypt or bypass access controls. Public receiver availability is not a blanket license to record or redistribute content. Operators are responsible for applicable radio, privacy and data-retention law.

License

Apache License 2.0. See LICENSE.