GNU Radio's DVBS2RX Package
gr::dvbs2rx::freq_sync Class Reference

Frequency Synchronizer. More...

#include <pl_freq_sync.h>

Inheritance diagram for gr::dvbs2rx::freq_sync:

Public Member Functions

 freq_sync (unsigned int period, int debug_level)
 Construct the frequency synchronizer object.
 
bool estimate_coarse (const gr_complex *in, bool full, uint8_t plsc=0)
 Data-aided coarse frequency offset estimation.
 
float estimate_sof_phase (const gr_complex *in)
 Estimate the average phase of the SOF.
 
float estimate_plheader_phase (const gr_complex *in, uint8_t plsc)
 Estimate the average phase of the PLHEADER.
 
float estimate_pilot_phase (const gr_complex *in, int i_blk)
 Estimate the average phase of a pilot block.
 
void estimate_fine_pilot_mode (const gr_complex *p_plheader, const gr_complex *p_payload, uint8_t n_pilot_blks, uint8_t plsc)
 Pilot-aided fine frequency offset estimation.
 
bool estimate_fine_pilotless_mode (float curr_plheader_phase, float next_plheader_phase, uint16_t curr_plframe_len, double curr_coarse_foffset)
 Pilotless fine frequency offset estimation.
 
void derotate_plheader (const gr_complex *in, bool open_loop=false)
 De-rotate PLHEADER symbols.
 
float get_plheader_phase ()
 Get the last PLHEADER phase estimate.
 
float get_pilot_phase (int i_blk)
 Get the phase estimate corresponding to a pilot block.
 
double get_coarse_foffset ()
 Get the last coarse frequency offset estimate.
 
double get_fine_foffset ()
 Get the last fine frequency offset estimate.
 
bool is_coarse_corrected ()
 Check whether the coarse frequency correction has been achieved.
 
bool has_fine_foffset_est ()
 Check whether a fine frequency offset estimate is available already.
 
const gr_complex * get_plheader ()
 Get the post-processed/de-rotated PLHEADER kept internally.
 
- Public Member Functions inherited from gr::dvbs2rx::pl_submodule
 pl_submodule (const std::string name, int debug_level)
 Verbose logger.
 

Additional Inherited Members

- Protected Attributes inherited from gr::dvbs2rx::pl_submodule
gr::logger_ptr d_logger
 Debug level.
 

Detailed Description

Frequency Synchronizer.

Provides methods to estimate the coarse and fine frequency offsets disturbing DVB-S2 frames, as well as methods to estimate the phases of various frame segments (SOF, PLHEADER, and pilot blocks). These methods are meant to be used in conjunction with an external frequency correction (or de-rotator/rotator) block. This class supplies the frequency offset estimates, while the external block applies the corrections, an operation denominated "closed-loop mode". In other words, this class is not responsible for frequency offset correction. Instead, it focuses on estimation only.

Due to the closed-loop operation, when estimating the phases of the SOF, PLHEADER, and pilot blocks, this class assumes the symbols are not rotating. This assumption holds closely as soon as the external rotator block converges to an accurate frequency correction. Thus, the phase estimates are obtained by assuming the symbols are only disturbed by white Gaussian noise. The only exception is on the derotate_plheader() method, which offers an "open-loop" option, documented there.

Once the frequency offset estimates are accurate enough, the external derotator block applies accurate corrections and the frequency offset observed by this block becomes sufficiently low. Moreover, once the normalized frequency offset magnitude falls below 3.268e-4, this class infers the system is already "coarse-corrected", and the corresponding state can be fetched through the is_coarse_corrected() method. At this point, it makes sense to start computing the fine frequency offset estimate. Before that, the fine frequency offset estimates are not reliable.

Once a fine frequency offset becomes available, this class returns true on method has_fine_foffset_est(). As of this version, a fine offset can be computed whenever the processed DVB-S2 frames contain pilot blocks and the system is already coarse-corrected. The estimate is based on the independent phases of each pilot block composing the frame, and is obtained by calling method estimate_fine_pilot_mode().

In contrast, the coarse frequency offset can be computed regardless of the presence of pilots. Also, unlike the fine frequency offset estimation, which is computed and refreshed on every frame, the coarse estimation is based on several consecutive frames. The number of frames considered in the computation is determined by the period parameter provided to the constructor.

In any case, the most recent coarse and fine frequency offset estimates can be fetched independently through the get_coarse_foffset() and get_fine_foffset() methods.

