rateControl

Execute loop at fixed frequency

Description

The rateControl object enables you to run a loop at a fixed frequency. It also collects statistics about the timing of the loop iterations. Use waitfor in the loop to pause code execution until the next time step. The loop operates every DesiredPeriod seconds, unless the enclosed code takes longer to operate. The object uses the OverrunAction property to determine how it handles longer loop operation times. The default setting, 'slip', immediately executes the loop if LastPeriod is greater than DesiredPeriod. Using 'drop' causes the waitfor method to wait until the next multiple of DesiredPeriod is reached to execute the next loop.

Tip

The scheduling resolution of your operating system and the level of other system activity can affect rate execution accuracy. As a result, accurate rate timing is limited to 100 Hz for execution of MATLAB^® code. To improve performance and execution speeds, use code generation.

Creation

Syntax

rateObj = rateControl(desiredRate)

Description

rateObj = rateControl(desiredRate) creates an object that operates loops at a fixed-rate based on your system time and directly sets the DesireRate property.

Properties

DesiredRate — Desired execution rate

scalar

Desired execution rate of loop, specified as a scalar in Hz. When using waitfor, the loop operates every DesiredRate seconds, unless the loop takes longer. It then begins the next loop based on the specified OverrunAction.

DesiredPeriod — Desired time period between executions

scalar

Desired time period between executions, specified as a scalar in seconds. This property is equal to the inverse of DesiredRate.

TotalElapsedTime — Elapsed time since construction or reset

scalar

Elapsed time since construction or reset, specified as a scalar in seconds.

LastPeriod — Elapsed time between last two calls to waitfor

NaN (default) | scalar

Elapsed time between last two calls to waitfor, specified as a scalar. By default, LastPeriod is set to NaN until waitfor is called for the first time. After the first call, LastPeriod equals TotalElapsedTime.

OverrunAction — Method for handling overruns

'slip' (default) | 'drop'

Method for handling overruns, specified as one of these character vectors:

• 'drop' — waits until the next time interval equal to a multiple of DesiredPeriod

• 'slip' — immediately executes the loop again

Each code section calls waitfor at the end of execution.

Object Functions

waitfor	Pause code execution to achieve desired execution rate
statistics	Statistics of past execution periods
reset	Reset Rate object

Examples

Run Loop at Fixed Rate

Create a rate object that runs at 1 Hz.

r = rateControl(1);

Start a loop using the rateControl object inside to control the loop execution. Reset the object prior to the loop execution to reset timer. Print the iteration and time elapsed.

reset(r)
for i = 1:10
	time = r.TotalElapsedTime;
	fprintf('Iteration: %d - Time Elapsed: %f\n',i,time)
	waitfor(r);
end

Iteration: 1 - Time Elapsed: 0.001646
Iteration: 2 - Time Elapsed: 1.001156
Iteration: 3 - Time Elapsed: 2.000720
Iteration: 4 - Time Elapsed: 3.000994
Iteration: 5 - Time Elapsed: 4.001643
Iteration: 6 - Time Elapsed: 5.001109
Iteration: 7 - Time Elapsed: 6.001165
Iteration: 8 - Time Elapsed: 7.000602
Iteration: 9 - Time Elapsed: 8.000919
Iteration: 10 - Time Elapsed: 9.000195

Each iteration executes at a 1-second interval.

Get Statistics From Rate Object Execution

Create a rateControl object for running at 20 Hz.

r = rateControl(20);

Start a loop and control operation using the rateControl object.

for i = 1:30
    % Your code goes here
    waitfor(r);
end

Get Rate object statistics after loop operation.

stats = statistics(r)

stats = struct with fields:
              Periods: [0.0535 0.0478 0.1206 0.0067 0.0483 0.0463 0.0498 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0508 0.0638 0.0355 0.0499 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500]
           NumPeriods: 30
        AveragePeriod: 0.0508
    StandardDeviation: 0.0158
          NumOverruns: 1

Run Loop At Fixed Rate and Reset Rate Object

Create a rateControl object for running at 20 Hz.

r = rateControl(2);

Start a loop and control operation using the Rate object.

for i = 1:30
    % Your code goes here
    waitfor(r);
end

Display the rateControl object properties after loop operation.

disp(r)

  rateControl with properties:

         DesiredRate: 2
       DesiredPeriod: 0.5000
       OverrunAction: 'slip'
    TotalElapsedTime: 15.0057
          LastPeriod: 0.5000

Reset the object to restart the time statistics.

reset(r);
disp(r)

  rateControl with properties:

         DesiredRate: 2
       DesiredPeriod: 0.5000
       OverrunAction: 'slip'
    TotalElapsedTime: 0.0018
          LastPeriod: NaN

Version History

Introduced in R2016a

R2019b: rateControl was renamed

The rateControl object was renamed from robotics.Rate. Use rateControl for all object creation.