Base class that provides the standard task interface to FreeRTOS::Timer and FreeRTOS::StaticTimer. More...

#include <FreeRTOS/Timer.hpp>

Inheritance diagram for FreeRTOS::TimerBase:

[legend]

Public Member Functions
	TimerBase (const TimerBase &)=delete

TimerBase &	operator= (const TimerBase &)=delete

virtual void	timerEntry () final
	Function that acts as the entry point of the timer instance.

bool	isValid () const
	Function that checks the value of the timer handle. This function should be called to ensure the timer was created successfully.

bool	isActive () const
	Function that calls `BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer )`

bool	start (const TickType_t blockTime=0) const
	Function that calls `BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xBlockTime )`

bool	startFromISR (bool &higherPriorityTaskWoken) const
	Function that calls `BaseType_t xTimerStartFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )`

bool	startFromISR () const
	Function that calls `BaseType_t xTimerStartFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )`

bool	stop (const TickType_t blockTime=0) const
	Function that calls `BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xBlockTime )`

bool	stopFromISR (bool &higherPriorityTaskWoken) const
	Function that calls `BaseType_t xTimerStopFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )`

bool	stopFromISR () const
	Function that calls `BaseType_t xTimerStopFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )`

bool	changePeriod (const TickType_t newPeriod, const TickType_t blockTime=0) const
	Function that calls `BaseType_t xTimerChangePeriod( TimerHandle_t xTimer, TickType_t xNewPeriod, TickType_t xBlockTime )`

bool	changePeriodFromISR (bool &higherPriorityTaskWoken, const TickType_t newPeriod) const
	Function that calls `BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer, TickType_t xNewPeriod, BaseType_t *pxHigherPriorityTaskWoken )`

bool	changePeriodFromISR (const TickType_t newPeriod) const
	Function that calls `BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer, TickType_t xNewPeriod, BaseType_t *pxHigherPriorityTaskWoken )`

bool	deleteTimer (const TickType_t blockTime=0)
	Function that calls `BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xBlockTime )`

bool	reset (const TickType_t blockTime=0) const
	Function that calls `BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xBlockTime )`

bool	resetFromISR (bool &higherPriorityTaskWoken) const
	Function that calls `BaseType_t xTimerResetFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )`

bool	resetFromISR () const
	Function that calls `BaseType_t xTimerResetFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )`

void	setReloadMode (const bool autoReload) const
	Function that calls `void vTimerSetReloadMode( TimerHandle_t xTimer, const UBaseType_t xAutoReload )`

const char *	getName () const
	Function that calls `const char * pcTimerGetName( TimerHandle_t xTimer )`

TickType_t	getPeriod () const
	Function that calls `TickType_t xTimerGetPeriod( TimerHandle_t xTimer )`

TickType_t	getExpiryTime () const
	Function that calls `TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer )`

bool	getReloadMode () const
	Function that calls `UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer )`

void	setDeleteBlockTime (const TickType_t deleteBlockTime=0)
	Set the delete block time. This value is used when the destructor calls deleteTimer().

TickType_t	getDeleteBlockTime () const
	Set the delete block time. This value is used when the destructor calls deleteTimer().

Static Public Member Functions
static void *	operator new (size_t)=delete

static void *	operator new[] (size_t)=delete

static void *	operator new (size_t, void *ptr)

static void *	operator new[] (size_t, void *ptr)

Protected Member Functions
virtual void	timerFunction ()=0
	Abstraction function that acts as the entry point of the timer callback for the user.

Private Member Functions
	TimerBase (const TickType_t deleteBlockTime=0)
	Construct a new TimerBase object. This default constructor is deliberately private as this class is not intended to be instantiated or derived from by the user. Use FreeRTOS::Timer or FreeRTOS::StaticTimer as a base class for creating a task.

	~TimerBase ()
	Destroy the TimerBase object.

	TimerBase (TimerBase &&) noexcept=default

TimerBase &	operator= (TimerBase &&) noexcept=default

Private Attributes
TimerHandle_t	handle = NULL

TickType_t	deleteBlockTime

Friends
class	Timer

class	StaticTimer

Detailed Description

Base class that provides the standard task interface to FreeRTOS::Timer and FreeRTOS::StaticTimer.

Note: This class is not intended to be instantiated or derived from by the user. Use FreeRTOS::Timer or FreeRTOS::StaticTimer as a base class for a user implemented task.

Constructor & Destructor Documentation

◆ TimerBase()

FreeRTOS::TimerBase::TimerBase ( const TickType_t deleteBlockTime = 0 )

inlineexplicitprivate

Construct a new TimerBase object. This default constructor is deliberately private as this class is not intended to be instantiated or derived from by the user. Use FreeRTOS::Timer or FreeRTOS::StaticTimer as a base class for creating a task.

