gpsprot

type Accuracy struct {
	Pos         opt.Val[Length] `json:"pos,omitzero"`         // 3D position accuracy
	Hor         opt.Val[Length] `json:"hor,omitzero"`         // horizontal position accuracy
	Vert        opt.Val[Length] `json:"vert,omitzero"`        // vertical position accuracy
	Speed       opt.Val[Speed]  `json:"speed,omitzero"`       // 3D speed accuracy
	GroundSpeed opt.Val[Speed]  `json:"groundSpeed,omitzero"` // 2D ground speed accuracy
	Course      opt.Val[Angle]  `json:"course,omitzero"`      // course/heading accuracy
}

type AltChecksumPacketFormat interface {
	PacketFormat
	// ComputeChecksum computes an alternate checksum for the given packet
	// Precondition: the packet must be valid according to Next()
	ComputeAltChecksum(pkt []byte) []byte
}

type Angle int64

type AuxSrc uint8

type Band uint16

type ConfigAction struct {
	Type     ConfigActionType
	Index    int       // Request index for Send actions
	Packet   []byte    // Packet to send for SendRequest action
	Speed    int       // Speed change after send (0 if none)
	Deadline time.Time // Deadline for WaitUntil actions
	Error    error     // Error details for Error action
}

type ConfigActionType int

type ConfigDirector struct {
	ErrorCount int // Number of ConfigActionError actions yielded
	// contains filtered or unexported fields
}

type ConfigOptions struct {
	Socket     bool                  // connected via socket, skip serial detection
	ForceProbe bool                  // force probe even when no config changes needed
	Save       SaveType              // what to save to non-volatile memory
	Reset      ResetType             // what kind of reset to perform
	PVTMsg     PVTMsgFlags           // messages relating to Position, Velocity, and Time
	NMEAMsg    opt.Val[NMEAMsgFlags] `json:",omitzero"`
	RTCMMsg    opt.Val[RTCMMsgFlags] `json:",omitzero"` // RTCM 3.x messages
	SatsMsg    opt.Val[SatsMsgFlags] `json:",omitzero"`
	RawMsg     opt.Val[RawMsgFlags]  `json:",omitzero"`
	Survey     Survey
	SetStatic  bool         // ensure receiver is in static mode without changing existing fixed position
	BaudRate   uint32       // serial port baud rate, 0 means do not change
	TimeAssist TimeEstimate // provide time assistance to the receiver
	OSNMA      OSNMAOptions // options for OSNMA authentication
}

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

type ConfigProtocol interface {
	NativeMsgHandler

	// ProbePacket returns a packet to be sent to the GPS receiver for probing.
	ProbePacket() []byte

	// ProbeOK returns true when a message has been received indicating the GPS receiver is responding.
	ProbeOK() bool

	// Configure creates a Configurator for the given configuration target.
	// The returned Configurator will receive packets via NativeMsg calls on this ConfigProtocol.
	Configure(target *ConfigTarget) (Configurator, error)
}

