1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
/*
* MIT License
*
* Copyright (c) 2020 Joey Castillo
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
#ifndef _WATCH_RTC_H_INCLUDED
#define _WATCH_RTC_H_INCLUDED
////< @file watch_rtc.h
#include "watch.h"
#include "hpl_calendar.h"
/** @addtogroup rtc Real-Time Clock
* @brief This section covers functions related to the SAM L22's real-time clock peripheral, including
* date, time and alarm functions.
* @details The real-time clock is the only peripheral that main.c enables for you. It is the cornerstone
* of low power operation on the watch, and it is required for several key functions that we
* assume will be available, namely the wake from BACKUP mode and the callback on the ALARM button.
* It is also required for the operation of the 1 Hz tick interrupt, which you will most likely use
* to wake from STANDBY mode.
*/
/// @{
#define WATCH_RTC_REFERENCE_YEAR (2020)
typedef union {
struct {
uint32_t second : 6; // 0-59
uint32_t minute : 6; // 0-59
uint32_t hour : 5; // 0-23
uint32_t day : 5; // 1-31
uint32_t month : 4; // 1-12
uint32_t year : 6; // 0-63 (representing 2020-2083)
} unit;
uint32_t reg; // the bit-packed value as expected by the RTC peripheral's CLOCK register.
} watch_date_time;
typedef enum watch_rtc_alarm_match {
ALARM_MATCH_DISABLED = 0,
ALARM_MATCH_SS,
ALARM_MATCH_MMSS,
ALARM_MATCH_HHMMSS,
} watch_rtc_alarm_match;
/** @brief Called by main.c to check if the RTC is enabled.
* You may call this function, but outside of app_init, it should always return true.
*/
bool _watch_rtc_is_enabled();
/** @brief Sets the date and time.
* @param date_time The date and time you wish to set, with a year value from 0-63 representing 2020-2083.
* @note The SAM L22 stores the year as six bits representing a value from 0 to 63. It treats this as a year
* offset from a reference year, which must be a leap year. Since 2020 was a leap year, and it allows
* useful dates through 2083, it is assumed that watch apps will use 2020 as the reference year; thus
* 1 means 2021, 2 means 2022, etc. **You will be responsible for handling this offset in your code**,
* if the calendar year is needed for timestamp calculation logic or display purposes.
*/
void watch_rtc_set_date_time(watch_date_time date_time);
/** @brief Returns the date and time.
* @return A watch_date_time with the current date and time, with a year value from 0-63 representing 2020-2083.
* @see watch_rtc_set_date_time for notes about how the year is stored.
*/
watch_date_time watch_rtc_get_date_time();
/** @brief Registers an alarm callback that will be called when the RTC time matches the target time, as masked
* by the provided mask.
* @param callback The function you wish to have called when the alarm fires. If this value is NULL, the alarm
* interrupt will still be enabled, but no callback function will be called.
* @param alarm_time The time that you wish to match. The date is currently ignored.
* @param mask One of the values in watch_rtc_alarm_match indicating which values to check.
* @details The alarm interrupt is a versatile tool for scheduling events in the future, especially since it can
* wake the device from both shallow and deep sleep modes. The key to its versatility is the mask
* parameter. Suppose we set an alarm for midnight, 00:00:00.
* * if mask is ALARM_MATCH_SS, the alarm will fire every minute when the clock ticks to seconds == 0.
* * with ALARM_MATCH_MMSS, the alarm will once an hour, at the top of each hour.
* * with ALARM_MATCH_HHMMSS, the alarm will fire at midnight every day.
* In theory the SAM L22's alarm function can match on days, months and even years, but I have not had
* success with this yet; as such, I am omitting these options for now.
*/
void watch_rtc_register_alarm_callback(ext_irq_cb_t callback, watch_date_time alarm_time, watch_rtc_alarm_match mask);
/** @brief Disables the alarm callback.
*/
void watch_rtc_disable_alarm_callback();
/** @brief Registers a "tick" callback that will be called once per second.
* @param callback The function you wish to have called when the clock ticks. If you pass in NULL, the tick
* interrupt will still be enabled, but no callback function will be called.
* @note this is equivalent to calling watch_rtc_register_periodic_callback with a frequency of 1. It can be
* disabled with either watch_rtc_disable_tick_callback() or watch_rtc_disable_periodic_callback(1),
* and will also be disabled when watch_rtc_disable_all_periodic_callbacks is called.
*/
void watch_rtc_register_tick_callback(ext_irq_cb_t callback);
/** @brief Disables the tick callback for the given period.
*/
void watch_rtc_disable_tick_callback();
/** @brief Registers a callback that will be called at a configurable period.
* @param callback The function you wish to have called at the specified period. If you pass in NULL, the periodic
* interrupt will still be enabled, but no callback function will be called.
* @param frequency The frequency of the tick in Hz. **Must be a power of 2**, from 1 to 128 inclusive.
* @note A 1 Hz tick (@see watch_rtc_register_tick_callback) is suitable for most applications, in that it gives you a
* chance to update the display once a second — an ideal update rate for a watch! If however you are displaying
* a value (such as an accelerometer output) that updates more frequently than once per second, you may want to
* tick at 16 or 32 Hz to update the screen more quickly. Just remember that the more frequent the tick, the more
* power your app will consume. Ideally you should enable the fast tick only when the user requires it (i.e. in
* response to an input event), and move back to the slow tick after some time.
*
* Also note that the RTC peripheral does not have sub-second resolution, so even if you set a 2 or 4 Hz interval,
* the system will not have any way of telling you where you are within a given second; watch_rtc_get_date_time
* will return the exact same timestamp until the second ticks over.
*/
void watch_rtc_register_periodic_callback(ext_irq_cb_t callback, uint8_t frequency);
/** @brief Disables the tick callback for the given period.
* @param frequency The frequency of the tick you wish to disable, in Hz. **Must be a power of 2**, from 1 to 128.
*/
void watch_rtc_disable_periodic_callback(uint8_t frequency);
/** @brief Disables all periodic callbacks, including the once-per-second tick callback.
*/
void watch_rtc_disable_all_periodic_callbacks();
/** @brief Sets the system date and time.
* @param date_time A struct representing the date and time you wish to set.
*/
__attribute__((deprecated("Use watch_rtc_set_date_time function instead")))
void watch_set_date_time(struct calendar_date_time date_time);
/** @brief Returns the system date and time in the provided struct.
* @param date_time A pointer to a calendar_date_time struct. It will have with the correct date and time on return.
*/
__attribute__((deprecated("Use the watch_rtc_get_date_time function instead")))
void watch_get_date_time(struct calendar_date_time *date_time);
/** @brief Registers a "tick" callback that will be called once per second.
* @param callback The function you wish to have called when the clock ticks. If you pass in NULL, the tick
* interrupt will still be enabled, but no callback function will be called.
*/
__attribute__((deprecated("Use the watch_rtc_register_tick_callback function instead")))
void watch_register_tick_callback(ext_irq_cb_t callback);
/// @}
#endif
|
