Frequency tracking

Estimate the frequency of a drifting oscillator from noisy gated measurements. More...

Data Structures
struct	pbl_freq_track_params
	Noise model of an oscillator and its measurements. More...
struct	pbl_freq_track
	Tracker state. More...

Functions
void	pbl_freq_track_init (struct pbl_freq_track *ft, const struct pbl_freq_track_params *params)
	Initialize a tracker with no estimate.
void	pbl_freq_track_seed (struct pbl_freq_track *ft, double hz, double gate_s, uint64_t t_ms)
	Start from a known frequency, e.g.
int	pbl_freq_track_update (struct pbl_freq_track *ft, double hz, double gate_s, uint64_t t_ms)
	Feed a measurement.
double	pbl_freq_track_get (const struct pbl_freq_track *ft)
	Get the estimate.
double	pbl_freq_track_get_dev (const struct pbl_freq_track *ft)
	Get the standard deviation of the estimate.

Detailed Description

Estimate the frequency of a drifting oscillator from noisy gated measurements.

A scalar Kalman filter on the frequency: the state random walks with density rw and each measurement, a gate of T seconds, reads it with white frequency noise wfm / sqrt(T) plus wander, the short-term fluctuation that a gate samples at one instant. All three are fractional, measured for the oscillator at hand. A measurement further than reject_sigma standard deviations from the prediction is dropped, at most max_rejects in a row; then the filter restarts from the next one.

static const struct pbl_freq_track_params s_params = {
  .wfm = 7.2e-6, .wander = 8e-6, .rw = 1.1e-6, .reject_sigma = 5.0, .max_rejects = 3,
};
struct pbl_freq_track ft;
 
pbl_freq_track_init(&ft, &s_params);
pbl_freq_track_update(&ft, measured_hz, gate_s, pbl_uptime_ms());
double hz = pbl_freq_track_get(&ft);

---

Data Structure Documentation

pbl_freq_track_params

struct pbl_freq_track_params

Noise model of an oscillator and its measurements.

Data Fields
uint8_t	max_rejects	Consecutive rejections before restarting.
double	reject_sigma	Rejection threshold, in standard deviations of the innovation.
double	rw	Frequency random walk density, fractional per square root of seconds.
double	wander	Short-term wander a gate samples at one instant, fractional.
double	wfm	White frequency noise, fractional times square root of seconds.

pbl_freq_track

struct pbl_freq_track

Tracker state.

Function Documentation

pbl_freq_track_get()

double pbl_freq_track_get

(

const struct pbl_freq_track *

ft

)

Get the estimate.

Parameters

ft

Tracker.

Returns

Frequency, or 0 before the first measurement or seed.

pbl_freq_track_get_dev()

double pbl_freq_track_get_dev

(

const struct pbl_freq_track *

ft

)

Get the standard deviation of the estimate.

Parameters

ft

Tracker.

Returns

Fractional standard deviation, or 0 before the first measurement or seed.

pbl_freq_track_init()

void pbl_freq_track_init	(	struct pbl_freq_track *	ft,
		const struct pbl_freq_track_params *	params
	)

Initialize a tracker with no estimate.

Parameters

ft	Tracker.
params	Noise model; must stay valid.

pbl_freq_track_seed()

void pbl_freq_track_seed	(	struct pbl_freq_track *	ft,
		double	hz,
		double	gate_s,
		uint64_t	t_ms
	)

Start from a known frequency, e.g.

one kept across a reset.

Parameters

ft	Tracker.
hz	Frequency.
gate_s	Gate length the frequency is as good as, in seconds.
t_ms	Current time, in milliseconds.

pbl_freq_track_update()

int pbl_freq_track_update	(	struct pbl_freq_track *	ft,
		double	hz,
		double	gate_s,
		uint64_t	t_ms
	)

Feed a measurement.

Parameters

ft	Tracker.
hz	Measured frequency.
gate_s	Gate length, in seconds.
t_ms	Time of the measurement, in milliseconds, not before the previous one.

Returns

0 if used, -ERANGE if rejected.