"""Lab046: многопакетная передача большого бинарного объекта поверх Lab045. Разделены два уровня, они не смешиваются: - Уровень 1 (внутри одного радиокадра) — Lab045: свёрточный код R=1/2 K=7, перемежитель, мягкий декодер Витерби, CRC пакета. Исправляет битовые ошибки внутри принятого кадра. - Уровень 2 (большой объект) — существующий ``protocol/image_fragments``: фрагментация, нумерация фрагментов, идентификатор объекта, сборка. Собирает объект из нескольких независимо переданных кадров. Новый код здесь минимален: он только связывает эти два готовых уровня и добавляет fail-closed сборщик объекта, который при недостающем или повреждённом фрагменте возвращает ``object_complete = False`` без исключений и без фиктивного объекта. Формат фрагмента не дублируется — используется существующий 12-байтовый заголовок ``image_fragments`` (``>IHHI``: object_id, fragment_index, fragment_count, original_size). Раскладка нагрузки пакета (256 байт, как в доказанной точке Lab045): [12 байт метаданных фрагмента][244 байта данных фрагмента] Последний фрагмент короче: его нагрузка добивается нулями до 256 байт перед Lab045 и обрезается на приёме по длине, вычисляемой из полей заголовка (object size и fragment count). Erasure-код 12+3 здесь НЕ используется — это отдельное будущее расширение для потери целых фрагментов. RF в этой лабе не запускается: RF TX = 0, только программная проверка. """ from __future__ import annotations import argparse import hashlib from dataclasses import dataclass, replace from typing import Callable import numpy as np from experiments import lab045_hackrf_bpsk_fec as lab045 from protocol import image_fragments as fragments # ============================================================ Константы Lab046 PACKET_PAYLOAD_SIZE = lab045.PAYLOAD_SIZE_BYTES # 256, доказанная точка Lab045 FRAGMENT_DATA_SIZE = PACKET_PAYLOAD_SIZE - fragments.FRAGMENT_HEADER_SIZE # 244 DEFAULT_OBJECT_SIZE = 16384 # 16 KiB, ровный размер, не JPEG DEFAULT_OBJECT_ID = 0x4C303436 # "L046" DEFAULT_OBJECT_SEED = 46 # ============================================================ Детерминированный объект def make_deterministic_object( size: int = DEFAULT_OBJECT_SIZE, seed: int = DEFAULT_OBJECT_SEED, ) -> bytes: """Собрать детерминированный псевдослучайный бинарный объект (не JPEG).""" if size <= 0: raise ValueError("Размер объекта должен быть положительным") generator = np.random.default_rng(seed) return generator.integers(0, 256, size=size, dtype=np.uint8).tobytes() def object_sha256(data: bytes) -> str: return hashlib.sha256(data).hexdigest() # ============================================================ Уровень объекта -> кадры @dataclass(frozen=True) class FramePlan: """Один фрагмент объекта, уже упакованный в кадр Lab045.""" fragment_index: int fragment_count: int encoded_payload_length: int # реальная длина 12+data до добивки нулями plan: lab045.TransmissionPlan def _pad_payload_to_packet(payload: bytes) -> bytes: if len(payload) > PACKET_PAYLOAD_SIZE: raise ValueError("Нагрузка фрагмента больше размера пакета Lab045") return payload + bytes(PACKET_PAYLOAD_SIZE - len(payload)) def build_object_frames( data: bytes, object_id: int = DEFAULT_OBJECT_ID, ) -> list[FramePlan]: """Разбить объект и упаковать каждый фрагмент в кадр Lab045.""" object_fragments = fragments.split_image_bytes( data, object_id, fragment_data_size=FRAGMENT_DATA_SIZE, ) frame_plans: list[FramePlan] = [] for fragment in object_fragments: payload = fragments.encode_image_fragment(fragment) packet_payload = _pad_payload_to_packet(payload) plan = lab045.build_transmission_plan(packet_payload) frame_plans.append( FramePlan( fragment_index=fragment.fragment_index, fragment_count=fragment.fragment_count, encoded_payload_length=len(payload), plan=plan, ) ) return frame_plans def expected_fragment_data_length( fragment_index: int, fragment_count: int, original_size: int, ) -> int | None: """Длина данных фрагмента, вычисленная только из полей заголовка. Возвращает None при несогласованных полях (fail-closed), не бросая. """ if fragment_count <= 0 or original_size <= 0: return None if not 0 <= fragment_index < fragment_count: return None full = FRAGMENT_DATA_SIZE # Верхняя граница: объект из fragment_count кусков по full байт не может # быть больше fragment_count*full. Это отсекает абсурдный original_size # для любого индекса и не даёт полю управлять размером аллокаций. if original_size > fragment_count * full: return None if (fragment_count - 1) * full >= original_size and fragment_count > 1: return None if fragment_index < fragment_count - 1: return full last = original_size - (fragment_count - 1) * full if not 1 <= last <= full: return None return last def recover_fragment_from_payload(packet_payload: bytes) -> fragments.ImageFragment | None: """Снять добивку и разобрать фрагмент из 256-байтной нагрузки. Fail-closed. Использует только принятую нагрузку. Переданный объект неизвестен. """ try: fragment = fragments.decode_image_fragment(packet_payload) except (fragments.ImageFragmentError, TypeError, ValueError): return None real_length = expected_fragment_data_length( fragment.fragment_index, fragment.fragment_count, fragment.original_size, ) if real_length is None or len(fragment.data) < real_length: return None return replace(fragment, data=fragment.data[:real_length]) # ============================================================ Fail-closed сборщик @dataclass class AssemblerCounters: accepted: int = 0 duplicates: int = 0 conflicting: int = 0 rejected: int = 0 class ObjectAssembler: """Собрать объект из независимо принятых фрагментов, ничего не бросая. Любой плохой вход (чужой object_id, несогласованный счётчик/размер, невозможный индекс, конфликтующий дубликат, malformed) отвергается и не выходит наружу исключением. Пока не собраны все индексы — ``object_complete()`` равен False, ``recovered_object()`` равен None. Фиктивный объект не создаётся. """ def __init__(self) -> None: self._object_id: int | None = None self._fragment_count: int | None = None self._original_size: int | None = None self._by_index: dict[int, fragments.ImageFragment] = {} self.counters = AssemblerCounters() def offer(self, fragment: fragments.ImageFragment | None) -> str: """Предложить фрагмент. Вернуть accepted/duplicate/conflicting/rejected.""" if fragment is None: self.counters.rejected += 1 return "rejected" try: index = int(fragment.fragment_index) count = int(fragment.fragment_count) size = int(fragment.original_size) object_id = int(fragment.image_id) if count <= 0 or size <= 0 or not 0 <= index < count: self.counters.rejected += 1 return "rejected" if len(fragment.data) < 1: self.counters.rejected += 1 return "rejected" if self._object_id is None: self._object_id = object_id self._fragment_count = count self._original_size = size elif ( object_id != self._object_id or count != self._fragment_count or size != self._original_size ): self.counters.rejected += 1 return "rejected" existing = self._by_index.get(index) if existing is not None: if existing.data == fragment.data: self.counters.duplicates += 1 return "duplicate" self.counters.conflicting += 1 return "conflicting" self._by_index[index] = fragment self.counters.accepted += 1 return "accepted" except Exception: self.counters.rejected += 1 return "rejected" def missing_indexes(self) -> list[int]: if self._fragment_count is None: return [] return [i for i in range(self._fragment_count) if i not in self._by_index] def object_complete(self) -> bool: return ( self._fragment_count is not None and len(self._by_index) == self._fragment_count and not self.missing_indexes() ) def recovered_object(self) -> bytes | None: """Собрать объект, только если он полон. Иначе None. Не бросает.""" if not self.object_complete(): return None try: return fragments.reassemble_image(list(self._by_index.values())) except fragments.ImageFragmentError: return None # ============================================================ Канал (программный) ChannelFunction = Callable[[lab045.TransmissionPlan, int], np.ndarray] def ideal_channel(plan: lab045.TransmissionPlan, frame_index: int) -> np.ndarray: del frame_index return lab045.modulate_bits_to_ideal_soft(plan.post_preamble_bits) def make_noisy_channel( noise_sigma: float, base_seed: int, ) -> ChannelFunction: """Детерминированный гауссов канал на уровне soft BPSK-символов. Гауссов шум реалистичнее жёстких переворотов знака и сохраняет мягкую информацию, которую использует декодер Витерби. Каждый кадр получает свой воспроизводимый seed ``base_seed + frame_index``. Уровень sigma выбран так, чтобы soft Viterbi исправлял все кадры (см. docs/lab046_current_state): при большем sigma отдельный кадр может не декодироваться, и без erasure- FEC объект окажется неполным — это отдельный сценарий, а не подгон. """ def channel(plan: lab045.TransmissionPlan, frame_index: int) -> np.ndarray: return lab045.simulate_soft_channel( plan, noise_sigma=noise_sigma, seed=base_seed + frame_index, ) return channel # ============================================================ Прогон объекта @dataclass class ObjectTransportResult: object_size: int object_sha256: str fragment_count: int protocol_packet_bytes: int bpsk_frame_count: int total_bpsk_symbols: int total_waveform_samples: int airtime_seconds: float crc_pass_count: int crc_fail_count: int pre_fec_coded_bit_errors: int post_fec_protocol_bit_errors: int valid_fragments: int duplicates: int conflicting: int rejected: int missing_indexes: list[int] object_complete: bool recovered_object_sha256: str | None object_byte_errors: int | None sha_match: bool def run_object_transport( data: bytes, object_id: int = DEFAULT_OBJECT_ID, channel: ChannelFunction = ideal_channel, delivery_order: list[int] | None = None, duplicate_indexes: tuple[int, ...] = (), drop_indexes: tuple[int, ...] = (), corrupt_indexes: tuple[int, ...] = (), ) -> ObjectTransportResult: """Полный программный тракт объект -> кадры -> канал -> приём -> сборка. Приёмник независим: TX-объект и TX-биты не используются для решений о приёме, FEC, метаданных или завершении объекта. Диагностическое сравнение с оригиналом делается только после независимой сборки. """ frame_plans = build_object_frames(data, object_id) frame_by_index = {frame.fragment_index: frame for frame in frame_plans} order = delivery_order if delivery_order is not None else [f.fragment_index for f in frame_plans] assembler = ObjectAssembler() crc_pass = 0 crc_fail = 0 pre_fec_errors = 0 post_fec_errors = 0 def deliver(frame_index: int, corrupt: bool) -> None: nonlocal crc_pass, crc_fail, pre_fec_errors, post_fec_errors frame = frame_by_index[frame_index] soft = channel(frame.plan, frame_index) if corrupt: # Детерминированно инвертируем весь coded-поток (после защищённого # PHY header): CRC гарантированно не пройдёт, пакет отвергается. soft = soft.copy() soft[lab045.PHY_HEADER_BIT_COUNT:] = -soft[lab045.PHY_HEADER_BIT_COUNT:] reception = lab045.analyze_post_preamble_soft(soft) # Диагностика pre/post-FEC только после независимого CRC-решения. diagnostic = lab045.diagnostic_pre_and_post_fec(reception, soft, frame.plan) pre = diagnostic["pre_fec_coded"]["bit_errors"] post = diagnostic["post_fec_packet"]["bit_errors"] if pre is not None: pre_fec_errors += pre if post is not None: post_fec_errors += post if reception.analysis["crc"] == lab045.CRC_PASS and reception.payload_bytes is not None: crc_pass += 1 fragment = recover_fragment_from_payload(reception.payload_bytes) assembler.offer(fragment) else: crc_fail += 1 for frame_index in order: deliver(frame_index, corrupt=frame_index in corrupt_indexes) for frame_index in duplicate_indexes: deliver(frame_index, corrupt=False) for frame_index in drop_indexes: assembler._by_index.pop(frame_index, None) recovered = assembler.recovered_object() recovered_sha = object_sha256(recovered) if recovered is not None else None original_sha = object_sha256(data) if recovered is not None and len(recovered) == len(data): byte_errors = int(np.count_nonzero( np.frombuffer(recovered, dtype=np.uint8) != np.frombuffer(data, dtype=np.uint8) )) elif recovered is not None: byte_errors = max(len(recovered), len(data)) else: byte_errors = None total_symbols = sum(f.plan.frame_symbol_count for f in frame_plans) total_samples = sum(f.plan.waveform_sample_count for f in frame_plans) airtime = sum(f.plan.airtime_seconds for f in frame_plans) return ObjectTransportResult( object_size=len(data), object_sha256=original_sha, fragment_count=len(frame_plans), protocol_packet_bytes=len(frame_plans[0].plan.packet), bpsk_frame_count=len(frame_plans), total_bpsk_symbols=total_symbols, total_waveform_samples=total_samples, airtime_seconds=airtime, crc_pass_count=crc_pass, crc_fail_count=crc_fail, pre_fec_coded_bit_errors=pre_fec_errors, post_fec_protocol_bit_errors=post_fec_errors, valid_fragments=assembler.counters.accepted, duplicates=assembler.counters.duplicates, conflicting=assembler.counters.conflicting, rejected=assembler.counters.rejected, missing_indexes=assembler.missing_indexes(), object_complete=assembler.object_complete(), recovered_object_sha256=recovered_sha, object_byte_errors=byte_errors, sha_match=(recovered_sha == original_sha and recovered is not None), ) # ============================================================ Airtime / goodput def goodput_report(result: ObjectTransportResult) -> dict: """Честная baseline-оценка эфирного времени и полезной пропускной способности.""" airtime = result.airtime_seconds object_bytes = result.object_size goodput_bytes_per_second = object_bytes / airtime if airtime > 0 else 0.0 goodput_kbit_per_second = goodput_bytes_per_second * 8 / 1000.0 useful_data_bits = object_bytes * 8 total_symbols = result.total_bpsk_symbols return { "airtime_seconds": airtime, "goodput_bytes_per_second": goodput_bytes_per_second, "goodput_kbit_per_second": goodput_kbit_per_second, "useful_data_bits": useful_data_bits, "total_bpsk_symbols": total_symbols, "useful_bits_per_symbol": useful_data_bits / total_symbols if total_symbols else 0.0, "overhead": { "fragment_metadata_bytes_per_packet": fragments.FRAGMENT_HEADER_SIZE, "protocol_header_plus_crc_bytes_per_packet": lab045.HEADER_SIZE + lab045.CRC_SIZE, "convolutional_rate": "1/2", "phy_preamble_bits_per_frame": lab045.PREAMBLE_BIT_COUNT, "protected_phy_header_bits_per_frame": lab045.PHY_HEADER_BIT_COUNT, "guard_plus_rrc_symbol_times_per_frame": 2 * lab045.GUARD_SYMBOL_COUNT + lab045.RRC_SPAN_SYMBOLS, }, } # ============================================================ Функциональные тесты def run_functional_tests() -> None: """Быстрые самопроверки без данных эксперимента (вызывается quick_gate).""" obj = make_deterministic_object(2048, seed=1) ideal = run_object_transport(obj, channel=ideal_channel) assert ideal.object_complete and ideal.sha_match and ideal.object_byte_errors == 0 assert ideal.crc_fail_count == 0 frames = build_object_frames(obj) assert frames[0].plan.frame_symbol_count == 5724 assert all(len(f.plan.packet) == 268 for f in frames) # Fragment round trip через существующий слой без канала. fs = fragments.split_image_bytes(obj, DEFAULT_OBJECT_ID, FRAGMENT_DATA_SIZE) rebuilt = fragments.reassemble_image(fs) assert rebuilt == obj # Последний короткий фрагмент восстанавливается по длине из заголовка. last = fs[-1] padded = _pad_payload_to_packet(fragments.encode_image_fragment(last)) recovered = recover_fragment_from_payload(padded) assert recovered is not None and recovered.data == last.data # ============================================================ main def main() -> int: parser = argparse.ArgumentParser(description="Lab046 multi-packet object transport (software)") parser.add_argument("--object-size", type=int, default=DEFAULT_OBJECT_SIZE) parser.add_argument("--seed", type=int, default=DEFAULT_OBJECT_SEED) parser.add_argument("--sigma", type=float, default=0.40) arguments = parser.parse_args() obj = make_deterministic_object(arguments.object_size, arguments.seed) ideal = run_object_transport(obj, channel=ideal_channel) noisy = run_object_transport( obj, channel=make_noisy_channel(arguments.sigma, base_seed=46000), ) report = goodput_report(ideal) print("Lab046 software object transport") print(f"object size = {ideal.object_size} bytes") print(f"object sha256 = {ideal.object_sha256}") print(f"fragment data size = {FRAGMENT_DATA_SIZE} bytes") print(f"fragment count = {ideal.fragment_count}") print(f"protocol packet = {ideal.protocol_packet_bytes} bytes") print(f"bpsk frames = {ideal.bpsk_frame_count}") print(f"total bpsk symbols = {ideal.total_bpsk_symbols}") print(f"total waveform samples = {ideal.total_waveform_samples}") print(f"estimated airtime = {report['airtime_seconds']:.2f} s") print(f"goodput = {report['goodput_bytes_per_second']:.1f} bytes/s = {report['goodput_kbit_per_second']:.2f} kbit/s") print("--- ideal ---") print(f"crc pass/fail = {ideal.crc_pass_count}/{ideal.crc_fail_count}") print(f"object complete = {ideal.object_complete}, sha match = {ideal.sha_match}, byte errors = {ideal.object_byte_errors}") print(f"--- noisy (gaussian sigma={arguments.sigma}) ---") print(f"pre-FEC coded errors = {noisy.pre_fec_coded_bit_errors}") print(f"post-FEC protocol errors = {noisy.post_fec_protocol_bit_errors}") print(f"crc pass/fail = {noisy.crc_pass_count}/{noisy.crc_fail_count}") print(f"object complete = {noisy.object_complete}, sha match = {noisy.sha_match}, byte errors = {noisy.object_byte_errors}") print("RF TX = 0 (software-only)") return 0 if __name__ == "__main__": raise SystemExit(main())