adsb-generator 0.1.0__py3-none-any.whl

adsb_generator/__init__.py

@@ -0,0 +1,9 @@
+__version__ = "0.1.0"
+
+from .generator import ADSBSample, ADSBGenerator
+from .channel import ChannelParams, ADSBChannel
+from .encoder import TXParams, ADSBEncoder
+from .message import MessageType, ADSBMessage
+
+__all__ = ["ADSBSample", "ADSBGenerator", "ChannelParams", "ADSBChannel",
+            "TXParams", "ADSBEncoder", "MessageType", "ADSBMessage"]

adsb_generator/algorithms.py

@@ -0,0 +1,84 @@
+import math
+
+class ADSBAlgorithms():
+
+    CRC_POLY = 0xFFF409
+
+    @classmethod
+    def calculate_crc(cls, data: int) -> int:
+
+        packet = data << 24
+        remainder = packet
+
+        for bit in range(111, 23, -1):
+            if (remainder >> bit) & 1:
+                remainder ^= cls.CRC_POLY << (bit - 24)
+
+        crc = remainder & 0xFFFFFF
+
+        return packet | crc
+
+    _NL_TABLE = [
+        (87, 59), (83, 58), (79, 57), (76, 56), (73, 55),
+        (70, 54), (66, 53), (63, 52), (60, 51), (57, 50),
+        (53, 49), (50, 48), (46, 47), (43, 46), (40, 45),
+        (37, 44), (34, 43), (31, 42), (28, 41), (25, 40),
+        (22, 39), (19, 38), (16, 37), (13, 36), (9, 35),
+        (6, 34), (3, 33), (0, 32),
+    ]
+
+    @classmethod
+    def _nl(cls, lat: float) -> int:
+        if abs(lat) >= 87:
+            return 1
+        for lat_min, nl in cls._NL_TABLE:
+            if abs(lat) >= lat_min:
+                return nl
+        return 32
+
+    @classmethod
+    def encode_cpr(cls, lat: float, lon: float, odd: bool) -> tuple[int, int]:
+        lat = max(-90.0, min(90.0, lat))
+        lon = max(-180.0, min(180.0, lon))
+
+        NB = 17
+        factor = 1 << NB
+
+        nz_lat = 59 if odd else 60
+        dlat = 360.0 / nz_lat
+
+        zone_lat = math.floor(lat / dlat)
+        rem_lat = lat - zone_lat * dlat
+        yz = int(round((rem_lat / dlat) * factor)) & (factor - 1)
+
+        rlat = dlat * (yz / factor + zone_lat)
+        rlat = max(-90.0, min(90.0, rlat))
+
+        nl = cls._nl(rlat)
+
+        dlon = 360.0 / nl
+        zone_lon = math.floor(lon / dlon)
+        rem_lon = lon - zone_lon * dlon
+        xz = int(round((rem_lon / dlon) * factor)) & (factor - 1)
+
+        return yz, xz
+
+    @staticmethod
+    def encode_altitude(alt: int) -> int:
+        alt_clamped = max(-1000, min(50100, alt))
+        n = (alt_clamped + 1000) // 25
+
+        top_bits = (n >> 4) & 0x7F
+        bottom_bits = n & 0x0F
+
+        return (top_bits << 5) | (1 << 4) | bottom_bits
+
+    @staticmethod
+    def encode_ground_track(degrees: float, valid: bool = True) -> tuple[int, int]:
+        if not valid or degrees is None:
+            return 0, 0
+
+        degrees = degrees % 360.0
+        trk_code = round(degrees * 128.0 / 360.0)
+
+        return 1, trk_code

adsb_generator/channel.py

