robotics.Rate

Execute loop at fixed frequency

Description

The Rate 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 = robotics.Rate(desiredRate)

Description

example

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

Properties

expand all

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.

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

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

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.

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

waitforPause code execution to achieve desired execution rate
statisticsStatistics of past execution periods
resetReset Rate object

Examples

collapse all

Create a rate object that runs at 1 Hz.

r = robotics.Rate(1);

Start a loop using the Rate 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.023253
Iteration: 2 - Time Elapsed: 1.077217
Iteration: 3 - Time Elapsed: 2.028522
Iteration: 4 - Time Elapsed: 3.013088
Iteration: 5 - Time Elapsed: 4.013310
Iteration: 6 - Time Elapsed: 5.039364
Iteration: 7 - Time Elapsed: 6.005941
Iteration: 8 - Time Elapsed: 7.008465
Iteration: 9 - Time Elapsed: 8.005125
Iteration: 10 - Time Elapsed: 9.007542

Each iteration executes at a 1-second interval.

Create a Rate object for running at 20 Hz.

r = robotics.Rate(2);

Start a loop and control operation using the Rate 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: [1x30 double]
           NumPeriods: 30
        AveragePeriod: 0.5000
    StandardDeviation: 0.0036
          NumOverruns: 0

Create a Rate object for running at 20 Hz.

r = robotics.Rate(2);

Start a loop and control operation using the Rate object.

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

Display the Rate object properties after loop operation.

disp(r)
  Rate with properties:

         DesiredRate: 2
       DesiredPeriod: 0.5000
       OverrunAction: 'slip'
    TotalElapsedTime: 15.0226
          LastPeriod: 0.4998

Reset the object to restart the time statistics.

reset(r);
disp(r)
  Rate with properties:

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

Introduced in R2016a