js8 Namespace Reference

JS8 namespace for Kalman filter-based trackers. More...

Classes
class	FrequencyTracker
	Lightweight PLL/Kalman-style tracker for residual frequency offset. More...
class	TimingTracker
class	SoftCombiner
	Cache and combine repeated LLR frames for the same decode candidate. More...
class	WhiteningProcessor
	Compute per-tone/symbol noise medians and whiten LLRs for a JS8 frame. More...

Functions
float	llrErasureThreshold ()
	Read configured LLR erasure threshold.
bool	ldpcFeedbackEnabled ()
	Whether LDPC feedback is enabled.
int	ldpcFeedbackMaxPasses ()
	Maximum LDPC feedback passes to attempt.
template<std::size_t N>
void	refineLlrsWithLdpcFeedback (std::array< float, N > const &llrIn, std::array< int8_t, N > const &cw, float erasureThreshold, std::array< float, N > &llrOut, int &confidentCount, int &uncertainCount)
	Refine LLRs using a decoded LDPC codeword as feedback.

Variables
constexpr float	LLR_ERASURE_THRESHOLD_DEFAULT = 0.25f
	LDPC erasure threshold config and feedback refinement helpers.
constexpr float	LLR_FEEDBACK_CONFIDENT_MIN = 3.0f
constexpr float	LLR_FEEDBACK_UNCERTAIN_MAX = 1.0f
constexpr float	LLR_FEEDBACK_CONFIDENT_BOOST = 1.2f
constexpr float	LLR_FEEDBACK_UNCERTAIN_SHRINK = 0.5f
constexpr float	LLR_FEEDBACK_MAX_MAG = 6.0f
constexpr int	LDPC_FEEDBACK_MAX_PASSES_DEFAULT = 8

Detailed Description

JS8 namespace for Kalman filter-based trackers.

Function Documentation

ldpcFeedbackEnabled()

bool js8::ldpcFeedbackEnabled ( )

inline

Whether LDPC feedback is enabled.

The JS8_LDPC_FEEDBACK environment variable may be set to 0 to explicitly disable feedback. If the variable is not present or cannot be parsed as an integer, feedback is enabled by default.

Returns

true when LDPC feedback is enabled, otherwise false.

ldpcFeedbackMaxPasses()

int js8::ldpcFeedbackMaxPasses ( )

inline

Maximum LDPC feedback passes to attempt.

Reads JS8_LDPC_MAX_PASSES and clamps the value to the range [1, LDPC_FEEDBACK_MAX_PASSES_DEFAULT]. Returns a sensible default when the variable is not provided or invalid.

Returns

Number of feedback passes to attempt.

llrErasureThreshold()

float js8::llrErasureThreshold ( )

inline

Read configured LLR erasure threshold.

Reads the JS8_LLR_ERASURE_THRESH environment variable (if present) and returns a positive finite threshold. If the environment variable is missing, invalid, or the JS8_DISABLE_ERASURE_THRESHOLDING variable is set, this function returns 0.0f to indicate erasure thresholding is disabled.

Returns

Positive erasure threshold, or 0.0f if disabled/invalid.

refineLlrsWithLdpcFeedback()

template<std::size_t N>

void js8::refineLlrsWithLdpcFeedback	(	std::array< float, N > const &	llrIn,
		std::array< int8_t, N > const &	cw,
		float	erasureThreshold,
		std::array< float, N > &	llrOut,
		int &	confidentCount,
		int &	uncertainCount )

Refine LLRs using a decoded LDPC codeword as feedback.

The algorithm adjusts each input LLR based on whether its sign matches the corresponding bit in the provided codeword cw and on the magnitude of the LLR:

• If the sign matches and the magnitude is >= LLR_FEEDBACK_CONFIDENT_MIN, the magnitude is boosted by LLR_FEEDBACK_CONFIDENT_BOOST (clamped to LLR_FEEDBACK_MAX_MAG) and the sign preserved.
• If the sign does not match, or the magnitude is <= LLR_FEEDBACK_UNCERTAIN_MAX, the magnitude is shrunk by LLR_FEEDBACK_UNCERTAIN_SHRINK. When an erasureThreshold > 0 is provided, shrunk magnitudes below that threshold are set to zero (erased).
• Non-finite input LLRs are replaced with zero and counted as uncertain.

This function writes results to llrOut and returns counts of confident and uncertain bits via confidentCount and uncertainCount respectively.

Template Parameters

N	Number of LLR elements (array length).

Parameters

	llrIn	Input LLR array (unchanged).
	cw	Decoded codeword as an array of int8_t (non-zero means bit 1).
	erasureThreshold	Threshold below which shrunk magnitudes are erased (set to zero). Use 0.0f to disable erasure thresholding.
[out]	llrOut	Output array receiving adjusted LLRs.
[out]	confidentCount	Number of bits considered confident after adjust.
[out]	uncertainCount	Number of bits considered uncertain after adjust.

Variable Documentation

LDPC_FEEDBACK_MAX_PASSES_DEFAULT

int js8::LDPC_FEEDBACK_MAX_PASSES_DEFAULT = 8

constexpr

Default maximum number of LDPC feedback passes when unset in env.

LLR_ERASURE_THRESHOLD_DEFAULT

float js8::LLR_ERASURE_THRESHOLD_DEFAULT = 0.25f

constexpr

LDPC erasure threshold config and feedback refinement helpers.

Inline env readers expose thresholds/pass limits; the templated refineLlrsWithLdpcFeedback shrinks/boosts LLRs using the decoded codeword to retry LDPC. Used inside the JS8 decode loop between LDPC passes. Default erasure threshold applied to shrunk LLRs (when enabled).

LLR_FEEDBACK_CONFIDENT_BOOST

float js8::LLR_FEEDBACK_CONFIDENT_BOOST = 1.2f

constexpr

Multiply confident magnitudes by this factor when boosting.

LLR_FEEDBACK_CONFIDENT_MIN

float js8::LLR_FEEDBACK_CONFIDENT_MIN = 3.0f

constexpr

Minimum magnitude to consider a bit "confident" when sign matches.

LLR_FEEDBACK_MAX_MAG

float js8::LLR_FEEDBACK_MAX_MAG = 6.0f

constexpr

Maximum allowed absolute magnitude for adjusted LLRs.

LLR_FEEDBACK_UNCERTAIN_MAX

float js8::LLR_FEEDBACK_UNCERTAIN_MAX = 1.0f

constexpr

Maximum magnitude considered "uncertain" (will be shrunk).

LLR_FEEDBACK_UNCERTAIN_SHRINK

float js8::LLR_FEEDBACK_UNCERTAIN_SHRINK = 0.5f

constexpr

Multiply uncertain magnitudes by this factor when shrinking.