System Timing#

Functionality related to the RAIL timer and general system time.

These functions can be used to get information about the current system time or to manipulate the RAIL timer.

The system time returned by RAIL_GetTime() is in the same timebase that is used throughout RAIL. Any callbacks or structures that provide a timestamp, such as RAIL_RxPacketDetails_t::timeReceived, will use the same timebase as will any APIs that accept an absolute time for scheduling their action. Throughout the documentation, the timebase is referred to as the RAIL timebase. The timebase is currently a value in microseconds from RAIL_Init() time, which means that it will wrap every 1.19 hours. ((2^32 - 1) / (3600 sec/hr * 1000000 us/sec)).

The provided timer is hardware-backed and interrupt-driven. It can be used for timing any event in the system, but is especially helpful for timing protocol-based state machines and other systems that interact with the radio. To avoid processing the expiration in interrupt context, leave the cb parameter passed to RAIL_SetTimer() as NULL and poll for expiration with the RAIL_IsTimerExpired() function. See below for an example of the interrupt driven method of interacting with the timer.

void timerCb(RAIL_Handle_t cbArg)
{
  // Timer callback action
}

void main(void)
{
  // Initialize RAIL ...

  // Set up a timer for 1 ms from now
  RAIL_SetTimer(railHandle, 1000, RAIL_TIME_RELATIVE, &timerCb);

  // Run main loop
  while(1);
}

If multiple software timers are needed to be run off of the one available hardware timer, enable a software multiplexing layer within RAIL using the RAIL_ConfigMultiTimer() function. This will allow you to set up as many timers as you want using the RAIL_*MultiTimer() functions. See the example below for using the multitimer functionality.

// Declare timer structures in global space or somewhere that will exist
// until the callback has fired
RAIL_MultiTimer_t tmr1, tmr2;

void timerCb(RAIL_MultiTimer_t *tmr,
             RAIL_Time_t expectedTimeOfEvent,
             void *cbArg)
{
  if (tmr == tmr1) {
    // Timer 1 action
  } else {
    // Timer 2 action
  }
}

void main(void)
{
  // Initialize RAIL ...

  RAIL_ConfigMultiTimer(true);

  // Set up one timer for 1 ms from now and one at time 2000000 in the RAIL
  // timebase
  RAIL_SetMultiTimer(&tmr1, 1000, RAIL_TIME_RELATIVE, &timerCb, NULL);
  RAIL_SetMultiTimer(&tmr2, 2000000, RAIL_TIME_ABSOLUTE, &timerCb, NULL);

  // Run main loop
  while(1);
}

Modules#

RAIL_MultiTimer_t

RAIL_PacketTimeStamp_t

RAIL_MultiTimer

Enumerations#

enum
RAIL_TIME_ABSOLUTE = 0
RAIL_TIME_DELAY = 1
RAIL_TIME_DISABLED = 2
}

Specify a time offset in RAIL APIs.

enum
RAIL_PACKET_TIME_INVALID = 0
RAIL_PACKET_TIME_DEFAULT = 1
RAIL_PACKET_TIME_AT_PREAMBLE_START = 2
RAIL_PACKET_TIME_AT_PREAMBLE_START_USED_TOTAL = 3
RAIL_PACKET_TIME_AT_SYNC_END = 4
RAIL_PACKET_TIME_AT_SYNC_END_USED_TOTAL = 5
RAIL_PACKET_TIME_AT_PACKET_END = 6
RAIL_PACKET_TIME_AT_PACKET_END_USED_TOTAL = 7
RAIL_PACKET_TIME_COUNT = 8
}

The available packet timestamp position choices.

Typedefs#

typedef uint32_t

Time in microseconds.

typedef void(*
RAIL_TimerCallback_t)(RAIL_Handle_t cbArg)

A pointer to the callback called when the RAIL timer expires.

typedef void(*
RAIL_MultiTimerCallback_t)(struct RAIL_MultiTimer *tmr, RAIL_Time_t expectedTimeOfEvent, void *cbArg)

Callback fired when timer expires.

Functions#

Get the current RAIL time.

RAIL_SetTime(RAIL_Time_t time)

Set the current RAIL time.

RAIL_DelayUs(RAIL_Time_t microseconds)