Timer.hpp

Parameters

deleteBlockTime Set the delete block time. This value is used when the destructor calls deleteTimer().

◆ ~TimerBase()

FreeRTOS::TimerBase::~TimerBase ( )

inlineprivate

Destroy the TimerBase object.

Timer.hpp

Note: This destructor will check that the timer is still valid and has not already been deleted by deleteTimer() before calling the function. If the timer is still valid the destructor will call deleteTimer() and block for up to the amount of time specified by deleteBlockTime.

Member Function Documentation

◆ changePeriod()

bool FreeRTOS::TimerBase::changePeriod	(	const TickType_t	newPeriod,
		const TickType_t	blockTime = `0`
	)		const

inline

Function that calls BaseType_t xTimerChangePeriod( TimerHandle_t xTimer, TickType_t xNewPeriod, TickType_t xBlockTime )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerChangePeriod.html

changePeriod() changes the period of a timer.

changePeriod() can be called to change the period of an active or dormant state timer. Changing the period of a dormant timers will also start the timer.

Parameters

newPeriod The new period for timer. Timer periods are specified in tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time that has been specified in milliseconds. For example, if the timer must expire after 100 ticks, then newPeriod should be set to 100. Alternatively, if the timer must expire after 500ms, then newPeriod can be set to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000.

blockTime Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the change period command to be successfully sent to the timer command queue, should the queue already be full when changePeriod() was called. blockTime is ignored if changePeriod() is called before the RTOS scheduler is started.

Returns: true If the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.; false If the change period command could not be sent to the timer command queue even after blockTime ticks had passed.

Example Usage

#include <FreeRTOS/Timer.hpp>
 
class MyTimer : public FreeRTOS::Timer {
 public:
  MyTimer() : FreeRTOS::Timer(0) {}
  void timerFunction() final;
};
 
void MyTimer::timerFunction() {
  // Timer function.
}
 
void aFunction() {
  MyTimer timer;
 
  if (timer.isActive()) {
    // Timer will be deleted when the object goes out of scope.
    return;
  }
 
  // timer is not active, change its period to 500ms.  This will also cause the
  // timer to start.  Block for a maximum of 100 ticks if the change period
  // command cannot immediately be sent to the timer command queue.
  if (timer.changePeriod((500 / portTICK_PERIOD_MS), 100)) {
    // The command was successfully sent.
  } else {
    //  The command could not be sent, even after waiting for 100 ticks to pass.
    //  Take appropriate action here.
  }
}

◆ changePeriodFromISR() [1/2]

bool FreeRTOS::TimerBase::changePeriodFromISR	(	bool &	higherPriorityTaskWoken,
		const TickType_t	newPeriod
	)		const

inline

Function that calls BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer, TickType_t xNewPeriod, BaseType_t *pxHigherPriorityTaskWoken )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerChangePeriodFromISR.html

A version of changePeriod() that can be called from an interrupt service routine.

Parameters

newPeriod The new period for timer. Timer periods are specified in tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time that has been specified in milliseconds. For example, if the timer must expire after 100 ticks, then newPeriod should be set to 100. Alternatively, if the timer must expire after 500ms, then newPeriod can be set to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000.

higherPriorityTaskWoken The timer service/daemon task spends most of its time in the Blocked state, waiting for messages to arrive on the timer command queue. Calling changePeriodFromISR() writes a message to the timer command queue, so has the potential to transition the timer service/ daemon task out of the Blocked state. If calling changePeriodFromISR() causes the timer service/daemon task to leave the Blocked state, and the timer service/daemon task has a priority equal to or greater than the currently executing task (the task that was interrupted), then higherPriorityTaskWoken will get set to true internally within the changePeriodFromISR() function. If changePeriodFromISR() sets this value to true, then a context switch should be performed before the interrupt exits.

Returns: true If the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.; false If the change period command could not be sent to the timer command queue.

Example Usage

#include <FreeRTOS/Timer.hpp>
 
class MyTimer : public FreeRTOS::StaticTimer {
 public:
  MyTimer() : FreeRTOS::StaticTimer(pdMS_TO_TICKS(5000)) {}
  void timerFunction() final;
};
 
void MyTimer::timerFunction() {
  // Timer function.
}
 
static MyTimer myTimer;
 