@@ -0,0 +1,248 @@
+import random
+import numpy as np
+from enum import Enum
+
+class ChannelParams(Enum):
+    """Supported channel impairment parameters for ADS-B signal simulation."""
+    SNR_DB = "snr_db"
+    NOISE_CORRELATION = "noise_correlation"
+
+    FREQUENCY_OFFSET = "frequency_offset"
+    PHASE_OFFSET = "phase_offset"
+    DC_OFFSET_I = "dc_offset_i"
+    DC_OFFSET_Q = "dc_offset_q"
+
+    IQ_GAIN_IMBALANCE = "iq_gain_imbalance"
+    IQ_PHASE_IMBALANCE = "iq_phase_imbalance"
+
+class ADSBChannel:
+    """
+    Simulates realistic RF channel impairments on ADS-B baseband I/Q signals.
+
+    This class applies a series of channel effects—including IQ imbalance, DC offset,
+    frequency offset, phase offset, and additive white Gaussian noise (AWGN)—to
+    simulate the degradations encountered in real-world ADS-B reception. Each
+    impairment parameter is sampled from configurable probability distributions.
+
+    Attributes:
+        sample_rate (float): Sampling rate in samples per second.
+        channel_params_distributions (dict[ChannelParams | str, list[list[float]]]): 
+            Mapping of channel parameters to their probability distributions defined
+            as intervals with associated weights.
+        seed (int | None): Seed for the internal random number generator to ensure 
+            reproducible channel simulation.
+    """
+    def __init__(self, sample_rate: float = 2e6, channel_params_distributions: (dict[ChannelParams | str, list[list[float]]]) | None = None, seed: int | None = None):
+        """
+        Initializes the channel simulator with sampling parameters and impairment distributions.
+
+        Args:
+            sample_rate: Sampling rate in samples per second. Defaults to 2 MHz.
+            channel_params_distributions: A mapping of ChannelParams to probability 
+                distributions defined as lists of [min_val, max_val, weight] intervals. 
+                If None, defaults to distributions covering typical ADS-B reception 
+                conditions for all eight channel parameters.
+            seed: Seed for the internal random number generator to ensure reproducible 
+                channel simulation. If None, the generator is seeded from system randomness.
+
+        Raises:
+            ValueError: If `channel_params_distributions` contains invalid keys, invalid 
+                intervals (min > max), weights that do not sum to 1.0, or noise correlation 
+                values outside [-1.0, 1.0] (validated via `_validate_distributions`).
+        """
+
+        self.sample_rate = sample_rate
+
+        default_dists = {
+            ChannelParams.SNR_DB: [
+                [3.0, 8.0, 0.20],
+                [8.0, 15.0, 0.55],
+                [15.0, 25.0, 0.25],
+            ],
+            ChannelParams.NOISE_CORRELATION: [
+                [0.0, 0.0, 1.0],
+            ],
+            ChannelParams.FREQUENCY_OFFSET: [
+                [-1000.0, 1000.0, 0.80],
+                [-3000.0, 3000.0, 0.20],
+            ],
+            ChannelParams.PHASE_OFFSET: [
+                [-0.10, 0.10, 0.80],
+                [-0.30, 0.30, 0.20],
+            ],
+            ChannelParams.DC_OFFSET_I: [
+                [-0.01, 0.01, 0.90],
+                [-0.03, 0.03, 0.10],
+            ],
+            ChannelParams.DC_OFFSET_Q: [
+                [-0.01, 0.01, 0.90],
+                [-0.03, 0.03, 0.10],
+            ],
+            ChannelParams.IQ_GAIN_IMBALANCE: [
+                [0.00, 0.02, 0.80],
+                [0.02, 0.05, 0.20],
+            ],
+            ChannelParams.IQ_PHASE_IMBALANCE: [
+                [-1.0, 1.0, 0.80],
+                [-3.0, 3.0, 0.20],
+            ],
+        }
+
+        self.channel_params_dists = channel_params_distributions or default_dists
+
+        self._validate_distributions
+
+        self._seed = seed if seed is not None else random.randint(0, 2**32 - 1)
+        self._rng = random.Random(self._seed)
+        self._np_rng = np.random.default_rng(self._seed)
+        
+    @property
+    def seed(self) -> int:
+        """Gets the seed value."""
+        return self._seed
+
+    def _validate_distributions(self):
+        valid_types = set(ChannelParams)
+        valid_values = {item.value for item in ChannelParams}
+
+        for channel_param, intervals in self.channel_params_dists.items():
+            if channel_param not in valid_types and channel_param not in valid_values:
+                raise ValueError(
+                    f"Invalid channel param key: '{channel_param}'. "
+                    f"Valid options are the ChannelParams enums or: {valid_values}"
+                )
+
+            enum_key = channel_param if isinstance(channel_param, ChannelParams) else ChannelParams(channel_param)
+
+            total_weights = 0.0
+            for min_val, max_val, weight in intervals:
+                if min_val > max_val:
+                    raise ValueError(
+                        f"Invalid range {min_val} > {max_val} in key '{channel_param}'"
+                    )
+
+                if enum_key == ChannelParams.NOISE_CORRELATION:
+                    if not (-1.0 <= min_val <= 1.0) or not (-1.0 <= max_val <= 1.0):
+                        raise ValueError(
+                            f"Noise correlation must be in range [-1.0, 1.0]. "
+                            f"Got range [{min_val}, {max_val}] for key '{channel_param}'"
+                        )
+                    if min_val > max_val:
+                        raise ValueError(
+                            f"Invalid noise correlation range: {min_val} > {max_val}"
+                        )
+                total_weights += weight
+
+            if not (0.99 <= total_weights <= 1.01):
+                raise ValueError(
+                    f"Sum of weights for key '{channel_param}' must equal 1.0, got {total_weights:.2f}"
+                )
+
+    def _sample_channel_params(self) -> dict[ChannelParams, float]:
+        sampled_params = {}
+
+        default_values = {
+            ChannelParams.SNR_DB: 15.0,
+            ChannelParams.NOISE_CORRELATION: 0.0,
+            ChannelParams.FREQUENCY_OFFSET: 0.0,
+            ChannelParams.PHASE_OFFSET: 0.0,
+            ChannelParams.DC_OFFSET_I: 0.0,
+            ChannelParams.DC_OFFSET_Q: 0.0,
+            ChannelParams.IQ_GAIN_IMBALANCE: 0.0,
+            ChannelParams.IQ_PHASE_IMBALANCE: 0.0,
+        }
+
+        for param_key, intervals in self.channel_params_dists.items(): 
+            ranges = [(low, high) for low, high, _ in intervals]
+            weights = [w for _, _, w in intervals]
+
+            selected_range = self._rng.choices(ranges, weights, k=1)[0]
+
+            sampled_val = self._rng.uniform(selected_range[0], selected_range[1])
+
+            enum_key = param_key if isinstance(param_key, ChannelParams) else ChannelParams(param_key)
+            sampled_params[enum_key] = sampled_val
+
+        for param in ChannelParams:
+            if param not in sampled_params:
+                sampled_params[param] = default_values[param]
+
+        return sampled_params
+
+    def _apply_dc_offset(self, signal: np.ndarray, dc_offset_i: float, dc_offset_q: float) -> np.ndarray:
+        dc_offset = dc_offset_i + 1j * dc_offset_q
+        return signal + dc_offset
+    
+    def _apply_freq_offset(self, signal: np.ndarray, freq_offset: float, sample_rate: float) -> np.ndarray:
+        t = np.arange(len(signal)) / sample_rate
+        return signal * np.exp(1j * 2 * np.pi * freq_offset * t)
+
+    def _apply_phase_offset(self, signal: np.ndarray, phase_offset: float) -> np.ndarray:
+        return signal * np.exp(1j * phase_offset)
+
+    def _apply_iq_imbalance(self, signal: np.ndarray, gain_imbalance: float, phase_imbalance: float) -> np.ndarray:
+        phi = np.deg2rad(phase_imbalance)
+        
+        i = signal.real * (1 + gain_imbalance / 2)
+        q = signal.imag * (1 - gain_imbalance / 2)
+        
+        i_out = i * np.cos(phi) + q * np.sin(phi)
+        q_out = i * np.sin(phi) + q * np.cos(phi)
+        
+        return i_out + 1j * q_out
+
+    def _apply_gaussian_noise(self, signal: np.ndarray, snr_db: float, noise_correlation: float = 0) -> np.ndarray:
+        if len(signal) == 0:
+            return signal.copy()
+        signal_power = np.mean(np.abs(signal) ** 2)
+        
+        snr_linear = 10 ** (snr_db / 10)
+        
+        noise_power = signal_power / snr_linear
+        noise_std = np.sqrt(noise_power / 2)
+        
+        if noise_correlation > 0:
+            cov_matrix = noise_power / 2 * np.array([
+                [1.0, noise_correlation],
+                [noise_correlation, 1.0]
+            ])
+            
+            noise = self._np_rng.multivariate_normal(
+                mean=[0, 0],
+                cov=cov_matrix,
+                size=len(signal)
+            )
+            noise_complex = noise[:, 0] + 1j * noise[:, 1]
+        else:
+            noise_i = self._np_rng.normal(0, noise_std, len(signal))
+            noise_q = self._np_rng.normal(0, noise_std, len(signal))
+            noise_complex = noise_i + 1j * noise_q
+        
+        return signal + noise_complex
+
+    def apply(self, signal: np.ndarray) -> tuple[np.ndarray, dict[ChannelParams, float]]:
+        """
+        Applies simulated channel impairments to an ADS-B baseband I/Q signal.
+
+        This method samples channel parameters from configured distributions and
+        applies impairments in the following order: IQ imbalance, DC offset,
+        frequency offset, phase offset, and finally additive Gaussian noise.
+
+        Args:
+            signal: Complex I/Q samples of the baseband signal (dtype=np.complex64).
+
+        Returns:
+            A tuple containing:
+                - np.ndarray: The impaired complex I/Q signal (dtype=np.complex64)
+                - dict[ChannelParams, float]: The channel parameters used for this operation
+        """
+        params = self._sample_channel_params()
+
+        signal = self._apply_iq_imbalance(signal, params[ChannelParams.IQ_GAIN_IMBALANCE], params[ChannelParams.IQ_PHASE_IMBALANCE])
+        signal = self._apply_dc_offset(signal, params[ChannelParams.DC_OFFSET_I], params[ChannelParams.DC_OFFSET_Q])
+        signal = self._apply_freq_offset(signal, params[ChannelParams.FREQUENCY_OFFSET], self.sample_rate)
+        signal = self._apply_phase_offset(signal, params[ChannelParams.PHASE_OFFSET])
+        signal = self._apply_gaussian_noise(signal, params[ChannelParams.SNR_DB], params[ChannelParams.NOISE_CORRELATION])
+
+        return signal, params
+

