GNU Radio C++ API Reference: gr::blocks::control_loop Class Reference

| GNU Radio C++ API Reference 3.10.12.0 The Free & Open Software Radio Ecosystem |

Loading...
Searching...
No Matches
gr::blocks::control_loop Class Reference

A second-order control loop implementation class. More...

`#include <gnuradio/blocks/control_loop.h>`

## Public Member Functions
| control_loop (void)
| control_loop (float loop_bw, float max_freq, float min_freq)
virtual | ~control_loop ()
void | update_gains ()
| Update the system gains from the loop bandwidth and damping factor.
void | advance_loop (float error)
| Advance the control loop based on the current gain settings and the inputted error signal.
void | phase_wrap ()
| Keep the phase between -2pi and 2pi.
void | frequency_limit ()
| Keep the frequency between d_min_freq and d_max_freq.
virtual void | set_loop_bandwidth (float bw)
| Set the loop bandwidth.
void | set_damping_factor (float df)
| Set the loop damping factor.
void | set_alpha (float alpha)
| Set the loop gain alpha.
void | set_beta (float beta)
| Set the loop gain beta.
void | set_frequency (float freq)
| Set the control loop's frequency.
void | set_phase (float phase)
| Set the control loop's phase.
void | set_max_freq (float freq)
| Set the control loop's maximum frequency.
void | set_min_freq (float freq)
| Set the control loop's minimum frequency.
float | get_loop_bandwidth () const
| Returns the loop bandwidth.
float | get_damping_factor () const
| Returns the loop damping factor.
float | get_alpha () const
| Returns the loop gain alpha.
float | get_beta () const
| Returns the loop gain beta.
float | get_frequency () const
| Get the control loop's frequency estimate.
float | get_phase () const
| Get the control loop's phase estimate.
float | get_max_freq () const
| Get the control loop's maximum frequency.
float | get_min_freq () const
| Get the control loop's minimum frequency.

## Protected Attributes
float | d_phase
float | d_freq
float | d_max_freq
float | d_min_freq
float | d_damping
float | d_loop_bw
float | d_alpha
float | d_beta

## Detailed Description

A second-order control loop implementation class.

This class implements a second order control loop and is intended to act as a parent class to blocks which need a control loop (e.g., gr::digital::costas_loop_cc, gr::analog::pll_refout_cc, etc.). It takes in a loop bandwidth as well as a max and min frequency and provides the functions that control the update of the loop.

The loop works of alpha and beta gains. These gains are calculated using the input loop bandwidth and a pre-set damping factor. The damping factor can be changed using the set_damping_factor after the block is constructed. The alpha and beta values can be set using their respective set_alpha or set_beta functions if very precise control over these is required.

The class tracks both phase and frequency of a signal based on an error signal. The error calculation is unique for each algorithm and is calculated externally and passed to the advance_loop function, which uses this to update its phase and frequency estimates.

This class also provides the functions phase_wrap and frequency_limit to easily keep the phase and frequency estimates within our set bounds (phase_wrap keeps it within +/-2pi).

## Constructor & Destructor Documentation

## ◆ control_loop() [1/2]

gr::blocks::control_loop::control_loop | ( | void |  | ) |
| inline

## ◆ control_loop() [2/2]

gr::blocks::control_loop::control_loop | ( | float | loop_bw,
|  | float | max_freq,
|  | float | min_freq )

## ◆ ~control_loop()

virtual gr::blocks::control_loop::~control_loop | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ advance_loop()

void gr::blocks::control_loop::advance_loop | ( | float | error | ) |
| inline

Advance the control loop based on the current gain settings and the inputted error signal.

References d_alpha, d_beta, d_freq, and d_phase.

## ◆ frequency_limit()

void gr::blocks::control_loop::frequency_limit | ( |  | ) |
| inline

Keep the frequency between d_min_freq and d_max_freq.

This function keeps the frequency between d_min_freq and d_max_freq. If the frequency is greater than d_max_freq, it is set to d_max_freq. If the frequency is less than d_min_freq, it is set to d_min_freq.

This function should be called after advance_loop to keep the frequency in the specified region. It is set as a separate method in case another way is desired as this is fairly heavy-handed.

References d_freq, d_max_freq, and d_min_freq.

## ◆ get_alpha()

float gr::blocks::control_loop::get_alpha | ( |  | ) | const

Returns the loop gain alpha.

## ◆ get_beta()

float gr::blocks::control_loop::get_beta | ( |  | ) | const

Returns the loop gain beta.

## ◆ get_damping_factor()

float gr::blocks::control_loop::get_damping_factor | ( |  | ) | const

Returns the loop damping factor.

## ◆ get_frequency()

float gr::blocks::control_loop::get_frequency | ( |  | ) | const

Get the control loop's frequency estimate.

## ◆ get_loop_bandwidth()

float gr::blocks::control_loop::get_loop_bandwidth | ( |  | ) | const

