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 time stamp, 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 railHandle)
{
// 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);
}
These functions can be used to get information about the current system time or to manipulate the RAIL timer.
The system time returned by sl_rail_get_time() is in the same timebase that is used throughout RAIL. Any callbacks or structures that provide a time stamp, such as sl_rail_rx_packet_details_t::time_received, 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 sl_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 sl_rail_set_timer() as NULL and poll for expiration with the sl_rail_is_timer_expired() function. See below for an example of the interrupt driven method of interacting with the timer.
void timer_callback(sl_rail_handle_t rail_handle)
{
// Timer callback action
}
void main(void)
{
// Initialize RAIL ...
// Set up a timer for 1 ms from now
sl_rail_set_timer(rail_handle, 1000, SL_RAIL_TIME_DELAY, &timer_callback);
// 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 sl_rail_config_multi_timer() function. This will allow you to set up as many timers as you want using the sl_rail_*_multi_timer() 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
sl_rail_multi_timer_t tmr_0, tmr_1;
void timer_callback(sl_rail_multi_timer_t *p_tmr,
sl_rail_time_t expected_time_of_event,
void *cb_arg)
{
if (p_tmr == &tmr_0) {
// Timer 1 action
} else {
// Timer 2 action
}
}
void main(void)
{
// Initialize RAIL ...
sl_rail_config_multi_timer(SL_RAIL_EFR32_HANDLE, true);
// Set up one timer for 1 ms from now and one at time 2000000 in the RAIL
// timebase
sl_rail_set_multi_timer(&tmr_0, 1000, SL_RAIL_TIME_DELAY, &timer_callback, NULL);
sl_rail_set_multi_timer(&tmr_1, 2000000, SL_RAIL_TIME_ABSOLUTE, &timer_callback, NULL);
// Run main loop
while(1);
}
Modules#
Enumerations#
Specify a time offset in RAIL APIs.
The available packet time stamp position choices.
Specify a time offset in RAIL APIs.
The available packet time stamp position choices.
Typedefs#
Time in microseconds.
A pointer to the callback called when the RAIL timer expires.
Callback fired when timer expires.
Time in microseconds.
A pointer to the callback called when the RAIL timer expires.
Callback fired when timer expires.
Functions#
Get the current RAIL time.
Set the current RAIL time.
Blocking delay routine for a specified number of microseconds.
Schedule a timer to expire using the RAIL timebase.
Return the absolute time that the RAIL timer was configured to expire.
Stop the currently scheduled RAIL timer.
Check whether the RAIL timer has expired.
Check whether the RAIL timer is currently running.
Configure the RAIL software timer feature.
Start a multitimer instance.
Stop the currently scheduled RAIL multitimer.
Check if a given timer is running.
Check if a given timer has expired.
Get time left before a given timer instance expires.
Get the current RAIL radio time.
Set the current RAIL radio time.
Blocking delay routine for a specified number of microseconds.
Schedule a timer to expire using the RAIL timebase.
Return the absolute time that the RAIL timer was configured to expire.
Stop the currently scheduled RAIL timer.
Check whether the RAIL timer has expired.
Check whether the RAIL timer is currently running.
Configure the RAIL software timer feature on a radio.
Start a multitimer instance.
Stop the currently scheduled RAIL multitimer.
Check if a given timer is running.
Check if a given timer has expired.
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.
DeprecatedRAIL 2.x synonym of sl_rail_time_mode_t.
| 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. |
RAIL_PacketTimePosition_t#
RAIL_PacketTimePosition_t
The available packet time stamp position choices.
DeprecatedRAIL 2.x synonym of sl_rail_packet_time_position_t.
| Enumerator | |
|---|---|
| RAIL_PACKET_TIME_INVALID | Indicate that a time stamp 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 time stamp corresponding to the first preamble bit sent or received. |
| RAIL_PACKET_TIME_AT_PREAMBLE_START_USED_TOTAL | Request the time stamp corresponding to the first preamble bit sent or received. |
| RAIL_PACKET_TIME_AT_SYNC_END | Request the time stamp corresponding to right after its last SYNC word bit has been sent or received. |
| RAIL_PACKET_TIME_AT_SYNC_END_USED_TOTAL | Request the time stamp corresponding to right after its last SYNC word bit has been sent or received. |
| RAIL_PACKET_TIME_AT_PACKET_END | Request the time stamp corresponding to right after its last bit has been sent or received. |
| RAIL_PACKET_TIME_AT_PACKET_END_USED_TOTAL | Request the time stamp corresponding to right after its last bit has been sent or received. |
| RAIL_PACKET_TIME_COUNT | A count of the choices in this enumeration. |
sl_rail_time_mode_t#
sl_rail_time_mode_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 | |
|---|---|
| SL_RAIL_TIME_ABSOLUTE | The time specified is an exact time in the RAIL timebase. |
| SL_RAIL_TIME_DELAY | The time specified is relative to the current time. |
| SL_RAIL_TIME_DISABLED | The specified time is invalid and should be ignored. |
sl_rail_packet_time_position_t#
sl_rail_packet_time_position_t
The available packet time stamp position choices.
| Enumerator | |
|---|---|
| SL_RAIL_PACKET_TIME_INVALID | Indicate that a time stamp is not to be or was not provided. |
| SL_RAIL_PACKET_TIME_DEFAULT | Request the choice most expedient for RAIL to calculate, which may depend on the radio and/or its configuration. |
| SL_RAIL_PACKET_TIME_AT_PREAMBLE_START | Request the time stamp corresponding to the first preamble bit sent or received. |
| SL_RAIL_PACKET_TIME_AT_PREAMBLE_START_USED_TOTAL | Request the time stamp corresponding to the first preamble bit sent or received. |
| SL_RAIL_PACKET_TIME_AT_SYNC_END | Request the time stamp corresponding to right after its last SYNC word bit has been sent or received. |
| SL_RAIL_PACKET_TIME_AT_SYNC_END_USED_TOTAL | Request the time stamp corresponding to right after its last SYNC word bit has been sent or received. |
| SL_RAIL_PACKET_TIME_AT_PACKET_END | Request the time stamp corresponding to right after its last bit has been sent or received. |
| SL_RAIL_PACKET_TIME_AT_PACKET_END_USED_TOTAL | Request the time stamp corresponding to right after its last bit has been sent or received. |
| SL_RAIL_PACKET_TIME_COUNT | A count of the choices in this enumeration. |
Typedef Documentation#
RAIL_TimerCallback_t#
typedef void(* RAIL_TimerCallback_t) (RAIL_Handle_t railHandle) )(RAIL_Handle_t railHandle)
A pointer to the callback called when the RAIL timer expires.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| [in] | railHandle | The RAIL handle that was used in the RAIL_SetTimer() call. |
DeprecatedRAIL 2.x synonym of sl_rail_timer_callback_t().
RAIL_MultiTimerCallback_t#
RAIL_MultiTimerCallback_t )(struct RAIL_MultiTimer *tmr, RAIL_Time_t expectedTimeOfEvent, void *cbArg)
Callback fired when timer expires.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| [in] | tmr | A pointer to an expired timer. | |
| [in] | expectedTimeOfEvent | An absolute time event fired. | |
| [in] | cbArg | A user-supplied callback argument. Since this callback doesn't include a parameter for the active RAIL_Handle_t that called RAIL_SetMultiTimer() it might be handy to pass that RAIL handle as the cbArg when calling RAIL_SetMultiTimer(). |
DeprecatedRAIL 2.x synonym of sl_rail_multi_timer_callback_t().
sl_rail_timer_callback_t#
typedef void(* sl_rail_timer_callback_t) (sl_rail_handle_t rail_handle) )(sl_rail_handle_t rail_handle)
A pointer to the callback called when the RAIL timer expires.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| [in] | rail_handle | The RAIL handle that was used in the sl_rail_set_timer() call. |
sl_rail_multi_timer_callback_t#
sl_rail_multi_timer_callback_t )(struct sl_rail_multi_timer *p_tmr, sl_rail_time_t expected_time_of_event, void *cb_arg)
Callback fired when timer expires.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| [in] | p_tmr | A pointer to an expired timer. | |
| [in] | expected_time_of_event | An absolute time event fired. | |
| [in] | cb_arg | A user-supplied callback argument. Since this callback doesn't include a parameter for the sl_rail_handle_t passed into sl_rail_set_multi_timer() it might be handy to also pass that RAIL handle as the cb_arg when calling sl_rail_set_multi_timer(). |
Function Documentation#
RAIL_GetTime#
RAIL_Time_t RAIL_GetTime (void )
Get the current RAIL time.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| void | 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 time stamps or to schedule transmits.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_get_time() with additional sl_rail_handle_t parameter.
RAIL_SetTime#
RAIL_Status_t RAIL_SetTime (RAIL_Time_t time)
Set the current RAIL time.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Time_t | [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.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_set_time() with additional sl_rail_handle_t parameter.
RAIL_DelayUs#
RAIL_Status_t RAIL_DelayUs (RAIL_Time_t microseconds)
Blocking delay routine for a specified number of microseconds.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Time_t | [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.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_delay_us() with additional sl_rail_handle_t parameter.
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
| RAIL_Time_t | [in] | time | The timer's expiration time in the RAIL timebase. |
| RAIL_TimeMode_t | [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(). |
| RAIL_TimerCallback_t | [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
RAIL_STATUS_NO_ERROR on success and RAIL_STATUS_INVALID_PARAMETER if the timer can't be scheduled.
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.
DeprecatedRAIL 2.x synonym of sl_rail_set_timer().
RAIL_GetTimer#
RAIL_Time_t RAIL_GetTimer (RAIL_Handle_t railHandle)
Return the absolute time that the RAIL timer was configured to expire.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [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.
DeprecatedRAIL 2.x synonym of sl_rail_get_timer().
RAIL_CancelTimer#
RAIL_Status_t RAIL_CancelTimer (RAIL_Handle_t railHandle)
Stop the currently scheduled RAIL timer.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
RAIL_STATUS_NO_ERROR on success and RAIL_STATUS_INVALID_CALL if the timer is 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.
DeprecatedRAIL 2.x synonym of sl_rail_cancel_timer().
RAIL_IsTimerExpired#
bool RAIL_IsTimerExpired (RAIL_Handle_t railHandle)
Check whether the RAIL timer has expired.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [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.
DeprecatedRAIL 2.x synonym of sl_rail_is_timer_expired().
RAIL_IsTimerRunning#
bool RAIL_IsTimerRunning (RAIL_Handle_t railHandle)
Check whether the RAIL timer is currently running.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_Handle_t | [in] | railHandle | A RAIL instance handle. |
Returns
true if the timer is running and false if the timer has expired or was never set.
DeprecatedRAIL 2.x synonym of sl_rail_is_timer_running().
RAIL_ConfigMultiTimer#
bool RAIL_ConfigMultiTimer (bool enable)
Configure the RAIL software timer feature.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| bool | [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.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_config_multi_timer() with additional sl_rail_handle_t parameter.
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_MultiTimer_t * | [inout] | tmr | A pointer to the timer instance to start. |
| RAIL_Time_t | [in] | expirationTime | A time when the timer is set to expire. |
| RAIL_TimeMode_t | [in] | expirationMode | Select mode of expirationTime. See RAIL_TimeMode_t. |
| RAIL_MultiTimerCallback_t | [in] | callback | A function to call on timer expiry. See RAIL_MultiTimerCallback_t(). May be NULL if no callback is desired. |
| void * | [in] | cbArg | An extra callback function parameter for the user application. Since the RAIL_MultiTimerCallback_t() callback function lacks a RAIL_Handle_t parameter this can be used to pass the current RAIL handle if desired. |
Returns
RAIL_STATUS_NO_ERROR on success.
RAIL_STATUS_INVALID_PARAMETER if tmr has an illegal value or if timeout is in the past.
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.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_set_multi_timer() with additional sl_rail_handle_t parameter.
RAIL_CancelMultiTimer#
bool RAIL_CancelMultiTimer (RAIL_MultiTimer_t * tmr)
Stop the currently scheduled RAIL multitimer.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_MultiTimer_t * | [inout] | tmr | A pointer to a RAIL timer instance. |
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.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_cancel_multi_timer() with additional sl_rail_handle_t parameter.
RAIL_IsMultiTimerRunning#
bool RAIL_IsMultiTimerRunning (RAIL_MultiTimer_t * tmr)
Check if a given timer is running.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_MultiTimer_t * | [inout] | tmr | A pointer to the timer instance. |
Returns
true if the timer is running; false if the timer is not running or tmr is not a timer instance.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_is_multi_timer_running() with additional sl_rail_handle_t parameter.
RAIL_IsMultiTimerExpired#
bool RAIL_IsMultiTimerExpired (RAIL_MultiTimer_t * tmr)
Check if a given timer has expired.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_MultiTimer_t * | [inout] | tmr | A pointer to the timer instance. |
Returns
true if the timer has expired or tmr is not a timer instance; false if the timer is running.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_is_multi_timer_expired() with additional sl_rail_handle_t parameter.
RAIL_GetMultiTimer#
RAIL_Time_t RAIL_GetMultiTimer (RAIL_MultiTimer_t * tmr, RAIL_TimeMode_t timeMode)
Get time left before a given timer instance expires.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| RAIL_MultiTimer_t * | [inout] | tmr | A pointer to the timer instance to query. |
| RAIL_TimeMode_t | [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 timer is not running or has already expired.
DeprecatedThis RAIL 2.x function has been replaced in RAIL 3 by sl_rail_get_multi_timer() with additional sl_rail_handle_t parameter.
sl_rail_get_time#
sl_rail_time_t sl_rail_get_time (sl_rail_handle_t rail_handle)
Get the current RAIL radio time.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A radio-generic or real RAIL instance handle. |
Returns
The RAIL radio time in microseconds. Note that this wraps after about 1.19 hours since it's stored in a 32 bit value.
Returns the current radio time in the RAIL timebase (microseconds). It can be used to compare with packet time stamps or to schedule transmits on that radio.
sl_rail_set_time#
sl_rail_status_t sl_rail_set_time (sl_rail_handle_t rail_handle, sl_rail_time_t time)
Set the current RAIL radio time.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A radio-generic or real RAIL instance handle. |
| sl_rail_time_t | [in] | time | Set the RAIL radio time 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 sl_rail_get_time() may not be designed for discontinuous changes to the RAIL time base.
sl_rail_delay_us#
sl_rail_status_t sl_rail_delay_us (sl_rail_handle_t rail_handle, sl_rail_time_t microseconds)
Blocking delay routine for a specified number of microseconds.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A radio-generic or real RAIL instance handle. |
| sl_rail_time_t | [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 sl_rail_get_time() 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 sl_rail_sleep() and sl_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.
sl_rail_set_timer#
sl_rail_status_t sl_rail_set_timer (sl_rail_handle_t rail_handle, sl_rail_time_t time, sl_rail_time_mode_t mode, sl_rail_timer_callback_t expiration_callback)
Schedule a timer to expire using the RAIL timebase.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
| sl_rail_time_t | [in] | time | The timer's expiration time in the RAIL timebase. |
| sl_rail_time_mode_t | [in] | mode | Indicates whether the time argument is an absolute RAIL time or relative to the current RAIL time. Specifying mode SL_RAIL_TIME_DISABLED is the same as calling sl_rail_cancel_timer(). |
| sl_rail_timer_callback_t | [in] | expiration_callback | A pointer to a callback function that RAIL will call when the timer expires. May be NULL if no callback is desired. |
Returns
SL_RAIL_STATUS_NO_ERROR on success and SL_RAIL_STATUS_INVALID_PARAMETER if the timer can't be scheduled.
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.
sl_rail_get_timer#
sl_rail_time_t sl_rail_get_timer (sl_rail_handle_t rail_handle)
Return the absolute time that the RAIL timer was configured to expire.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
The absolute time that this timer was set to expire.
Provides the absolute time regardless of the sl_rail_time_mode_t that was passed into sl_rail_set_timer(). 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.
sl_rail_cancel_timer#
sl_rail_status_t sl_rail_cancel_timer (sl_rail_handle_t rail_handle)
Stop the currently scheduled RAIL timer.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
SL_RAIL_STATUS_NO_ERROR on success and SL_RAIL_STATUS_INVALID_CALL if the timer is not running.
Cancels the timer. If this function is called before the timer expires, the expiration_callback specified in the earlier sl_rail_set_timer() call will never be called.
sl_rail_is_timer_expired#
bool sl_rail_is_timer_expired (sl_rail_handle_t rail_handle)
Check whether the RAIL timer has expired.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
true if the previously scheduled timer has expired and false otherwise.
Polling with this function is an alternative to the expiration_callback.
sl_rail_is_timer_running#
bool sl_rail_is_timer_running (sl_rail_handle_t rail_handle)
Check whether the RAIL timer is currently running.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A real RAIL instance handle. |
Returns
true if the timer is running and false if the timer has expired or was never set.
sl_rail_config_multi_timer#
sl_rail_status_t sl_rail_config_multi_timer (sl_rail_handle_t rail_handle, bool enable)
Configure the RAIL software timer feature on a radio.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A radio-generic or real RAIL instance handle. |
| bool | [in] | enable | Enables/disables the RAIL multitimer. |
Returns
SL_RAIL_STATUS_NO_ERROR if the multitimer was successfully enabled/disabled, an appropriate error 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 multi_timer APIs are not used.
Note
This function must be called before calling sl_rail_set_multi_timer(). 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 sl_rail_is_timer_running() 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.
sl_rail_set_multi_timer#
sl_rail_status_t sl_rail_set_multi_timer (sl_rail_handle_t rail_handle, sl_rail_multi_timer_t * p_tmr, sl_rail_time_t expiration_time, sl_rail_time_mode_t expiration_mode, sl_rail_multi_timer_callback_t expiration_callback, void * cb_arg)
Start a multitimer instance.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A radio-generic or real RAIL instance handle. |
| sl_rail_multi_timer_t * | [inout] | p_tmr | A pointer to the timer instance to start. |
| sl_rail_time_t | [in] | expiration_time | A time when the timer is set to expire. |
| sl_rail_time_mode_t | [in] | expiration_mode | Select mode of expiration_time. See sl_rail_time_mode_t. |
| sl_rail_multi_timer_callback_t | [in] | expiration_callback | A function to call on timer expiry. See sl_rail_multi_timer_callback_t(). May be NULL if no callback is desired. |
| void * | [in] | cb_arg | An extra callback function parameter for the user application. Since the sl_rail_multi_timer_callback_t() callback function lacks a sl_rail_handle_t parameter this can be used to pass the current RAIL handle if desired. |
Returns
SL_RAIL_STATUS_NO_ERROR on success.
SL_RAIL_STATUS_INVALID_PARAMETER if tmr has an illegal value or if timeout is in the past.
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 expiration_time is 0, the callback is called immediately.
sl_rail_cancel_multi_timer#
sl_rail_status_t sl_rail_cancel_multi_timer (sl_rail_handle_t rail_handle, sl_rail_multi_timer_t * p_tmr)
Stop the currently scheduled RAIL multitimer.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A radio-generic or real RAIL instance handle. |
| sl_rail_multi_timer_t * | [inout] | p_tmr | A pointer to a RAIL timer instance. |
Returns
SL_RAIL_STATUS_NO_ERROR if the timer was successfully canceled, or an error status otherwise.
Cancels the timer. If this function is called before the timer expires, the expiration_callback specified in the earlier sl_rail_set_timer() call will never be called.
sl_rail_is_multi_timer_running#
bool sl_rail_is_multi_timer_running (sl_rail_handle_t rail_handle, sl_rail_multi_timer_t * p_tmr)
Check if a given timer is running.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A radio-generic or real RAIL instance handle. |
| sl_rail_multi_timer_t * | [inout] | p_tmr | A pointer to the timer instance. |
Returns
true if the timer is running; false if the timer is not running or p_tmr is not a timer instance associated with rail_handle.
sl_rail_is_multi_timer_expired#
bool sl_rail_is_multi_timer_expired (sl_rail_handle_t rail_handle, sl_rail_multi_timer_t * p_tmr)
Check if a given timer has expired.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A radio-generic or real RAIL instance handle. |
| sl_rail_multi_timer_t * | [inout] | p_tmr | A pointer to the timer instance. |
Returns
true if the timer has expired or p_tmr is not a timer instance associated with rail_handle; false if the timer is running.
sl_rail_get_multi_timer#
sl_rail_time_t sl_rail_get_multi_timer (sl_rail_handle_t rail_handle, sl_rail_multi_timer_t * p_tmr, sl_rail_time_mode_t time_mode)
Get time left before a given timer instance expires.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rail_handle_t | [in] | rail_handle | A radio-generic or real RAIL instance handle. |
| sl_rail_multi_timer_t * | [inout] | p_tmr | A pointer to the timer instance to query. |
| sl_rail_time_mode_t | [in] | time_mode | Indicates how the function provides the time remaining. By choosing sl_rail_time_mode_t::SL_RAIL_TIME_ABSOLUTE, the function returns the absolute expiration time, and by choosing sl_rail_time_mode_t::SL_RAIL_TIME_DELAY, the function returns the amount of time remaining before the timer's expiration. |
Returns
Time left expressed in the RAIL radio's time units. 0 if the timer is not running or has already expired.