Coldwave Documentation

Appearance

Timer & Delay ​

Software millisecond/microsecond timer and delay functions.

all "Timer" functions can be used to execute code periodically in millisecond intervals. Please be aware, that the timer thread runs at the lowest priority and uses the SysTick Interrupt to time thing. Therefore, this API should not be used for time-critical code that requires millisecond-precision but more for delayed one-time execution or periodic tasks that need to be performed, but don't suffer from a slight tolerance in the 1digit millisecond region.

The microsecond "Ticker" is a hardware-dependent feature and relies on an implementation in the specific HAL. It utilizes (and therefore occupies) timer hardware, offering precise periodic function calls, for example in time-critical sensor readouts. If a HAL library does not implement it, all functions will return "0" instead of a handle.

Types ​

Name
structosTimerAttr_t
Attributes structure for timer.
enumosTimerType_t
Timer type.
typedef void(*)(void *argument)osTimerFunc_t
Timer callback function.

Functions Overview ​

Name
osTimerId_tosTimerNew(osTimerFunc_t func, osTimerType_t type, void * argument, const osTimerAttr_t * attr)
Create and Initialize a timer.
const char *osTimerGetName(osTimerId_t timer_id)
Get name of a timer.
osStatus_tosTimerStart(osTimerId_t timer_id, uint32_t ticks)
Start or restart a timer.
osStatus_tosTimerStop(osTimerId_t timer_id)
Stop a timer.
uint32_tosTimerIsRunning(osTimerId_t timer_id)
Check if a timer is running.
osStatus_tosTimerDelete(osTimerId_t timer_id)
Delete a timer.
osStatus_tosDelay(uint32_t ticks)
Wait for Timeout (Time Delay).
osStatus_tosDelayUntil(uint32_t ticks)
Wait until specified time.
osStatus_tosDelayUs(uint32_t microseconds)
Wait for Timeout (Microsecond Delay).
osTickerId_tosTickerNew(osTickerFunc_t func, void * arg, uint32_t microseconds, uint32_t stack_size)
creates a new ticker instance.
osStatus_tosTickerDelete(osTickerId_t ticker)
destroy a ticker instance.
osStatus_tosTickerStart(osTickerId_t ticker)
start executing a ticker instance.
osStatus_tosTickerStop(osTickerId_t ticker)
stop executing a ticker instance.

Types Documentation ​

enum osTimerType_t ​

EnumeratorDescription
osTimerOnceOne-shot timer.
osTimerPeriodicRepeating timer.

Timer type.

typedef osTimerFunc_t ​

cpp
typedef void(* osTimerFunc_t) (void *argument);

Timer callback function.

Function Details ​

function osTimerNew ​

cpp
osTimerId_t osTimerNew(
    osTimerFunc_t func,
    osTimerType_t type,
    void * argument,
    const osTimerAttr_t * attr
)

Create and Initialize a timer.

Parameters:

  • func function pointer to callback function.
  • type osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
  • argument argument to the timer callback function.
  • attr timer attributes; NULL: default values.

Return: timer ID for reference by other functions or NULL in case of error.

function osTimerGetName ​

cpp
const char * osTimerGetName(
    osTimerId_t timer_id
)

Get name of a timer.

Parameters:

Return: name as null-terminated string.

function osTimerStart ​

cpp
osStatus_t osTimerStart(
    osTimerId_t timer_id,
    uint32_t ticks
)

Start or restart a timer.

Parameters:

  • timer_id timer ID obtained by osTimerNew.
  • ticks millisecond tick value of the timer.

Return: status code that indicates the execution status of the function.

function osTimerStop ​

cpp
osStatus_t osTimerStop(
    osTimerId_t timer_id
)

Stop a timer.

Parameters:

Return: status code that indicates the execution status of the function.

function osTimerIsRunning ​

cpp
uint32_t osTimerIsRunning(
    osTimerId_t timer_id
)

Check if a timer is running.

Parameters:

Return: 0 not running, 1 running.

function osTimerDelete ​

cpp
osStatus_t osTimerDelete(
    osTimerId_t timer_id
)

Delete a timer.

Parameters:

Return: status code that indicates the execution status of the function.

function osDelay ​

cpp
osStatus_t osDelay(
    uint32_t ticks
)

Wait for Timeout (Time Delay).

Parameters:

  • ticks milliseconds to delay current execution.

Return: status code that indicates the execution status of the function.

function osDelayUntil ​

cpp
osStatus_t osDelayUntil(
    uint32_t ticks
)

Wait until specified time.

Parameters:

  • ticks absolute time in ticks

Return: status code that indicates the execution status of the function.

function osDelayUs ​

cpp
osStatus_t osDelayUs(
    uint32_t microseconds
)

Wait for Timeout (Microsecond Delay).

Parameters:

  • microseconds microseconds to delay current execution

Return: status code that indicates the execution status of the function.

function osTickerNew ​

cpp
osTickerId_t osTickerNew(
    osTickerFunc_t func,
    void * arg,
    uint32_t microseconds,
    uint32_t stack_size
)

creates a new ticker instance.

Parameters:

  • func callback function to be executed every interval
  • arg pointer to be passed to the callback function upon invocation
  • microseconds interval the callback should be invoked at.
  • stack_size the stack size to allocate for the callback function.

Return: Id of the ticker instance created.

function osTickerDelete ​

cpp
osStatus_t osTickerDelete(
    osTickerId_t ticker
)

destroy a ticker instance.

Parameters:

  • ticker Id of the ticker instance obtained from a previous call to osTickerNew

Return: status. osOK if the instance was deleted successfully.

function osTickerStart ​

cpp
osStatus_t osTickerStart(
    osTickerId_t ticker
)

start executing a ticker instance.

Parameters:

  • ticker Id of the ticker instance obtained from a previous call to osTickerNew

Return: status. osOK if the instance was started successfully.

function osTickerStop ​

cpp
osStatus_t osTickerStop(
    osTickerId_t ticker
)

stop executing a ticker instance.

Parameters:

  • ticker Id of the ticker instance obtained from a previous call to osTickerNew

Return: status. osOK if the instance was stopped successfully.