Returns the loop bandwidth.

## ◆ get_max_freq()

float gr::blocks::control_loop::get_max_freq | ( |  | ) | const

Get the control loop's maximum frequency.

## ◆ get_min_freq()

float gr::blocks::control_loop::get_min_freq | ( |  | ) | const

Get the control loop's minimum frequency.

## ◆ get_phase()

float gr::blocks::control_loop::get_phase | ( |  | ) | const

Get the control loop's phase estimate.

## ◆ phase_wrap()

void gr::blocks::control_loop::phase_wrap | ( |  | ) |
| inline

Keep the phase between -2pi and 2pi.

This function keeps the phase between -2pi and 2pi. If the phase is greater than 2pi by d, it wraps around to be -2pi+d; similarly if it is less than -2pi by d, it wraps around to 2pi-d.

This function should be called after advance_loop to keep the phase in a good operating region. It is set as a separate method in case another way is desired as this is fairly heavy-handed.

References d_phase, and GR_M_PI.

## ◆ set_alpha()

void gr::blocks::control_loop::set_alpha | ( | float | alpha | ) |

Set the loop gain alpha.

Sets the loop filter's alpha gain parameter.

This value should really only be set by adjusting the loop bandwidth and damping factor.

Parameters

  alpha | (float) new alpha gain

## ◆ set_beta()

void gr::blocks::control_loop::set_beta | ( | float | beta | ) |

Set the loop gain beta.

Sets the loop filter's beta gain parameter.

This value should really only be set by adjusting the loop bandwidth and damping factor.

Parameters

  beta | (float) new beta gain

## ◆ set_damping_factor()

void gr::blocks::control_loop::set_damping_factor | ( | float | df | ) |

Set the loop damping factor.

Set the loop filter's damping factor to `df`. The damping factor should be sqrt(2)/2.0 for critically damped systems. Set it to anything else only if you know what you are doing. It must be a number between 0 and 1.

When a new damping factor is set, the gains, alpha and beta, of the loop are recalculated by a call to update_gains().

Parameters

  df | (float) new damping factor

## ◆ set_frequency()

void gr::blocks::control_loop::set_frequency | ( | float | freq | ) |

Set the control loop's frequency.

Sets the control loop's frequency. While this is normally updated by the inner loop of the algorithm, it could be useful to manually initialize, set, or reset this under certain circumstances.

Parameters

  freq | (float) new frequency

## ◆ set_loop_bandwidth()

virtual void gr::blocks::control_loop::set_loop_bandwidth | ( | float | bw | ) |
| virtual

Set the loop bandwidth.

Set the loop filter's bandwidth to `bw`. This should be between 2*pi/200 and 2*pi/100 (in rads/samp). It must also be a positive number.

When a new damping factor is set, the gains, alpha and beta, of the loop are recalculated by a call to update_gains().

Parameters

  bw | (float) new bandwidth

## ◆ set_max_freq()

void gr::blocks::control_loop::set_max_freq | ( | float | freq | ) |

Set the control loop's maximum frequency.

Set the maximum frequency the control loop can track.

Parameters

  freq | (float) new max frequency

## ◆ set_min_freq()

void gr::blocks::control_loop::set_min_freq | ( | float | freq | ) |

Set the control loop's minimum frequency.

Set the minimum frequency the control loop can track.

Parameters

  freq | (float) new min frequency

## ◆ set_phase()

void gr::blocks::control_loop::set_phase | ( | float | phase | ) |

Set the control loop's phase.

Sets the control loop's phase. While this is normally updated by the inner loop of the algorithm, it could be useful to manually initialize, set, or reset this under certain circumstances.

Parameters

  phase | (float) new phase

## ◆ update_gains()

void gr::blocks::control_loop::update_gains | ( |  | ) |

Update the system gains from the loop bandwidth and damping factor.

This function updates the system gains based on the loop bandwidth and damping factor of the system. These two factors can be set separately through their own set functions.

## Member Data Documentation

## ◆ d_alpha

float gr::blocks::control_loop::d_alpha
| protected

Referenced by advance_loop().

## ◆ d_beta

float gr::blocks::control_loop::d_beta
| protected

Referenced by advance_loop().

## ◆ d_damping

float gr::blocks::control_loop::d_damping
| protected

## ◆ d_freq

float gr::blocks::control_loop::d_freq
| protected

Referenced by advance_loop(), and frequency_limit().

## ◆ d_loop_bw

float gr::blocks::control_loop::d_loop_bw
| protected

## ◆ d_max_freq

float gr::blocks::control_loop::d_max_freq
| protected

Referenced by frequency_limit().

## ◆ d_min_freq

float gr::blocks::control_loop::d_min_freq
| protected

Referenced by frequency_limit().

## ◆ d_phase

float gr::blocks::control_loop::d_phase
| protected

Referenced by advance_loop(), and phase_wrap().

The documentation for this class was generated from the following file:

- control_loop.h