type ConfigRequest interface {
	// GetPacket returns the packet bytes for this request.
	// Precondition: request state is ConfigRequestReadyToSend, ConfigRequestMayResend, or ConfigRequestFailed
	// The returned packet is ready to transmit to the GPS receiver without modification.
	// For ConfigRequestMayResend and ConfigRequestFailed states, this is useful for error reporting.
	GetPacket() []byte

	// GetSpeedChangeAfter returns the new baud rate to configure after sending this request.
	// Precondition: request state is ConfigRequestReadyToSend, ConfigRequestMayResend, or ConfigRequestFailed
	// Returns 0 if no speed change is required.
	// Speed changes are protocol-specific operations that must be handled by the client
	// after the packet is sent but before waiting for acknowledgment.
	GetSpeedChangeAfter() int

	// GetState returns the current state of this request.
	// This is the primary method for tracking configuration progress.
	GetState() ConfigRequestState

	// GetDeadline returns the absolute time by which response packets are expected.
	// Precondition: request state is ConfigRequestAwaitingResponse, ConfigRequestMaybeComplete, or ConfigRequestPausing
	// The returned time is non-zero and includes monotonic time for accurate timeout comparisons.
	// For ConfigRequestAwaitingResponse: deadline for receiving first/only response (based on SetSentTime timestamp)
	// For ConfigRequestMaybeComplete: deadline for receiving next response in burst (based on last response time + idle period)
	// For ConfigRequestPausing: deadline for when pause completes and GPS receiver is ready for next command
	GetDeadline() time.Time

	// GetError returns the error details for a failed request.
	// Precondition: request state is ConfigRequestFailed
	// Error details may include protocol-specific failure reasons, NACK codes, or timeout information.
	// The caller should use this error for logging, user feedback, or determining recovery strategies.
	GetError() error

	// SetSentTime records when the request packet was transmitted to the GPS receiver.
	// Precondition: request state is ConfigRequestReadyToSend or ConfigRequestMayResend
	// State transitions:
	//   - ConfigRequestReadyToSend → ConfigRequestAwaitingResponse (if response expected)
	//   - ConfigRequestReadyToSend → ConfigRequestSucceeded (if no response expected)
	//   - ConfigRequestMayResend → ConfigRequestAwaitingResponse (retry)
	// The timestamp is used for timeout calculations and protocol timing requirements.
	SetSentTime(tSent time.Time)

	// SetDeadlinePassed notifies that the response deadline has passed.
	// Precondition: request state is ConfigRequestAwaitingResponse, ConfigRequestMaybeComplete, or ConfigRequestPausing
	// State transitions:
	//   - ConfigRequestAwaitingResponse → ConfigRequestMayResend (timeout, can retry)
	//   - ConfigRequestMaybeComplete → ConfigRequestSucceeded (idle period over, no more responses expected)
	//   - ConfigRequestPausing → ConfigRequestSucceeded (pause duration elapsed, ready for next request)
	// The client should call this when GetDeadline() time has passed.
	SetDeadlinePassed()

	// SetWontResend marks a request as permanently failed because the client decides not to retry.
	// Precondition: request state is ConfigRequestMayResend
	// State transitions:
	//   - ConfigRequestMayResend → ConfigRequestFailed
	// This should be called when the client decides not to retry a timed-out request,
	// typically after reaching a maximum retry count.
	SetWontResend()

	// MaybeSpeedChangeSucceeded notifies the request that a valid packet was received at the given time.
	// Precondition: request state is ConfigRequestAwaitingResponse
	// State transitions:
	//   - ConfigRequestAwaitingResponse → ConfigRequestSucceeded (if conditions met)
	// The request will check if it's a speed change awaiting ACK and if sufficient time has passed
	// since sending to treat this as confirmation of success.
	MaybeSpeedChangeSucceeded(validPacketTime time.Time)
}

type ConfigRequestState int

type ConfigTarget struct {
	Props ConfigProps
	Get   PropIDs // Bitmask of properties to retrieve
	Opts  ConfigOptions
}

type Configurator interface {
	// ConfigProps returns the current configuration of the GPS receiver.
	// Should be called after configuration completes to see what was achieved.
	ConfigProps() *ConfigProps

	// ReceiverInfo returns static information about the GPS receiver.
	ReceiverInfo() *ReceiverInfo

	// GenerateRequests attempts to generate more requests, potentially increasing the slice size.
	// This is the only method that can increase the slice size.
	// May also change states of existing requests (see ConfigRequestState documentation).
	// Generation is lazy - it may generate only some requests if later requests depend on earlier results.
	// After successful return, either some request will be actionable or GetRequestCount will return complete=true.
	// Should be called when the client needs more requests than are currently available.
	// Returns an error if request generation fails.
	GenerateRequests() error

	// GetRequestCount returns the current number of requests and whether the slice is complete.
	// When bool is true, the slice count will never increase.
	// When bool is false, the slice count may increase after calling GenerateRequests().
	GetRequestCount() (count int, complete bool)

	// Request returns the ConfigRequest at the given index.
	// Precondition: index < count from GetRequestCount()
	// Panics if index is out of bounds.
	Request(index int) ConfigRequest
}