// The interrupt service routine that changes the period of timer.
void anExampleInterruptServiceRoutine() {
  bool higherPriorityTaskWoken = false;
 
  // The interrupt has occurred - change the period of xTimer to 500ms.
  // higherPriorityTaskWoken was set to false where it was defined (within this
  // function).  As this is an interrupt service routine, only FreeRTOS API
  // functions that end in "FromISR" can be used.
  if (!myTimer.changePeriodFromISR(higherPriorityTaskWoken,
                                   pdMS_TO_TICKS(500))) {
    // The command to change the timers period was not executed successfully.
    // Take appropriate action here.
  }
 
  // If higherPriorityTaskWoken equals true, then a context switch should be
  // performed.  The syntax required to perform a context switch from inside an
  // ISR varies from port to port, and from compiler to compiler.  Inspect the
  // demos for the port you are using to find the actual syntax required.
  if (higherPriorityTaskWoken) {
    // Call the interrupt safe yield function here (actual function depends on
    // the FreeRTOS port being used).
  }
}

◆ changePeriodFromISR() [2/2]

bool FreeRTOS::TimerBase::changePeriodFromISR ( const TickType_t newPeriod ) const

inline

Function that calls BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer, TickType_t xNewPeriod, BaseType_t *pxHigherPriorityTaskWoken )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerChangePeriodFromISR.html

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ deleteTimer()

bool FreeRTOS::TimerBase::deleteTimer ( const TickType_t blockTime = 0 )

inline

Function that calls BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xBlockTime )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerDelete.html

deleteTimer() deletes a timer from the FreeRTOS timer task.

Note: This function is also called in the destructor of the timer using the deleteBlockTime specified when the object was created. This function should be used when the user wants to delete the timer from the FreeRTOS timer task without destroying the timer object or with a different block time than what was specified in the constructor.

Parameters

blockTime Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the delete command to be successfully sent to the timer command queue, should the queue already be full when deleteTimer() was called. blockTime is ignored if deleteTimer() is called before the RTOS scheduler is started.

Returns: true If the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.; false If the delete command could not be sent to the timer command queue even after blockTime ticks had passed.

Example Usage

#include <FreeRTOS/Timer.hpp>
 
class MyTimer : public FreeRTOS::Timer {
 public:
  MyTimer() : FreeRTOS::Timer(0) {}
  void timerFunction() final;
};
 
void MyTimer::timerFunction() {
  // Timer function.
}
 
void aFunction() {
  MyTimer timer;
 
  if (timer.isActive()) {
    // Timer will be deleted when the object goes out of scope.
    return;
  }
 
  // timer is not active, change its period to 500ms.  This will also cause the
  // timer to start.  Block for a maximum of 100 ticks if the change period
  // command cannot immediately be sent to the timer command queue.
  if (timer.changePeriod((500 / portTICK_PERIOD_MS), 100)) {
    // The command was successfully sent.
  } else {
    //  The command could not be sent, even after waiting for 100 ticks to pass.
    //  Take appropriate action here.
  }
}

◆ getDeleteBlockTime()

TickType_t FreeRTOS::TimerBase::getDeleteBlockTime ( ) const

inline

Set the delete block time. This value is used when the destructor calls deleteTimer().

Timer.hpp

Returns: TickType_t Delete block time in ticks.

◆ getExpiryTime()

TickType_t FreeRTOS::TimerBase::getExpiryTime ( ) const

inline

Function that calls TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerGetExpiryTime.html

Returns the time at which the software timer will expire, which is the time at which the timer's callback function will execute.

If the value returned by getExpiryTime() is less than the current time then the timer will expire after the tick count has overflowed and wrapped back to 0. Overflows are handled in the RTOS implementation itself, so a timer's callback function will execute at the correct time whether it is before or after the tick count overflows.

Returns: TickType_t If the timer is active, then the time at which the timer will next expire is returned (which may be after the current tick count has overflowed, see the notes above). If the timer is not active then the return value is undefined.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Timer.hpp>
 
class MyTimer : public FreeRTOS::StaticTimer {
 public:
  MyTimer() : FreeRTOS::StaticTimer(pdMS_TO_TICKS(500)) {}
  void timerFunction() final;
};
 
void MyTimer::timerFunction() {
  TickType_t remainingTime;
 
  // Query the period of the timer that expires.
  remainingTime = getExpiryTime() - FreeRTOS::Kernel::getTickCount();
}
 
static MyTimer myTimer;

◆ getName()

const char * FreeRTOS::TimerBase::getName ( ) const

inline

Function that calls const char * pcTimerGetName( TimerHandle_t xTimer )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-pcTimerGetName.html

Returns the human readable text name of a software timer.

Text names are assigned to timers in the constructor.

Returns: const char* A pointer to the text name of the timer as a standard NULL terminated C string.

Example Usage

#include <FreeRTOS/Timer.hpp>
 
#include "cstring"
 
constexpr char const *pcTimerName = "ExampleTimer";
 
class MyTimer : public FreeRTOS::Timer {
 public:
  MyTimer() : FreeRTOS::Timer(pdMS_TO_TICKS(500), true, pcTimerName) {}
  void timerFunction() final;
};
 
