524 lines
22 KiB
Python
524 lines
22 KiB
Python
"""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())
|