APPLICATION NOTE
AT03266: SAM RTC Calendar Driver (RTC CAL)
ASF PROGRAMMERS MANUAL
SAM RTC Calendar Driver (RTC CAL)
This driver for Atmel® | SMART SAM devices provides an interface for the
configuration and management of the device's Real Time Clock functionality in
Calendar operating mode, for the configuration and retrieval of the current time and
date as maintained by the RTC module. The following driver API modes are covered
by this manual:
●
Polled APIs
●
Callback APIs
The following peripherals are used by this module:
●
RTC (Real Time Clock)
The following devices can use this module:
●
Atmel | SMART SAM D20/D21
●
Atmel | SMART SAM R21
●
Atmel | SMART SAM D10/D11
The outline of this documentation is as follows:
●
Prerequisites
●
Module Overview
●
Special Considerations
●
Extra Information
●
Examples
●
API Overview
42126D-SAMD20/D21-12/2014
Table of Contents
SAM RTC Calendar Driver (RTC CAL) .............................................. 1
Software License ................................................................................ 3
1. Prerequisites ................................................................................. 4
2. Module Overview .......................................................................... 5
2.1.
2.2.
2.3.
Alarms and Overflow ................................................................... 5
Periodic Events .......................................................................... 5
Digital Frequency Correction ......................................................... 6
3. Special Considerations ................................................................. 7
3.1.
3.2.
Year Limit .................................................................................. 7
Clock Setup ............................................................................... 7
4. Extra Information .......................................................................... 8
5. Examples ...................................................................................... 9
6. API Overview .............................................................................. 10
6.1.
6.2.
6.3.
Structure Definitions ................................................................... 10
6.1.1.
Struct rtc_calendar_alarm_time ........................................ 10
6.1.2.
Struct rtc_calendar_config ............................................... 10
6.1.3.
Struct rtc_calendar_events .............................................. 10
6.1.4.
Struct rtc_calendar_time ................................................. 11
Function Definitions ................................................................... 11
6.2.1.
Configuration and Initialization ......................................... 11
6.2.2.
Time and Alarm Management .......................................... 15
6.2.3.
Status Flag Management ................................................ 16
6.2.4.
Event Management ....................................................... 18
6.2.5.
Callbacks ..................................................................... 19
Enumeration Definitions .............................................................. 21
6.3.1.
Enum rtc_calendar_alarm .............................................. 21
6.3.2.
Enum rtc_calendar_alarm_mask ..................................... 21
6.3.3.
Enum rtc_calendar_callback ........................................... 21
6.3.4.
Enum rtc_calendar_prescaler ......................................... 22
7. Extra Information for RTC (CAL) Driver ..................................... 23
7.1.
7.2.
7.3.
7.4.
Acronyms ................................................................................
Dependencies ...........................................................................
Errata ......................................................................................
Module History .........................................................................
23
23
23
23
8. Examples for RTC CAL Driver ................................................... 24
8.1.
8.2.
Quick Start Guide for RTC (CAL) - Basic .......................................
8.1.1.
Prerequisites ................................................................
8.1.2.
Setup ..........................................................................
8.1.3.
Implementation .............................................................
Quick Start Guide for RTC (CAL) - Callback ...................................
8.2.1.
Prerequisites ................................................................
8.2.2.
Setup ..........................................................................
8.2.3.
Implementation .............................................................
8.2.4.
Callback ......................................................................
24
24
24
26
27
27
27
30
30
Index ................................................................................................. 31
Document Revision History .............................................................. 32
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
2
Software License
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
3. The name of Atmel may not be used to endorse or promote products derived from this software without specific
prior written permission.
4. This software may only be redistributed and used in connection with an Atmel microcontroller product.
THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN
NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
3
1.
Prerequisites
There are no prerequisites for this module.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
4
2.
Module Overview
The RTC module in the SAM devices is a 32-bit counter, with a 10-bit programmable prescaler. Typically, the
RTC clock is run continuously, including in the device's low-power sleep modes, to track the current time and date
information. The RTC can be used as a source to wake up the system at a scheduled time or periodically using the
alarm functions.
In this driver, the RTC is operated in Calendar mode. This allows for an easy integration of a real time clock and
calendar into a user application to track the passing of time and/or perform scheduled tasks.
Whilst operating in Calendar mode, the RTC features:
●
Time tracking in seconds, minutes, and hours
●
●
Date tracking in day, month, and year
●
2.1
12 or 24 hour mode
Automatic leap year correction
Alarms and Overflow
The RTC has four independent hardware alarms that can be configured by the user application. These alarms will
be will triggered on match with the current clock value, and can be set up to trigger an interrupt, event, or both. The
RTC can also be configured to clear the clock value on alarm match, resetting the clock to the original start time.
If the RTC is operated in clock-only mode (i.e. with calendar disabled), the RTC counter value will instead be
cleared on overflow once the maximum count value has been reached:
(2.1)
When the RTC is operated with the calendar enabled and run using a nominal 1Hz input clock frequency, a register
overflow will occur after 64 years.
2.2
Periodic Events
The RTC can generate events at periodic intervals, allowing for direct peripheral actions without CPU intervention.
The periodic events can be generated on the upper eight bits of the RTC prescaler, and will be generated on
the rising edge transition of the specified bit. The resulting periodic frequency can be calculated by the following
formula:
(2.2)
Where
(2.3)
refers to the asynchronous clock set up in the RTC module configuration. For the RTC to operate correctly in
calendar mode, this frequency must be 1KHz, while the RTC's internal prescaler should be set to divide by 1024.
The n parameter is the event source generator index of the RTC module. If the asynchronous clock is operated at
the recommended 1KHz, the formula results in the values shown in Table 2-1: RTC Event Frequencies for Each
Prescaler Bit Using a 1KHz Clock on page 5.
Table 2-1. RTC Event Frequencies for Each Prescaler Bit Using a 1KHz Clock
n
Periodic event
7
1Hz
6
2Hz
5
4Hz
4
8Hz
3
16Hz
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
5
Note
2.3
n
Periodic event
2
32Hz
1
64Hz
0
128Hz
The connection of events between modules requires the use of the SAM Event System Driver
(EVENTS) to route output event of one module to the the input event of another. For more information
on event routing, refer to the event driver documentation.
Digital Frequency Correction
The RTC module contains Digital Frequency Correction logic to compensate for inaccurate source clock
frequencies which would otherwise result in skewed time measurements. The correction scheme requires that at
least two bits in the RTC module prescaler are reserved by the correction logic. As a result of this implementation,
frequency correction is only available when the RTC is running from a 1Hz reference clock.
The correction procedure is implemented by subtracting or adding a single cycle from the RTC prescaler every
1024 RTC GCLK cycles. The adjustment is applied the specified number of time (maximum 127) over 976 of these
periods. The corresponding correction in PPM will be given by:
(2.4)
The RTC clock will tick faster if provided with a positive correction value, and slower when given a negative
correction value.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
6
3.
Special Considerations
3.1
Year Limit
The RTC module has a year range of 63 years from the starting year configured when the module is initialized.
Dates outside the start to end year range described below will need software adjustment:
(3.1)
3.2
Clock Setup
The RTC is typically clocked by a specialized GCLK generator that has a smaller prescaler than the others. By
default the RTC clock is on, selected to use the internal 32KHz RC-oscillator with a prescaler of 32, giving a
resulting clock frequency of 1024Hz to the RTC. When the internal RTC prescaler is set to 1024, this yields an endfrequency of 1Hz for correct time keeping operations.
The implementer also has the option to set other end-frequencies. Table 3-1: RTC Output Frequencies from
Allowable Input Clocks on page 7 lists the available RTC frequencies for each possible GCLK and RTC input
prescaler options.
Table 3-1. RTC Output Frequencies from Allowable Input Clocks
End-frequency
GCLK prescaler
RTC prescaler
32KHz
1
1
1KHz
32
1
1Hz
32
1024
The overall RTC module clocking scheme is shown in Figure 3-1: Clock Setup on page 7.
Figure 3-1. Clock Setup
Note
GCLK
RTC
RTC
RTC_GCLK
RTC P RE S CALE R
RTC CLOCK
For the calendar to operate correctly, an asynchronous clock of 1Hz should be used.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
7
4.
Extra Information
For extra information, see Extra Information for RTC (CAL) Driver. This includes:
●
Acronyms
●
Dependencies
●
Errata
●
Module History
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
8
5.
Examples
For a list of examples related to this driver, see Examples for RTC CAL Driver.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
9
6.
API Overview
6.1
Structure Definitions
6.1.1
Struct rtc_calendar_alarm_time
Alarm structure containing time of the alarm and a mask to determine when the alarm will trigger.
Table 6-1. Members
6.1.2
Type
Name
Description
enum rtc_calendar_alarm_mask
mask
Alarm mask to determine on what
precision the alarm will match.
struct rtc_calendar_time
time
Alarm time.
Struct rtc_calendar_config
Configuration structure for the RTC instance. This structure should be initialized using the
rtc_calendar_get_config_defaults() before any user configurations are set.
Table 6-2. Members
6.1.3
Type
Name
Description
struct rtc_calendar_alarm_time
alarm[]
Alarm values.
bool
clear_on_match
If true, clears the clock on alarm
match.
bool
clock_24h
If true, time is represented in 24
hour mode.
bool
continuously_update
If true, the digital counter registers
will be continuously updated so
that internal synchronization is not
needed when reading the current
count.
enum rtc_calendar_prescaler
prescaler
Input clock prescaler for the RTC
module.
uint16_t
year_init_value
Initial year for counter value 0.
Struct rtc_calendar_events
Event flags for the rtc_calendar_enable_events() and rtc_calendar_disable_events().
Table 6-3. Members
Type
Name
Description
bool
generate_event_on_alarm[]
Generate an output event on a
alarm channel match against the
RTC count.
bool
generate_event_on_overflow
Generate an output event on each
overflow of the RTC count.
bool
generate_event_on_periodic[]
Generate an output event
periodically at a binary division of
the RTC counter frequency.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
10
6.1.4
Struct rtc_calendar_time
Time structure containing the time given by or set to the RTC calendar. The structure uses seven
values to give second, minute, hour, PM/AM, day, month, and year. It should be initialized via the
rtc_calendar_get_time_defaults() function before use.
Table 6-4. Members
Type
Name
Description
uint8_t
day
Day value, where day 1 is the first
day of the month.
uint8_t
hour
Hour value.
uint8_t
minute
Minute value.
uint8_t
month
Month value, where month 1 is
January.
bool
pm
PM/AM value, true for PM, or false
for AM.
uint8_t
second
Second value.
uint16_t
year
Year value.
6.2
Function Definitions
6.2.1
Configuration and Initialization
6.2.1.1
Function rtc_calendar_is_syncing()
Determines if the hardware module(s) are currently synchronizing to the bus.
bool rtc_calendar_is_syncing(
struct rtc_module *const module)
Checks to see if the underlying hardware peripheral module(s) are currently synchronizing across multiple clock
domains to the hardware bus. This function can be used to delay further operations on a module until such time
that it is ready, to prevent blocking delays for synchronization in the user application.
Table 6-5. Parameters
Data direction
Parameter name
Description
[in]
module
RTC hardware module
Returns
Synchronization status of the underlying hardware module(s).
Table 6-6. Return Values
6.2.1.2
Return value
Description
true
if the module has completed synchronization
false
if the module synchronization is ongoing
Function rtc_calendar_get_time_defaults()
Initialize a time structure.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
11
void rtc_calendar_get_time_defaults(
struct rtc_calendar_time *const time)
This will initialize a given time structure to the time 00:00:00 (hh:mm:ss) and date 2000-01-01 (YYYY-MM-DD).
Table 6-7. Parameters
6.2.1.3
Data direction
Parameter name
Description
[out]
time
Time structure to initialize.
Function rtc_calendar_get_config_defaults()
Gets the RTC default settings.
void rtc_calendar_get_config_defaults(
struct rtc_calendar_config *const config)
Initializes the configuration structure to the known default values. This function should be called at the start of any
RTC initiation.
The default configuration is as follows:
●
Input clock divided by a factor of 1024
●
Clear on alarm match off
●
Continuously sync clock off
●
12 hour calendar
●
Start year 2000 (Year 0 in the counter will be year 2000)
●
Events off
●
Alarms set to January 1. 2000, 00:00:00
●
Alarm will match on second, minute, hour, day, month, and year
Table 6-8. Parameters
6.2.1.4
Data direction
Parameter name
Description
[out]
config
Configuration structure to be
initialized to default values.
Function rtc_calendar_reset()
Resets the RTC module Resets the RTC module to hardware defaults.
void rtc_calendar_reset(
struct rtc_module *const module)
Table 6-9. Parameters
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
12
6.2.1.5
Function rtc_calendar_enable()
Enables the RTC module.
void rtc_calendar_enable(
struct rtc_module *const module)
Enables the RTC module once it has been configured, ready for use. Most module configuration parameters cannot
be altered while the module is enabled.
Table 6-10. Parameters
6.2.1.6
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
Function rtc_calendar_disable()
Disables the RTC module.
void rtc_calendar_disable(
struct rtc_module *const module)
Disables the RTC module.
Table 6-11. Parameters
6.2.1.7
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
Function rtc_calendar_init()
Initializes the RTC module with given configurations.
void rtc_calendar_init(
struct rtc_module *const module,
Rtc *const hw,
const struct rtc_calendar_config *const config)
Initializes the module, setting up all given configurations to provide the desired functionality of the RTC.
Table 6-12. Parameters
6.2.1.8
Data direction
Parameter name
Description
[out]
module
Pointer to the software instance
struct
[in]
hw
Pointer to hardware instance
[in]
config
Pointer to the configuration
structure.
Function rtc_calendar_swap_time_mode()
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
13
Swaps between 12h and 24h clock mode.
void rtc_calendar_swap_time_mode(
struct rtc_module *const module)
Swaps the current RTC time mode:
●
If currently in 12h mode, it will swap to 24h
●
If currently in 24h mode, it will swap to 12h
Note
This will not change setting in user's configuration structure.
Table 6-13. Parameters
6.2.1.9
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
Function rtc_calendar_frequency_correction()
Calibrate for too-slow or too-fast oscillator.
enum status_code rtc_calendar_frequency_correction(
struct rtc_module *const module,
const int8_t value)
When used, the RTC will compensate for an inaccurate oscillator. The RTC module will add or subtract cycles from
the RTC prescaler to adjust the frequency in approximately 1 PPM steps. The provided correction value should be
between -127 and 127, allowing for a maximum 127 PPM correction in either direction.
If no correction is needed, set value to zero.
Note
Can only be used when the RTC is operated at 1Hz.
Table 6-14. Parameters
Returns
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[in]
value
Between -127 and 127 used for the
correction.
Status of the calibration procedure.
Table 6-15. Return Values
Return value
Description
STATUS_OK
If calibration was done correctly.
STATUS_ERR_INVALID_ARG
If invalid argument(s) were provided.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
14
6.2.2
Time and Alarm Management
6.2.2.1
Function rtc_calendar_set_time()
Set the current calendar time to desired time.
void rtc_calendar_set_time(
struct rtc_module *const module,
const struct rtc_calendar_time *const time)
Sets the time provided to the calendar.
Table 6-16. Parameters
6.2.2.2
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[in]
time
The time to set in the calendar.
Function rtc_calendar_get_time()
Get the current calendar value.
void rtc_calendar_get_time(
struct rtc_module *const module,
struct rtc_calendar_time *const time)
Retrieves the current time of the calendar.
Table 6-17. Parameters
6.2.2.3
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[out]
time
Pointer to value that will be filled
with current time.
Function rtc_calendar_set_alarm()
Set the alarm time for the specified alarm.
enum status_code rtc_calendar_set_alarm(
struct rtc_module *const module,
const struct rtc_calendar_alarm_time *const alarm,
const enum rtc_calendar_alarm alarm_index)
Sets the time and mask specified to the requested alarm.
Table 6-18. Parameters
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[in]
alarm
The alarm struct to set the alarm
with.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
15
Data direction
Parameter name
Description
[in]
alarm_index
The index of the alarm to set.
Returns
Status of setting alarm.
Table 6-19. Return Values
6.2.2.4
Return value
Description
STATUS_OK
If alarm was set correctly.
STATUS_ERR_INVALID_ARG
If invalid argument(s) were provided.
Function rtc_calendar_get_alarm()
Get the current alarm time of specified alarm.
enum status_code rtc_calendar_get_alarm(
struct rtc_module *const module,
struct rtc_calendar_alarm_time *const alarm,
const enum rtc_calendar_alarm alarm_index)
Retrieves the current alarm time for the alarm specified.
Table 6-20. Parameters
Returns
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[out]
alarm
Pointer to the struct that will be
filled with alarm time and mask of
the specified alarm.
[in]
alarm_index
Index of alarm to get alarm time
from.
Status of getting alarm.
Table 6-21. Return Values
Return value
Description
STATUS_OK
If alarm was read correctly.
STATUS_ERR_INVALID_ARG
If invalid argument(s) were provided.
6.2.3
Status Flag Management
6.2.3.1
Function rtc_calendar_is_overflow()
Check if an RTC overflow has occurred.
bool rtc_calendar_is_overflow(
struct rtc_module *const module)
Checks the overflow flag in the RTC. The flag is set when there is an overflow in the clock.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
16
Table 6-22. Parameters
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
Returns
Overflow state of the RTC module.
Table 6-23. Return Values
6.2.3.2
Return value
Description
true
If the RTC count value has overflowed
false
If the RTC count value has not overflowed
Function rtc_calendar_clear_overflow()
Clears the RTC overflow flag.
void rtc_calendar_clear_overflow(
struct rtc_module *const module)
Table 6-24. Parameters
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
Clears the RTC module counter overflow flag, so that new overflow conditions can be detected.
6.2.3.3
Function rtc_calendar_is_alarm_match()
Check the RTC alarm flag.
bool rtc_calendar_is_alarm_match(
struct rtc_module *const module,
const enum rtc_calendar_alarm alarm_index)
Check if the specified alarm flag is set. The flag is set when there is an compare match between the alarm value
and the clock.
Table 6-25. Parameters
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[in]
alarm_index
Index of the alarm to check.
Returns
Match status of the specified alarm.
Table 6-26. Return Values
Return value
Description
true
If the specified alarm has matched the current time
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
17
6.2.3.4
Return value
Description
false
If the specified alarm has not matched the current time
Function rtc_calendar_clear_alarm_match()
Clears the RTC alarm match flag.
enum status_code rtc_calendar_clear_alarm_match(
struct rtc_module *const module,
const enum rtc_calendar_alarm alarm_index)
Clear the requested alarm match flag, so that future alarm matches can be determined.
Table 6-27. Parameters
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[in]
alarm_index
The index of the alarm match to
clear.
Returns
Status of the alarm match clear operation.
Table 6-28. Return Values
Return value
Description
STATUS_OK
If flag was cleared correctly.
STATUS_ERR_INVALID_ARG
If invalid argument(s) were provided.
6.2.4
Event Management
6.2.4.1
Function rtc_calendar_enable_events()
Enables a RTC event output.
void rtc_calendar_enable_events(
struct rtc_module *const module,
struct rtc_calendar_events *const events)
Enables one or more output events from the RTC module. See rtc_calendar_events for a list of events this module
supports.
Note
Events cannot be altered while the module is enabled.
Table 6-29. Parameters
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[in]
events
Struct containing flags of events to
enable
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
18
6.2.4.2
Function rtc_calendar_disable_events()
Disables a RTC event output.
void rtc_calendar_disable_events(
struct rtc_module *const module,
struct rtc_calendar_events *const events)
Disabled one or more output events from the RTC module. See rtc_calendar_events for a list of events this module
supports.
Note
Events cannot be altered while the module is enabled.
Table 6-30. Parameters
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[in]
events
Struct containing flags of events to
disable
6.2.5
Callbacks
6.2.5.1
Function rtc_calendar_register_callback()
Registers callback for the specified callback type.
enum status_code rtc_calendar_register_callback(
struct rtc_module *const module,
rtc_calendar_callback_t callback,
enum rtc_calendar_callback callback_type)
Associates the given callback function with the specified callback type. To enable the callback, the
rtc_calendar_enable_callback function must be used.
Table 6-31. Parameters
Returns
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[in]
callback
Pointer to the function desired for
the specified callback
[in]
callback_type
Callback type to register
Status of registering callback.
Table 6-32. Return Values
Return value
Description
STATUS_OK
Registering was done successfully
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
19
6.2.5.2
Return value
Description
STATUS_ERR_INVALID_ARG
If trying to register a callback not available
Function rtc_calendar_unregister_callback()
Unregisters callback for the specified callback type.
enum status_code rtc_calendar_unregister_callback(
struct rtc_module *const module,
enum rtc_calendar_callback callback_type)
When called, the currently registered callback for the given callback type will be removed.
Table 6-33. Parameters
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[in]
callback_type
Specifies the callback type to
unregister
Returns
Status of unregistering callback.
Table 6-34. Return Values
6.2.5.3
Return value
Description
STATUS_OK
Unregistering was done successfully
STATUS_ERR_INVALID_ARG
If trying to unregister a callback not available
Function rtc_calendar_enable_callback()
Enables callback.
void rtc_calendar_enable_callback(
struct rtc_module *const module,
enum rtc_calendar_callback callback_type)
Enables the callback specified by the callback_type.
Table 6-35. Parameters
6.2.5.4
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[in]
callback_type
Callback type to enable
Function rtc_calendar_disable_callback()
Disables callback.
void rtc_calendar_disable_callback(
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
20
struct rtc_module *const module,
enum rtc_calendar_callback callback_type)
Disables the callback specified by the callback_type.
Table 6-36. Parameters
Data direction
Parameter name
Description
[in, out]
module
Pointer to the software instance
struct
[in]
callback_type
Callback type to disable
6.3
Enumeration Definitions
6.3.1
Enum rtc_calendar_alarm
Available alarm channels.
Note
Not all alarm channels are available on all devices.
Table 6-37. Members
6.3.2
Enum value
Description
RTC_CALENDAR_ALARM_0
Alarm channel 0.
RTC_CALENDAR_ALARM_1
Alarm channel 1.
RTC_CALENDAR_ALARM_2
Alarm channel 2.
RTC_CALENDAR_ALARM_3
Alarm channel 3.
Enum rtc_calendar_alarm_mask
Available mask options for alarms.
Table 6-38. Members
6.3.3
Enum value
Description
RTC_CALENDAR_ALARM_MASK_DISABLED
Alarm disabled.
RTC_CALENDAR_ALARM_MASK_SEC
Alarm match on second.
RTC_CALENDAR_ALARM_MASK_MIN
Alarm match on second and minute.
RTC_CALENDAR_ALARM_MASK_HOUR
Alarm match on second, minute, and hour.
RTC_CALENDAR_ALARM_MASK_DAY
Alarm match on second, minute, hour, and day.
RTC_CALENDAR_ALARM_MASK_MONTH
Alarm match on second, minute, hour, day, and
month.
RTC_CALENDAR_ALARM_MASK_YEAR
Alarm match on second, minute, hour, day,
month, and year.
Enum rtc_calendar_callback
The available callback types for the RTC calendar module.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
21
Table 6-39. Members
6.3.4
Enum value
Description
RTC_CALENDAR_CALLBACK_ALARM_0
Callback for alarm 0.
RTC_CALENDAR_CALLBACK_ALARM_1
Callback for alarm 1.
RTC_CALENDAR_CALLBACK_ALARM_2
Callback for alarm 2.
RTC_CALENDAR_CALLBACK_ALARM_3
Callback for alarm 3.
RTC_CALENDAR_CALLBACK_OVERFLOW
Callback for overflow.
Enum rtc_calendar_prescaler
The available input clock prescaler values for the RTC calendar module.
Table 6-40. Members
Enum value
Description
RTC_CALENDAR_PRESCALER_DIV_1
RTC input clock frequency is prescaled by a
factor of 1.
RTC_CALENDAR_PRESCALER_DIV_2
RTC input clock frequency is prescaled by a
factor of 2.
RTC_CALENDAR_PRESCALER_DIV_4
RTC input clock frequency is prescaled by a
factor of 4.
RTC_CALENDAR_PRESCALER_DIV_8
RTC input clock frequency is prescaled by a
factor of 8.
RTC_CALENDAR_PRESCALER_DIV_16
RTC input clock frequency is prescaled by a
factor of 16.
RTC_CALENDAR_PRESCALER_DIV_32
RTC input clock frequency is prescaled by a
factor of 32.
RTC_CALENDAR_PRESCALER_DIV_64
RTC input clock frequency is prescaled by a
factor of 64.
RTC_CALENDAR_PRESCALER_DIV_128
RTC input clock frequency is prescaled by a
factor of 128.
RTC_CALENDAR_PRESCALER_DIV_256
RTC input clock frequency is prescaled by a
factor of 256.
RTC_CALENDAR_PRESCALER_DIV_512
RTC input clock frequency is prescaled by a
factor of 512.
RTC_CALENDAR_PRESCALER_DIV_1024
RTC input clock frequency is prescaled by a
factor of 1024.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
22
7.
Extra Information for RTC (CAL) Driver
7.1
Acronyms
Below is a table listing the acronyms used in this module, along with their intended meanings.
7.2
Acronym
Description
RTC
Real Time Counter
PPM
Part Per Million
RC
Resistor/Capacitor
Dependencies
This driver has the following dependencies:
●
7.3
None
Errata
There are no errata related to this driver.
7.4
Module History
An overview of the module history is presented in the table below, with details on the enhancements and fixes
made to the module since its first release. The current version of this corresponds to the newest version in the
table.
Changelog
Added support for SAMD21 and added driver instance parameter to all API function calls, except
get_config_defaults
Updated initialization function to also enable the digital interface clock to the module if it is disabled
Initial Release
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
23
8.
Examples for RTC CAL Driver
This is a list of the available Quick Start guides (QSGs) and example applications for SAM RTC Calendar Driver
(RTC CAL). QSGs are simple examples with step-by-step instructions to configure and use this driver in a selection
of use cases. Note that QSGs can be compiled as a standalone application or be added to the user application.
8.1
●
Quick Start Guide for RTC (CAL) - Basic
●
Quick Start Guide for RTC (CAL) - Callback
Quick Start Guide for RTC (CAL) - Basic
In this use case, the RTC is set up in calendar mode. The time is set and also an alarm is set to show a general
use of the RTC in calendar mode. Also the clock is swapped from 24h to 12h mode after initialization. The board
LED will be toggled once the current time matches the set time.
8.1.1
Prerequisites
The Generic Clock Generator for the RTC should be configured and enabled; if you are using the System Clock
driver, this may be done via conf_clocks.h.
8.1.1.1
Clocks and Oscillators
The conf_clock.h file needs to be changed with the following values to configure the clocks and oscillators for
the module.
The following oscillator settings are needed:
/*
#
#
#
#
#
#
SYSTEM_CLOCK_SOURCE_OSC32K configuration - Internal 32KHz oscillator */
define CONF_CLOCK_OSC32K_ENABLE
true
define CONF_CLOCK_OSC32K_STARTUP_TIME
SYSTEM_OSC32K_STARTUP_130
define CONF_CLOCK_OSC32K_ENABLE_1KHZ_OUTPUT
true
define CONF_CLOCK_OSC32K_ENABLE_32KHZ_OUTPUT
true
define CONF_CLOCK_OSC32K_ON_DEMAND
true
define CONF_CLOCK_OSC32K_RUN_IN_STANDBY
false
The following generic clock settings are needed:
/*
#
#
#
#
#
Configure GCLK generator 2 (RTC) */
define CONF_CLOCK_GCLK_2_ENABLE
define CONF_CLOCK_GCLK_2_RUN_IN_STANDBY
define CONF_CLOCK_GCLK_2_CLOCK_SOURCE
define CONF_CLOCK_GCLK_2_PRESCALER
define CONF_CLOCK_GCLK_2_OUTPUT_ENABLE
8.1.2
Setup
8.1.2.1
Initialization Code
true
false
SYSTEM_CLOCK_SOURCE_OSC32K
32
false
Create an rtc_module struct and add to the main application source file, outside of any functions:
struct rtc_module rtc_instance;
Copy-paste the following setup code to your application:
void configure_rtc_calendar(void)
{
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
24
/* Initialize RTC in calendar mode. */
struct rtc_calendar_config config_rtc_calendar;
rtc_calendar_get_config_defaults(&config_rtc_calendar);
struct rtc_calendar_time alarm;
rtc_calendar_get_time_defaults(&alarm);
alarm.year
= 2013;
alarm.month = 1;
alarm.day
= 1;
alarm.hour
= 0;
alarm.minute = 0;
alarm.second = 4;
config_rtc_calendar.clock_24h
= true;
config_rtc_calendar.alarm[0].time = alarm;
config_rtc_calendar.alarm[0].mask = RTC_CALENDAR_ALARM_MASK_YEAR;
rtc_calendar_init(&rtc_instance, RTC, &config_rtc_calendar);
}
8.1.2.2
rtc_calendar_enable(&rtc_instance);
Add to Main
Add the following to main().
system_init();
struct rtc_calendar_time time;
time.year
= 2012;
time.month = 12;
time.day
= 31;
time.hour
= 23;
time.minute = 59;
time.second = 59;
configure_rtc_calendar();
/* Set current time. */
rtc_calendar_set_time(&rtc_instance, &time);
rtc_calendar_swap_time_mode(&rtc_instance);
8.1.2.3
Workflow
1.
Make configuration structure.
struct rtc_calendar_config config_rtc_calendar;
2.
Fill the configuration structure with the default driver configuration.
rtc_calendar_get_config_defaults(&config_rtc_calendar);
Note
This should always be performed before using the configuration struct to ensure that all values
are initialized to known default settings.
3.
Make time structure for alarm and set with default and desired values.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
25
struct rtc_calendar_time alarm;
rtc_calendar_get_time_defaults(&alarm);
alarm.year
= 2013;
alarm.month = 1;
alarm.day
= 1;
alarm.hour
= 0;
alarm.minute = 0;
alarm.second = 4;
4.
Change configurations as desired.
config_rtc_calendar.clock_24h
= true;
config_rtc_calendar.alarm[0].time = alarm;
config_rtc_calendar.alarm[0].mask = RTC_CALENDAR_ALARM_MASK_YEAR;
5.
Initialize module.
rtc_calendar_init(&rtc_instance, RTC, &config_rtc_calendar);
6.
Enable module.
rtc_calendar_enable(&rtc_instance);
8.1.3
Implementation
Add the following to main().
while (true) {
if (rtc_calendar_is_alarm_match(&rtc_instance, RTC_CALENDAR_ALARM_0)) {
/* Do something on RTC alarm match here */
port_pin_toggle_output_level(LED_0_PIN);
}
8.1.3.1
}
rtc_calendar_clear_alarm_match(&rtc_instance, RTC_CALENDAR_ALARM_0);
Workflow
1.
Start an infinite loop, to continuously poll for a RTC alarm match.
while (true) {
2.
Check to see if a RTC alarm match has occurred.
if (rtc_calendar_is_alarm_match(&rtc_instance, RTC_CALENDAR_ALARM_0)) {
3.
Once an alarm match occurs, perform the desired user action.
/* Do something on RTC alarm match here */
port_pin_toggle_output_level(LED_0_PIN);
4.
Clear the alarm match, so that future alarms may occur.
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
26
rtc_calendar_clear_alarm_match(&rtc_instance, RTC_CALENDAR_ALARM_0);
8.2
Quick Start Guide for RTC (CAL) - Callback
In this use case, the RTC is set up in calendar mode. The time is set and an alarm is enabled, as well as a callback
for when the alarm time is hit. Each time the callback fires, the alarm time is reset to five seconds in the future and
the board LED toggled.
8.2.1
Prerequisites
The Generic Clock Generator for the RTC should be configured and enabled; if you are using the System Clock
driver, this may be done via conf_clocks.h.
8.2.1.1
Clocks and Oscillators
The conf_clock.h file needs to be changed with the following values to configure the clocks and oscillators for
the module.
The following oscillator settings are needed:
/*
#
#
#
#
#
#
SYSTEM_CLOCK_SOURCE_OSC32K configuration - Internal 32KHz oscillator */
define CONF_CLOCK_OSC32K_ENABLE
true
define CONF_CLOCK_OSC32K_STARTUP_TIME
SYSTEM_OSC32K_STARTUP_130
define CONF_CLOCK_OSC32K_ENABLE_1KHZ_OUTPUT
true
define CONF_CLOCK_OSC32K_ENABLE_32KHZ_OUTPUT
true
define CONF_CLOCK_OSC32K_ON_DEMAND
true
define CONF_CLOCK_OSC32K_RUN_IN_STANDBY
false
The following generic clock settings are needed:
/*
#
#
#
#
#
Configure GCLK generator 2 (RTC) */
define CONF_CLOCK_GCLK_2_ENABLE
define CONF_CLOCK_GCLK_2_RUN_IN_STANDBY
define CONF_CLOCK_GCLK_2_CLOCK_SOURCE
define CONF_CLOCK_GCLK_2_PRESCALER
define CONF_CLOCK_GCLK_2_OUTPUT_ENABLE
8.2.2
Setup
8.2.2.1
Code
true
false
SYSTEM_CLOCK_SOURCE_OSC32K
32
false
Create an rtc_module struct and add to the main application source file, outside of any functions:
struct rtc_module rtc_instance;
The following must be added to the user application:
Function for setting up the module:
void configure_rtc_calendar(void)
{
/* Initialize RTC in calendar mode. */
struct rtc_calendar_config config_rtc_calendar;
rtc_calendar_get_config_defaults(&config_rtc_calendar);
alarm.time.year
alarm.time.month
alarm.time.day
alarm.time.hour
=
=
=
=
2013;
1;
1;
0;
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
27
alarm.time.minute
alarm.time.second
= 0;
= 4;
config_rtc_calendar.clock_24h = true;
config_rtc_calendar.alarm[0].time = alarm.time;
config_rtc_calendar.alarm[0].mask = RTC_CALENDAR_ALARM_MASK_YEAR;
rtc_calendar_init(&rtc_instance, RTC, &config_rtc_calendar);
}
rtc_calendar_enable(&rtc_instance);
Callback function:
void rtc_match_callback(void)
{
/* Do something on RTC alarm match here */
port_pin_toggle_output_level(LED_0_PIN);
/* Set new alarm in 5 seconds */
alarm.mask = RTC_CALENDAR_ALARM_MASK_SEC;
alarm.time.second += 5;
alarm.time.second = alarm.time.second % 60;
}
rtc_calendar_set_alarm(&rtc_instance, &alarm, RTC_CALENDAR_ALARM_0);
Function for setting up the callback functionality of the driver:
void configure_rtc_callbacks(void)
{
rtc_calendar_register_callback(
&rtc_instance, rtc_match_callback, RTC_CALENDAR_CALLBACK_ALARM_0);
rtc_calendar_enable_callback(&rtc_instance, RTC_CALENDAR_CALLBACK_ALARM_0);
}
Add to user application main():
system_init();
struct rtc_calendar_time time;
rtc_calendar_get_time_defaults(&time);
time.year
= 2012;
time.month = 12;
time.day
= 31;
time.hour
= 23;
time.minute = 59;
time.second = 59;
/* Configure and enable RTC */
configure_rtc_calendar();
/* Configure and enable callback */
configure_rtc_callbacks();
/* Set current time. */
rtc_calendar_set_time(&rtc_instance, &time);
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
28
8.2.2.2
Workflow
1.
Initialize system.
system_init();
2.
Create and initialize a time structure.
struct rtc_calendar_time time;
rtc_calendar_get_time_defaults(&time);
time.year
= 2012;
time.month = 12;
time.day
= 31;
time.hour
= 23;
time.minute = 59;
time.second = 59;
3.
Configure and enable module.
configure_rtc_calendar();
a.
Create a RTC configuration structure to hold the desired RTC driver settings and fill it with the default
driver configuration values.
struct rtc_calendar_config config_rtc_calendar;
rtc_calendar_get_config_defaults(&config_rtc_calendar);
Note
This should always be performed before using the configuration struct to ensure that all
values are initialized to known default settings.
b.
Create and initialize an alarm.
alarm.time.year
alarm.time.month
alarm.time.day
alarm.time.hour
alarm.time.minute
alarm.time.second
c.
=
=
=
=
=
=
2013;
1;
1;
0;
0;
4;
Change settings in the configuration and set alarm.
config_rtc_calendar.clock_24h = true;
config_rtc_calendar.alarm[0].time = alarm.time;
config_rtc_calendar.alarm[0].mask = RTC_CALENDAR_ALARM_MASK_YEAR;
d.
Initialize the module with the set configurations.
rtc_calendar_init(&rtc_instance, RTC, &config_rtc_calendar);
e.
Enable the module.
rtc_calendar_enable(&rtc_instance);
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
29
4.
Configure callback functionality.
configure_rtc_callbacks();
a.
Register overflow callback.
rtc_calendar_register_callback(
&rtc_instance, rtc_match_callback, RTC_CALENDAR_CALLBACK_ALARM_0);
b.
Enable overflow callback.
rtc_calendar_enable_callback(&rtc_instance, RTC_CALENDAR_CALLBACK_ALARM_0);
5.
Set time of the RTC calendar.
rtc_calendar_set_time(&rtc_instance, &time);
8.2.3
Implementation
8.2.3.1
Code
Add to user application main:
while (true) {
/* Infinite loop */
}
8.2.3.2
Workflow
1.
Infinite while loop while waiting for callbacks.
while (true) {
8.2.4
Callback
Each time the RTC time matches the configured alarm, the callback function will be called.
8.2.4.1
Workflow
1.
Create alarm struct and initialize the time with current time.
struct rtc_calendar_alarm_time alarm;
2.
Set alarm to trigger on seconds only.
alarm.mask = RTC_CALENDAR_ALARM_MASK_SEC;
3.
Add one second to the current time and set new alarm.
alarm.time.second += 5;
alarm.time.second = alarm.time.second % 60;
rtc_calendar_set_alarm(&rtc_instance, &alarm, RTC_CALENDAR_ALARM_0);
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
30
Index
E
Enumeration Definitions
rtc_calendar_alarm, 21
rtc_calendar_alarm_mask, 21
rtc_calendar_callback, 21
rtc_calendar_prescaler, 22
F
Function Definitions
rtc_calendar_clear_alarm_match, 18
rtc_calendar_clear_overflow, 17
rtc_calendar_disable, 13
rtc_calendar_disable_callback, 20
rtc_calendar_disable_events, 19
rtc_calendar_enable, 13
rtc_calendar_enable_callback, 20
rtc_calendar_enable_events, 18
rtc_calendar_frequency_correction, 14
rtc_calendar_get_alarm, 16
rtc_calendar_get_config_defaults, 12
rtc_calendar_get_time, 15
rtc_calendar_get_time_defaults, 11
rtc_calendar_init, 13
rtc_calendar_is_alarm_match, 17
rtc_calendar_is_overflow, 16
rtc_calendar_is_syncing, 11
rtc_calendar_register_callback, 19
rtc_calendar_reset, 12
rtc_calendar_set_alarm, 15
rtc_calendar_set_time, 15
rtc_calendar_swap_time_mode, 13
rtc_calendar_unregister_callback, 20
S
Structure Definitions
rtc_calendar_alarm_time, 10
rtc_calendar_config, 10
rtc_calendar_events, 10
rtc_calendar_time, 11
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
31
Document Revision History
Doc. Rev.
Date
Comments
D
12/2014
Added support for SAMR21 and
SAMD10/D11.
C
01/2014
Added support for SAMD21.
B
06/2013
Added additional documentation
on the event system. Corrected
documentation typos.
A
06/2013
Initial release
AT03266: SAM RTC Calendar Driver (RTC CAL) [APPLICATION NOTE]
42126D-SAMD20/D21-12/2014
32
Atmel Corporation
1600 Technology Drive, San Jose, CA 95110 USA
T: (+1)(408) 441.0311
F: (+1)(408) 436.4200
|
www.atmel.com
© 2014 Atmel Corporation. / Rev.: 42126D-SAMD20/D21-12/2014
®
®
Atmel , Atmel logo and combinations thereof, Enabling Unlimited Possibilities , and others are registered trademarks or trademarks of Atmel Corporation in U.S. and other
countries. Other terms and product names may be trademarks of others.
DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted
by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL
ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF
INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no
representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any
time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used
in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.
SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any applications where the failure of
such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without an Atmel officer's specific written consent. Safety-Critical Applications
include, without limitation, life support devices and systems, equipment or systems for the operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in
military or aerospace applications or environments unless specifically designated by Atmel as military- grade. Atmel products are not designed nor intended for use in automotive applications unless
specifically designated by Atmel as automotive-grade.