type CorrKind uint16

type DOP struct {
	Geom opt.Val[float64] `json:"geom,omitzero"` // geometric DOP
	Pos  opt.Val[float64] `json:"pos,omitzero"`  // position (3D) DOP
	Hor  opt.Val[float64] `json:"hor,omitzero"`  // horizontal DOP
	Vert opt.Val[float64] `json:"vert,omitzero"` // vertical DOP
	Time opt.Val[float64] `json:"time,omitzero"` // time DOP
}

type DefaultHandler struct{}

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

type Duration time.Duration

type EpochFlusher interface {
	FlushNavEpoch(tRead time.Time) (*NavEpochMsg, MsgPriority, MsgHandler)
}

type FixLevel uint8

type GNSS uint8

type GNSSSet uint32

type LeapSecondMsg struct {
	ptime.LeapSecond
	GNSS GNSS `json:"gnss,omitempty"` // the GNSS that is the source of this leap second
}

type Length int64

type LookAngles struct {
	Azimuth   int16 `json:"azimuth"`   // in degrees, 0 to 360
	Elevation int8  `json:"elevation"` // in degrees, -
}

type Mode struct {
	Static       bool     // true if receiver should assume antenna position does not move
	PosType      PosType  // which coordinate system to use for fixed position
	FixedPosECEF Point3D  // ECEF coordinates (when PosType == PosTypeECEF)
	FixedPosLLH  [2]Angle // Latitude and Longitude (when PosType == PosTypeLLH)
	Height       Length   // Height (when PosType == PosTypeLLH)
	FixedPosAcc  Length   // accuracy of fixed position
}

type Msg interface {
	Dispatch(MsgHandler, time.Time)
}

type MsgHandler interface {
	Time(msg *TimeMsg, tRead time.Time)
	PosGeo(msg *PosGeoMsg, tRead time.Time)
	PosECEF(msg *PosECEFMsg, tRead time.Time)
	VelGeo(msg *VelGeoMsg, tRead time.Time)
	VelECEF(msg *VelECEFMsg, tRead time.Time)
	LeapSecond(msg *LeapSecondMsg, tRead time.Time)
	Survey(msg *SurveyMsg, tRead time.Time)
	Satellites(msg *SatellitesMsg, tRead time.Time)
	NavEpoch(msg *NavEpochMsg, tRead time.Time)
}

type MsgPriority uint8

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

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

type NMEAMsgFlags uint16

type NMEAPacketProcessor interface {
	PacketProcessor
	// SetSVNumbering sets the satellite numbering scheme for NMEA.
	// The ranges must be non-overlapping and in increasing order of MinID/MaxID.
	SetSVNumbering([]NMEASVNumberingRange)
}

type NMEASVNumberingRange struct {
	MinID    uint16
	MaxID    uint16
	MinNum   uint8
	GNSS     GNSS
	SignalID SignalID
}

type NativeMsgHandler interface {
	// NativeMsg processes a protocol-specific message.
	// tag: identifies the protocol (e.g., UBX, NMEA).
	// msgID: identifies the message type within the protocol (e.g., UBX-NAV-PVT, NMEA-GGA).
	// msg: the protocol-specific message object.
	// tRead: timestamp when the message was received.
	NativeMsg(tag Tag, msgID string, msg any, tRead time.Time) error
}

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