adsb_generator/encoder.py

@@ -0,0 +1,155 @@
+import random
+import numpy as np
+from enum import Enum
+
+class TXParams(Enum):
+    AMPLITUDE = "amplitude"
+
+class ADSBEncoder:
+    """
+    Converts ADS-B raw frames into baseband I/Q samples with randomized transmission parameters.
+
+    This class handles the encoding of 112-bit ADS-B messages into a complex baseband 
+    signal representation, following the pulse-position modulation (PPM) encoding 
+    scheme defined in the Mode S/ADS-B standard. The encoder adds configurable 
+    random variations to transmission parameters (e.g., amplitude) to simulate 
+    real-world signal variability.
+
+    Attributes:
+        sample_rate (float): Sampling rate in samples per second.
+        tx_params_distributions (dict[TXParams | str, list[list[float]]]): Mapping 
+            of transmission parameters to their probability distributions defined 
+            as intervals with associated weights.
+        seed (int | None): Seed for the internal random number generator to ensure 
+            reproducible signal generation.
+    """
+    def __init__(self, sample_rate: float = 2e6, tx_params_distributions: (dict[TXParams | str, list[list[float]]]) | None = None, seed: int | None = None):
+        """
+        Initializes the encoder with sampling parameters and transmission parameter distributions.
+
+        Args:
+            sample_rate: Sampling rate in samples per second. Defaults to 2 MHz.
+            tx_params_distributions: A mapping of TXParams to probability distributions 
+                defined as lists of [min_val, max_val, weight] intervals. If None, 
+                defaults to a single amplitude distribution with three intervals 
+                covering the range [0.05, 1.00].
+            seed: Seed for the internal random number generator to ensure reproducible 
+                signal generation. If None, the generator is seeded from system randomness.
+
+        Raises:
+            ValueError: If `tx_params_distributions` contains invalid keys, invalid 
+                intervals (min > max), or weights that do not sum to 1.0 (validated 
+                via `_validate_distributions`).
+        """
+        self.sample_rate = sample_rate
+
+        default_dists = {
+                TXParams.AMPLITUDE: [
+                    [0.05, 0.25, 0.5],
+                    [0.25, 0.65, 0.3],
+                    [0.65, 1.00, 0.2]
+                ]}
+
+        self.tx_params_dists = tx_params_distributions or default_dists
+
+        self._validate_distributions
+
+        self._seed = seed if seed is not None else random.randint(0, 2**32 - 1)
+        self._rng = random.Random(self._seed)
+
+    @property
+    def seed(self) -> int:
+        """Gets the seed value."""
+        return self._seed
+
+    def _validate_distributions(self):
+        valid_types = set(TXParams)
+        valid_values = {item.value for item in TXParams}
+
+        for tx_param, intervals in self.tx_params_dists.items():
+            if tx_param not in valid_types and tx_param not in valid_values:
+                raise ValueError(
+                    f"Invalid tx param key: '{tx_param}'. "
+                    f"Valid options are the TXParams enums or: {valid_values}"
+                )
+
+            total_weights = 0.0
+            for min_val, max_val, weight in intervals:
+                if min_val > max_val:
+                    raise ValueError(
+                        f"Invalid range {min_val} > {max_val} in key '{tx_param}'"
+                    )
+                total_weights += weight
+
+            if not (0.99 <= total_weights <= 1.01):
+                raise ValueError(
+                    f"Sum of weights for key '{tx_param}' must equal 1.0, got {total_weights:.2f}"
+                )
+
+    def _sample_tx_params(self) -> dict[TXParams, float]:
+        sampled_params = {}
+        for param_key, intervals in self.tx_params_dists.items(): 
+            ranges = [(low, high) for low, high, _ in intervals]
+            weights = [w for _, _, w in intervals]
+
+            selected_range = self._rng.choices(ranges, weights, k=1)[0]
+
+            sampled_val = self._rng.uniform(selected_range[0], selected_range[1])
+
+            enum_key = param_key if isinstance(param_key, TXParams) else TXParams(param_key)
+            sampled_params[enum_key] = sampled_val
+
+        return sampled_params
+
+    def encode(self, msg: int) -> tuple[np.ndarray, dict[TXParams, float]]:
+        """
+        Encodes a 112-bit ADS-B message into a complex baseband I/Q signal.
+
+        This method samples transmission parameters from configured distributions and 
+        generates a 120 μs signal containing the preamble and 112 data bits encoded 
+        using PPM at 1 Mbps.
+
+        The timing follows the ADS-B standard:
+            - Preamble: 8.0 μs with pulses at specific positions
+            - Data bits: 112 bits at 1 μs per bit starting at 8.0 μs
+            - Pulse width: 0.5 μs for both preamble and data pulses
+
+        Args:
+            msg: The 112-bit ADS-B message as an integer (LSB alignment).
+
+        Returns:
+            A tuple containing:
+                - np.ndarray: Complex I/Q samples of the baseband signal (dtype=np.complex64)
+                - dict[TXParams, float]: The transmission parameters used for this encode operation
+        """
+        params = self._sample_tx_params()
+        amplitude = params[TXParams.AMPLITUDE]
+
+        samples_per_us = self.sample_rate / 1e6
+        total_samples = int(round(120.0 * samples_per_us))
+
+        signal = np.zeros(total_samples, dtype=np.float32)
+
+        for start_us, end_us in ((0.0, 0.5), (1.0, 1.5), (3.5, 4.0), (4.5, 5.0)):
+            signal[
+                int(round(start_us * samples_per_us)):
+                int(round(end_us * samples_per_us))
+            ] = amplitude
+
+        bit_start_us = 8.0
+
+        for shift in range(111, -1, -1):
+            bit = (msg >> shift) & 1
+
+            pulse_offset_us = 0.0 if bit else 0.5
+
+            p_start = round((bit_start_us + pulse_offset_us) * samples_per_us)
+            p_end = round((bit_start_us + pulse_offset_us + 0.5) * samples_per_us)
+
+            signal[p_start:p_end] = amplitude
+
+            bit_start_us += 1.0
+
+        iq_samples = signal.astype(np.complex64)
+
+        return iq_samples, params

