REFERENCE TEMPLATE GENERATOR
============================

OVERVIEW
--------

This module generates the Starlink Ku-band downlink reference template -- a reference
QPSK frame used for signal identification, synchronization, and calibration. The
reference template is derived from the consensus pattern across multiple observed
all-QPSK frames in the exemplar dataset.


FILES
=====

genReferenceTemplate.m
----------------------
Main function that generates the time-domain reference template from reference rotations.

Usage:
  [templateFrame, rotations] = genReferenceTemplate();

Outputs:
  templateFrame: Time-domain IQ samples of the reference template
                 (length = 302 x 1056 = 319,104 samples)
                 - 301 OFDM symbols (1 SSS + 300 data symbols)
                 - Each symbol: 1024 samples + 32-sample cyclic prefix = 1056 samples/symbol

  rotations:     Frequency-domain QPSK rotations [1024 x 301]
                 - Values: 0, 1, 2, 3 representing 0 deg, 90 deg, 180 deg, 270 deg phase rotations
                 - Value: -1 represents inactive (zero) subcarriers

Algorithm:
  1. Load reference rotations from referenceTemplate.mat
  2. Convert rotations to complex IQ: exp(1j * rotations * pi/2)
  3. Zero out inactive subcarriers (where rotations = -1)
  4. Apply IFFT to convert to time domain
  5. Add cyclic prefix and reshape into single vector


referenceTemplate.mat
---------------------
Reference template rotations extracted from the exemplar frames dataset.

Contents:
  referenceTemplateRotations: [1024 x 301] integer array
    - Derived from mode (consensus) across all pure-QPSK frames in the exemplar dataset
    - Represents the "golden template" used for frame identification

Generation:
  - Source: 1009 decoded frames from STARLINK-31848 (v2.0-mini, Jan. 21, 2025)
  - Method: Computed as the mode across all all-QPSK frames


genPss.m
--------
Generates the Primary Synchronization Sequence (PSS) -- a chirp-like LFSR-based
waveform that precedes the first OFDM symbol (SSS) of each frame.

Usage:
  pkVec = genPss();

Outputs:
  pkVec: Time-domain PSS with cyclic prefix [(1024 + 32) x 1]

Notes:
  - PSS is generated from a 7-bit Fibonacci LFSR with taps [3 7]
  - Composed of 8 segments, each 128 samples
  - Used for coarse timing acquisition and frame detection


genSss.m
--------
Generates the Secondary Synchronization Sequence (SSS) -- the first OFDM symbol
in every Starlink frame.

Usage:
  [sssTimeDomain, sssFreqDomain] = genSss();

Outputs:
  sssTimeDomain: Time-domain SSS with cyclic prefix [(1024 + 32) x 1]
  sssFreqDomain: Frequency-domain SSS (QPSK symbols on unit circle) [1024 x 1]

Notes:
  - SSS is the same for all frames (not data-dependent)
  - Used for initial synchronization and frequency offset estimation
  - Loads SSS pattern from sssVec.mat


genEdgePilots.m
---------------
Generates the edge pilot matrix containing deterministic 4QAM symbols at the
channel boundaries.

Usage:
  [edgePilotMatrix, pilotSubcarrierIndices] = genEdgePilots();

Outputs:
  edgePilotMatrix:        N-by-Nsf complex matrix [1024 x 302]
  pilotSubcarrierIndices: 16-by-1 vector of pilot subcarrier indices

Notes:
  - Edge pilots occupy subcarriers 488-495 and 528-535
  - Pattern is identical across all frames and all satellites
  - Hex codes are from Appendix A of the paper


correlateEdgePilots.m
---------------------
Correlates IQ samples against the edge pilot local replica in the time domain.

Usage:
  [Cy, lags, localReplica] = correlateEdgePilots(yVec);
  [Cy, lags, localReplica] = correlateEdgePilots(yVec, Fdoppler);

Inputs:
  yVec:     Complex IQ samples at 240 MHz, frequency-shifted to channel center
  Fdoppler: (Optional) Doppler offset in Hz to apply to local replica

Outputs:
  Cy:           Complex correlation result
  lags:         Lag indices corresponding to Cy
  localReplica: Time-domain edge pilot local replica (300 symbols)

Notes:
  - Peaks in abs(Cy) indicate frame boundaries
  - Uses fftcorr for efficient FFT-based correlation


sssVec.mat
----------
Pre-computed SSS vector in frequency domain.

Contents:
  sssVecFull: [1024 x 1] complex vector of QPSK symbols


REFERENCE TEMPLATE STRUCTURE
============================

Frequency Domain (Before IFFT)
------------------------------
- Dimensions: 1024 subcarriers x 300 symbols
- Symbol 1: SSS (fixed synchronization sequence)
- Symbols 2-301: Data symbols with QPSK modulation following LFSR-based pattern
- Inactive subcarriers: DC (subcarrier 513), guard bands, and gutter region

Time Domain (After IFFT + Cyclic Prefix)
----------------------------------------
- Total samples: 319,104 samples
- Sample rate: 240 MHz
- Duration: 1.33 ms (1/750 Hz)
- Structure: Concatenation of 301 OFDM symbols, each with 32-sample cyclic prefix

