Sleep Timer
Description
Sleep Timer.
The sleeptimer.c and sleeptimer.h source files for the SLEEPTIMER device driver library are in the service/sleeptimer folder.
Introduction
The Sleeptimer driver provides software timers, delays, timekeeping and date functionalities using a low-frequency real-time clock peripheral.
All Silicon Labs microcontrollers equipped with the RTC or RTCC peripheral are currently supported. Only one instance of this driver can be initialized by the application.
Functionalities overview
Software Timers
This functionality allows the user to create periodic and one shot timers. A user callback can be associated with a timer and is called when the timer expires.
Timer structures must be allocated by the user. The function is called from within an interrupt handler with interrupts enabled.
Timekeeping
A 64-bits tick counter is accessible through the
- uint64_t sl_sleeptimer_get_tick_count64(void) API. It keeps the tick count since the initialization of the driver
The
SL_SLEEPTIMER_WALLCLOCK_CONFIG
configuration enables a UNIX timestamp (seconds count since January 1, 1970, 00:00:00).
This timestamp can be retrieved/modified using the following API:
- sl_sleeptimer_timestamp_t sl_sleeptimer_get_time(void) ;
- sl_status_t sl_sleeptimer_set_time(sl_sleeptimer_timestamp_t time) ;
Convenience conversion functions are provided to convert UNIX timestamp to/from NTP and Zigbee cluster format :
- sl_status_t sl_sleeptimer_convert_unix_time_to_ntp(sl_sleeptimer_timestamp_t time, uint32_t *ntp_time) ;
- sl_status_t sl_sleeptimer_convert_ntp_time_to_unix(uint32_t ntp_time, sl_sleeptimer_timestamp_t *time) ;
- sl_status_t sl_sleeptimer_convert_unix_time_to_zigbee(sl_sleeptimer_timestamp_t time, uint32_t *zigbee_time) ;
- sl_status_t sl_sleeptimer_convert_zigbee_time_to_unix(uint32_t zigbee_time, sl_sleeptimer_timestamp_t *time) ;
Date
The previously described internal timestamp can also be retrieved/modified in a date format sl_sleeptimer_date_t.
API :
- sl_status_t sl_sleeptimer_get_datetime(sl_sleeptimer_date_t *date) ;
- sl_status_t sl_sleeptimer_set_datetime(sl_sleeptimer_date_t *date) ;
Frequency Setup and Tick Count
This driver works with a configurable time unit called tick.
The frequency of the ticks is based on the clock source and the internal frequency divider.
One of the following clock sources must be enabled before initializing the sleeptimer:
- LFXO: external crystal oscillator. Typically running at 32.768 kHz.
- LFRCO: internal oscillator running at 32.768 kHz
- ULFRCO: Ultra low-frequency oscillator running at 1.000 kHz
The frequency divider is selected with the
SL_SLEEPTIMER_FREQ_DIVIDER
configuration. Its value must be a power of two within the range of 1 to 32. The number of ticks per second (sleeptimer frequency) is dictated by the following formula:
Tick (seconds) = 1 / (clock_frequency / frequency_divider)
The highest resolution for a tick is 30.5 us. It is achieved with a 32.768 kHz clock and a divider of 1.
Getting Started
Clock Selection
The sleeptimer relies on the hardware timer to operate. The hardware timer peripheral must be properly clocked from the application. Selecting the appropriate timer is crucial for design considerations. Each timer can potentially be used as a sleeptimer and is also available to the user. However, note that if a timer is used by the sleeptimer, it can't be used by the application and vice versa.
Selection in a Project without Micrium OS
When RTC, RTCC, or BURTC is selected, the clock source for the peripheral must be configured and enabled in the application before initializing the sleeptimer module or any communication stacks. Most of the time, it consists in enabling the desired oscillators and setting up the clock source for the peripheral, like in the following example:
Clock Branch Select
Clock | Enum | Description | Frequency |
---|---|---|---|
LFXO | cmuSelect_LFXO | Low-frequency crystal oscillator | 32.768 Khz |
LFRCO | cmuSelect_LFRCO | Low-frequency RC oscillator | 32.768 Khz |
ULFRCO | cmuSelect_ULFRCO | Ultra low-frequency RC oscillator | 1 Khz |
Timer Clock Enable
Module | Enum | Description |
---|---|---|
RTCC | cmuClock_RTCC | Real-time counter and calendar clock (LF E branch) |
RTC | cmuClock_RTC | Real time counter clock (LF A branch) |
BURTC | cmuClock_BURTC | BURTC clock (EM4 Group A branch) |
When the Radio internal RTC (PRORTC) is selected, it is not necessary to configure the clock source for the peripheral. However, it is important to enable the desired oscillator before initializing the sleeptimer module or any communication stacks. The best oscillator available (LFXO being the first choice) will be used by the sleeptimer at initalization. The following example shows how the desired oscilator should be enabled:
Clock Selection in a Project with Micrium OS
When Micrium OS is used, a BSP (all instances) is provided that sets up some parts of the clock tree. The sleeptimer clock source will be enabled by this bsp. However, the desired oscillator remains configurable from the file bsp_cfg.h .
The configuration
BSP_LF_CLK_SEL
determines which oscillator will be used by the sleeptimer's hardware timer peripheral. It can take the following values:
Config | Description | Frequency |
---|---|---|
BSP_LF_CLK_LFXO | Low-frequency crystal oscillator | 32.768 Khz |
BSP_LF_CLK_LFRCO | Low-frequency RC oscillator | 32.768 Khz |
BSP_LF_CLK_ULFRCO | Ultra low-frequency RC oscillator | 1 Khz |
Configuration Options
SL_SLEEPTIMER_PERIPHERAL
can be set to one of the following values:
Config | Description |
---|---|
SL_SLEEPTIMER_PERIPHERAL_DEFAULT
|
Selects either RTC or RTCC, depending of what is available on the platform. |
SL_SLEEPTIMER_PERIPHERAL_RTCC
|
Selects RTCC |
SL_SLEEPTIMER_PERIPHERAL_RTC
|
Selects RTC |
SL_SLEEPTIMER_PERIPHERAL_PRORTC
|
Selects Internal radio RTC. Available only on EFR32XG13, EFR32XG14, EFR32XG21 and EFR32XG22 families. |
SL_SLEEPTIMER_PERIPHERAL_BURTC
|
Selects BURTC. Not available on Series 0 devices. |
SL_SLEEPTIMER_WALLCLOCK_CONFIG
must be set to 1 to enable timestamp and date functionnalities.
SL_SLEEPTIMER_FREQ_DIVIDER
must be a power of 2 within the range 1 to 32. When
SL_SLEEPTIMER_PERIPHERAL
is set to
SL_SLEEPTIMER_PERIPHERAL_PRORTC
,
SL_SLEEPTIMER_FREQ_DIVIDER
must be set to 1.
SL_SLEEPTIMER_PRORTC_HAL_OWNS_IRQ_HANDLER
is only meaningful when
SL_SLEEPTIMER_PERIPHERAL
is set to
SL_SLEEPTIMER_PERIPHERAL_PRORTC
. Set to 1 if no communication stack is used in your project. Otherwise, must be set to 0.
The API
This section contains brief descriptions of the API functions. For more information about input and output parameters and return values, click on the hyperlinked function names. Most functions return an error code,
SL_STATUS_OK
is returned on success, see sl_status.h for other error codes.
The application code must include the sl_sleeptimer.h header file.
All API functions can be called from within interrupt handlers.
sl_sleeptimer_init()
These functions initialize the sleeptimer driver. Typically, sl_sleeptimer_init() is called once in the startup code.
sl_sleeptimer_start_timer()
Start a one shot 32 bits timer. When a timer expires, a user-supplied callback function is called. A pointer to this function is passed to sl_sleeptimer_start_timer(). See
callback
for details of the callback prototype.
sl_sleeptimer_restart_timer()
Restart a one shot 32 bits timer. When a timer expires, a user-supplied callback function is called. A pointer to this function is passed to sl_sleeptimer_start_timer(). See
callback
for details of the callback prototype.
sl_sleeptimer_start_periodic_timer()
Start a periodic 32 bits timer. When a timer expires, a user-supplied callback function is called. A pointer to this function is passed to sl_sleeptimer_start_timer(). See
callback
for details of the callback prototype.
sl_sleeptimer_restart_periodic_timer()
Restart a periodic 32 bits timer. When a timer expires, a user-supplied callback function is called. A pointer to this function is passed to sl_sleeptimer_start_timer(). See
callback
for details of the callback prototype.
sl_sleeptimer_stop_timer()
Stop a timer.
sl_sleeptimer_get_timer_time_remaining()
Get the time remaining before the timer expires.
sl_sleeptimer_delay_millisecond()
Delay for the given number of milliseconds. This is an "active wait" delay function.
sl_sleeptimer_is_timer_running()
Check if a timer is running.
sl_sleeptimer_get_time()
,
sl_sleeptimer_set_time()
Get or set wallclock time.
sl_sleeptimer_ms_to_tick()
,
sl_sleeptimer_ms32_to_tick()
,
sl_sleeptimer_tick_to_ms()
,
sl_sleeptimer_tick64_to_ms()
Convert between milliseconds and RTC/RTCC counter ticks.
The timer expiry callback function:
The callback function, prototyped as
sl_sleeptimer_timer_callback_t()
, is called from within the RTC peripheral interrupt handler on timer expiration. sl_sleeptimer_timer_callback_t(sl_sleeptimer_timer_handle_t *handle, void *data)
Example
Data Structures |
|
struct | sl_sleeptimer_timer_handle_t |
Timer structure for sleeptimer.
|
|
struct | time_date |
Time and Date structure.
|
|
Functions |
|
SLEEPTIMER_ENUM (sl_sleeptimer_month_t) | |
Month enum.
|
|
SLEEPTIMER_ENUM (sl_sleeptimer_weekDay_t) | |
Week Day enum.
|
|
sl_status_t | sl_sleeptimer_init (void) |
Initializes the Sleeptimer.
|
|
sl_status_t | sl_sleeptimer_start_timer (sl_sleeptimer_timer_handle_t *handle, uint32_t timeout, sl_sleeptimer_timer_callback_t callback, void *callback_data, uint8_t priority, uint16_t option_flags) |
Starts a 32 bits timer.
|
|
sl_status_t | sl_sleeptimer_restart_timer (sl_sleeptimer_timer_handle_t *handle, uint32_t timeout, sl_sleeptimer_timer_callback_t callback, void *callback_data, uint8_t priority, uint16_t option_flags) |
Restarts a 32 bits timer.
|
|
sl_status_t | sl_sleeptimer_start_periodic_timer (sl_sleeptimer_timer_handle_t *handle, uint32_t timeout, sl_sleeptimer_timer_callback_t callback, void *callback_data, uint8_t priority, uint16_t option_flags) |
Starts a 32 bits periodic timer.
|
|
sl_status_t | sl_sleeptimer_restart_periodic_timer (sl_sleeptimer_timer_handle_t *handle, uint32_t timeout, sl_sleeptimer_timer_callback_t callback, void *callback_data, uint8_t priority, uint16_t option_flags) |
Restarts a 32 bits periodic timer.
|
|
sl_status_t | sl_sleeptimer_stop_timer (sl_sleeptimer_timer_handle_t *handle) |
Stops a timer.
|
|
sl_status_t | sl_sleeptimer_is_timer_running (sl_sleeptimer_timer_handle_t *handle, bool *running) |
Gets the status of a timer.
|
|
sl_status_t | sl_sleeptimer_get_timer_time_remaining (sl_sleeptimer_timer_handle_t *handle, uint32_t *time) |
Gets remaining time until timer expires.
|
|
sl_status_t | sl_sleeptimer_get_remaining_time_of_first_timer (uint16_t option_flags, uint32_t *time_remaining) |
Gets the time remaining until the first timer with the matching set of flags expires.
|
|
uint32_t | sl_sleeptimer_get_tick_count (void) |
Gets current 32 bits global tick count.
|
|
uint64_t | sl_sleeptimer_get_tick_count64 (void) |
Gets current 64 bits global tick count.
|
|
uint32_t | sl_sleeptimer_get_timer_frequency (void) |
Get timer frequency.
|
|
sl_status_t | sl_sleeptimer_convert_time_to_date ( sl_sleeptimer_timestamp_t time, sl_sleeptimer_time_zone_offset_t time_zone, sl_sleeptimer_date_t *date) |
Converts a Unix timestamp into a date.
|
|
sl_status_t | sl_sleeptimer_convert_date_to_time (sl_sleeptimer_date_t *date, sl_sleeptimer_timestamp_t *time) |
Converts a date into a Unix timestamp.
|
|
uint32_t | sl_sleeptimer_convert_date_to_str (char *str, size_t size, const uint8_t *format, sl_sleeptimer_date_t *date) |
Convert date to string.
|
|
void | sl_sleeptimer_set_tz ( sl_sleeptimer_time_zone_offset_t offset) |
Sets time zone offset.
|
|
sl_sleeptimer_time_zone_offset_t | sl_sleeptimer_get_tz (void) |
Gets time zone offset.
|
|
sl_sleeptimer_timestamp_t | sl_sleeptimer_get_time (void) |
Retrieves current time.
|
|
sl_status_t | sl_sleeptimer_set_time ( sl_sleeptimer_timestamp_t time) |
Sets current time.
|
|
sl_status_t | sl_sleeptimer_get_datetime (sl_sleeptimer_date_t *date) |
Gets current date.
|
|
sl_status_t | sl_sleeptimer_set_datetime (sl_sleeptimer_date_t *date) |
Sets current time, in date format.
|
|
sl_status_t | sl_sleeptimer_build_datetime (sl_sleeptimer_date_t *date, uint16_t year, sl_sleeptimer_month_t month, uint8_t month_day, uint8_t hour, uint8_t min, uint8_t sec, sl_sleeptimer_time_zone_offset_t tzOffset) |
Builds a date time structure based on the provided parameters.
|
|
sl_status_t | sl_sleeptimer_convert_unix_time_to_ntp ( sl_sleeptimer_timestamp_t time, uint32_t *ntp_time) |
Converts Unix timestamp into NTP timestamp.
|
|
sl_status_t | sl_sleeptimer_convert_ntp_time_to_unix (uint32_t ntp_time, sl_sleeptimer_timestamp_t *time) |
Converts NTP timestamp into Unix timestamp.
|
|
sl_status_t | sl_sleeptimer_convert_unix_time_to_zigbee ( sl_sleeptimer_timestamp_t time, uint32_t *zigbee_time) |
Converts Unix timestamp into Zigbee timestamp.
|
|
sl_status_t | sl_sleeptimer_convert_zigbee_time_to_unix (uint32_t zigbee_time, sl_sleeptimer_timestamp_t *time) |
Converts Zigbee timestamp into Unix timestamp.
|
|
sl_sleeptimer_time_zone_offset_t | sl_sleeptimer_set_tz_ahead_utc (uint8_t hours, uint8_t minutes) |
Calculates offset for time zone after UTC-0.
|
|
sl_sleeptimer_time_zone_offset_t | sl_sleeptimer_set_tz_behind_utc (uint8_t hours, uint8_t minutes) |
Calculates offset for time zone before UTC-0.
|
|
void | sl_sleeptimer_delay_millisecond (uint16_t time_ms) |
Active delay.
|
|
uint32_t | sl_sleeptimer_ms_to_tick (uint16_t time_ms) |
Converts milliseconds in ticks.
|
|
sl_status_t | sl_sleeptimer_ms32_to_tick (uint32_t time_ms, uint32_t *tick) |
Converts 32-bits milliseconds in ticks.
|
|
uint32_t | sl_sleeptimer_get_max_ms32_conversion (void) |
Gets the maximum value that can be passed to the functions that have a 32-bits time or timeout argument expressed in milliseconds.
|
|
uint32_t | sl_sleeptimer_tick_to_ms (uint32_t tick) |
Converts ticks in milliseconds.
|
|
sl_status_t | sl_sleeptimer_tick64_to_ms (uint64_t tick, uint64_t *ms) |
Converts 64-bit ticks in milliseconds.
|
|
bool | sl_sleeptimer_is_power_manager_early_restore_timer_latest_to_expire (void) |
Allow sleep after ISR exit.
|
|
sl_status_t | sl_sleeptimer_start_timer_ms (sl_sleeptimer_timer_handle_t *handle, uint32_t timeout_ms, sl_sleeptimer_timer_callback_t callback, void *callback_data, uint8_t priority, uint16_t option_flags) |
Starts a 32 bits timer.
|
|
sl_status_t | sl_sleeptimer_restart_timer_ms (sl_sleeptimer_timer_handle_t *handle, uint32_t timeout_ms, sl_sleeptimer_timer_callback_t callback, void *callback_data, uint8_t priority, uint16_t option_flags) |
Restarts a 32 bits timer.
|
|
sl_status_t | sl_sleeptimer_start_periodic_timer_ms (sl_sleeptimer_timer_handle_t *handle, uint32_t timeout_ms, sl_sleeptimer_timer_callback_t callback, void *callback_data, uint8_t priority, uint16_t option_flags) |
Starts a 32 bits periodic timer.
|
|
sl_status_t | sl_sleeptimer_restart_periodic_timer_ms (sl_sleeptimer_timer_handle_t *handle, uint32_t timeout_ms, sl_sleeptimer_timer_callback_t callback, void *callback_data, uint8_t priority, uint16_t option_flags) |
Restarts a 32 bits periodic timer.
|
|
Typedefs |
|
typedef uint32_t | sl_sleeptimer_timestamp_t |
Timestamp, wall clock time in seconds.
|
|
typedef int32_t | sl_sleeptimer_time_zone_offset_t |
Time zone offset from UTC(second).
|
|
typedef void(* | sl_sleeptimer_timer_callback_t ) (sl_sleeptimer_timer_handle_t *handle, void *data) |
Typedef for the user supplied callback function which is called when a timer expires.
|
|
Function Documentation
◆ SLEEPTIMER_ENUM() [1/2]
SLEEPTIMER_ENUM | ( | sl_sleeptimer_month_t |
|
) |
Month enum.
◆ SLEEPTIMER_ENUM() [2/2]
SLEEPTIMER_ENUM | ( | sl_sleeptimer_weekDay_t |
|
) |
Week Day enum.
◆ sl_sleeptimer_init()
sl_status_t sl_sleeptimer_init | ( | void |
|
) |
Initializes the Sleeptimer.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_start_timer()
sl_status_t sl_sleeptimer_start_timer | ( | sl_sleeptimer_timer_handle_t * |
handle,
|
uint32_t |
timeout,
|
||
sl_sleeptimer_timer_callback_t |
callback,
|
||
void * |
callback_data,
|
||
uint8_t |
priority,
|
||
uint16_t |
option_flags
|
||
) |
Starts a 32 bits timer.
- Parameters
-
handle
Pointer to handle to timer. timeout
Timer timeout, in timer ticks. callback
Callback function that will be called when initial/periodic timeout expires. callback_data
Pointer to user data that will be passed to callback. priority
Priority of callback. Useful in case multiple timer expire at the same time. 0 = highest priority. option_flags
Bit array of option flags for the timer. Valid bit-wise OR of one or more of the following: - SL_SLEEPTIMER_NO_HIGH_PRECISION_HF_CLOCKS_REQUIRED_FLAG
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_restart_timer()
sl_status_t sl_sleeptimer_restart_timer | ( | sl_sleeptimer_timer_handle_t * |
handle,
|
uint32_t |
timeout,
|
||
sl_sleeptimer_timer_callback_t |
callback,
|
||
void * |
callback_data,
|
||
uint8_t |
priority,
|
||
uint16_t |
option_flags
|
||
) |
Restarts a 32 bits timer.
- Parameters
-
handle
Pointer to handle to timer. timeout
Timer timeout, in timer ticks. callback
Callback function that will be called when initial/periodic timeout expires. callback_data
Pointer to user data that will be passed to callback. priority
Priority of callback. Useful in case multiple timer expire at the same time. 0 = highest priority. option_flags
Bit array of option flags for the timer. Valid bit-wise OR of one or more of the following: - SL_SLEEPTIMER_NO_HIGH_PRECISION_HF_CLOCKS_REQUIRED_FLAG or 0 for not flags.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_start_periodic_timer()
sl_status_t sl_sleeptimer_start_periodic_timer | ( | sl_sleeptimer_timer_handle_t * |
handle,
|
uint32_t |
timeout,
|
||
sl_sleeptimer_timer_callback_t |
callback,
|
||
void * |
callback_data,
|
||
uint8_t |
priority,
|
||
uint16_t |
option_flags
|
||
) |
Starts a 32 bits periodic timer.
- Parameters
-
handle
Pointer to handle to timer. timeout
Timer periodic timeout, in timer ticks. callback
Callback function that will be called when initial/periodic timeout expires. callback_data
Pointer to user data that will be passed to callback. priority
Priority of callback. Useful in case multiple timer expire at the same time. 0 = highest priority. option_flags
Bit array of option flags for the timer. Valid bit-wise OR of one or more of the following: - SL_SLEEPTIMER_NO_HIGH_PRECISION_HF_CLOCKS_REQUIRED_FLAG or 0 for not flags.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_restart_periodic_timer()
sl_status_t sl_sleeptimer_restart_periodic_timer | ( | sl_sleeptimer_timer_handle_t * |
handle,
|
uint32_t |
timeout,
|
||
sl_sleeptimer_timer_callback_t |
callback,
|
||
void * |
callback_data,
|
||
uint8_t |
priority,
|
||
uint16_t |
option_flags
|
||
) |
Restarts a 32 bits periodic timer.
- Parameters
-
handle
Pointer to handle to timer. timeout
Timer periodic timeout, in timer ticks. callback
Callback function that will be called when initial/periodic timeout expires. callback_data
Pointer to user data that will be passed to callback. priority
Priority of callback. Useful in case multiple timer expire at the same time. 0 = highest priority. option_flags
Bit array of option flags for the timer. Valid bit-wise OR of one or more of the following: - SL_SLEEPTIMER_NO_HIGH_PRECISION_HF_CLOCKS_REQUIRED_FLAG or 0 for not flags.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_stop_timer()
sl_status_t sl_sleeptimer_stop_timer | ( | sl_sleeptimer_timer_handle_t * |
handle
|
) |
Stops a timer.
- Parameters
-
handle
Pointer to handle to timer.
- Returns
◆ sl_sleeptimer_is_timer_running()
sl_status_t sl_sleeptimer_is_timer_running | ( | sl_sleeptimer_timer_handle_t * |
handle,
|
bool * |
running
|
||
) |
Gets the status of a timer.
- Parameters
-
handle
Pointer to handle to timer. running
Pointer to the status of the timer.
- Note
- A non periodic timer is considered not running during its callback.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_get_timer_time_remaining()
sl_status_t sl_sleeptimer_get_timer_time_remaining | ( | sl_sleeptimer_timer_handle_t * |
handle,
|
uint32_t * |
time
|
||
) |
Gets remaining time until timer expires.
- Parameters
-
handle
Pointer to handle to timer. time
Time left in timer ticks.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_get_remaining_time_of_first_timer()
sl_status_t sl_sleeptimer_get_remaining_time_of_first_timer | ( | uint16_t |
option_flags,
|
uint32_t * |
time_remaining
|
||
) |
Gets the time remaining until the first timer with the matching set of flags expires.
- Parameters
-
option_flags
Set of flags to match. time_remaining
Time left in timer ticks.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_get_tick_count()
uint32_t sl_sleeptimer_get_tick_count | ( | void |
|
) |
Gets current 32 bits global tick count.
- Returns
- Current tick count.
◆ sl_sleeptimer_get_tick_count64()
uint64_t sl_sleeptimer_get_tick_count64 | ( | void |
|
) |
Gets current 64 bits global tick count.
- Returns
- Current tick count.
◆ sl_sleeptimer_get_timer_frequency()
uint32_t sl_sleeptimer_get_timer_frequency | ( | void |
|
) |
Get timer frequency.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_convert_time_to_date()
sl_status_t sl_sleeptimer_convert_time_to_date | ( | sl_sleeptimer_timestamp_t |
time,
|
sl_sleeptimer_time_zone_offset_t |
time_zone,
|
||
sl_sleeptimer_date_t * |
date
|
||
) |
Converts a Unix timestamp into a date.
- Parameters
-
time
Unix timestamp to convert. time_zone
Offset from UTC in second. date
Pointer to converted date.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_convert_date_to_time()
sl_status_t sl_sleeptimer_convert_date_to_time | ( | sl_sleeptimer_date_t * |
date,
|
sl_sleeptimer_timestamp_t * |
time
|
||
) |
Converts a date into a Unix timestamp.
- Parameters
-
date
Pointer to date to convert. time
Pointer to converted Unix timestamp.
- Returns
- 0 if successful. Error code otherwise.
- Note
-
Dates are based on the Unix time representation. Range of dates supported :
- January 1, 1970, 00:00:00 to January 19, 2038, 03:14:00
◆ sl_sleeptimer_convert_date_to_str()
uint32_t sl_sleeptimer_convert_date_to_str | ( | char * |
str,
|
size_t |
size,
|
||
const uint8_t * |
format,
|
||
sl_sleeptimer_date_t * |
date
|
||
) |
Convert date to string.
- Parameters
-
str
Output string. size
Size of the input array. format
The format specification character. date
Pointer to date structure.
- Returns
- 0 if error. Number of character in the output string.
- Note
- Refer strftime() from UNIX. http://man7.org/linux/man-pages/man3/strftime.3.html
◆ sl_sleeptimer_set_tz()
void sl_sleeptimer_set_tz | ( | sl_sleeptimer_time_zone_offset_t |
offset
|
) |
Sets time zone offset.
- Parameters
-
offset
Time zone offset, in seconds.
◆ sl_sleeptimer_get_tz()
sl_sleeptimer_time_zone_offset_t sl_sleeptimer_get_tz | ( | void |
|
) |
Gets time zone offset.
- Returns
- Time zone offset, in seconds.
◆ sl_sleeptimer_get_time()
sl_sleeptimer_timestamp_t sl_sleeptimer_get_time | ( | void |
|
) |
Retrieves current time.
- Returns
- Current timestamps in Unix format.
◆ sl_sleeptimer_set_time()
sl_status_t sl_sleeptimer_set_time | ( | sl_sleeptimer_timestamp_t |
time
|
) |
Sets current time.
- Parameters
-
time
Time to set.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_get_datetime()
sl_status_t sl_sleeptimer_get_datetime | ( | sl_sleeptimer_date_t * |
date
|
) |
Gets current date.
- Parameters
-
date
Pointer to a sl_sleeptimer_date_t structure.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_set_datetime()
sl_status_t sl_sleeptimer_set_datetime | ( | sl_sleeptimer_date_t * |
date
|
) |
Sets current time, in date format.
- Parameters
-
date
Pointer to current date.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_build_datetime()
sl_status_t sl_sleeptimer_build_datetime | ( | sl_sleeptimer_date_t * |
date,
|
uint16_t |
year,
|
||
sl_sleeptimer_month_t |
month,
|
||
uint8_t |
month_day,
|
||
uint8_t |
hour,
|
||
uint8_t |
min,
|
||
uint8_t |
sec,
|
||
sl_sleeptimer_time_zone_offset_t |
tzOffset
|
||
) |
Builds a date time structure based on the provided parameters.
- Parameters
-
date
Pointer to the structure to be populated. year
Current year. May be provided based on a 0 Epoch or a 1900 Epoch. month
Months since January. Expected value: 0-11. month_day
Day of the month. Expected value: 1-31. hour
Hours since midnight. Expected value: 0-23. min
Minutes after the hour. Expected value: 0-59. sec
Seconds after the minute. Expected value: 0-59. tzOffset
Offset, in seconds, from UTC.
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_convert_unix_time_to_ntp()
sl_status_t sl_sleeptimer_convert_unix_time_to_ntp | ( | sl_sleeptimer_timestamp_t |
time,
|
uint32_t * |
ntp_time
|
||
) |
Converts Unix timestamp into NTP timestamp.
- Parameters
-
time
Unix timestamp. ntp_time
Pointer to NTP Timestamp.
- Note
- Unix timestamp range supported : 0x0 to 0x7C55 817F ie. January 1, 1970, 00:00:00 to February 07, 2036, 06:28:15
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_convert_ntp_time_to_unix()
sl_status_t sl_sleeptimer_convert_ntp_time_to_unix | ( | uint32_t |
ntp_time,
|
sl_sleeptimer_timestamp_t * |
time
|
||
) |
Converts NTP timestamp into Unix timestamp.
- Parameters
-
ntp_time
NTP Timestamp. time
Pointer to Unix timestamp.
- Note
- NTP timestamp range supported : 0x83AA 7E80 to 0xFFFF FFFF ie. January 1, 1970, 00:00:00 to February 07, 2036, 06:28:15
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_convert_unix_time_to_zigbee()
sl_status_t sl_sleeptimer_convert_unix_time_to_zigbee | ( | sl_sleeptimer_timestamp_t |
time,
|
uint32_t * |
zigbee_time
|
||
) |
Converts Unix timestamp into Zigbee timestamp.
- Parameters
-
time
Unix timestamp. zigbee_time
Pointer to NTP Timestamp.
- Note
- Unix timestamp range supported : 0x386D 4380 to 0x7FFF FFFF ie. January 1, 2000, 00:00:0 to January 19, 2038, 03:14:00
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_convert_zigbee_time_to_unix()
sl_status_t sl_sleeptimer_convert_zigbee_time_to_unix | ( | uint32_t |
zigbee_time,
|
sl_sleeptimer_timestamp_t * |
time
|
||
) |
Converts Zigbee timestamp into Unix timestamp.
- Parameters
-
zigbee_time
NTP Timestamp. time
Pointer to Unix timestamp.
- Note
- ZIGBEE timestamp range supported : 0x0 to 0x4792 BC7F ie. January 1, 2000, 00:00:00 to January 19, 2038, 03:14:00
- Returns
- 0 if successful. Error code otherwise.
◆ sl_sleeptimer_set_tz_ahead_utc()
|
inline |
Calculates offset for time zone after UTC-0.
- Parameters
-
hours
Number of hours from UTC-0. minutes
Number of minutes from UTC-0.
- Returns
- The time zone offset in seconds.
◆ sl_sleeptimer_set_tz_behind_utc()
|
inline |
Calculates offset for time zone before UTC-0.
- Parameters
-
hours
Number of hours to UTC-0. minutes
Number of minutes to UTC-0.
- Returns
- The time zone offset in seconds.
◆ sl_sleeptimer_delay_millisecond()
void sl_sleeptimer_delay_millisecond | ( | uint16_t |
time_ms
|
) |
Active delay.
- Parameters
-
time_ms
Delay duration in milliseconds.
◆ sl_sleeptimer_ms_to_tick()
uint32_t sl_sleeptimer_ms_to_tick | ( | uint16_t |
time_ms
|
) |
Converts milliseconds in ticks.
- Parameters
-
time_ms
Number of milliseconds.
- Returns
- Corresponding ticks number.
- Note
- The result is "rounded" to the superior tick number. This function is light and cannot fail so it should be privilegied to perform a millisecond to tick conversion.
◆ sl_sleeptimer_ms32_to_tick()
sl_status_t sl_sleeptimer_ms32_to_tick | ( | uint32_t |
time_ms,
|
uint32_t * |
tick
|
||
) |
Converts 32-bits milliseconds in ticks.
- Parameters
-
time_ms
Number of milliseconds. tick
Pointer to the converted tick number.
- Returns
- 0 if successful. Error code otherwise.
- Note
- The result is "rounded" to the superior tick number. If possible the sl_sleeptimer_ms_to_tick() function should be used.
- This function converts the delay expressed in milliseconds to timer ticks (represented on 32 bits). This means that the value that can be passed to the argument 'time_ms' is limited. The maximum timeout value that can be passed to this function can be retrieved by calling sl_sleeptimer_get_max_ms32_conversion() . If the value passed to 'time_ms' is too large, SL_STATUS_INVALID_PARAMETER will be returned.
◆ sl_sleeptimer_get_max_ms32_conversion()
uint32_t sl_sleeptimer_get_max_ms32_conversion | ( | void |
|
) |
Gets the maximum value that can be passed to the functions that have a 32-bits time or timeout argument expressed in milliseconds.
- Returns
- Maximum time or timeout value in milliseconds.
◆ sl_sleeptimer_tick_to_ms()
uint32_t sl_sleeptimer_tick_to_ms | ( | uint32_t |
tick
|
) |
Converts ticks in milliseconds.
- Parameters
-
tick
Number of tick.
- Returns
- Corresponding milliseconds number.
- Note
- The result is rounded to the inferior millisecond.
◆ sl_sleeptimer_tick64_to_ms()
sl_status_t sl_sleeptimer_tick64_to_ms | ( | uint64_t |
tick,
|
uint64_t * |
ms
|
||
) |
Converts 64-bit ticks in milliseconds.
- Parameters
-
tick
Number of tick. ms
Pointer to the converted milliseconds number.
- Returns
- 0 if successful. Error code otherwise.
- Note
- The result is rounded to the inferior millisecond.
◆ sl_sleeptimer_is_power_manager_early_restore_timer_latest_to_expire()
bool sl_sleeptimer_is_power_manager_early_restore_timer_latest_to_expire | ( | void |
|
) |
Allow sleep after ISR exit.
- Returns
- true if sleep is allowed after ISR exit. False otherwise.
◆ sl_sleeptimer_start_timer_ms()
|
inline |
Starts a 32 bits timer.
- Parameters
-
handle
Pointer to handle to timer. timeout_ms
Timer timeout, in milliseconds. callback
Callback function that will be called when initial/periodic timeout expires. callback_data
Pointer to user data that will be passed to callback. priority
Priority of callback. Useful in case multiple timer expire at the same time. 0 = highest priority. option_flags
Bit array of option flags for the timer. Valid bit-wise OR of one or more of the following: - SL_SLEEPTIMER_NO_HIGH_PRECISION_HF_CLOCKS_REQUIRED_FLAG or 0 for not flags.
- Returns
- 0 if successful. Error code otherwise.
- Note
- This function converts the delay expressed in milliseconds to timer ticks (represented on 32 bits). This means that the value that can be passed to the argument 'timeout_ms' is limited. The maximum timeout value that can be passed to this function can be retrieved by calling sl_sleeptimer_get_max_ms32_conversion() . If the value passed to 'timeout_ms' is too large, SL_STATUS_INVALID_PARAMETER will be returned.
◆ sl_sleeptimer_restart_timer_ms()
|
inline |
Restarts a 32 bits timer.
- Parameters
-
handle
Pointer to handle to timer. timeout_ms
Timer timeout, in milliseconds. callback
Callback function that will be called when initial/periodic timeout expires. callback_data
Pointer to user data that will be passed to callback. priority
Priority of callback. Useful in case multiple timer expire at the same time. 0 = highest priority. option_flags
Bit array of option flags for the timer. Valid bit-wise OR of one or more of the following: - SL_SLEEPTIMER_NO_HIGH_PRECISION_HF_CLOCKS_REQUIRED_FLAG or 0 for not flags.
- Returns
- 0 if successful. Error code otherwise.
- Note
- This function converts the delay expressed in milliseconds to timer ticks (represented on 32 bits). This means that the value that can be passed to the argument 'timeout_ms' is limited. The maximum timeout value that can be passed to this function can be retrieved by calling sl_sleeptimer_get_max_ms32_conversion() . If the value passed to 'timeout_ms' is too large, SL_STATUS_INVALID_PARAMETER will be returned.
◆ sl_sleeptimer_start_periodic_timer_ms()
|
inline |
Starts a 32 bits periodic timer.
- Parameters
-
handle
Pointer to handle to timer. timeout_ms
Timer periodic timeout, in milliseconds. callback
Callback function that will be called when initial/periodic timeout expires. callback_data
Pointer to user data that will be passed to callback. priority
Priority of callback. Useful in case multiple timer expire at the same time. 0 = highest priority. option_flags
Bit array of option flags for the timer. Valid bit-wise OR of one or more of the following: - SL_SLEEPTIMER_NO_HIGH_PRECISION_HF_CLOCKS_REQUIRED_FLAG or 0 for not flags.
- Returns
- 0 if successful. Error code otherwise.
- Note
- This function converts the delay expressed in milliseconds to timer ticks (represented on 32 bits). This means that the value that can be passed to the argument 'timeout_ms' is limited. The maximum timeout value that can be passed to this function can be retrieved by calling sl_sleeptimer_get_max_ms32_conversion() . If the value passed to 'timeout_ms' is too large, SL_STATUS_INVALID_PARAMETER will be returned.
◆ sl_sleeptimer_restart_periodic_timer_ms()
|
inline |
Restarts a 32 bits periodic timer.
- Parameters
-
handle
Pointer to handle to timer. timeout_ms
Timer periodic timeout, in milliseconds. callback
Callback function that will be called when initial/periodic timeout expires. callback_data
Pointer to user data that will be passed to callback. priority
Priority of callback. Useful in case multiple timer expire at the same time. 0 = highest priority. option_flags
Bit array of option flags for the timer. Valid bit-wise OR of one or more of the following: - SL_SLEEPTIMER_NO_HIGH_PRECISION_HF_CLOCKS_REQUIRED_FLAG or 0 for not flags.
- Returns
- 0 if successful. Error code otherwise.
- Note
- This function converts the delay expressed in milliseconds to timer ticks (represented on 32 bits). This means that the value that can be passed to the argument 'timeout_ms' is limited. The maximum timeout value that can be passed to this function can be retrieved by calling sl_sleeptimer_get_max_ms32_conversion() . If the value passed to 'timeout_ms' is too large, SL_STATUS_INVALID_PARAMETER will be returned.
Typedef Documentation
◆ sl_sleeptimer_timestamp_t
typedef uint32_t sl_sleeptimer_timestamp_t |
Timestamp, wall clock time in seconds.
◆ sl_sleeptimer_time_zone_offset_t
typedef int32_t sl_sleeptimer_time_zone_offset_t |
Time zone offset from UTC(second).
◆ sl_sleeptimer_timer_callback_t
typedef void(* sl_sleeptimer_timer_callback_t) (sl_sleeptimer_timer_handle_t *handle, void *data) |
Typedef for the user supplied callback function which is called when a timer expires.
- Parameters
-
handle
The timer handle. data
An extra parameter for the user application.