trunking

type ActiveCall struct {
	Device      *VoiceDevice
	Grant       Grant
	Talkgroup   *TalkGroup
	StartedAt   time.Time
	LastHeardAt time.Time
}

type Affiliation struct {
	System            string              // System name, matches trunking.System.Name
	Protocol          string              // "p25" / "dmr" / "nxdn"
	SourceID          uint32              // radio unit being affiliated
	GroupID           uint32              // talkgroup the unit is joining
	AnnouncementGroup uint32              // optional announcement-group association (0 if unused)
	Response          AffiliationResponse // accepted / failed / denied / refused
	At                time.Time
}

type AffiliationResponse uint8

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

type CachedSystem struct {
	LastFrequencyHz uint32    `json:"last_frequency_hz"`
	LastLockAt      time.Time `json:"last_lock_at,omitempty"`
	NAC             uint16    `json:"nac,omitempty"`
}

type CallEnd struct {
	Grant        Grant
	Talkgroup    *TalkGroup
	DeviceSerial string
	StartedAt    time.Time
	EndedAt      time.Time
	Reason       EndReason
}

type CallStart struct {
	Grant        Grant
	Talkgroup    *TalkGroup // resolved via the engine's TalkgroupDB; nil if unknown
	DeviceSerial string     // which Voice SDR is following the call
	StartedAt    time.Time
}

type EndReason uint8

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

type EngineOptions struct {
	Bus        *events.Bus
	Log        *slog.Logger
	VoicePool  *VoicePool
	Talkgroups *TalkgroupDB
	// CallTimeout is how long a call can run without a Touch before the
	// watchdog ends it as EndReasonTimeout. Default 30 s.
	CallTimeout time.Duration
	// Now is injectable for tests; defaults to time.Now.
	Now func() time.Time
	// ScanMode controls whether HandleGrant respects the per-talkgroup
	// Scan flag. Default ScanModeAll keeps every non-locked-out grant
	// flowing through; ScanModeList enforces the talkgroup scan list.
	ScanMode ScanMode
}

type Grant struct {
	System      string // System name, matches trunking.System.Name
	Protocol    string // "p25" / "dmr" / "nxdn"
	GroupID     uint32 // talkgroup or destination subscriber address
	SourceID    uint32 // originator (subscriber unit)
	FrequencyHz uint32 // voice channel frequency
	ChannelID   uint8  // raw channel ID (P25 band-plan ID, DMR LCN high)
	ChannelNum  uint16 // raw channel number within the ID
	Encrypted   bool
	Emergency   bool
	// AlgorithmID and KeyID carry the encryption parameters the
	// protocol's privacy header advertises (the DMR PI header, etc.).
	// They are meaningful only when Encrypted is true and stay zero
	// until a privacy header has been parsed. Persisted to the call
	// log so an operator can see which key a recorded call needs.
	AlgorithmID uint8
	KeyID       uint16
	DataCall    bool // false = voice call (default)
	// ProVoice marks the grant as an EDACS ProVoice (digital) call. The
	// vocoder is patent + trade-secret encumbered so we cannot ship a
	// built-in decoder; the recorder treats this flag as a directive to
	// emit a `.raw` frame sidecar regardless of its global WriteRaw
	// setting, so researchers can decode out-of-band.
	ProVoice bool
	// PatchedGroups, when non-empty, lists the member talkgroups of a
	// patch / dynamic-regroup super-group: the call on GroupID is
	// physically the shared traffic of these groups. The engine fills
	// it from its PatchRegistry so the call can be attributed to every
	// member. Empty for an ordinary (non-patched) grant.
	PatchedGroups []uint32
	At            time.Time
}

type HuntFailed struct {
	System    string    `json:"system"`
	At        time.Time `json:"at"`
	BackoffMs int       `json:"backoff_ms"`
}

type HuntProgress struct {
	System          string    `json:"system"`
	AttemptedFreqHz uint32    `json:"attempted_freq_hz"`
	AttemptIndex    int       `json:"attempt_index"`
	TotalCandidates int       `json:"total_candidates"`
	At              time.Time `json:"at"`
}

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

type HunterOptions struct {
	System System
	Tuner  Tuner
	Bus    *events.Bus
	Cache  *Cache
	Log    *slog.Logger
	// Dwell is how long to wait on each candidate before giving up.
	// Defaults to 3 seconds.
	Dwell time.Duration
}

type LockResult struct {
	System    string
	Frequency uint32
	NAC       uint16
	At        time.Time
}

type LockedPayload interface {
	LockedFrequencyHz() uint32
	LockedNAC() uint16
}

type Patch struct {
	System     string
	Protocol   string
	SuperGroup uint32
	Members    []uint32
	Vendor     string
	Add        bool // true = patch now active, false = patch cancelled
	At         time.Time
}

