class mrpt::system::CControlledRateTimer

Overview

A class for calling sleep() in a loop, such that the amount of sleep time will be computed to make the loop run at the desired rate (in Hz).

This class implements a PI controller on top of a vanilla CRateTimer object, ensuring a high accuracy in achieved execution rates. Note that this is done by setting a slightly-higher rate (“control action”) to the internal CRateTimer, such that the error between the user-provided expected rate and the actual measured rate (low-pass filtered) is decreased by means of a PI controller.

Note that rates higher than a few kHz are not attainable in all CPUs and/or kernel versions. Find below some graphs illustrating how this class tries to achieve a constant setpoint rate (given by the user), reacting to changes in the setpoint values:

This graphs is generated with the example:

system_control_rate_timer_example --rate1 2000.0 --rate2 4000.0

All the parameters for the PI controller and low-pass filter (rate estimator) are settable by the user to adapt them to specific needs.

Control law by Francisco Jose Mañas Alvarez

[New in MRPT 2.0.4]

#include <mrpt/system/CControlledRateTimer.h>

class CControlledRateTimer: public mrpt::system::COutputLogger
{
public:
    // construction

    CControlledRateTimer(const double rate_hz = 1.0);
    CControlledRateTimer(const CControlledRateTimer&);
    CControlledRateTimer(CControlledRateTimer&&);

    // methods

    CControlledRateTimer& operator = (const CControlledRateTimer&);
    CControlledRateTimer& operator = (CControlledRateTimer&&);
    void setRate(const double rate_hz);
    bool sleep();
    double controllerParam_Kp() const;
    void controllerParam_Kp(double v);
    double controllerParam_Ti() const;
    void controllerParam_Ti(double v);
    double lowPassParam_a0() const;
    void lowPassParam_a0(double v);
    double followErrorRatioToRaiseWarning() const;
    void followErrorRatioToRaiseWarning(double v);
    double actualControlledRate() const;
    double estimatedRate() const;
    double estimatedRateRaw() const;
};

Inherited Members

public:
    // structs

    struct TMsg;

    // fields

    bool logging_enable_console_output {true};
    bool logging_enable_keep_record {false};

    // methods

    void logStr(const VerbosityLevel level, std::string_view msg_str) const;
    void logFmt(const VerbosityLevel level, const char* fmt, ...) const;
    void void logCond(const VerbosityLevel level, bool cond, const std::string& msg_str) const;
    void setLoggerName(const std::string& name);
    std::string getLoggerName() const;
    void setVerbosityLevel(const VerbosityLevel level);
    void setVerbosityLevelForCallbacks(const VerbosityLevel level);
    void setMinLoggingLevel(const VerbosityLevel level);
    VerbosityLevel getMinLoggingLevel() const;
    VerbosityLevel getMinLoggingLevelForCallbacks() const;
    bool isLoggingLevelVisible(VerbosityLevel level) const;
    void getLogAsString(std::string& log_contents) const;
    std::string getLogAsString() const;
    void writeLogToFile(const std::optional<std::string>& fname_in = std::nullopt) const;
    void dumpLogToConsole() const;
    std::string getLoggerLastMsg() const;
    void getLoggerLastMsg(std::string& msg_str) const;
    void loggerReset();
    void logRegisterCallback(output_logger_callback_t userFunc);
    bool logDeregisterCallback(output_logger_callback_t userFunc);
    COutputLogger& operator = (const COutputLogger&);
    COutputLogger& operator = (COutputLogger&&);
    static std::array<mrpt::system::ConsoleForegroundColor, NUMBER_OF_VERBOSITY_LEVELS>& logging_levels_to_colors();
    static const std::array<const char*, NUMBER_OF_VERBOSITY_LEVELS>& logging_levels_to_names();

Construction

CControlledRateTimer(const double rate_hz = 1.0)

Ctor: specifies the desired rate (Hz)

Methods

void setRate(const double rate_hz)

Changes the object loop rate (Hz)

bool sleep()

Sleeps for some time, such as the return of this method is 1/rate (seconds) after the return of the previous call.

Returns:

false if the rate could not be achieved (“we are already late”), true if all went right.

double controllerParam_Kp() const

PI controller Kp parameter [default=1.0].

double controllerParam_Ti() const

PI controller Ti parameter [default=0.1].

double lowPassParam_a0() const

Low-pass filter a0 value [default=0.99]: estimation = a0*former_estimation + (1-a0)*input so larger values of a0 mean heavier smoothing of the measured rate.

double followErrorRatioToRaiseWarning() const

Get/set ratio threshold for issuing a warning (via COutputLogger interface) if the achieved rate is not this close to the set-point [Default=0.2, =20%].

double actualControlledRate() const

Gets the actual controller output: the rate (Hz) of the internal CRateTimer object.

double estimatedRate() const

Gets the latest estimated run rate (Hz), which comes from actual period measurement, low-pass filtered.

double estimatedRateRaw() const

Last actual execution rate measured (Hz), without low-pass filtering.