mfsk_core/msg/ap.rs
1//! A Priori (AP) hint for WSJT 77-bit message payloads.
2//!
3//! Known parts of the message (callsigns, grid, report) are converted to
4//! their packed bit representation and marked as "locked" so a downstream
5//! FEC decoder can clamp those LLRs to a high-confidence value. AP hints
6//! typically drop the decode threshold by a few dB when the caller knows
7//! the expected message format (e.g. "CQ from a specific DX call", or
8//! "RRR/RR73/73 as part of a QSO exchange").
9//!
10//! The 77-bit bit layout is shared across FT8, FT4, FT2 and FST4 — all WSJT
11//! Type-1 messages use the same `call1 / call2 / grid-or-report / i3` field
12//! positions — so `ApHint` lives in the protocol-agnostic message layer.
13
14use super::wsjt77::{pack_grid4, pack28};
15use crate::core::MessageCodec;
16
17/// Marker trait for `MessageCodec`s whose information-bit layout matches the
18/// 77-bit Wsjt77 family field positions (call1 at 0..28, call2 at 29..57,
19/// grid at 58..73, message-type i3 at 74..76). Used to gate the
20/// callsign/grid-based [`ApHint`] AP path to compatible protocols.
21///
22/// Implementing this trait is an assertion that the codec's bit layout is
23/// byte-for-byte equivalent to [`crate::msg::Wsjt77Message`] for the first 77
24/// bits — the AP module reads / writes those positions directly. Codecs with
25/// different layouts (e.g. byte-oriented packet codecs whose first bits
26/// encode a length field rather than a callsign hash) must NOT implement
27/// this trait; they need their own AP design.
28///
29/// Sealed: only the `mfsk-core` crate may implement.
30pub trait WsjtApCompatible: MessageCodec + sealed::Sealed {}
31
32mod sealed {
33 pub trait Sealed {}
34}
35
36impl sealed::Sealed for super::Wsjt77Message {}
37impl WsjtApCompatible for super::Wsjt77Message {}
38
39#[cfg(feature = "q65")]
40impl sealed::Sealed for super::Q65Message {}
41#[cfg(feature = "q65")]
42impl WsjtApCompatible for super::Q65Message {}
43
44/// A Priori information to bias decoding.
45#[derive(Debug, Clone, Default)]
46pub struct ApHint {
47 /// Known first callsign (e.g. "CQ", "JA1ABC"). Locks message bits 0–28.
48 pub call1: Option<String>,
49 /// Known second callsign (e.g. "3Y0Z"). Locks message bits 29–57.
50 pub call2: Option<String>,
51 /// Known grid locator (e.g. "PM95"). Locks bits 58–73.
52 pub grid: Option<String>,
53 /// Known response token: "RRR", "RR73", or "73". Locks bits 58–73.
54 pub report: Option<String>,
55}
56
57impl ApHint {
58 pub fn new() -> Self {
59 Self::default()
60 }
61 pub fn with_call1(mut self, call: &str) -> Self {
62 self.call1 = Some(call.to_string());
63 self
64 }
65 pub fn with_call2(mut self, call: &str) -> Self {
66 self.call2 = Some(call.to_string());
67 self
68 }
69 pub fn with_grid(mut self, grid: &str) -> Self {
70 self.grid = Some(grid.to_string());
71 self
72 }
73 pub fn with_report(mut self, rpt: &str) -> Self {
74 self.report = Some(rpt.to_string());
75 self
76 }
77
78 /// True if any AP field is populated.
79 pub fn has_info(&self) -> bool {
80 self.call1.is_some() || self.call2.is_some()
81 }
82
83 /// Build the `(mask, bit_values)` bit vectors of length `n_codeword` for
84 /// a downstream FEC codec. Bits 0–76 (the message payload) are populated
85 /// from the hint fields; bits 77..N are left unmasked.
86 ///
87 /// `mask[i] == 1` means bit `i` is AP-locked; `values[i]` is the target
88 /// bit value (0 or 1). The FEC codec clamps its LLR at these positions
89 /// to `±apmag` accordingly.
90 pub fn build_bits(&self, n_codeword: usize) -> (Vec<u8>, Vec<u8>) {
91 let mut mask = vec![0u8; n_codeword];
92 let mut values = vec![0u8; n_codeword];
93
94 // Write 28-bit packed call + 1-bit flag (=0) starting at `start`.
95 let mut set_call_bits = |call: &str, start: usize| {
96 if let Some(n28) = pack28(call) {
97 for i in 0..28 {
98 let bit = ((n28 >> (27 - i)) & 1) as u8;
99 mask[start + i] = 1;
100 values[start + i] = bit;
101 }
102 // Flag bit (ipa/ipb) = 0 for standard calls.
103 mask[start + 28] = 1;
104 values[start + 28] = 0;
105 }
106 };
107
108 if let Some(ref c1) = self.call1 {
109 set_call_bits(c1, 0);
110 }
111 if let Some(ref c2) = self.call2 {
112 set_call_bits(c2, 29);
113 }
114
115 // Bits 58–73: grid or response field (15-bit value + 1-bit ir flag).
116 if let Some(ref grid) = self.grid
117 && let Some(igrid) = pack_grid4(grid)
118 {
119 mask[58] = 1;
120 values[58] = 0; // ir=0
121 for i in 0..15 {
122 let bit = ((igrid >> (14 - i)) & 1) as u8;
123 mask[59 + i] = 1;
124 values[59 + i] = bit;
125 }
126 }
127 if let Some(ref rpt) = self.report {
128 let igrid_val: Option<u32> = match rpt.as_str() {
129 "RRR" => Some(32_400 + 2),
130 "RR73" => Some(32_400 + 3),
131 "73" => Some(32_400 + 4),
132 _ => None,
133 };
134 if let Some(igrid) = igrid_val {
135 mask[58] = 1;
136 values[58] = 0;
137 for i in 0..15 {
138 let bit = ((igrid >> (14 - i)) & 1) as u8;
139 mask[59 + i] = 1;
140 values[59 + i] = bit;
141 }
142 }
143 }
144
145 // Lock message type i3 = 001 (Type 1 standard) when any call known.
146 if self.has_info() {
147 mask[74] = 1;
148 values[74] = 0;
149 mask[75] = 1;
150 values[75] = 0;
151 mask[76] = 1;
152 values[76] = 1;
153 }
154
155 (mask, values)
156 }
157
158 /// Number of AP-locked message bits (informational; callers use it to
159 /// scale per-pass confidence thresholds).
160 pub fn locked_bits(&self, n_codeword: usize) -> usize {
161 let (mask, _) = self.build_bits(n_codeword);
162 mask.iter().filter(|&&m| m != 0).count()
163 }
164}