adsb_generator/generator.py

@@ -0,0 +1,85 @@
+import random
+import numpy as np
+from dataclasses import dataclass
+from .message import ADSBMessage, MessageType
+from .encoder import ADSBEncoder, TXParams
+from .channel import ADSBChannel, ChannelParams
+
+@dataclass
+class ADSBSample:
+    """A single ADS-B sample containing the raw message, encoded signal, and impaired signal."""
+    message: int
+    message_type: MessageType
+
+    clean_signal: np.ndarray
+    tx_params: dict[TXParams, float]
+
+    channel_signal: np.ndarray
+    channel_params: dict[ChannelParams, float]
+
+class ADSBGenerator():
+    """
+    End-to-end ADS-B signal generator that produces synthetic I/Q samples with channel impairments.
+
+    This class orchestrates the full ADS-B signal generation pipeline: building random
+    112-bit ADS-B messages, encoding them into baseband I/Q signals using PPM, and
+    applying realistic RF channel impairments. It is implemented as an infinite iterator
+    that yields ADSBSample instances on each iteration.
+
+    Attributes:
+        seed (int): Seed used for the internal random number generators.
+    """
+    def __init__(self, message_type_probs: dict[MessageType | str, float] | None = None , tx_params_distributions: dict[TXParams | str, list[list[float]]] | None = None,
+                 channel_params_distributions: dict[ChannelParams | str, list[list[float]]] | None = None, sample_rate: float = 2e6, seed: int | None = None):
+        """
+        Initializes the generator with message, transmission, and channel distributions.
+
+        Args:
+            message_type_probs: Mapping of MessageType to their emission probabilities. 
+                If None, defaults to an equal 25% distribution across all message types.
+            tx_params_distributions: Mapping of TXParams to probability distributions 
+                defined as lists of [min_val, max_val, weight] intervals. If None, 
+                defaults to a single amplitude distribution.
+            channel_params_distributions: Mapping of ChannelParams to probability 
+                distributions defined as lists of [min_val, max_val, weight] intervals. 
+                If None, defaults to distributions covering typical ADS-B reception 
+                conditions.
+            sample_rate: Sampling rate in samples per second. Defaults to 2 MHz.
+            seed: Seed for the internal random number generators to ensure reproducible 
+                output. If None, the generator is seeded from system randomness.
+        """
+
+        self._seed = seed if seed is not None else random.randint(0, 2**32 - 1)
+
+        self.builder = ADSBMessage(message_type_probs, self._seed)
+        self.encoder = ADSBEncoder(sample_rate, tx_params_distributions, self._seed)
+        self.channel = ADSBChannel(sample_rate, channel_params_distributions, self._seed)
+
+    @property
+    def seed(self) -> int:
+        """Gets the seed value."""
+        return self._seed
+
+    def __iter__(self):
+        """
+        Yields an infinite stream of ADS-B samples.
+
+        Each iteration builds a random ADS-B message, encodes it into a baseband
+        I/Q signal, applies channel impairments, and yields an ADSBSample containing
+        the raw message, clean signal, and impaired signal along with their parameters.
+        """
+        while True:
+            message, message_type = self.builder.build()
+
+            clean_signal, tx_params = self.encoder.encode(message)
+
+            channel_signal, channel_params = self.channel.apply(clean_signal)
+
+            yield ADSBSample(
+                message=message,
+                message_type=message_type,
+                clean_signal=clean_signal,
+                tx_params=tx_params,
+                channel_signal=channel_signal,
+                channel_params=channel_params,
+            )