void MyTimer::timerFunction() {
  // Timer function.
}
 
int main() {
  MyTimer myTimer;
 
  if (myTimer.isValid()) {
    myTimer.start(portMAX_DELAY);
 
    // Just to demonstrate getName(), query the timer's name and assert if it
    // does not equal pcTimerName.
    configASSERT(strcmp(myTimer.getName(), pcTimerName) == 0);
  }
}

◆ getPeriod()

TickType_t FreeRTOS::TimerBase::getPeriod ( ) const

inline

Function that calls TickType_t xTimerGetPeriod( TimerHandle_t xTimer )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerGetPeriod.html

Returns the period of a software timer. The period is specified in ticks.

The period of a timer is initially set using the period parameter of the constructor. It can then be changed using the changePeriod() and changePeriodFromISR() API functions.

Returns: TickType_t The period of the timer, in ticks.

Example Usage

#include <FreeRTOS/Timer.hpp>
 
class MyTimer : public FreeRTOS::StaticTimer {
 public:
  MyTimer() : FreeRTOS::StaticTimer(pdMS_TO_TICKS(500)) {}
  void timerFunction() final;
};
 
void MyTimer::timerFunction() {
  TickType_t timerPeriod;
 
  // Query the period of the timer that expires.
  timerPeriod = getPeriod();
}
 
static MyTimer myTimer;

◆ getReloadMode()

bool FreeRTOS::TimerBase::getReloadMode ( ) const

inline

Function that calls UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer )

Timer.hpp

See also: https://www.freertos.org/uxTimerGetReloadMode.html

Queries the 'mode' of the software timer.

The mode can be either an auto-reloaded timer, which automatically resets itself each time it expires, or a one-shot timer, which will expire only once unless it is manually restarted.

Returns: true If the timer is an auto-reload timer.; false Otherwise.

◆ isActive()

bool FreeRTOS::TimerBase::isActive ( ) const

inline

Function that calls BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerIsTimerActive.html

Queries a software timer to see if it is active or dormant.

A timer will be dormant if:

It has been created but not started, or
It is an expired one-shot timer that has not been restarted.

Note: Timers are created in the dormant state. The start(), reset(), startFromISR(), resetFromISR(), changePeriod() and changePeriodFromISR() API functions can all be used to transition a timer into the active state.

Returns: false If the timer is dormant.; true Otherwise.

Example Usage

#include <FreeRTOS/Timer.hpp>
 
class MyTimer : public FreeRTOS::Timer {
 public:
  MyTimer() : FreeRTOS::Timer(100) {}
  void timerFunction() final;
};
 
void MyTimer::timerFunction() {
  // Timer function.
}
 
void aFunction() {
  MyTimer timer;
 
  if (timer.isActive()) {
    // Timer is active, do something.
  } else {
    // Timer is not active, do something else.
  }
}

◆ isValid()

bool FreeRTOS::TimerBase::isValid ( ) const

inline

Function that checks the value of the timer handle. This function should be called to ensure the timer was created successfully.

Timer.hpp

Returns: true If the timer was created successfully.; false If the timer was not created successfully due to insufficient memory.

◆ reset()

bool FreeRTOS::TimerBase::reset ( const TickType_t blockTime = 0 ) const

inline

Function that calls BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xBlockTime )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerReset.html

reset() re-starts a timer. If the timer had already been started and was already in the active state, then reset() will cause the timer to re-evaluate its expiry time so that it is relative to when reset() was called. If the timer was in the dormant state then reset() has equivalent functionality to the start() API function.

Resetting a timer ensures the timer is in the active state. If the timer is not stopped, deleted, or reset in the mean time, the callback function associated with the timer will get called 'n' ticks after reset() was called, where 'n' is the timers defined period.

It is valid to call reset() before the RTOS scheduler has been started, but when this is done the timer will not actually start until the RTOS scheduler is started, and the timers expiry time will be relative to when the RTOS scheduler is started, not relative to when reset() was called.

Parameters

blockTime Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the reset command to be successfully sent to the timer command queue, should the queue already be full when reset() was called. blockTime is ignored if reset() is called before the RTOS scheduler is started.

Returns: true If the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system, although the timers expiry time is relative to when reset() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.; false If the reset command could not be sent to the timer command queue even after blockTime ticks had passed.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Timer.hpp>
 
// Fake backlight interface functions.
constexpr bool backlightOff = false;
constexpr bool backlightOn = true;
void vSetBacklightState(bool);
 
// When a key is pressed, an LCD back-light is switched on.  If 5 seconds pass
// without a key being pressed, then the LCD back-light is switched off.  In
// this case, the timer is a one-shot timer.
class BacklightTimer : public FreeRTOS::StaticTimer {
 public:
  BacklightTimer()
      : FreeRTOS::StaticTimer(pdMS_TO_TICKS(5000), false, "BacklightTimer") {}
  void timerFunction() final;
};
 