type PatchGroup struct {
	SuperGroup uint32
	Members    []uint32
	Vendor     string // "motorola" | "harris"
	UpdatedAt  time.Time
}

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

type Protocol uint8

type RegistrationResponse uint8

type ScanMode uint8

type System struct {
	Name            string
	Protocol        Protocol
	ControlChannels []uint32 // candidate CC frequencies in Hz
	WACN            uint32   // 20-bit Wide-Area Communication Network ID (P25)
	SystemID        uint16   // 12-bit system identifier (P25 SYSID)
	RFSS            uint8    // RF SubSystem ID (P25)
	Site            uint8    // Site ID

	// TETRAColourCode is the low 30 bits of the extended colour code
	// the TETRA scrambler uses to seed its LFSR per ETSI EN 300 392-2
	// §8.2.5 ("ec" in the spec). The ccdecoder connector forwards this
	// into tetra.ControlChannel.SetColourCode under ChannelCodingOn.
	// Zero is valid only for BSCH (§8.2.5.2). For all other channel
	// types the colour code is the per-cell secret the descrambler
	// needs to recover the type-3 stream — leaving it at zero with
	// channel coding on produces garbage. Bits 30..31 are silently
	// ignored downstream.
	TETRAColourCode uint32
	// TETRAChannel selects which TETRA logical channel lives in each
	// burst window under ChannelCodingOn. Recognised values:
	// "sch/hd" | "sch/f" | "sch/hu" | "bsch" | "aach" (case-insensitive,
	// "/" optional). Empty defaults to "sch/hd" — the most common
	// signaling carrier for cc.locked / Grant events. Forwarded into
	// tetra.ControlChannel.SetExpectedChannel by the ccdecoder
	// connector after parsing via tetra.ParseChannelType.
	TETRAChannel string
	// TETRAChannelCoding gates the full ETSI EN 300 392-2 §8.3.1
	// channel-coding chain (descramble + deinterleave + depuncture +
	// Viterbi + CRC-16 verify + tail strip). Recognised values
	// (case-insensitive): "" / "on" / "true" / "1" → ChannelCodingOn
	// (the new default; required for live on-air captures); "off" /
	// "false" / "0" → ChannelCodingOff (legacy raw-dibit path, opt-out
	// for operators feeding pre-stripped DSD-FME / OP25 fixtures).
	// Forwarded into tetra.ControlChannel.SetChannelCoding by the
	// ccdecoder connector after parsing via tetra.ParseChannelCoding.
	TETRAChannelCoding string

	// LTRFCSMode enables CRC-7 FCS verification on the LTR Status
	// Ingest path (per DSheirer/sdrtrunk's CRCLTR.java layout).
	// Recognised values (case-insensitive): "" / "on" / "true" / "1" →
	// FCSOn (the new default; drop Status words whose 7-bit FCS
	// trailer doesn't match the CRC over the 24-bit message vector);
	// "off" / "false" / "0" → FCSOff (no verification — opt-out for
	// pre-stripped fixtures). Forwarded into
	// ltr.ControlChannel.SetFCSMode by the ccdecoder connector after
	// parsing via ltr.ParseFCSMode.
	LTRFCSMode string
	// LTRManchesterMode controls Manchester decoding of the LTR
	// sub-audible bit stream. Recognised values (case-insensitive):
	// "" / "on" / "soft" → ManchesterSoft (the new default —
	// majority-decode each pair; matches the dominant on-air
	// encoding for sub-audible LTR signaling); "strict" —
	// require a mid-bit transition per pair, drop transition-less
	// pairs; "off" / "nrz" → ManchesterOff (raw NRZ — opt-out for
	// synthesized NRZ fixtures). Forwarded into
	// ltr.ControlChannel.SetManchesterMode by the ccdecoder
	// connector after parsing via ltr.ParseManchesterMode.
	LTRManchesterMode string

	// P25Phase1DemodMode selects the symbol-recovery path for the
	// P25 Phase 1 receiver. Recognised values (case-insensitive):
	// "" / "c4fm" / "fm" → DemodC4FM (the default — FM
	// discriminator + 4-level slicer; matches every previously
	// shipping config and works on conventional non-simulcast P25
	// transmitters); "cqpsk" / "lsm" / "linear" → DemodCQPSK (the
	// linear / LSM path — complex RRC + Gardner + differential
	// QPSK; required for simulcast P25 deployments whose control
	// channel transmits Linear Simulcast Modulation rather than
	// straight C4FM, see issue #275 and TIA-102.BAAA). Forwarded
	// into p25phase1rx.Options.DemodMode by the ccdecoder connector
	// after parsing via p25phase1rx.ParseDemodMode.
	P25Phase1DemodMode string

	// P25Phase2TrellisMode enables the 4-state ½-rate trellis FEC
	// decoder on the P25 Phase 2 MAC PDU window. Recognised values
	// (case-insensitive): "" / "on" / "true" / "1" → TrellisOn (the
	// new default — 146 channel dibits via the TIA-102.AABF trellis
	// decoder); "off" / "false" / "0" → TrellisOff (legacy 72-dibit
	// raw-MAC-PDU path, opt-out for pre-stripped fixtures). Forwarded
	// into p25phase2.ControlChannel.SetTrellisMode by the ccdecoder
	// connector after parsing via p25phase2.ParseTrellisMode.
	P25Phase2TrellisMode string
	// P25Phase2RSMode enables the outer Reed-Solomon RS(24, 16, 9)
	// verification layer on top of the trellis-decoded MAC PDU.
	// Recognised values (case-insensitive): "" / "off" / "false" /
	// "0" → RSOff (the default — no outer RS verification; matches
	// historical decoder behaviour); "on" / "true" / "1" → RSOn
	// (verify RS syndromes per TIA-102.BAAA-A §5.9; drop MAC PDUs
	// whose syndromes are non-zero before parsing). Forwarded into
	// p25phase2.ControlChannel.SetRSMode by the ccdecoder connector
	// after parsing via p25phase2.ParseRSMode.
	P25Phase2RSMode string
	// P25Phase2InterleaveMode enables the TIA-102.BBAC per-burst block
	// deinterleaver applied to the MAC-burst dibits before trellis
	// decoding. Recognised values (case-insensitive): "" / "off" /
	// "false" / "0" → InterleaveOff (the default); "on" / "true" / "1"
	// → InterleaveOn. Forwarded into p25phase2.ControlChannel.
	// SetInterleaveMode by the ccdecoder connector after parsing via
	// p25phase2.ParseInterleaveMode.
	P25Phase2InterleaveMode string
	// P25Phase2ScramblerMode enables the PN44 descrambler per
	// TIA-102.BBAC-1 §7.2.5 on the trellis-decoded MAC PDU bits.
	// Recognised values (case-insensitive): "" / "off" / "false" /
	// "0" → ScramblerOff (the default — no PN44 descrambling);
	// "on" / "true" / "1" → ScramblerOn. The seed is computed from
	// (WACN, SystemID, low 12 bits of Site as the spec's Color
	// Code = NAC) per spec equation (5). Forwarded into
	// p25phase2.ControlChannel.SetScramblerMode +
	// SetScramblerSeed by the ccdecoder connector.
	P25Phase2ScramblerMode string
	// P25Phase2ClockMode selects the symbol-timing-recovery strategy
	// for the P25 Phase 2 receiver. Recognised values (case-
	// insensitive): "" / "gardner" / "on" → ClockGardner (the new
	// default — non-data-aided Gardner loop; recommended for live
	// SDR captures); "naive" / "off" → ClockNaive (decimate every
	// sps-th sample; works on sample-aligned synthesized IQ).
	// Forwarded into p25phase2rx.Options.ClockMode by the ccdecoder
	// connector after parsing via p25phase2rx.ParseClockMode.
	P25Phase2ClockMode string
	// TETRAClockMode mirrors P25Phase2ClockMode for the TETRA
	// receiver. Same recognised values + parser semantics; the
	// underlying ClockMode enums in the two receivers share the
	// same name + values but are independent types.
	TETRAClockMode string
	// NXDNViterbiMode enables the K=5 ½-rate Viterbi FEC decoder
	// on the NXDN CAC region. Recognised values (case-insensitive):
	// "" / "spec" → ViterbiSpec (the new default — full NXDN-TS-1-A
	// §4.5.1.1 outbound CAC chain); "on" / "true" / "1" → ViterbiOn
	// (intermediate 92-dibit K=5 Viterbi path for older
	// MMDVMHost / DSDcc fixtures); "off" / "false" / "0" → ViterbiOff
	// (legacy 44-dibit raw-CAC path, opt-out for pre-stripped
	// fixtures). Forwarded into nxdn.ControlChannel.SetViterbiMode
	// by the ccdecoder connector after parsing via
	// nxdn.ParseViterbiMode.
	NXDNViterbiMode string
	// NXDNDeviationHz overrides the peak frequency deviation (Hz)
	// the NXDN receiver's slicer is calibrated against. Spec value
	// is 1800 Hz (matches the FM-discriminator output level so live
	// captures slice correctly out of the box). Operators with
	// on-air captures whose dibit distribution is bimodal (outer
	// ±3 dominate, inner ±1 underrepresented) can override here —
	// see samples/nxdn/README.md for the calibration recipe.
	// Forwarded into nxdnrx.Options.DeviationHz by the ccdecoder
	// connector; values <= 0 fall back to the spec default.
	NXDNDeviationHz float64
	// EDACSBCHMode enables the BCH(40, 28, 2) FEC layer on the
	// EDACS CCW. Recognised values (case-insensitive): "" / "on" /
	// "true" / "1" → BCHOn (the new default — 40-bit on-wire
	// BCH(40, 28, 2) decode + single/double-bit correction); "off" /
	// "false" / "0" → BCHOff (legacy pre-stripped 40-bit CCW path,
	// opt-out for pre-stripped fixtures). Forwarded into
	// edacs.ControlChannel.SetBCHMode by the ccdecoder connector
	// after parsing via edacs.ParseBCHMode.
	EDACSBCHMode string
	// MPT1327BCHMode enables the BCH(63, 38) FEC layer on the MPT
	// 1327 codeword. Recognised values (case-insensitive): "" /
	// "on" / "true" / "1" → BCHOn (the new default — 64-bit on-wire
	// BCH(63, 38) decode); "off" / "false" / "0" → BCHOff (legacy
	// 38-bit pre-stripped codeword path, opt-out for pre-stripped
	// fixtures). Forwarded into mpt1327.ControlChannel.SetBCHMode
	// by the ccdecoder connector after parsing via
	// mpt1327.ParseBCHMode.
	MPT1327BCHMode string
	// MPT1327CWSCTolerance sets the Hamming-distance threshold the
	// MPT 1327 Process adapter uses when matching the 16-bit
	// Codeword Synchronisation Code. Recognised values
	// (case-insensitive): "" → 2-bit tolerance (the new default,
	// matches commercial MPT 1327 receivers on noisy on-air
	// captures); "0" / "exact" / "off" → exact match (for
	// pre-stripped synthesized fixtures); a decimal integer in
	// [0, 15]. Forwarded into mpt1327.ControlChannel.SetCWSCTolerance
	// by the ccdecoder connector after parsing via
	// mpt1327.ParseCWSCTolerance.
	MPT1327CWSCTolerance string
	// MotorolaBCHMode enables the BCH(64, 16, 11) FEC layer on the
	// Motorola Type II OSW. Recognised values (case-insensitive):
	// "" / "on" / "true" / "1" → BCHOn (the new default — two
	// 64-bit BCH(64, 16, 11) codewords reassembled into the 32-bit
	// OSW, with up to 11 bit errors corrected per codeword); "off" /
	// "false" / "0" → BCHOff (legacy 32-bit raw-OSW path, opt-out
	// for pre-stripped fixtures). Forwarded into
	// motorola.ControlChannel.SetBCHMode by the ccdecoder
	// connector after parsing via motorola.ParseBCHMode.
	MotorolaBCHMode string
	// DStarFECMode enables the JARL DV-mode header FEC chain on the
	// D-STAR Process adapter. Recognised values (case-insensitive):
	// "" / "off" / "false" / "0" → FECOff (the default — reads 328
	// info bits straight off the wire, matches synthesized fixtures
	// + pre-FEC-stripped inputs); "on" / "true" / "1" → FECOn (660
	// on-wire bits → deinterleave 22×30 → PN15 descramble →
	// depuncture → K=5 R=1/2 Viterbi → 328 info bits → ParseHeader).
	// Forwarded into dstar.ControlChannel.SetFECMode by the
	// ccdecoder connector after parsing via dstar.ParseFECMode.
	DStarFECMode string
}