adsb_generator/message.py

@@ -0,0 +1,198 @@
+import random
+import string
+from enum import Enum
+from .algorithms import ADSBAlgorithms
+
+class MessageType(Enum):
+    """Supported Automatic Dependent Surveillance-Broadcast (ADS-B) message types."""
+    IDENTIFICATION = "identification"
+    SURFACE_POSITION = "surface_position"
+    AIRBORNE_POSITION = "airborne_position"
+    AIRBORNE_VELOCITY = "airborne_velocity"
+
+class ADSBMessage():
+    """
+    Generates synthetic 112-bit ADS-B (Mode S Downlink Format 17) raw frames.
+
+    This class handles the probabilistic generation and bit-level encoding of 
+    various ADS-B message types—including aircraft identification, surface position, 
+    airborne position, and airborne velocity—complete with 24-bit CRC parity generation.
+
+    Attributes:
+        message_type_probs (dict[MessageType | str, float]): Mapping of message 
+            types to their selection probabilities.
+        seed: int | None = None: Seed for the internal random number generator to ensure reproducible 
+            message output.
+    """
+    def __init__(self, message_type_probs: dict = None, seed: int | None = None):
+        """
+        Initializes the instance with message type probabilities.
+
+        Args:
+            message_type_probs: A mapping of MessageType to their respective 
+                emission probabilities. If None, defaults to an equal 25% distribution 
+                across IDENTIFICATION, SURFACE_POSITION, AIRBORNE_POSITION, and 
+                AIRBORNE_VELOCITY.
+            seed: Seed for the internal random number generator to ensure reproducible 
+                message output. If None, the generator is seeded from system randomness.
+
+        Raises:
+            ValueError: If `message_type_probs` contains invalid probability values 
+                or does not sum to 1.0 (validated via `_validate_probabilities`).
+        """
+
+        default_probs = {
+            MessageType.IDENTIFICATION: 0.25,
+            MessageType.SURFACE_POSITION: 0.25,
+            MessageType.AIRBORNE_POSITION: 0.25,
+            MessageType.AIRBORNE_VELOCITY: 0.25
+        }
+
+        self.message_type_probs = message_type_probs or default_probs
+        self._validate_probabilities()
+
+        self._seed = seed if seed is not None else random.randint(0, 2**32 - 1)
+        self._rng = random.Random(self._seed)
+
+        self._CALLSIGN_CHARSET = {
+            " ": 0,
+            **{chr(ord("A") + i): i + 1 for i in range(26)},
+            **{str(i): 48 + i for i in range(10)},
+        }
+
+    @property
+    def seed(self) -> int:
+        """Gets the seed value."""
+        return self._seed
+
+
+    def _validate_probabilities(self):
+        valid_types = set(item for item in MessageType)
+        valid_values = set(item.value for item in MessageType)
+
+        for msg_type in self.message_type_probs.keys():
+            if msg_type not in valid_types and msg_type not in valid_values:
+                raise ValueError(
+                    f"Invalid message type key: '{msg_type}'. "
+                    f"Valid options are the MessageType enums or: {valid_values}"
+                )
+            
+        total= sum(self.message_type_probs.values())
+        if not (0.99 <= total <= 1.01):
+            raise ValueError(
+                f"Sum of probabilities must equal 1.0, got {total}"
+            )
+
+    def _build_identification_message(self) -> int:
+        tc = self._rng.randint(1, 4)
+        ca = self._rng.randint(0, 7)
+
+        prefix = "".join(self._rng.choices(string.ascii_uppercase, k=3))
+        digits = str(self._rng.randint(10, 99999))
+        callsign = (prefix + digits).ljust(8, " ")[:8]
+
+        callsign_48bit = 0
+        for char in callsign:
+            code = self._CALLSIGN_CHARSET.get(char, 0)
+            callsign_48bit = (callsign_48bit << 6) | (code & 0x3F)
+
+        return (tc << 51) | (ca << 48) | callsign_48bit
+
+    def _build_surface_position_message(self) -> int:
+        tc = self._rng.randint(5, 8)
+        mov = self._rng.randint(0, 127)
+        s, trk = ADSBAlgorithms.encode_ground_track(self._rng.uniform(0, 360), self._rng.choice([True, False]))
+        t = self._rng.choices([1, 0], [0.9, 0.1], k=1)[0]
+
+        f = self._rng.randint(0, 1)
+        lat_cpr, lon_cpr = ADSBAlgorithms.encode_cpr(self._rng.uniform(-90, 90), self._rng.uniform(-180, 180), (f == 1))
+
+        return ((tc << 51) | (mov << 44) | (s << 43) | (trk << 36) |
+        (t << 35) | (f << 34) | (lat_cpr << 17) | lon_cpr)
+
+    def _build_airborne_position_message(self) -> int:
+        tc = self._rng.choice([self._rng.randint(9, 18), self._rng.randint(20, 22)])
+        ss = self._rng.randint(0 ,3)
+        saf = self._rng.choice([0, 1])
+
+        alt = ADSBAlgorithms.encode_altitude(self._rng.randint(500, 45000))
+
+        t = self._rng.choices([1, 0], [0.9, 0.1], k=1)[0]
+
+        f = self._rng.randint(0, 1)
+        lat_cpr, lon_cpr = ADSBAlgorithms.encode_cpr(self._rng.uniform(-90, 90), self._rng.uniform(-180, 180), (f == 1))
+
+        return ((tc << 51) | (ss << 49) | (saf << 48) | (alt << 36) |
+                (t << 35) | (f << 34) | (lat_cpr << 17) | lon_cpr)
+
+    def _build_airborne_velocity_message(self) -> int:
+        tc = 19
+        st = self._rng.randint(1, 4)
+        ic = self._rng.choice([0, 1])
+        ifr = self._rng.choice([0, 1])
+        nucv = self._rng.randint(0, 4)
+
+        subtype = 0
+        if st in [1, 2]:
+            dew = self._rng.choice([0, 1])
+            vew = (self._rng.randint(0, 1021) + 1) if st == 1 else (int(self._rng.choice([x for x in range(0, 4085, 4)]) / 4) + 1)
+            dns = self._rng.choice([0, 1])
+            vns = (self._rng.randint(0, 1021) + 1) if st == 1 else (int(self._rng.choice([x for x in range(0, 4085, 4)]) / 4) + 1)
+            
+            subtype = (dew << 21) | (vew << 11) | (dns << 10) | vns
+        else:
+            sh = self._rng.choice([0, 1])
+            hdg = round((self._rng.uniform(0.0, 360.0) * 1024) / 360) % 1024
+            t = self._rng.choice([0, 1])
+            ais = (self._rng.randint(0, 1021) + 1) if st == 3 else (int(self._rng.choice([x for x in range(0, 4085, 4)]) / 4) + 1)
+
+            subtype = (sh << 21) | (hdg << 11) | (t << 10) | ais
+
+        vrsrc = self._rng.choice([0, 1])
+        svr = self._rng.choice([0, 1])
+        vr = int(self._rng.choice([x for x in range(0, 32641, 64)]) / 64) + 1
+        res = 0
+        sdif = self._rng.choice([0, 1])
+        dalt = int(self._rng.choice([x for x in range(0, 3151, 25)]) / 25) + 1
+
+        return ((tc << 51) | (st << 48) | (ic << 47) | (ifr << 46) | (nucv << 43) |
+                (subtype << 21) | (vrsrc << 20) | (svr << 19) | (vr << 10) | (res << 8) | (sdif << 7) | dalt)
+
+
+    def build(self) -> tuple[int, MessageType]:
+        """
+        Generates a self._rng ADS-B message based on configured probabilities and calculates its CRC.
+
+        self._rngly selects an ADS-B message type using the configured probability distribution, 
+        constructs the message fields (Downlink Format, Capability, ICAO address, and Message payload), 
+        and computes the final parity checksum.
+
+        Returns:
+            The complete 112-bit ADS-B message encoded as an integer, including 
+            the 24-bit Parity/Interrogation ID (CRC).
+
+            Message type.
+        """
+        types = list(self.message_type_probs.keys())
+        weights = list(self.message_type_probs.values())
+        selected_type = self._rng.choices(types, weights, k=1)[0]
+
+        selected_type = MessageType(selected_type) if isinstance(selected_type, str) else selected_type
+
+        df = 17                       
+        ca = self._rng.randint(0, 7)        
+        icao = self._rng.getrandbits(24)   
+        me = 0  
+
+        generators = {
+            MessageType.IDENTIFICATION: self._build_identification_message,
+            MessageType.SURFACE_POSITION: self._build_surface_position_message,
+            MessageType.AIRBORNE_POSITION: self._build_airborne_position_message,
+            MessageType.AIRBORNE_VELOCITY: self._build_airborne_velocity_message,
+        }
+
+        me = generators[selected_type]()
+
+        data = (df << 83) | (ca << 80) | (icao << 56) | me
+
+        return ADSBAlgorithms.calculate_crc(data), selected_type