void BacklightTimer::timerFunction() {
  // The timer expired, therefore 5 seconds must have passed since a key was
  // pressed.  Switch off the LCD back-light.
  vSetBacklightState(backlightOff);
}
 
static BacklightTimer backlightTimer;
 
// The key press event handler.
void keyPressEventHandler() {
  // Ensure the LCD back-light is on, then restart the timer that is responsible
  // for turning the back-light off after 5 seconds of key inactivity.  Wait 10
  // ticks for the command to be successfully sent if it cannot be sent
  // immediately.
  vSetBacklightState(backlightOn);
 
  if (!backlightTimer.reset(10)) {
    // The reset command was not executed successfully.  Take appropriate action
    // here.
  }
 
  // Perform the rest of the key processing here.
}
 
int main() {
  if (!backlightTimer.isValid()) {
    // The timer was not created.
  } else {
    // Start the timer.  No block time is specified, and even if one was it
    // would be ignored because the RTOS scheduler has not yet been started.
    if (!backlightTimer.start()) {
      // The timer could not be set into the active state.
    }
  }
 
  // Create tasks here.
 
  // Starting the RTOS scheduler will start the timer running as it has already
  // been set into the active state.
  FreeRTOS::Kernel::startScheduler();
 
  /* Should not reach here. */
  for (;;) {
    ;
  }
}

◆ resetFromISR() [1/2]

bool FreeRTOS::TimerBase::resetFromISR ( ) const

inline

Function that calls BaseType_t xTimerResetFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerResetFromISR.html

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ resetFromISR() [2/2]

bool FreeRTOS::TimerBase::resetFromISR ( bool & higherPriorityTaskWoken ) const

inline

Function that calls BaseType_t xTimerResetFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerResetFromISR.html

A version of reset() that can be called from an interrupt service routine.

Parameters

higherPriorityTaskWoken The timer service/daemon task spends most of its time in the Blocked state, waiting for messages to arrive on the timer command queue. Calling resetFromISR() writes a message to the timer command queue, so has the potential to transition the timer service/daemon task out of the Blocked state. If calling resetFromISR() causes the timer service/daemon task to leave the Blocked state, and the timer service/daemon task has a priority equal to or greater than the currently executing task (the task that was interrupted), then higherPriorityTaskWoken will get set to true internally within the resetFromISR() function. If resetFromISR() sets this value to true, then a context switch should be performed before the interrupt exits.

Returns: true If the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system, although the timers expiry time is relative to when resetFromISR() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.; false If the change period command could not be sent to the timer command queue.

Example Usage

#include <FreeRTOS/Timer.hpp>
 
// Fake backlight interface functions.
constexpr bool backlightOff = false;
constexpr bool backlightOn = true;
void vSetBacklightState(bool);
 
// When a key is pressed, an LCD back-light is switched on.  If 5 seconds pass
// without a key being pressed, then the LCD back-light is switched off.  In
// this case, the timer is a one-shot timer, and unlike the example given for
// the reset() function, the key press event handler is an interrupt service
// routine.
class BacklightTimer : public FreeRTOS::StaticTimer {
 public:
  BacklightTimer() : FreeRTOS::StaticTimer(pdMS_TO_TICKS(5000)) {}
  void timerFunction() final;
};
 
void BacklightTimer::timerFunction() {
  // The timer expired, therefore 5 seconds must have passed since a key was
  // pressed.  Switch off the LCD back-light.
  vSetBacklightState(backlightOff);
}
 
static BacklightTimer backlightTimer;
 
// The key press interrupt service routine.
void keyPressEventInterruptHandler() {
  bool higherPriorityTaskWoken = false;
 
  // Ensure the LCD back-light is on, then restart the timer that is responsible
  // for turning the back-light off after 5 seconds of key inactivity.  This is
  // an interrupt service routine so can only call FreeRTOS API functions that
  // end in "FromISR".
  vSetBacklightState(backlightOn);
 
  // startFromISR() or resetFromISR() could be called here as both cause the
  // timer to re-calculate its expiry time. higherPriorityTaskWoken was
  // initialised to false when it was declared (in this function).
  if (!backlightTimer.resetFromISR(higherPriorityTaskWoken)) {
    // The reset command was not executed successfully.  Take appropriate action
    // here.
  }
 
  // Perform the rest of the key processing here.
 
  // If higherPriorityTaskWoken equals true, then a context switch should be
  // performed.  The syntax required to perform a context switch from inside an
  // ISR varies from port to port, and from compiler to compiler.  Inspect the
  // demos for the port you are using to find the actual syntax required.
  if (higherPriorityTaskWoken) {
    // Call the interrupt safe yield function here (actual function depends on
    // the FreeRTOS port being used).
  }
}

