Hello Documentation Writers, the API documentation of xTimerStart(…) says: “… Starting a timer ensures the timer is in the active state. …” This is really misleading because “ensures” wrongly insinuates the timer to have been started before the completion of the call xTimerStart(…). In the Return-Section it says: “… 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 xTimerStart() is actually called.” This is really contradicting. Instead the above sentence should read somthing like: “Starting a timer ensures the timer is in the active state only if the priority of the service/deamon task is the highest in the system.” Other software timer related API documentation may be affected in the same way. Could you consider making the documentation more explicit in that matter? Thank you very much, Philipp

Hi – sorry if you found this wording confusing.

“… Starting a timer ensures the timer is in the active state. …”

I think this line is meant to indicate that when a timer is started, it will be in the active state, not necessarily that the timer is started immediately (as you point out, that depends on the priority of the timer task). I will have a look to see if it can be clearer.

Hello Richard, if there is a difference between “started” and “active” the naming of xTimerIsTimerActive(…) is also misleading. We were surprised to discover, that a xTimerIsTimerActive(…) might return pdFALSE directly after xTimerStart() completes succesfully. It took us a while to understand that the semantics of software timers is way more complicated than it looks at first glance — particularly with the priority of the timer-task beeing (too) low. Our solution is to make sure the timer task has highest priority so we can be sure the timer is started by calling xTimerStart(). Thank you for looking into the issue. Philipp

Here are the links that describe how it works https://www.freertos.org/RTOS-software-timer.html https://www.freertos.org/RTOS-software-timer-service-daemon-task.html