adsb_generator-0.1.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: adsb-generator
+Version: 0.1.0
+Summary: `adsb-generator` produces realistic I/Q (In-phase/Quadrature) samples of clean and impaired ADS-B (Mode S Downlink Format 17) baseband signals, along with the raw 112-bit message and all applied parameters. It implements an infinite iterator that streams reproducible samples with full control over message type distributions, transmission parameters, and channel impairments.
+Author-email: Adam Hamri <adamhamri9@proton.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/adamhamri9/adsb-datagen
+Project-URL: Repository, https://github.com/adamhamri9/adsb-datagen
+Project-URL: Issues, https://github.com/adamhamri9/adsb-datagen/issues
+Keywords: adsb,mode-s,aviation,signal-generation,iq-samples,baseband
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Communications :: Ham Radio
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+# adsb-generator
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB.svg)](https://www.python.org/downloads/)
+
+**Synthetic ADS-B data generator.**
+
+`adsb-generator` produces realistic I/Q (In-phase/Quadrature) samples of clean and impaired ADS-B (Mode S Downlink Format 17) baseband signals, along with the raw 112-bit message and all applied parameters. It implements an infinite iterator that streams reproducible samples with full control over message type distributions, transmission parameters, and channel impairments.
+
+## Key Features
+
+- **End-to-end pipeline**: random message generation, PPM encoding, and RF channel simulation in a single call.
+- **Four ADS-B message types**: identification, surface position, airborne position, and airborne velocity with configurable emission probabilities.
+- **Realistic channel impairments**: Gaussian Noise(both AWGN and Correlated) , frequency & phase offset, IQ imbalance, and DC offset, all sampled from configurable probability distributions.
+- **Reproducibility**: deterministic output via a shared seed across all pipeline stages.
+- **Configurable distributions**: override any transmission or channel parameter distribution to model specific receiver conditions or hardware behavior.
+- **NumPy-native**: all signals are `np.complex64` arrays, ready for direct use with any downstream processing tool.
+
+## Requirements
+
+- Python 3.10+
+- NumPy
+
+## Installation
+
+```bash
+pip install adsb-generator
+```
+
+## Usage
+
+```python
+from adsb_generator import ADSBGenerator
+
+# Create a generator with a fixed seed for reproducibility
+gen = ADSBGenerator(seed=42)
+
+# Each iteration yields an ADSBSample with the raw message,
+# clean signal, and channel-impaired signal
+for sample in gen:
+    print(f"Message type : {sample.message_type.value}")
+    print(f"Raw message  : {sample.message:#028x}")
+    print(f"Clean signal : {sample.clean_signal.shape} complex64 samples")
+    print(f"Noisy signal : {sample.channel_signal.shape} complex64 samples")
+    print(f"SNR (dB)     : {sample.channel_params['snr_db']:.1f}")
+    print(f"Amplitude    : {sample.tx_params['amplitude']:.3f}")
+    break
+```
+
+### Customizing Distributions
+
+```python
+from adsb_generator import ADSBGenerator, MessageType, ChannelParams
+
+# Favor airborne positions, restrict SNR to low-moderate range
+gen = ADSBGenerator(
+    message_type_probs={
+        MessageType.AIRBORNE_POSITION: 0.60,
+        MessageType.AIRBORNE_VELOCITY: 0.20,
+        MessageType.IDENTIFICATION: 0.10,
+        MessageType.SURFACE_POSITION: 0.10,
+    },
+    channel_params_distributions={
+        ChannelParams.SNR_DB: [
+            [3.0, 8.0, 0.70],
+            [8.0, 15.0, 0.30],
+        ],
+    },
+    sample_rate=2e6,
+    seed=12345,
+)
+
+sample = next(gen)
+```
+
+## API Reference
+
+### `ADSBGenerator`
+
+```python
+ADSBGenerator(
+    message_type_probs: dict[MessageType | str, float] | None = None,
+    tx_params_distributions: dict[TXParams | str, list[list[float]]] | None = None,
+    channel_params_distributions: dict[ChannelParams | str, list[list[float]]] | None = None,
+    sample_rate: float = 2e6,
+    seed: int | None = None,
+)
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `message_type_probs` | `dict` or `None` | Equal 25% per type | Mapping of `MessageType` to emission probabilities (must sum to 1.0). |
+| `tx_params_distributions` | `dict` or `None` | Single amplitude band | Mapping of `TXParams` to `[[min, max, weight], ...]` intervals. |
+| `channel_params_distributions` | `dict` or `None` | Typical ADS-B conditions | Mapping of `ChannelParams` to `[[min, max, weight], ...]` intervals. |
+| `sample_rate` | `float` | `2e6` | Sampling rate in samples per second. |
+| `seed` | `int` or `None` | Random | Seed for deterministic output across all pipeline stages. |
+
+---
+
+### `ADSBSample`
+
+Dataclass returned by each iteration of `ADSBGenerator`.
+
+| Field | Type | Description |
+|---|---|---|
+| `message` | `int` | Complete 112-bit ADS-B message (including 24-bit CRC) as an integer. |
+| `message_type` | `MessageType` | The type of ADS-B message generated. |
+| `clean_signal` | `np.ndarray` | Complex baseband I/Q signal before channel impairments (`complex64`). |
+| `tx_params` | `dict[TXParams, float]` | Transmission parameters applied during encoding. |
+| `channel_signal` | `np.ndarray` | Complex baseband I/Q signal after channel impairments (`complex64`). |
+| `channel_params` | `dict[ChannelParams, float]` | Channel parameters applied to the signal. |
+
+---
+
+### `MessageType`
+
+| Value | Description |
+|---|---|
+| `IDENTIFICATION` | Aircraft identification (callsign) messages (TC 1--4). |
+| `SURFACE_POSITION` | Surface position messages (TC 5--8). |
+| `AIRBORNE_POSITION` | Airborne position messages (TC 9--18, 20--22). |
+| `AIRBORNE_VELOCITY` | Airborne velocity messages (TC 19). |
+
+---
+
+### `ADSBEncoder`
+
+Encodes 112-bit messages into complex baseband I/Q samples using PPM per the Mode S standard.
+
+```python
+ADSBEncoder(
+    sample_rate: float = 2e6,
+    tx_params_distributions: dict[TXParams | str, list[list[float]]] | None = None,
+    seed: int | None = None,
+)
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `encode(msg: int)` | `tuple[np.ndarray, dict[TXParams, float]]` | Encodes a 112-bit message into a 120-us baseband I/Q signal. |
+
+---
+
+### `ADSBChannel`
+
+Simulates realistic RF channel impairments on baseband I/Q signals.
+
+```python
+ADSBChannel(
+    sample_rate: float = 2e6,
+    channel_params_distributions: dict[ChannelParams | str, list[list[float]]] | None = None,
+    seed: int | None = None,
+)
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `apply(signal: np.ndarray)` | `tuple[np.ndarray, dict[ChannelParams, float]]` | Applies impairments: IQ imbalance, DC offset, frequency offset, phase offset, AWGN. |
+
+---
+
+### `ChannelParams`
+
+| Value | Description |
+|---|---|
+| `SNR_DB` | Signal-to-noise ratio in dB. |
+| `NOISE_CORRELATION` | I/Q noise correlation coefficient (-1.0 to 1.0). |
+| `FREQUENCY_OFFSET` | Carrier frequency offset in Hz. |
+| `PHASE_OFFSET` | Phase offset in radians. |
+| `DC_OFFSET_I` | DC offset on the in-phase component. |
+| `DC_OFFSET_Q` | DC offset on the quadrature component. |
+| `IQ_GAIN_IMBALANCE` | Gain imbalance between I and Q channels. |
+| `IQ_PHASE_IMBALANCE` | Phase imbalance between I and Q channels (degrees). |
+
+---
+
+### `ADSBAlgorithms`
+
+Static utility class providing ADS-B encoding algorithms.
+
+| Method | Returns | Description |
+|---|---|---|
+| `calculate_crc(data: int)` | `int` | Computes 24-bit CRC parity using polynomial `0xFFF409`. |
+| `encode_cpr(lat, lon, odd)` | `tuple[int, int]` | Encodes lat/lon into CPR 17-bit values. |
+| `encode_altitude(alt: int)` | `int` | Encodes altitude in feet into 12-bit Gillham-coded format. |
+| `encode_ground_track(degrees, valid)` | `tuple[int, int]` | Encodes ground track heading into the 7-bit format. |
+
+## Distribution Format
+
+All configurable distributions use the format `[[min_val, max_val, weight], ...]` where weights for a given parameter must sum to `1.0` (+/- 0.01 tolerance). Keys can be enum members or their string values (e.g., `ChannelParams.SNR_DB` or `"snr_db"`).
+
+## License
+
+[MIT](LICENSE) - Copyright (c) 2026 Adam Hamri (adamhamri9)

adsb_generator-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+adsb_generator/__init__.py,sha256=AU84UFFLrdWoMK_uix9uCYodx7bh5YUJNrQf6IHrN54,352
+adsb_generator/algorithms.py,sha256=LBcTkbK94gouSkFmDo48ZiZaC_-4mY9TtFJwes3shxw,2265
+adsb_generator/channel.py,sha256=_5hUjqhpJyu_n8T8y1OdQycydrJUFEq11nTGZo1x79E,10416
+adsb_generator/encoder.py,sha256=X4zUdVVU2ixI7x4xi9g5QFXV2r4CN9vFUcLMJDnLXNk,6235
+adsb_generator/generator.py,sha256=RTdwA0DcWVc6P2IriJIfSNIqEz9bgDPrN9nV3xd8nU4,3774
+adsb_generator/message.py,sha256=x9zIOKdtV-uikBkC1KtqiWnj-w61OTgvZuHQl2N2mqQ,8209
+adsb_generator-0.1.0.dist-info/licenses/LICENSE,sha256=0Zc5Y-ihUySF2-U3su0-ERhEq-pYJPvcbfUMkONdrWY,1079
+adsb_generator-0.1.0.dist-info/METADATA,sha256=chG4asTjaw4k5sUR0sOm4l0Nu1uK9nQD0d-q6whIPIE,8851
+adsb_generator-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+adsb_generator-0.1.0.dist-info/top_level.txt,sha256=Dqxs5s64BNiCODLScEChyq31fa8AKNVZxQDDv6BDmKM,15
+adsb_generator-0.1.0.dist-info/RECORD,,

adsb_generator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

adsb_generator-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Hamri (adamhamri9)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adsb_generator-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+adsb_generator