Introduction of downlinkHandling module to communication architecture

[dhutererprats]

• Tickets addressed: TBD (bsk-xxxx)
• Review: By commit
• Merge strategy: Merge (no squash)

Description

This PR introduces the downlinkHandling communication module and all supporting interfaces, tests, and documentation required to use and validate it in Basilisk.

The module maps link quality from linkBudget into usable downlink outcomes, including:

• BER/PER from CNR, overlap bandwidth, and user-selected bit rate
• retry-limited ARQ success/drop behavior
• attempted, delivered, dropped, and storage-removal data rates
• storage-aware downlink gating and drain behavior
• receiver-path selection using CNR1/CNR2 and antenna RX state
• diagnostic outputs for communication fault analysis and integrated simulation studies

The current analytical BER path uses the standard coherent BPSK/QPSK-style AWGN BER expression. User-selectable modulation/coding models and empirical BER lookup tables are intentionally left as future extensions.

Core implementation and integration work includes:

• New downlink message payload and diagnostics fields:

  • src/architecture/msgPayloadDefC/DownlinkHandlingMsgPayload.h

• New/hardened downlinkHandling module implementation and interface:

  • src/simulation/communication/downlinkHandling/downlinkHandling.h
  • src/simulation/communication/downlinkHandling/downlinkHandling.cpp
  • src/simulation/communication/downlinkHandling/downlinkHandling.i
  • src/simulation/communication/downlinkHandling/Custom.cmake

• Unit test coverage:

  • src/simulation/communication/downlinkHandling/_UnitTest/test_downlinkHandling.py

• Documentation and figures:

  • src/simulation/communication/downlinkHandling/downlinkHandling.rst
  • src/simulation/communication/downlinkHandling/_Documentation/Images/DownlinkHandlingFlow.png
  • src/simulation/communication/downlinkHandling/_Documentation/Images/DownlinkHandlingReliabilityChain.png
  • src/simulation/communication/downlinkHandling/_Documentation/Images/DownlinkHandlingFlow.svg
  • src/simulation/communication/downlinkHandling/_Documentation/Images/DownlinkHandlingReliabilityChain.svg

• Release note snippet:

  • docs/source/Support/bskReleaseNotesSnippets/downlinkHandling.rst

Commit organization is by feature layer:

1. Core downlinkHandling module and SWIG interface
2. Downlink diagnostics message payload
3. Module code comments and documentation
4. Unit test implementation and validation expansion
5. API hardening, setter validation, removal policy, and storage-routing safeguards
6. Documentation figures and release-note snippet updates

Verification

Validation commands for this branch:

• cmake --build dist3 -j4
• .venv/bin/pytest -q -p no:rerunfailures src/simulation/communication/downlinkHandling/_UnitTest/test_downlinkHandling.py

Test coverage includes:

• C++ output parity with a Python-equivalent BER/PER/ARQ formulation
• invalid-link zero-flow behavior
• disabled-node behavior, including stale-diagnostics clearing
• re-enable behavior ensuring disabled downtime is not integrated as active downlink time
• retry-cap behavior and drop probability effects
• removal policy behavior (REMOVE_ATTEMPTED vs REMOVE_DELIVERED_ONLY)
• storage-limited capping and drain behavior
• auto and forced receiver-path selection (CNR1/CNR2, antenna RX states)
• invalid setter input rejection and retained prior valid configuration
• duplicate storage-message registration rejection
• largest-partition selection across multiple storage status inputs
• ambiguous multi-storage partition-name protection, where removal is blocked and a BSK warning is emitted to avoid silent double-draining

Documentation

Documentation delivered in:

• src/simulation/communication/downlinkHandling/downlinkHandling.rst

It includes:

• model scope, assumptions, and integration role
• implemented equations (C/N0, Eb/N0, BER, PER, retry-limited ARQ, throughput scaling)
• message interfaces and outputs
• receiver-path selection behavior
• removal-policy semantics
• storage-selection behavior and integration caveats
• warning that spaceToGroundTransmitter and downlinkHandling should not be used as competing downlink removers on the same storage partitions
• usage and validation guidance

Future work

• Add explicit packet-level ACK/NACK timing model. The current ARQ implementation is expectation-based.
• Add user-selectable modulation/coding models.
• Add empirical or semi-empirical BER lookup-table support for fault studies and communication degradation campaigns.

[dhutererprats]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3be776cccd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[dhutererprats]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: edec469cda

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[dhutererprats]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 76f68abd32

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[dhutererprats]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e2ed86a9fc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[schaubh]

Nice PR. Even Codex commented on how detailed your RST documentation is ;-)

Just saw a few minor things, should be quick to address.

[schaubh]

thanks, great PR!