sjg/trx-rs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docs](trx-ftx): update README with new module architecture

Browse Source 
Reflect the common/ft8/ft4/ft2 directory reorganization in the
architecture diagram, file tree, and signal flow description.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Stan Grams <sjg@haxx.space>
This commit is contained in:
Stan Grams
2026-03-20 00:08:38 +01:00
parent ab8425c85c
commit 11097a5133
1 changed files with 67 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/decoders/trx-ftx/README.md
+67 -31
View File
@@ -16,56 +16,92 @@ FT2 is an experimental protocol that doubles FT4's symbol rate
## Architecture ## Architecture
```
trx-ftx/src/
├── lib.rs # Module declarations
├── decoder.rs # Public API: Ft8Decoder, Ft8DecodeResult
├── common/
│ ├── protocol.rs # FTx constants, timing, FtxProtocol enum
│ ├── constants.rs # LDPC tables, Costas patterns, Gray maps
│ ├── crc.rs # CRC-14 compute/extract
│ ├── ldpc.rs # Belief-propagation LDPC decoder
│ ├── osd.rs # OSD-1/OSD-2 CRC-guided bit-flip decoder
│ ├── encode.rs # LDPC(174,91) encoder
│ ├── decode.rs # Candidate search, CRC verify, SNR, dispatchers
│ ├── monitor.rs # Waterfall FFT spectrogram engine
│ ├── message.rs # 77-bit message pack/unpack
│ ├── callsign_hash.rs # Callsign hash table for decode dedup
│ └── text.rs # Callsign & grid character encoding
├── ft8/
│ └── mod.rs # FT8 sync scoring, likelihood extraction, tone encoding
├── ft4/
│ └── mod.rs # FT4 sync scoring, likelihood extraction, tone encoding
└── ft2/
├── mod.rs # FT2 pipeline orchestration (peak search, decode loop)
├── decode.rs # FT2 waterfall sync scoring & multi-scale likelihood
├── bitmetrics.rs # Per-symbol FFT, 1/2/4-symbol coherent bit metrics
├── downsample.rs # Frequency-domain shift & downsample via IFFT
└── sync.rs # 2D Costas reference waveforms & correlation
```
```mermaid ```mermaid
graph TD graph TD
subgraph "Shared Modules" subgraph "common/"
protocol[protocol.rs<br/>FTx constants & timing] protocol[protocol.rs<br/>FTx constants & timing]
constants[constants.rs<br/>LDPC tables, Costas patterns] constants[constants.rs<br/>LDPC tables, Costas patterns]
crc[crc.rs<br/>CRC-14] crc[crc.rs<br/>CRC-14]
ldpc[ldpc.rs<br/>Sum-product & BP decoders] ldpc[ldpc.rs<br/>BP LDPC decoder]
encode[encode.rs<br/>LDPC encoder, tone generation] osd[osd.rs<br/>BP + OSD-1/OSD-2 decoder]
encode[encode.rs<br/>LDPC encoder]
decode[decode.rs<br/>Candidate search & dispatchers]
monitor[monitor.rs<br/>Waterfall FFT]
message[message.rs<br/>Pack/unpack 77-bit messages] message[message.rs<br/>Pack/unpack 77-bit messages]
text[text.rs<br/>Callsign & grid formatting] text[text.rs<br/>Callsign & grid formatting]
callsign_hash[callsign_hash.rs<br/>Hash table for callsign lookup] callsign_hash[callsign_hash.rs<br/>Hash table for callsign lookup]
end end
subgraph "FT8 / FT4 Pipeline" subgraph "ft8/"
monitor[monitor.rs<br/>Waterfall FFT & peak search] ft8[mod.rs<br/>Sync, likelihood, encode]
decode[decode.rs<br/>Sync, bit metrics, LDPC decode]
decoder[decoder.rs<br/>Public API: Ft8Decoder]
end end
subgraph "FT2 Pipeline" subgraph "ft4/"
ft2_mod[ft2/mod.rs<br/>Pipeline orchestration] ft4[mod.rs<br/>Sync, likelihood, encode]
ft2_ds[ft2/downsample.rs<br/>Frequency-shift & downsample]
ft2_sync[ft2/sync.rs<br/>2D Costas correlation]
ft2_bm[ft2/bitmetrics.rs<br/>Multi-scale soft metrics]
ft2_osd[ft2/osd.rs<br/>BP + OSD-1/OSD-2 decoder]
end end
decoder --> monitor --> decode subgraph "ft2/"
decode --> ldpc & crc & encode & message & constants ft2_mod[mod.rs<br/>Pipeline orchestration]
ft2_decode[decode.rs<br/>Waterfall sync & likelihood]
ft2_ds[downsample.rs<br/>Frequency-shift & downsample]
ft2_sync[sync.rs<br/>2D Costas correlation]
ft2_bm[bitmetrics.rs<br/>Multi-scale soft metrics]
end
ft2_mod --> ft2_ds & ft2_sync & ft2_bm & ft2_osd decoder[decoder.rs<br/>Public API: Ft8Decoder] --> monitor & decode & message
ft2_osd --> constants & crc & encode
ft2_mod --> decode decode --> ft8 & ft4 & ft2_decode
decode --> protocol decode --> ldpc & crc & constants & protocol
ft2_mod --> protocol
ft8 --> constants & encode & crc
ft4 --> constants & encode & crc
ft2_mod --> ft2_ds & ft2_sync & ft2_bm & ft2_decode
ft2_mod --> osd & decode
ft2_bm --> constants
ft2_sync --> constants
``` ```
### Signal flow ### Signal flow
**FT8/FT4:** Audio samples enter `monitor.rs` which accumulates a **FT8/FT4:** Audio samples enter `common/monitor.rs` which accumulates
waterfall spectrogram. `decode.rs` finds sync candidates via Costas a waterfall spectrogram. `common/decode.rs` finds sync candidates by
correlation, extracts log-likelihood ratios from tone amplitudes, and dispatching to protocol-specific scoring in `ft8/` or `ft4/`, extracts
runs the LDPC decoder. Decoded 77-bit messages are unpacked by log-likelihood ratios from tone amplitudes, and runs the BP LDPC
`message.rs`. decoder. Decoded 77-bit messages are unpacked by `common/message.rs`.
**FT2:** Audio enters `ft2/mod.rs` which drives a dedicated pipeline: **FT2:** Audio enters `ft2/mod.rs` which drives a dedicated pipeline:
peak search in the averaged spectrum, frequency-shift downsampling peak search in the averaged spectrum, frequency-shift downsampling
(`downsample.rs`), 2D sync scoring against precomputed Costas (`ft2/downsample.rs`), 2D sync scoring against precomputed Costas
reference waveforms (`sync.rs`), multi-scale coherent bit metric reference waveforms (`ft2/sync.rs`), multi-scale coherent bit metric
extraction at 1/2/4-symbol integration depths (`bitmetrics.rs`), and extraction at 1/2/4-symbol integration depths (`ft2/bitmetrics.rs`),
multi-pass LDPC decoding via iterative belief-propagation with OSD and multi-pass LDPC decoding via iterative belief-propagation with OSD
fallback (`osd.rs`). The shared `encode.rs`, `crc.rs`, and fallback (`common/osd.rs`). The shared `common/` modules (encode, crc,
`constants.rs` modules are reused across all three protocols. constants, protocol) are reused across all three protocols.