◆ setDeleteBlockTime()

void FreeRTOS::TimerBase::setDeleteBlockTime ( const TickType_t deleteBlockTime = 0 )

inline

Set the delete block time. This value is used when the destructor calls deleteTimer().

Timer.hpp

Parameters

deleteBlockTime Delete block time to be set in ticks.

◆ setReloadMode()

void FreeRTOS::TimerBase::setReloadMode ( const bool autoReload ) const

inline

Function that calls void vTimerSetReloadMode( TimerHandle_t xTimer, const UBaseType_t xAutoReload )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-Timers-vTimerSetReloadMode.html

Updates the 'mode' of a software timer to be either an auto reload timer or a one-shot timer.

An auto reload timer resets itself each time it expires, causing the timer to expire (and therefore execute its callback) periodically.

A one shot timer does not automatically reset itself, so will only expire (and therefore execute its callback) once unless it is manually restarted.

Parameters

autoReload Set autoReload to true to set the timer into auto reload mode, or false to set the timer into one shot mode.

◆ start()

bool FreeRTOS::TimerBase::start ( const TickType_t blockTime = 0 ) const

inline

Function that calls BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xBlockTime )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerStart.html

start() starts a timer. If the timer had already been started and was already in the active state, then start() has equivalent functionality to the reset() API function.

Starting a timer ensures the timer is in the active state. If the timer is not stopped, deleted, or reset in the mean time, timerFunction() will get called 'n 'ticks after start() was called, where 'n' is the timers defined period.

It is valid to call start() before the RTOS scheduler has been started, but when this is done the timer will not actually start until the RTOS scheduler is started, and the timers expiry time will be relative to when the RTOS scheduler is started, not relative to when start() was called.

Parameters

blockTime Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the start command to be successfully sent to the timer command queue, should the queue already be full when start() was called. blockTime is ignored if start() is called before the RTOS scheduler is started.

Returns: true If the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system, although the timers expiry time is relative to when start() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.; false If the start command could not be sent to the timer command queue even after blockTime ticks had passed.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Timer.hpp>
 
constexpr size_t numberOfTimers = 5;
 
class MyTimer : public FreeRTOS::Timer {
 public:
  MyTimer() : FreeRTOS::Timer(0, true, "Timer") {}
  void timerFunction() final;
 
 private:
  uint8_t count = 0;
};
 
// Define a callback function that will be used by multiple timer instances. The
// callback function does nothing but count the number of times the associated
// timer expires, and stop the timer once the timer has expired 10 times.
void MyTimer::timerFunction() {
  constexpr uint8_t maxExpiryCountBeforeStopping = 10;
 
  // Optionally do something if the pxTimer parameter is NULL.
  configASSERT(!isValid());
 
  // Increment the count, then test to see if the timer has expired
  // maxExpiryCountBeforeStopping yet.
  count++;
 
  // If the timer has expired 10 times then stop it from running.
  if (count++ >= maxExpiryCountBeforeStopping) {
    // Do not use a block time if calling a timer API function from a timer
    // callback function, as doing so could cause a deadlock!
    stop();
  }
}
 
int aFunction() {
  // An array to hold handles to the created timer. Create some timers.
  MyTimer xTimers[numberOfTimers];
 
  // Initialize then start some timers.  Starting the timers before the RTOS
  // scheduler has been started means the timers will start running immediately
  // that the RTOS scheduler starts.
  for (size_t x = 0; x < numberOfTimers; x++) {
    if (xTimers[x].isValid()) {
      xTimers[x].changePeriod((100 * x) + 100);
      if (!xTimers[x].start()) {
        // The timer could not be set into the Active state.
      }
    } else {
      // The timer was not created.
    }
  }
 
  // Create tasks here.
 
  // Starting the RTOS scheduler will start the timers running as they have
  // already been set into the active state.
  FreeRTOS::Kernel::startScheduler();
 
  // Should not reach here.
  for (;;) {
    ;
  }
}

◆ startFromISR() [1/2]

bool FreeRTOS::TimerBase::startFromISR ( ) const

inline

Function that calls BaseType_t xTimerStartFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerStartFromISR.html

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ startFromISR() [2/2]

bool FreeRTOS::TimerBase::startFromISR ( bool & higherPriorityTaskWoken ) const

inline

Function that calls BaseType_t xTimerStartFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerStartFromISR.html

A version of start() that can be called from an interrupt service routine.

Parameters

