changetracker

type ByteMaskDiff ¶

type ByteMaskDiff struct{}

ByteMaskDiff is the default diff method. Any byte-level change is significant.

Short format (packets <= 8 bytes):

[mask:1] [changed bytes...]

Extended format (packets > 8 bytes):

[maskLen:2 LE] [mask bytes...] [changed bytes...]

func (ByteMaskDiff) Apply(prev, diff []byte) []byte

func (ByteMaskDiff) Diff(prev, curr []byte) (bool, []byte)

type ChangeEvent ¶

type ChangeEvent struct {
	Type      ChangeEventType
	Timestamp time.Time
	Source    uint8
	PGN       uint32
	SubKey    uint64
	Seq       uint64
	Data      []byte // Full data for Snapshot, diff for Delta, nil for Idle.
}

ChangeEvent is emitted by the ChangeTracker when a meaningful state change (or silence) is detected for a (source, PGN, subkey) tracking key.

type ChangeEventType ¶

type ChangeEventType uint8

ChangeEventType identifies the kind of change event.

const (
	// Snapshot is the first observation for a key. Contains full packet data.
	Snapshot ChangeEventType = 1
	// Delta means a significant change was detected. Contains a compact diff.
	Delta ChangeEventType = 2
	// Idle means a source stopped producing for this key.
	Idle ChangeEventType = 3
)

func (t ChangeEventType) String() string

type ChangeReplayer ¶

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

ChangeReplayer reconstructs full packet data from a stream of ChangeEvents. Maintains per-key state and applies diffs to recover the original packets.

func NewChangeReplayer(methods map[uint32]DiffMethod, subKeys map[uint32]SubKeyFunc) *ChangeReplayer

func (r *ChangeReplayer) Apply(event ChangeEvent) ([]byte, error)

func (r *ChangeReplayer) State(source uint8, pgnID uint32, subKey uint64) []byte

type ChangeTracker ¶

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

ChangeTracker tracks per-(source, PGN, subkey) state and emits compact change events. Not goroutine-safe; designed for single-goroutine callers (like the broker's handleFrame).

func NewChangeTracker(cfg Config) *ChangeTracker

func (ct *ChangeTracker) Process(ts time.Time, source uint8, pgnID uint32, data []byte, seq uint64) *ChangeEvent

func (ct *ChangeTracker) Remove(source uint8, pgnID uint32, subKey uint64)

func (ct *ChangeTracker) Reset()

func (ct *ChangeTracker) Tick(now time.Time) []ChangeEvent

func (ct *ChangeTracker) TrackedPairs() int

type Config ¶

type Config struct {
	// DefaultMethod is the diff method used for PGNs without a specific override.
	// Nil defaults to ByteMaskDiff.
	DefaultMethod DiffMethod

	// Methods maps specific PGNs to custom diff methods.
	Methods map[uint32]DiffMethod

	// SubKeys maps specific PGNs to sub-key extractor functions for
	// multiplexed PGNs (e.g., Victron registers on PGN 61184).
	SubKeys map[uint32]SubKeyFunc

	// DefaultIdleTimeout is the fallback idle timeout when no PGN-specific
	// timeout can be resolved. Defaults to 5s.
	DefaultIdleTimeout time.Duration

	// IdleMultiplier is applied to the PGN registry interval to compute
	// the idle timeout. Defaults to 3.
	IdleMultiplier int

	// IdleTimeouts maps specific PGNs to explicit idle timeout overrides.
	IdleTimeouts map[uint32]time.Duration
}

Config configures the ChangeTracker.

type DiffMethod ¶

type DiffMethod interface {
	// Diff compares prev and curr, returning whether the change is significant
	// and a compact diff encoding. If not significant, diff is nil.
	Diff(prev, curr []byte) (significant bool, diff []byte)

	// Apply reconstructs curr from prev and a diff produced by Diff.
	Apply(prev, diff []byte) []byte
}

DiffMethod computes and applies compact binary diffs between packet payloads.

type FieldTolerance ¶

type FieldTolerance struct {
	Field     string
	Tolerance float64
}

FieldTolerance defines a tolerance threshold for a named field. Changes within the tolerance are suppressed (not emitted as significant).

type FieldToleranceDiff ¶

type FieldToleranceDiff struct {
	Inner      DiffMethod
	PGN        uint32
	Decode     func([]byte) (any, error)
	Tolerances []FieldTolerance
}

FieldToleranceDiff wraps an inner DiffMethod and uses PGN decode functions plus reflection to check field-level tolerances. If all changed fields are within their tolerance, the change is suppressed. The encoding is always delegated to the inner method (tolerances only gate significance).

The baseline is NOT updated when a change is suppressed, preventing tolerance drift over time.

func (f *FieldToleranceDiff) Apply(prev, diff []byte) []byte

func (f *FieldToleranceDiff) Diff(prev, curr []byte) (bool, []byte)

type SubKeyFunc ¶

type SubKeyFunc func(data []byte) uint64

SubKeyFunc extracts a sub-discriminator from raw packet data for multiplexed PGNs. Returns 0 for non-multiplexed PGNs (i.e., no sub-key extractor configured).