type NavEpochMsg struct {
	// FixLevel is the primary GNSS solution mode, ordered by increasing
	// quality (None < Doppler < Code < CodeCorrected <
	// CarrierFloat < CarrierFixed).
	FixLevel FixLevel `json:"fixLevel,omitzero"`
	// SolutionDim is the dimensionality of the position/time solution
	// (2D, 3D, time-only). Unset when FixLevel < FixLevelCode.
	SolutionDim SolutionDim `json:"solutionDim,omitzero"`
	// Correction is a bitmask of assertions about corrections applied.
	// Meaningful when FixLevel >= FixLevelCodeCorrected.
	Correction CorrKind `json:"correction,omitzero"`
	// AuxSrc is a bitmask of additional sources (DR, INS) that contributed
	// to the solution. GNSS is implicit when FixLevel indicates a fix.
	AuxSrc AuxSrc `json:"auxSrc,omitzero"`
	// Acc holds estimated position, velocity, and course accuracy.
	Acc Accuracy `json:"acc,omitzero"`
	// DOP holds dilution of precision values (GDOP, PDOP, HDOP, VDOP, TDOP).
	DOP DOP `json:"dop,omitzero"`
	// DiffAge is the age of the differential corrections applied to the
	// current solution. Unset when no corrections are in use or the
	// protocol doesn't report it.
	DiffAge opt.Val[Duration] `json:"diffAge,omitzero"`
	// RTCMRefBaseID is the RTCM reference station ID (DF003, 0-4095) of
	// the base station whose corrections are applied to this solution.
	// Distinct from the RTCMBaseID config property, which is this
	// receiver's own base ID for RTCM output.
	RTCMRefBaseID opt.Val[uint16] `json:"rtcmRefBaseID,omitzero"`
	// NumSVUsed is the number of satellites used in the solution.
	NumSVUsed opt.Val[uint16] `json:"numSVUsed,omitzero"`
	// NumSVTracked is the number of satellites tracked by the receiver.
	NumSVTracked opt.Val[uint16] `json:"numSVTracked,omitzero"`
	// NumSVInView is the number of satellites in view of the receiver.
	NumSVInView opt.Val[uint16] `json:"numSVInView,omitzero"`
	// SignalsUsed is the set of GNSS signals used in the solution.
	SignalsUsed SignalSet `json:"signalsUsed,omitzero"`
	// Tag identifies the protocol source (e.g. UBX, NMEA, Unicore).
	Tag Tag `json:"tag,omitzero"`
	// StartTime is when the first message in this epoch was read.
	StartTime time.Time `json:"startTime"`
}

type NavMsgAuth byte

type OSNMAOptions struct {
	MerkleTreeRoot [32]byte // all zeros means not set
}

type PVMsg interface {
	Msg
	SetPriority(MsgPriority)
}

type PVMsgAccum struct {
	DefaultHandler
	PVMsgBundle
}

type PVMsgBundle struct {
	PosGeo  opt.Val[PosGeoMsg]  `json:"posGeo,omitzero"`
	PosECEF opt.Val[PosECEFMsg] `json:"posECEF,omitzero"`
	VelGeo  opt.Val[VelGeoMsg]  `json:"velGeo,omitzero"`
	VelECEF opt.Val[VelECEFMsg] `json:"velECEF,omitzero"`
}

type PVTMsgFlags uint16

type PacketFormat interface {
	// Tag returns the protocol-specific packet kind
	Tag() Tag

	// Next takes the current state, buffer, index, and packet length, and returns the next state
	// buf is the buffer containing the packet data
	// nextScanIndex is the index of the byte to process
	// packetLen is the length of the packet so far, not including the one at nextScanIndex
	Next(state ScanState, buf []byte, nextScanIndex, packetLen int) ScanState

	// IsFinal determines if the given state represents a complete packet
	IsFinal(state ScanState) bool

	// MsgID returns a human readable ID of the packet
	// Precondition: the packet must be valid according to Next()
	MsgID(pkt []byte) string

	// ExtractChecksum extracts the checksum from the packet
	// Precondition: the packet must be valid according to Next()
	ExtractChecksum(pkt []byte) []byte

	// ComputeChecksum computes the checksum for the given packet
	// Precondition: the packet must be valid according to Next()
	ComputeChecksum(pkt []byte) []byte

	// RescanOnBadChecksum determines if the scanner should rescan on a bad checksum
	// starting with the byte after the first byte of the packet with the bad checksum
	// prevPktValid indicates if the previous packet was valid
	RescanOnBadChecksum(prevPktValid bool, pkt []byte) bool
}

