System Timing
Functionality related to the RAIL timer and general system time.
Data Structures | |
struct | RAIL_MultiTimer_t |
RAIL timer state structure. | |
struct | RAIL_PacketTimeStamp_t |
Information needed to calculate and represent a packet timestamp. |
Typedefs | |
typedef void(* | RAIL_TimerCallback_t) (RAIL_Handle_t cbArg) |
Pointer to 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. |
Enumerations | |
enum | RAIL_TimeMode_t { RAIL_TIME_ABSOLUTE, RAIL_TIME_DELAY, RAIL_TIME_DISABLED } |
Specifies a time offset in RAIL APIs. | |
enum | RAIL_SleepConfig_t { RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED, RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED } |
The config. | |
enum | RAIL_PacketTimePosition_t { 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 } |
The available packet timestamp position choices. |
Functions | |
bool | RAIL_ConfigMultiTimer (bool enable) |
Configure the RAIL timer plugin. | |
RAIL_Time_t | RAIL_GetTime (void) |
Gets the current RAIL time. | |
RAIL_Status_t | RAIL_SetTime (RAIL_Time_t time) |
Sets the current RAIL time. | |
RAIL_Status_t | RAIL_SetTimer (RAIL_Handle_t railHandle, RAIL_Time_t time, RAIL_TimeMode_t mode, RAIL_TimerCallback_t cb) |
Schedules a timer to expire using the RAIL timebase. | |
RAIL_Time_t | RAIL_GetTimer (RAIL_Handle_t railHandle) |
Returns the absolute time that the RAIL timer was configured to expire. | |
void | RAIL_CancelTimer (RAIL_Handle_t railHandle) |
Stops the currently scheduled RAIL timer. | |
bool | RAIL_IsTimerExpired (RAIL_Handle_t railHandle) |
Checks whether the RAIL timer has expired. | |
bool | RAIL_IsTimerRunning (RAIL_Handle_t railHandle) |
Checks whether the RAIL timer is currently running. | |
RAIL_Status_t | RAIL_SetMultiTimer (RAIL_MultiTimer_t *tmr, RAIL_Time_t expirationTime, RAIL_TimeMode_t expirationMode, RAIL_MultiTimerCallback_t callback, void *cbArg) |
Starts a multitimer instance. | |
bool | RAIL_CancelMultiTimer (RAIL_MultiTimer_t *tmr) |
Stops the currently scheduled RAIL multi timer. | |
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_Time_t | RAIL_GetMultiTimer (RAIL_MultiTimer_t *tmr, RAIL_TimeMode_t timeMode) |
Get time left before a given timer instance expires. | |
RAIL_Status_t | RAIL_ConfigSleep (RAIL_Handle_t railHandle, RAIL_SleepConfig_t sleepConfig) |
Initialize RAIL timer synchronization. | |
RAIL_Status_t | RAIL_Sleep (uint16_t wakeupProcessTime, bool *deepSleepAllowed) |
Stop the RAIL timer and prepare RAIL for sleep. | |
RAIL_Status_t | RAIL_Wake (RAIL_Time_t elapsedTime) |
Wake RAIL from sleep and restart the RAIL timer. |
Detailed Description
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 that return a timestamp, such as rxPacketReceived() callback, will use this same timebase as will any APIs that accept an absolute time for scheduling their action. Throughout this documentation the timebase used for this will be referred to as the RAIL timebase. This is currently a value in microseconds from chip boot time. This 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 your system, but will be especially helpful for timing protocol based state machines and other systems that interact with the radio. If you do not want to process the expiration in interrupt context, leave the timerExpired() callback empty and poll for expiration with the RAIL_IsTimerExpired() function.
Typedef Documentation
◆ RAIL_MultiTimerCallback_t
RAIL_MultiTimerCallback_t |
Callback fired when timer expires.
- Parameters
-
[in] tmr
pointer to expired timer [in] expectedTimeOfEvent
Absolute time event fired [in] cbArg
User supplied callback argument
Definition at line 1185
of file rail_types.h
.
◆ RAIL_TimerCallback_t
typedef void(* RAIL_TimerCallback_t) (RAIL_Handle_t cbArg) |
Pointer to callback called when the RAIL timer expires.
- Parameters
-
[in] cbArg
The argument passed to the callback.
- Returns
- void.
Definition at line 1135
of file rail_types.h
.
Enumeration Type Documentation
◆ RAIL_PacketTimePosition_t
The available packet timestamp position choices.
Enumerator | |
---|---|
RAIL_PACKET_TIME_INVALID | Indicates timestamp is not to be, or was not, provided. Useful if the application doesn't care about packet timestamps and doesn't want RAIL to spend time calculating one. |
RAIL_PACKET_TIME_DEFAULT | Requests the choice most expedient for RAIL to calculate, which may depend on the radio and/or its configuration. The actual choice would always be reflected in the timePosition field of RAIL_RxPacketDetails_t or RAIL_TxPacketDetails_t returned, and would never be one of the _USED_TOTAL values. |
RAIL_PACKET_TIME_AT_PREAMBLE_START | Requests the timestamp corresponding to the first preamble bit sent or received. Indicates that timestamp did not require using totalPacketBytes. |
RAIL_PACKET_TIME_AT_PREAMBLE_START_USED_TOTAL | Requests the timestamp corresponding to the first preamble bit sent or received. Indicates that timestamp did require using totalPacketBytes. |
RAIL_PACKET_TIME_AT_SYNC_END | Requests the timestamp corresponding to right after its last SYNC word bit has been sent or received. Indicates that timestamp did not require using totalPacketBytes. |
RAIL_PACKET_TIME_AT_SYNC_END_USED_TOTAL | Requests the timestamp corresponding to right after its last SYNC word bit has been sent or received. Indicates that timestamp did require using totalPacketBytes. |
RAIL_PACKET_TIME_AT_PACKET_END | Reqeusts the timestamp corresponding to right after its last bit has been sent or received. Indicates that timestamp did not require using totalPacketBytes. |
RAIL_PACKET_TIME_AT_PACKET_END_USED_TOTAL | Reqeusts the timestamp corresponding to right after its last bit has been sent or received. Indicates that timestamp did require using totalPacketBytes. |
RAIL_PACKET_TIME_COUNT | Count of the choices in this enum. |
Definition at line 1220
of file rail_types.h
.
◆ RAIL_SleepConfig_t
enum RAIL_SleepConfig_t |
◆ RAIL_TimeMode_t
enum RAIL_TimeMode_t |
Specifies 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. The given event should happen at exactly that time. If this time is already in the past, an error is returned. Because the RAIL timebase wraps at 32 bits, there is no real 'past'. Instead, any event greater than 3/4 of the way into the future is considered to be in the past. |
RAIL_TIME_DELAY | The time specified is relative to the current time. The event should occur that many ticks in the future. Delays are only guaranteed at least as long as the value specified. An overhead may occur between the time when the API is called and when the delay starts. As a result, using this for operations that must happen at an exact given time is not recommended. For that, you must use RAIL_TIME_ABSOLUTE delays. Note that, if you specify a delay 0, that event is triggered as soon as possible. This is different than specifying an absolute time of now which would return an error unless it was possible. |
RAIL_TIME_DISABLED | The specified time is invalid and should be ignored. For some APIs this can also indicate that any previously stored delay should be invalidated and disabled. |
Definition at line 1144
of file rail_types.h
.
Function Documentation
◆ RAIL_CancelMultiTimer()
bool RAIL_CancelMultiTimer | ( | RAIL_MultiTimer_t * | tmr | ) |
Stops the currently scheduled RAIL multi timer.
- Parameters
-
[in,out] tmr
A RAIL timer instance handle.
- Returns
- true if timer was successfully cancelled. false if 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.
◆ RAIL_CancelTimer()
void RAIL_CancelTimer | ( | RAIL_Handle_t | railHandle | ) |
Stops the currently scheduled RAIL timer.
- Parameters
-
[in] railHandle
A RAIL instance handle.
- Returns
- void.
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.
◆ RAIL_ConfigMultiTimer()
bool RAIL_ConfigMultiTimer | ( | bool | enable | ) |
Configure the RAIL timer plugin.
- Parameters
-
[in] enable
Enables/Disables the RAIL multitimer.
- Returns
- True if the multitimer was successfully enabled/disabled, false otherwise.
- Note
- This function must be called before calling RAIL_SetMultiTimer. This function must be called to use the timer driver plugin with the RAIL single protocol library. This function should not be called 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. This will allow the multitimer code to be dead stripped.
◆ RAIL_ConfigSleep()
RAIL_Status_t RAIL_ConfigSleep | ( | RAIL_Handle_t | railHandle, |
RAIL_SleepConfig_t | sleepConfig |
||
) |
Initialize RAIL timer synchronization.
- Parameters
-
[in] railHandle
A RAIL instance handle. [in] sleepConfig
A sleep configuration.
- Returns
- Status code indicating success of the function call.
◆ 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
An indication as to 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.
◆ RAIL_GetTime()
RAIL_Time_t RAIL_GetTime | ( | void |
| ) |
Gets the current RAIL time.
- Returns
- Returns the RAIL timebase in microseconds. Note that this wraps after around 1.19 hours since it's stored in a 32bit value.
Returns the current time in the RAIL timebase (microseconds). It can be used to compare with packet timestamps or to schedule transmits.
◆ RAIL_GetTimer()
RAIL_Time_t RAIL_GetTimer | ( | RAIL_Handle_t | railHandle | ) |
Returns 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.
It will give the absolute time regardless of the RAIL_TimeMode_t that was passed into RAIL_SetTimer. Note that this time might be in the past if the timer already expired. The return value is undefined if the timer was never set.
◆ RAIL_IsMultiTimerExpired()
bool RAIL_IsMultiTimerExpired | ( | RAIL_MultiTimer_t * | tmr | ) |
Check if a given timer has expired.
- Parameters
-
[in] tmr
A pointer to the timer structure to query.
- Returns
- true if timer is expired. false if timer is running.
◆ 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 timer is running. false if timer is not running.
◆ RAIL_IsTimerExpired()
bool RAIL_IsTimerExpired | ( | RAIL_Handle_t | railHandle | ) |
Checks 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 via this function can be used as an alternative to the callback.
◆ RAIL_IsTimerRunning()
bool RAIL_IsTimerRunning | ( | RAIL_Handle_t | railHandle | ) |
Checks whether the RAIL timer is currently running.
- Parameters
-
[in] railHandle
A RAIL instance handle.
- Returns
- Returns true if the timer is running and false if the timer has expired or was never set.
◆ 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 |
||
) |
Starts a multitimer instance.
- Note
- It is legal to start an already running timer. If this is done, the timer will first be stopped before the new configurations are applied. If expirationTime is 0, the callback will be called immediately.
- Parameters
-
[in,out] tmr
A pointer to the timer instance to start. [in] expirationTime
When the timer is to expire. [in] expirationMode
Select mode of expirationTime. See RAIL_TimeMode_t. [in] callback
Function to call on timer expiry. See RAIL_MultiTimerCallback_t. NULL is a legal value. [in] cbArg
Extra callback function parameter for user application.
- Returns
- RAIL_STATUS_NO_ERROR on success.
RAIL_STATUS_INVALID_PARAMETER if tmr has an illegal value or if timeout is in the past.
◆ RAIL_SetTime()
RAIL_Status_t RAIL_SetTime | ( | RAIL_Time_t | time | ) |
Sets the current RAIL time.
- Parameters
-
[in] time
Set the RAIL timebase to this value in microseconds.
- Returns
- Status code indicating success of the function call.
Sets the current time in the RAIL timebase in microseconds.
◆ RAIL_SetTimer()
RAIL_Status_t RAIL_SetTimer | ( | RAIL_Handle_t | railHandle, |
RAIL_Time_t | time, |
||
RAIL_TimeMode_t | mode, |
||
RAIL_TimerCallback_t | cb |
||
) |
Schedules 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
The callback for RAIL to call when the timer expires.
- Returns
- RAIL_STATUS_NO_ERROR on success and RAIL_STATUS_INVALID_PARAMETER if the timer could not be scheduled.
Configures a timer to expire after some period in the RAIL timebase. This timer can be used to implement low level protocol features.
- Warning
- It is an error to attempt to schedule the timer when it is still running from a previous request – 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 in this case 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 such ambiguity.
◆ RAIL_Sleep()
RAIL_Status_t RAIL_Sleep | ( | uint16_t | wakeupProcessTime, |
bool * | deepSleepAllowed |
||
) |
Stop the RAIL timer and prepare RAIL for sleep.
- Parameters
-
[in] wakeupProcessTime
Time in microseconds that the application and hardware need to recover from sleep state. [out] deepSleepAllowed
true - system can go to deep sleep. false - system should not go to deep sleep. Deep sleep should be blocked in this case.
- Returns
- Status code indicating success of the function call.
- Warning
- The active RAIL configuration must be idle for enabling sleep.
◆ RAIL_Wake()
RAIL_Status_t RAIL_Wake | ( | RAIL_Time_t | elapsedTime | ) |
Wake RAIL from sleep and restart the RAIL timer.
- Parameters
-
[in] elapsedTime
Add the sleep duration to the RAIL timer before restarting the RAIL timer.
- Returns
- Status code indicating success of the function call.
If timer sync was enabled by RAIL_ConfigSleep, synchronize the RAIL timer using an alternate timer. Otherwise, add elapsedTime to the RAIL timer.