Subcarrier Allocation
---------------------
- Active data subcarriers: 2-1021 (1020 subcarriers)
- Edge pilots: 488-495, 528-535 (16 subcarriers)
- DC (null): Subcarrier 512
- Guard bands: Subcarriers 0-1, 1022-1023


USE CASES
=========

1. Frame Detection
------------------
Correlate received IQ samples with the reference template to identify reference template
arrivals.

  [templateFrame, ~] = genReferenceTemplate();

  % Cross-correlate received signal with template
  rxSignal = ...; % Your received IQ data
  [xcorr, lags] = xcorr(rxSignal, templateFrame);

  % Find peaks indicating reference template locations
  [peaks, locations] = findpeaks(abs(xcorr), 'MinPeakHeight', threshold);


2. Frequency-Domain Pattern Analysis
------------------------------------
Extract the reference rotation pattern for differential analysis.

  [~, rotations] = genReferenceTemplate();

  % Compare decoded frame to template
  decodedRotations = qpsk2rotations(yDataDec(:, :, frameIdx));
  deviation = mod(decodedRotations - rotations, 4);

  % Visualize deviations
  imagesc(deviation);
  title('Rotation Deviations from Template');


3. Channel Estimation
---------------------
Use the known template pattern for channel equalization.

  [~, rotations] = genReferenceTemplate();
  knownTemplate = exp(1j * rotations * pi/2);

  % Received symbols (frequency domain)
  receivedSymbols = ...; % From FFT of received frame

  % Estimate channel gain per subcarrier
  channelEstimate = receivedSymbols ./ knownTemplate;


4. LFSR Sequence Analysis
-------------------------
Study the underlying linear feedback shift register (LFSR) structure.

  [~, rotations] = genReferenceTemplate();

  % Extract bit patterns from rotations
  bits = de2bi(rotations(:), 2, 'left-msb'); % Convert to 2-bit representation

  % Analyze periodicity, autocorrelation, etc.


REFERENCE TEMPLATE PROPERTIES
=============================

Statistical Properties
----------------------
- Constellation: Pure QPSK (4 points: +/-1+/-j)
- Symbol distribution: Approximately uniform across 0 deg, 90 deg, 180 deg, 270 deg
- Autocorrelation: Sharp peak at zero lag (good for synchronization)
- Cross-correlation: Low correlation with non-reference templates

Modulation Consistency
----------------------
Reference templates are characterized by:
  1. All-QPSK modulation across all 301 data symbols
  2. High agreement rate (>99%) to the consensus pattern
  3. Deterministic LFSR-based structure (not random data)

Identification in Real Signals
------------------------------
Reference templates can be identified by:
  - All OFDM symbols using QPSK (no higher-order QAM)
  - Strong correlation with reference rotations
  - Consistent appearance (every ~750 frames in observed data)


TECHNICAL DETAILS
=================

QPSK Rotation Encoding
----------------------
Rotations are encoded as integers 0-3:
   0: 0 deg phase   -> +1 + 0j (real axis, positive)
   1: 90 deg phase  ->  0 + 1j (imaginary axis, positive)
   2: 180 deg phase -> -1 + 0j (real axis, negative)
   3: 270 deg phase ->  0 - 1j (imaginary axis, negative)
  -1: Inactive (zero subcarrier)

OFDM Symbol Processing
----------------------
Each OFDM symbol undergoes:
  1. Modulation: Map rotations to complex IQ (exp(1j * rotations * pi/2))
  2. IFFT: Convert frequency domain to time domain (1024-point IFFT)
  3. Scaling: Multiply by sqrt(1024) to preserve energy
  4. Cyclic Prefix: Prepend last 32 samples to front of symbol
  5. Serialization: Concatenate all symbols into single time-domain vector


DEPENDENCIES
============

Required Functions
------------------
- starlinkConstants.m: Starlink signal parameters (N, Ng, Fs, etc.)
- qpsk2rotations.m: Convert QPSK symbols to rotation indices

Required Data Files
-------------------
- referenceTemplate.mat: Reference template rotations
- sssVec.mat: SSS pattern


EXAMPLE: VISUALIZE TEMPLATE ROTATIONS
=====================================

  [~, rotations] = genReferenceTemplate();

  % Plot rotation pattern
  figure;
  imagesc(rotations);
  colorbar;
  clim([-1 3]);
  colormap(gca, [0.5 0.5 0.5; parula(4)]); % Gray for -1, colors for 0-3
  axis xy;
  xlabel('OFDM Symbol Index');
  ylabel('Subcarrier Index');
  title('Reference Template Rotation Pattern');

  % Add colorbar labels
  cb = colorbar;
  cb.Ticks = [-1 0 1 2 3];
  cb.TickLabels = {'Inactive', '0 deg', '90 deg', '180 deg', '270 deg'};


REFERENCES
==========

- Exemplar Frames GUIDE (exemplar-frames-data/EXEMPLAR_FRAMES_GUIDE.txt)
- Starlink OFDM specification: 1024-subcarrier, 750 Hz frame rate, Ku-band