higherPriorityTaskWoken The timer service/daemon task spends most of its time in the Blocked state, waiting for messages to arrive on the timer command queue. Calling startFromISR() writes a message to the timer command queue, so has the potential to transition the timer service/daemon task out of the Blocked state. If calling startFromISR() causes the timer service/daemon task to leave the Blocked state, and the timer service/ daemon task has a priority equal to or greater than the currently executing task (the task that was interrupted), then higherPriorityTaskWoken will get set to true internally within the startFromISR() function. If startFromISR() sets this value to true, then a context switch should be performed before the interrupt exits.

Returns: true If the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system, although the timers expiry time is relative to when startFromISR() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.; false If the start command could not be sent to the timer command queue.

Example Usage

#include <FreeRTOS/Timer.hpp>
 
// Fake backlight interface functions.
constexpr bool backlightOff = false;
constexpr bool backlightOn = true;
void vSetBacklightState(bool);
 
// When a key is pressed, an LCD back-light is switched on.  If 5 seconds pass
// without a key being pressed, then the LCD back-light is switched off.  In
// this case, the timer is a one-shot timer, and unlike the example given for
// the reset() function, the key press event handler is an interrupt service
// routine.
class BacklightTimer : public FreeRTOS::StaticTimer {
 public:
  BacklightTimer() : FreeRTOS::StaticTimer(pdMS_TO_TICKS(5000)) {}
  void timerFunction() final;
};
 
void BacklightTimer::timerFunction() {
  // The timer expired, therefore 5 seconds must have passed since a key was
  // pressed.  Switch off the LCD back-light.
  vSetBacklightState(backlightOff);
}
 
static BacklightTimer backlightTimer;
 
// The key press interrupt service routine.
void keyPressEventInterruptHandler() {
  bool higherPriorityTaskWoken = false;
 
  // Ensure the LCD back-light is on, then restart the timer that is responsible
  // for turning the back-light off after 5 seconds of key inactivity.  This is
  // an interrupt service routine so can only call FreeRTOS API functions that
  // end in "FromISR".
  vSetBacklightState(backlightOn);
 
  // startFromISR() or resetFromISR() could be called here as both cause the
  // timer to re-calculate its expiry time. higherPriorityTaskWoken was
  // initialised to false when it was declared (in this function).
  if (!backlightTimer.startFromISR(higherPriorityTaskWoken)) {
    // The start command was not executed successfully.  Take appropriate action
    // here.
  }
 
  // Perform the rest of the key processing here.
 
  // If higherPriorityTaskWoken equals true, then a context switch should be
  // performed.  The syntax required to perform a context switch from inside an
  // ISR varies from port to port, and from compiler to compiler.  Inspect the
  // demos for the port you are using to find the actual syntax required.
  if (higherPriorityTaskWoken) {
    // Call the interrupt safe yield function here (actual function depends on
    // the FreeRTOS port being used).
  }
}

◆ stop()

bool FreeRTOS::TimerBase::stop ( const TickType_t blockTime = 0 ) const

inline

Function that calls BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xBlockTime )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerStop.html

stop() stops a timer that was previously started using either of the start(), reset(), startFromISR(), resetFromISR(), changePeriod() and changePeriodFromISR() API functions.

Stopping a timer ensures the timer is not in the active state.

Parameters

blockTime Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the stop command to be successfully sent to the timer command queue, should the queue already be full when stop() was called. blockTime is ignored if stop() is called before the RTOS scheduler is started.

Returns: true If the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.; false If the stop command could not be sent to the timer command queue even after blockTime ticks had passed.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Timer.hpp>
 
constexpr size_t numberOfTimers = 5;
 
class MyTimer : public FreeRTOS::Timer {
 public:
  MyTimer() : FreeRTOS::Timer(0, true, "Timer") {}
  void timerFunction() final;
 
 private:
  uint8_t count = 0;
};
 
// Define a callback function that will be used by multiple timer instances. The
// callback function does nothing but count the number of times the associated
// timer expires, and stop the timer once the timer has expired 10 times.
void MyTimer::timerFunction() {
  constexpr uint8_t maxExpiryCountBeforeStopping = 10;
 
  // Optionally do something if the pxTimer parameter is NULL.
  configASSERT(!isValid());
 
  // Increment the count, then test to see if the timer has expired
  // maxExpiryCountBeforeStopping yet.
  count++;
 
  // If the timer has expired 10 times then stop it from running.
  if (count++ >= maxExpiryCountBeforeStopping) {
    // Do not use a block time if calling a timer API function from a timer
    // callback function, as doing so could cause a deadlock!
    stop();
  }
}
 