type PacketProcessor interface {
	// ProcessPacket processes a packet's data and returns a string with the type of the packet and an error
	ProcessPacket(data string, tRead time.Time) (string, error)

	// No data has been received for a period of time (usually 0.1s).
	// tRead is the end of the period.
	// There is no implication that data is received immediately after this.
	Idle(tRead time.Time)

	// SetMsgHandler sets the handler for protocol-agnostic messages
	SetMsgHandler(handler MsgHandler)

	// SetNativeMsgHandler sets the handler for protocol-specific messages
	SetNativeMsgHandler(handler NativeMsgHandler)

	// GetNativeMsgHandler returns the current protocol message handler
	GetNativeMsgHandler() NativeMsgHandler

	// NativeOnly returns true if this processor only generates native messages
	// and never produces protocol-agnostic messages like TimeMsg or SatellitesMsg.
	// This is typically true for protocols that provide correction data rather
	// than positioning solutions (e.g., RTCM).
	NativeOnly() bool
}

type Point3D [3]Length

type PosECEFMsg struct {
	Pos         Point3D     `json:"pos"` // ECEF X, Y, Z
	Priority    MsgPriority `json:"-"`
	Tag         Tag         `json:"tag"`
	NativeMsgID string      `json:"nativeMsgID"`
}

type PosGeoMsg struct {
	LatLon      [2]Angle        `json:"latLon"`             // [lat, lon]; lat positive north, lon positive east
	Height      opt.Val[Length] `json:"height,omitzero"`    // above WGS-84 ellipsoid
	HeightMSL   opt.Val[Length] `json:"heightMSL,omitzero"` // above mean sea level
	Priority    MsgPriority     `json:"-"`
	Tag         Tag             `json:"tag"`
	NativeMsgID string          `json:"nativeMsgID"`
}

type PosType byte

type PropIDs uint32

type RTCMMsgFlags uint16

type RawMsgFlags uint8

type ReceiverInfo struct {
	Vendor         string      `json:"vendor"`        // receiver vendor (e.g., "u-blox")
	Firmware       string      `json:"firmware"`      // information about firmware; for u-blox, format would be e.g. "TIM 2.20 PROTVER 18.00"
	Hardware       string      `json:"hardware"`      // information about hardware; for u-blox, this is the model (e.g., "ZED-F9T")
	SupportedGNSS  GNSSSet     `json:"supportedGNSS"` // supported GNSS constellations
	VendorSpecific interface{} `json:"-"`             // vendor-specific information, excluded from JSON
}

type ResetType uint8

type SVID struct {
	GNSS GNSS
	// Num is a number identifying the SV within a specific GNSS.
	// Numbering is the same as in RINEX 3.04.
	// For GPS, GAL, BDS, NAVIC, this is the PRN (pseudo-random noise) number.
	// For GLONASS, this is the orbital slot number.
	// For SBAS, this is the PRN number minus 100.
	// For QZSS, this is the PRN number minus 192.
	// This gives two-digit, non-zero numbers.
	// In addition, this can be GLOUnknown, when the GNSS is GLONASS
	Num uint8
}

type SVInfo struct {
	ID         SVID         `json:"id"`
	LookAngles *LookAngles  `json:"lookAngles,omitempty"` // look angle of the satellite
	Signals    []SignalInfo `json:"signals"`              // signals being transmitted by a satellite
	Used       bool         `json:"used,omitempty"`       // true if the satellite is used in the navigation solution
}