Blocking delay routine for a specified number of microseconds.

RAIL_SetTimer(RAIL_Handle_t railHandle, RAIL_Time_t time, RAIL_TimeMode_t mode, RAIL_TimerCallback_t cb)

Schedule a timer to expire using the RAIL timebase.

RAIL_GetTimer(RAIL_Handle_t railHandle)

Return the absolute time that the RAIL timer was configured to expire.

RAIL_CancelTimer(RAIL_Handle_t railHandle)

Stop the currently scheduled RAIL timer.

bool
RAIL_IsTimerExpired(RAIL_Handle_t railHandle)

Check whether the RAIL timer has expired.

bool
RAIL_IsTimerRunning(RAIL_Handle_t railHandle)

Check whether the RAIL timer is currently running.

bool

Configure the RAIL software timer feature.

RAIL_SetMultiTimer(RAIL_MultiTimer_t *tmr, RAIL_Time_t expirationTime, RAIL_TimeMode_t expirationMode, RAIL_MultiTimerCallback_t callback, void *cbArg)

Start a multitimer instance.

bool
RAIL_CancelMultiTimer(RAIL_MultiTimer_t *tmr)

Stop the currently scheduled RAIL multitimer.

bool
RAIL_IsMultiTimerRunning(RAIL_MultiTimer_t *tmr)

Check if a given timer is running.

bool
RAIL_IsMultiTimerExpired(RAIL_MultiTimer_t *tmr)

Check if a given timer has expired.

RAIL_GetMultiTimer(RAIL_MultiTimer_t *tmr, RAIL_TimeMode_t timeMode)

Get time left before a given timer instance expires.

Enumeration Documentation#

RAIL_TimeMode_t#

RAIL_TimeMode_t

Specify a time offset in RAIL APIs.

Different APIs use the same constants and may provide more specifics about how they're used but the general use for each is described below.

Enumerator
RAIL_TIME_ABSOLUTE

The time specified is an exact time in the RAIL timebase.

RAIL_TIME_DELAY

The time specified is relative to the current time.

RAIL_TIME_DISABLED

The specified time is invalid and should be ignored.


Definition at line 229 of file common/rail_types.h

RAIL_PacketTimePosition_t#

RAIL_PacketTimePosition_t

The available packet timestamp position choices.

Enumerator
RAIL_PACKET_TIME_INVALID

Indicate that a timestamp is not to be or was not provided.

RAIL_PACKET_TIME_DEFAULT

Request the choice most expedient for RAIL to calculate, which may depend on the radio and/or its configuration.

RAIL_PACKET_TIME_AT_PREAMBLE_START

Request the timestamp corresponding to the first preamble bit sent or received.

RAIL_PACKET_TIME_AT_PREAMBLE_START_USED_TOTAL

Request the timestamp corresponding to the first preamble bit sent or received.

RAIL_PACKET_TIME_AT_SYNC_END

Request the timestamp corresponding to right after its last SYNC word bit has been sent or received.

RAIL_PACKET_TIME_AT_SYNC_END_USED_TOTAL

Request the timestamp corresponding to right after its last SYNC word bit has been sent or received.

RAIL_PACKET_TIME_AT_PACKET_END

Request the timestamp corresponding to right after its last bit has been sent or received.

RAIL_PACKET_TIME_AT_PACKET_END_USED_TOTAL

Request the timestamp corresponding to right after its last bit has been sent or received.

RAIL_PACKET_TIME_COUNT

A count of the choices in this enumeration.


Definition at line 312 of file common/rail_types.h

Typedef Documentation#

RAIL_Time_t#

RAIL_Time_t

Time in microseconds.


Definition at line 213 of file common/rail_types.h

RAIL_TimerCallback_t#

typedef void(* RAIL_TimerCallback_t) (RAIL_Handle_t cbArg) )(RAIL_Handle_t cbArg)

A pointer to the callback called when the RAIL timer expires.

Parameters
[in]cbArg

The argument passed to the callback.


Definition at line 220 of file common/rail_types.h

RAIL_MultiTimerCallback_t#

RAIL_MultiTimerCallback_t )(struct RAIL_MultiTimer *tmr, RAIL_Time_t expectedTimeOfEvent, void *cbArg)