int aFunction() {
  // An array to hold handles to the created timer. Create some timers.
  MyTimer xTimers[numberOfTimers];
 
  // Initialize then start some timers.  Starting the timers before the RTOS
  // scheduler has been started means the timers will start running immediately
  // that the RTOS scheduler starts.
  for (size_t x = 0; x < numberOfTimers; x++) {
    if (xTimers[x].isValid()) {
      xTimers[x].changePeriod((100 * x) + 100);
      if (!xTimers[x].start()) {
        // The timer could not be set into the Active state.
      }
    } else {
      // The timer was not created.
    }
  }
 
  // Create tasks here.
 
  // Starting the RTOS scheduler will start the timers running as they have
  // already been set into the active state.
  FreeRTOS::Kernel::startScheduler();
 
  // Should not reach here.
  for (;;) {
    ;
  }
}

◆ stopFromISR() [1/2]

bool FreeRTOS::TimerBase::stopFromISR ( ) const

inline

Function that calls BaseType_t xTimerStopFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerStopFromISR.html

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ stopFromISR() [2/2]

bool FreeRTOS::TimerBase::stopFromISR ( bool & higherPriorityTaskWoken ) const

inline

Function that calls BaseType_t xTimerStopFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken )

Timer.hpp

See also: https://www.freertos.org/FreeRTOS-timers-xTimerStopFromISR.html

A version of stop() that can be called from an interrupt service routine.

Parameters

higherPriorityTaskWoken The timer service/daemon task spends most of its time in the Blocked state, waiting for messages to arrive on the timer command queue. Calling stopFromISR() writes a message to the timer command queue, so has the potential to transition the timer service/daemon task out of the Blocked state. If calling stopFromISR() causes the timer service/daemon task to leave the Blocked state, and the timer service/ daemon task has a priority equal to or greater than the currently executing task (the task that was interrupted), then higherPriorityTaskWoken will get set to true internally within the stopFromISR() function. If stopFromISR() sets this value to true, then a context switch should be performed before the interrupt exits.

Returns: true If the command was successfully sent to the timer command queue. When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.; false If the start command could not be sent to the timer command queue.

Example Usage

#include <FreeRTOS/Timer.hpp>
 
class MyTimer : public FreeRTOS::StaticTimer {
 public:
  MyTimer() : FreeRTOS::StaticTimer(pdMS_TO_TICKS(5000)) {}
  void timerFunction() final;
};
 
void MyTimer::timerFunction() {
  // Timer function.
}
 
static MyTimer myTimer;
 
// The interrupt service routine that stops the timer.
void anExampleInterruptServiceRoutine() {
  bool higherPriorityTaskWoken = false;
 
  // The interrupt has occurred - simply stop the timer. higherPriorityTaskWoken
  // was set to false where it was defined (within this function).  As this is
  // an interrupt service routine, only FreeRTOS API functions that end in
  // "FromISR"
  //  can be used.
  if (!myTimer.stopFromISR(higherPriorityTaskWoken)) {
    // The stop command was not executed successfully.  Take appropriate action
    // here.
  }
 
  // If higherPriorityTaskWoken equals true, then a context switch should be
  // performed.  The syntax required to perform a context switch from inside an
  // ISR varies from port to port, and from compiler to compiler.  Inspect the
  // demos for the port you are using to find the actual syntax required.
  if (higherPriorityTaskWoken) {
    // Call the interrupt safe yield function here (actual function depends on
    // the FreeRTOS port being used).
  }
}

◆ timerEntry()

virtual void FreeRTOS::TimerBase::timerEntry ( )

inlinefinalvirtual

Function that acts as the entry point of the timer instance.

Timer.hpp

Note: This function is only public so that it can be accessed by the C interface function callTimerFunction() and should not be called or referenced by the user.

◆ timerFunction()

virtual void FreeRTOS::TimerBase::timerFunction ( )

protectedpure virtual

Abstraction function that acts as the entry point of the timer callback for the user.

Timer.hpp

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

/home/runner/work/FreeRTOS-Cpp/FreeRTOS-Cpp/FreeRTOS-Cpp/include/FreeRTOS/Timer.hpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ TimerBase()

◆ ~TimerBase()

Member Function Documentation

◆ changePeriod()

◆ changePeriodFromISR() [1/2]

◆ changePeriodFromISR() [2/2]

◆ deleteTimer()

◆ getDeleteBlockTime()

◆ getExpiryTime()

◆ getName()

◆ getPeriod()

◆ getReloadMode()

◆ isActive()

◆ isValid()

◆ reset()

◆ resetFromISR() [1/2]

◆ resetFromISR() [2/2]

◆ setDeleteBlockTime()

◆ setReloadMode()

◆ start()

◆ startFromISR() [1/2]

◆ startFromISR() [2/2]

◆ stop()

◆ stopFromISR() [1/2]

◆ stopFromISR() [2/2]

◆ timerEntry()

◆ timerFunction()