Constructor & Destructor Documentation

◆ freq_sync()

gr::dvbs2rx::freq_sync::freq_sync ( unsigned int period,
int debug_level )

Construct the frequency synchronizer object.

Parameters
periodInterval in PLFRAMEs between coarse frequency offset estimations.
debug_levelDebugging log level (0 disables logs).

Member Function Documentation

◆ derotate_plheader()

void gr::dvbs2rx::freq_sync::derotate_plheader ( const gr_complex * in,
bool open_loop = false )

De-rotate PLHEADER symbols.

Parameters
in(const gr_complex *) Input rotated PLHEADER buffer.
open_loop(bool) Whether to assume this block is running in open loop, without an external frequency correction block. In this case, it is assumed the most recent frequency offset estimate is still uncorrected and disturbing the input PLHEADER, so this method attempts to compensate for this frequency offset when derotating the PLHEADER.
Note
The de-rotated PLHEADER is saved internally and can be accessed using the get_plheader() method.
The open-loop option is useful when there is too much uncertainty about the the frequency offset estimate, for example while still searching for a DVB-S2 signal. By running derotate_plheader() in open loop, only the PLHEADER will be derotated based on the internal frequency offset estimate, with no need to send the estimate to an external rotator block. At a minimum, if this derotation is successful, it can be determinant for a successful PLSC decoding, which then leads to frame locking. After that, the caller can be more certain about the frequency offset estimates being valid and switch to the usual closed-loop operation, while sending the frequency offset estimates to the external rotator block.

◆ estimate_coarse()

bool gr::dvbs2rx::freq_sync::estimate_coarse ( const gr_complex * in,
bool full,
uint8_t plsc = 0 )

Data-aided coarse frequency offset estimation.

The implementation accumulates period frames before outputting an estimate, where period comes from the parameter provided to the constructor.

Parameters
in(gr_complex *) Pointer to the start of frame.
full(bool) Whether to use the full PLHEADER for the estimation. When set to false, only the SOF symbols are used. Otherwise, the full PLHEADER is used and the PLSC dataword must be indicated so that the correct PLHEADER sequence is used by the data-aided estimator.
plsc(uint8_t) PLSC corresponding to the PLHEADER being processed. Must be within the range from 0 to 127. It is ignored if full=false.
Returns
(bool) Whether a new estimate was computed in this iteration.
Note
The coarse frequency offset estimate is kept internally. It can be fetched using the get_coarse_foffset() method.

◆ estimate_fine_pilot_mode()

void gr::dvbs2rx::freq_sync::estimate_fine_pilot_mode ( const gr_complex * p_plheader,
const gr_complex * p_payload,
uint8_t n_pilot_blks,
uint8_t plsc )

Pilot-aided fine frequency offset estimation.

Should be executed only for PLFRAMEs containing pilot symbols, and after the coarse correction is sufficiently accurate (after reaching the coarse-corrected state).

Parameters
p_plheader(const gr_complex*) Pointer to the frame's PLHEADER.
p_payload(const gr_complex*) Pointer to the descrambled PLFRAME payload.
n_pilot_blks(uint8_t) Number of pilot blocks in the PLFRAME being processed.
plsc(uint8_t) PLSC corresponding to the PLHEADER being processed. Must be within the range from 0 to 127.
Note
The fine frequency offset estimate is kept internally. It can be fetched using the get_fine_foffset() method.
The payload pointed by p_payload must be descrambled. This function assumes the pilot symbols on this array are descrambled already.

◆ estimate_fine_pilotless_mode()

bool gr::dvbs2rx::freq_sync::estimate_fine_pilotless_mode ( float curr_plheader_phase,
float next_plheader_phase,
uint16_t curr_plframe_len,
double curr_coarse_foffset )

Pilotless fine frequency offset estimation.

Works for any PLFRAME, but should only be called for PLFRAMEs without pilots. For frames containing pilot symbols, the pilot-mode estimator should be preferred.