Callback fired when timer expires.

Parameters
[in]tmr

A pointer to an expired timer.

[in]expectedTimeOfEvent

An absolute time event fired.

[in]cbArg

A user-supplied callback argument.


Definition at line 278 of file common/rail_types.h

Function Documentation#

RAIL_GetTime#

RAIL_Time_t RAIL_GetTime (void )

Get the current RAIL time.

Parameters
N/A

Returns

  • The RAIL time in microseconds. Note that this wraps after about 1.19 hours since it's stored in a 32 bit value.

Returns the current time in the RAIL timebase (microseconds). It can be used to compare with packet timestamps or to schedule transmits.


Definition at line 982 of file common/rail.h

RAIL_SetTime#

RAIL_Status_t RAIL_SetTime (RAIL_Time_t time)

Set the current RAIL time.

Parameters
[in]time

Set the RAIL timebase to this value in microseconds.

Returns

  • Status code indicating the success of the function call.

Warnings

  • Use this API only for testing purposes or in very limited circumstances during RAIL Timer Synchronization. Undefined behavior can result by calling it in multiprotocol or when the radio is not idle or timed events are active. Applications using RAIL_GetTime() may not be designed for discontinuous changes to the RAIL time base.


Definition at line 997 of file common/rail.h

RAIL_DelayUs#

RAIL_Status_t RAIL_DelayUs (RAIL_Time_t microseconds)

Blocking delay routine for a specified number of microseconds.

Parameters
[in]microseconds

Delay duration in microseconds.

Returns

  • Status code indicating success of the function call.

Use this RAIL API only for short blocking delays because it has less overhead than calling RAIL_GetTime() in a loop.

Note

  • Passing large delay values may give unpredictable results or trigger the Watchdog reset. Also, this function will start the clocks required for the RAIL timebase if they are not running, except between RAIL_Sleep() and RAIL_Wake() where the timer must remain stopped. Interrupts are not disabled during the delay, so the delay may be longer if an interrupt extends beyond the delay duration.


Definition at line 1016 of file common/rail.h

RAIL_SetTimer#

RAIL_Status_t RAIL_SetTimer (RAIL_Handle_t railHandle, RAIL_Time_t time, RAIL_TimeMode_t mode, RAIL_TimerCallback_t cb)

Schedule a timer to expire using the RAIL timebase.

Parameters
[in]railHandle

A RAIL instance handle.

[in]time

The timer's expiration time in the RAIL timebase.

[in]mode

Indicates whether the time argument is an absolute RAIL time or relative to the current RAIL time. Specifying mode RAIL_TIME_DISABLED is the same as calling RAIL_CancelTimer().

[in]cb

A pointer to a callback function that RAIL will call when the timer expires. May be NULL if no callback is desired.

Returns

Configures a timer to expire after a period in the RAIL timebase. This timer can be used to implement low-level protocol features.

Warnings

  • Attempting to schedule the timer when it is still running from a previous request is bad practice, unless the cb callback is identical to that used in the previous request, in which case the timer is rescheduled to the new time. Note that if the original timer expires as it is being rescheduled, the callback may or may not occur. It is generally good practice to cancel a running timer before rescheduling it to minimize ambiguity.


Definition at line 1042 of file common/rail.h

RAIL_GetTimer#

RAIL_Time_t RAIL_GetTimer (RAIL_Handle_t railHandle)

Return the absolute time that the RAIL timer was configured to expire.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • The absolute time that this timer was set to expire.

Provides the absolute time regardless of the RAIL_TimeMode_t that was passed into RAIL_SetTimer. Note that the time might be in the past if the timer has already expired. The return value is undefined if the timer was never set.


Definition at line 1058 of file common/rail.h

RAIL_CancelTimer#

RAIL_Status_t RAIL_CancelTimer (RAIL_Handle_t railHandle)

Stop the currently scheduled RAIL timer.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

Cancels the timer. If this function is called before the timer expires, the cb callback specified in the earlier RAIL_SetTimer() call will never be called.


Definition at line 1071 of file common/rail.h

RAIL_IsTimerExpired#

bool RAIL_IsTimerExpired (RAIL_Handle_t railHandle)

Check whether the RAIL timer has expired.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • true if the previously scheduled timer has expired and false otherwise.