type TalkGroup struct {
	ID          uint32 `json:"id"`
	AlphaTag    string `json:"alpha_tag"`
	Description string `json:"description,omitempty"`
	Tag         string `json:"tag,omitempty"`      // department / category
	Group       string `json:"group,omitempty"`    // top-level group
	Mode        string `json:"mode,omitempty"`     // D=digital, A=analog, M=mixed
	Priority    int    `json:"priority,omitempty"` // 1 = highest, 10 = lowest, 0 = unset
	Lockout     bool   `json:"lockout,omitempty"`
	Scan        bool   `json:"scan"`
}

type TalkerAlias struct {
	System   string // System name, matches trunking.System.Name
	Protocol string // "p25-phase2"
	SourceID uint32 // radio unit the alias names
	Alias    string // the reassembled display name
	At       time.Time
}

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

type Tuner interface {
	SetCenterFreq(hz uint32) error
}

type UnitRegistration struct {
	System   string               // System name, matches trunking.System.Name
	Protocol string               // "p25" / "dmr" / "nxdn"
	SourceID uint32               // radio unit's WUID
	WACN     uint32               // 20-bit Wide Area Communications Network ID
	SystemID uint16               // 12-bit system identifier
	Response RegistrationResponse // accepted / failed / denied / refused
	At       time.Time
}

type VoiceDevice struct {
	Tuner  Tuner
	Serial string
}

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