symbolscope

type Engine struct {
	// contains filtered or unexported fields
}

type Frame struct {
	TimestampNs  int64     `json:"ts_ns"`
	SymbolRateHz float64   `json:"symbol_rate_hz"`
	CenterHz     uint32    `json:"center_hz"`
	OffsetHz     int32     `json:"offset_hz"`
	Soft         []float32 `json:"soft"`
	SymI         []float32 `json:"sym_i"`
	SymQ         []float32 `json:"sym_q"`
	// EyeSoft is a window of the oversampled, AGC-scaled matched-filter
	// output (EyeSPS samples per symbol) on the C4FM path — fold it over
	// the symbol period for the 4-level eye diagram. Empty on paths
	// without an eye tap (CQPSK). It is NOT aligned with Dibits (it runs
	// EyeSPS× faster) and is a bounded recent window, not the full
	// stream. EyeSPS is the integer samples-per-symbol to fold on.
	EyeSoft []float32 `json:"eye_soft"`
	EyeSPS  int       `json:"eye_sps"`
	Dibits  []uint8   `json:"dibits"`
	IsBits  bool      `json:"is_bits"`
	BaseIdx int       `json:"base_idx"`

	// Receiver-state metrics, read from the live receiver each frame —
	// the data behind the Tuning panel (OP25's Mixer / Tuner-FLL). The
	// getters are demod-specific: CarrierOffsetHz is the AFC estimate on
	// C4FM and the carrier-recovery estimate on CQPSK; ClockMu/ClockSPS
	// come from Mueller-Müller (C4FM) or Gardner (CQPSK); AGCLevel is the
	// C4FM symbol-AGC mean|x| or the CQPSK matched-filter AGC gain, with
	// AGCTarget set only on C4FM; CMAError is the CQPSK equalizer
	// convergence proxy (0 on C4FM).
	CarrierOffsetHz float64 `json:"carrier_offset_hz"`
	AGCLevel        float64 `json:"agc_level"`
	AGCTarget       float64 `json:"agc_target"`
	ClockMu         float64 `json:"clock_mu"`
	ClockSPS        float64 `json:"clock_sps"`
	CMAError        float64 `json:"cma_error"`
}

type MixerFrame struct {
	TimestampNs     int64
	CenterHz        uint32
	SampleRateHz    uint32
	OffsetHz        int32
	CarrierOffsetHz float64
	RawBins         []float32
	TunedBins       []float32
}

type Options struct {
	// Protocol selects the receiver. Phase 1 supports trunking.ProtocolP25.
	Protocol trunking.Protocol
	// DemodMode is the P25 demod path: "c4fm" (default) or "cqpsk".
	// Ignored for other protocols.
	DemodMode string
	// InRateHz is the wideband input rate (the SDR's sample rate).
	InRateHz float64
	// OffsetHz tunes a channel sitting at this offset (relative to the
	// SDR centre) down to baseband before channelizing — pulls an
	// off-centre control/voice channel out from under the DC spike.
	OffsetHz int32
	// CenterHz stamps each frame with the SDR centre (informational).
	CenterHz uint32
	// SystemName / FrequencyHz are informational labels passed to the
	// receiver construction.
	SystemName  string
	FrequencyHz uint32
	// FrameSymbols is the per-frame symbol batch size. Zero picks
	// defaultFrameSymbols.
	FrameSymbols int
	// NowNs is an injectable clock for tests. Nil uses time.Now.
	NowNs func() int64
	// Emit receives each completed Frame. Required. The slices it
	// carries are freshly allocated per frame; the callee owns them.
	Emit func(Frame)

	// MixerEmit, when non-nil, enables the Mixer plot: the engine runs a
	// rate-limited FFT over the channelized baseband (raw) and over that
	// baseband re-mixed by the receiver's carrier-offset estimate (tuned),
	// delivering each pair as a MixerFrame. Nil disables the work entirely.
	MixerEmit func(MixerFrame)
	// MixerFFTSize is the FFT length for the Mixer plot (power of two).
	// Zero picks defaultMixerFFTSize. Ignored when MixerEmit is nil.
	MixerFFTSize int
	// MixerFPS caps the Mixer frame rate. Zero picks defaultMixerFPS.
	// Ignored when MixerEmit is nil.
	MixerFPS float64
}