Polling with this function is an alternative to the callback.


Definition at line 1082 of file common/rail.h

RAIL_IsTimerRunning#

bool RAIL_IsTimerRunning (RAIL_Handle_t railHandle)

Check whether the RAIL timer is currently running.

Parameters
[in]railHandle

A RAIL instance handle.

Returns

  • true if the timer is running and false if the timer has expired or was never set.


Definition at line 1091 of file common/rail.h

RAIL_ConfigMultiTimer#

bool RAIL_ConfigMultiTimer (bool enable)

Configure the RAIL software timer feature.

Parameters
[in]enable

Enables/disables the RAIL multitimer.

Returns

  • true if the multitimer was successfully enabled/disabled, false otherwise.

Turning this on will add a software timer layer above the physical RAIL timer so that the user can have as many timers as desired. It is not necessary to call this function if the MultiTimer APIs are not used.

Note

  • This function must be called before calling RAIL_SetMultiTimer. This function is a no-op on multiprotocol as this layer is already used under the hood. Do not call this function while the RAIL timer is running. Call RAIL_IsTimerRunning before enabling/disabling the multitimer. If the multitimer is not needed, do not call this function to allow the multitimer code to be dead stripped. If the multitimer is enabled for use, the multitimer and timer APIs can both be used. However, no timer can be in use while this function is being called.


Definition at line 1114 of file common/rail.h

RAIL_SetMultiTimer#

RAIL_Status_t RAIL_SetMultiTimer (RAIL_MultiTimer_t * tmr, RAIL_Time_t expirationTime, RAIL_TimeMode_t expirationMode, RAIL_MultiTimerCallback_t callback, void * cbArg)

Start a multitimer instance.

Parameters
[inout]tmr

A pointer to the timer instance to start.

[in]expirationTime

A time when the timer is set to expire.

[in]expirationMode

Select mode of expirationTime. See RAIL_TimeMode_t.

[in]callback

A function to call on timer expiry. See RAIL_MultiTimerCallback_t. NULL is a legal value.

[in]cbArg

An extra callback function parameter for the user application.

Returns

Note

  • It is legal to start an already running timer. If this is done, the timer will first be stopped before the new configuration is applied. If expirationTime is 0, the callback is called immediately.


Definition at line 1135 of file common/rail.h

RAIL_CancelMultiTimer#

bool RAIL_CancelMultiTimer (RAIL_MultiTimer_t * tmr)

Stop the currently scheduled RAIL multitimer.

Parameters
[inout]tmr

A RAIL timer instance handle.

Returns

  • true if the timer was successfully canceled; false if the timer was not running.

Cancels the timer. If this function is called before the timer expires, the cb callback specified in the earlier RAIL_SetTimer() call will never be called.


Definition at line 1152 of file common/rail.h

RAIL_IsMultiTimerRunning#

bool RAIL_IsMultiTimerRunning (RAIL_MultiTimer_t * tmr)

Check if a given timer is running.

Parameters
[in]tmr

A pointer to the timer structure to query.

Returns

  • true if the timer is running; false if the timer is not running.


Definition at line 1160 of file common/rail.h

RAIL_IsMultiTimerExpired#

bool RAIL_IsMultiTimerExpired (RAIL_MultiTimer_t * tmr)

Check if a given timer has expired.

Parameters
[in]tmr

A pointer to the timer instance.

Returns

  • true if the timer is expired; false if the timer is running.


Definition at line 1168 of file common/rail.h

RAIL_GetMultiTimer#

RAIL_Time_t RAIL_GetMultiTimer (RAIL_MultiTimer_t * tmr, RAIL_TimeMode_t timeMode)

Get time left before a given timer instance expires.

Parameters
[in]tmr

A pointer to the timer structure to query.

[in]timeMode

Indicates how the function provides the time remaining. By choosing RAIL_TimeMode_t::RAIL_TIME_ABSOLUTE, the function returns the absolute expiration time, and by choosing RAIL_TimeMode_t::RAIL_TIME_DELAY, the function returns the amount of time remaining before the timer's expiration.

Returns

  • Time left expressed in RAIL's time units. 0 if the soft timer is not running or has already expired.


Definition at line 1184 of file common/rail.h