Parameters
curr_plheader_phase(float) Phase of the current PLHEADER.
next_plheader_phase(float) Phase of the next PLHEADER.
curr_plframe_len(uint16_t) Length of the current PLFRAME.
curr_coarse_foffset(double) Coarse frequency offset over the current frame.
Returns
(bool) Whether a new estimate was computed during this call.
Note
The fine frequency offset estimate is kept internally. It can be fetched using the get_fine_foffset() method.
This function can only compute a new fine frequency offset estimate if the residual coarse frequency offset lies within an acceptable range. Otherwise, it returns early and does not produce a new estimate. Hence, before accessing the estimate, check the result returned by the has_fine_foffset_est() method.
Even though this class stores the most recent coarse frequency offset estimate as an attribute, the coarse offset that matters is the one affecting the current PLFRAME. This important distinction arises when the current payload is only processed after handling the subsequent PLHEADER (whose phase is next_plheader_phase), as is the case on the PL Sync logic. In this scenario, by the time this function is called, the coarse estimate held internally may already be that of the subsequent PLHEADER. Hence, to avoid confusion, the coarse offset distubing the current frame must be provided by argument.

◆ estimate_pilot_phase()

float gr::dvbs2rx::freq_sync::estimate_pilot_phase ( const gr_complex * in,
int i_blk )

Estimate the average phase of a pilot block.

Parameters
in(gr_complex *) Pointer to the pilot symbol array.
i_blk(int) Index of this pilot block within the PLFRAME
Returns
(float) The phase estimate within -pi to +pi.

◆ estimate_plheader_phase()

float gr::dvbs2rx::freq_sync::estimate_plheader_phase ( const gr_complex * in,
uint8_t plsc )

Estimate the average phase of the PLHEADER.

Parameters
in(gr_complex *) Pointer to the PLHEADER symbol array.
plsc(uint8_t) PLSC corresponding to the PLHEADER being processed. Must be within the range from 0 to 127.
Returns
(float) The phase estimate within -pi to +pi.
Note
plsc indicates the expected PLHEADER symbols so that the phase estimation can be fully data-aided.

◆ estimate_sof_phase()

float gr::dvbs2rx::freq_sync::estimate_sof_phase ( const gr_complex * in)

Estimate the average phase of the SOF.

Parameters
in(gr_complex *) Pointer to the SOF symbol array.
Returns
(float) The phase estimate in radians within -pi to +pi.

◆ get_coarse_foffset()

double gr::dvbs2rx::freq_sync::get_coarse_foffset ( )
inline

Get the last coarse frequency offset estimate.

The estimate is kept internally after a call to the estimate_coarse() method.

Returns
(double) Last normalized coarse frequency offset estimate.

◆ get_fine_foffset()

double gr::dvbs2rx::freq_sync::get_fine_foffset ( )
inline

Get the last fine frequency offset estimate.

The estimate is kept internally after a call to the estimate_fine_pilot_mode() method.

Returns
(double) Last normalized fine frequency offset estimate.

◆ get_pilot_phase()

float gr::dvbs2rx::freq_sync::get_pilot_phase ( int i_blk)
inline

Get the phase estimate corresponding to a pilot block.

This phase estimate becomes available only after calling estimate_fine_pilot_mode(). Otherwise, it's undefined.

Parameters
i_blk(int) Pilot block index from 0 up to 21.
Returns
(float) Phase estimate in radians within -pi to +pi.

◆ get_plheader()

const gr_complex * gr::dvbs2rx::freq_sync::get_plheader ( )
inline

Get the post-processed/de-rotated PLHEADER kept internally.

A de-rotated version of the PLHEADER is stored internally after a call to the derotate_plheader() method.

Returns
(const gr_complex*) Pointer to the de-rotated PLHEADER.

◆ get_plheader_phase()

float gr::dvbs2rx::freq_sync::get_plheader_phase ( )
inline

Get the last PLHEADER phase estimate.

The estimate is kept internally after a call to the estimate_plheader_phase() method.

Returns
(float) Last PLHEADER phase estimate in radians within -pi to +pi.

◆ has_fine_foffset_est()

bool gr::dvbs2rx::freq_sync::has_fine_foffset_est ( )
inline

Check whether a fine frequency offset estimate is available already.

An estimate becomes available internally after a call to the estimate_fine_pilot_mode() method.

Returns
(bool) True when a fine frequency offset estimate is available.

◆ is_coarse_corrected()

bool gr::dvbs2rx::freq_sync::is_coarse_corrected ( )
inline

Check whether the coarse frequency correction has been achieved.

The coarse corrected state is considered achieved when the coarse frequency offset estimate falls within the fine frequency offset estimation range.

Returns
(bool) Coarse corrected state.

Referenced by gr::dvbs2rx::plsync_cc_impl::get_coarse_freq_corr_state().


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