type SatelliteUsedValidity int

type SatellitesMsg struct {
	Tag          Tag                   `json:"tag,omitempty"`
	NativeMsgID  string                `json:"nativeMsgID,omitempty"`
	SVs          []SVInfo              `json:"info"`                   // satellites being tracked
	UsedValidity SatelliteUsedValidity `json:"usedValidity,omitempty"` // says whether Used fields in SVInfo and SignalInfo are valid
}

type SatsMsgFlags uint8

type SaveType uint8

type ScanState uint32

type Signal int

type SignalID string

type SignalInfo struct {
	ID   SignalID `json:"id,omitempty"`   // human-readable label of the signal e.g. "L5"
	CN0  uint8    `json:"cn0"`            // C/NO signal to noise ratio
	Used bool     `json:"used,omitempty"` // true if the signal is used in the navigation solution
}

type SignalSet uint64

type SolutionDim uint8

type Speed int64

type Survey struct {
	Flags    SurveyFlags   // control survey behavior
	MinDur   time.Duration // survey should run at least this long
	AccLimit Length        // survey should run until this accuracy is achieved
}

type SurveyFlags int

type SurveyMsg struct {
	Position   Point3D  `json:"position,omitzero"`
	Accuracy   Length   `json:"accuracy"`
	ObsCount   uint32   `json:"obsCount"`
	ObsTime    Duration `json:"obsTime"`
	Valid      bool     `json:"valid"`
	InProgress bool     `json:"inProgress"`
}

type Tag string

type TimeEstimate struct {
	EstimatedTime  time.Time             // the estimated wall-clock time
	TimeOfEstimate time.Time             // the monotonic time at which the estimate was made
	Accuracy       time.Duration         // the accuracy of the estimate
	LeapSecond     ptime.LeapSecondState // leap second information, if known
	Trusted        bool                  // whether the estimate is trusted
}

type TimeMode byte

type TimeModeSet byte

type TimeMsg struct {
	TAITime     ptime.Time     `json:"taiTime,omitempty"`
	UTCTime     *ptime.UTCTime `json:"utcTime,omitempty"`
	Accuracy    time.Duration  `json:"accuracy,omitempty"`
	UTCOffset   uint8          `json:"utcOffset,omitempty"`
	PulseOffset *float64       `json:"pulseOffset,omitempty"` // the true time of the top of second is the time of the pulse plus the PulseOffset
	GNSS        GNSS           `json:"gnss,omitempty"`
	Ref         TimeRef        `json:"ref,omitempty"`
	Tag         Tag            `json:"tag,omitempty"`
	NativeMsgID string         `json:"nativeMsgID,omitempty"`
}

type TimePulse struct {
	Width          time.Duration // width of 0 means disabled
	Period         time.Duration
	AlignToGNSS    bool
	OnlyWhenLocked bool
	PolarityRising bool
}

type TimeRef int

type TimeTicker struct {
	DefaultHandler
	// contains filtered or unexported fields
}

type VelECEFMsg struct {
	Vel         [3]Speed    `json:"vel"` // ECEF VX, VY, VZ
	Priority    MsgPriority `json:"-"`
	Tag         Tag         `json:"tag"`
	NativeMsgID string      `json:"nativeMsgID"`
}

type VelGeoMsg struct {
	VelNED      opt.Val[[3]Speed] `json:"velNED,omitzero"`      // north, east, down
	GroundSpeed opt.Val[Speed]    `json:"groundSpeed,omitzero"` // 2D ground speed
	Speed3D     opt.Val[Speed]    `json:"speed3D,omitzero"`     // 3D speed
	Course      opt.Val[Angle]    `json:"course,omitzero"`      // course over ground, true north
	Priority    MsgPriority       `json:"-"`
	Tag         Tag               `json:"tag"`
	NativeMsgID string            `json:"nativeMsgID"`
}