1.. _maxim-ds3231-sample:
2
3Maxim DS3231 TCXO RTC Sample Application
4########################################
5
6Overview
7********
8
9The `DS3231`_ temperature-compensated real-time clock is a
10high-precision (2 ppm) battery backed clock that maintains civil time
11and supports alarms.  The `Chronodot`_ breakout board can be used to
12test it.
13
14Annotated Example Output
15************************
16
17The sample first displays the boot banner, board identifier and
18frequency of the local clock used for synchronization, and whether the
19DS3231 has recorded a loss-of-oscillator::
20
21   ***** Booting Zephyr OS build zephyr-v1.14.0-2409-g322d53aedaa0 *****
22   DS3231 on particle_xenon syncclock 1000 Hz
23   .
24   DS3231 has not experienced an oscillator fault
25
26Next, information about the device as a counter is displayed.  The
27counter value is read, and its value formatted as the date, time, day of
28week, and day of year (19 July 2019 is a Friday, and is the 200th day of
292019)::
30
31   Counter at 0x20001a58
32           Max top value: 4294967295 (ffffffff)
33           2 channels
34           1 Hz
35   Top counter value: 4294967295 (ffffffff)
36   Now 1563512509: 2019-07-19 05:01:49 Fri 200
37
38The DS3231 control and status register values are displayed::
39
40   DS3231 ctrl 04 ; ctrl_stat 08
41
42Next, if the sample application option ``CONFIG_APP_SET_ALIGNED_CLOCK``
43is set, the civil time will be advanced to the start of the next hour,
44and the clock will be set to align that time with the time of the boot,
45which in the output below is 34 ms in the past.  The time required to
46synchronize the clock is 967 ms, and the whole second value of one
47second past the hour is written at 1000 ms local uptime::
48
49   Set 2019-07-19 06:00:00.034000000 Fri 200 at 34 ms past: 0
50   Synchronize final: 0 0 in 967 ms
51   wrote sync 0: 1563516001 0 at 1000
52
53Then a synchronization point is read.  This takes 894 ms (it must align
54to an RTC one-second rollover)::
55
56   Synchronize init: 0
57   Synchronize complete in 894 ms: 0 0
58   .
59   read sync 0: 1563516002 0 at 2000
60
61The alarm configuration is read from non-volatile memory and displayed.
62See the ``maxim_ds3231.h`` for interpretation of the integer value and
63flags::
64
65   Alarm 1 flags 0 at 254034017: 0
66   Alarm 2 flags e at 252374400: 0
67
68Five seconds is added to the current time and the civil time
69representation displayed.  The second-resolution alarm is configured to
70fire at that time on the current day-of-week.  The minute-resolution
71alarm is configured to fire once per minute::
72
73   Min Sec base time: 2019-07-19 06:00:07 Fri 200
74   Set sec alarm 90 at 1563516007 ~ 2019-07-19 06:00:07 Fri 200: 5
75   Set min alarm flags f at 1563516007 ~ 2019-07-19 06:00:07 Fri 200: 7
76
77We're now 2.131 ms into the run, at which point the alarms are read back
78and displayed.  Alarms do not include date but can include day-of-week
79or day-of-month; the date is selected to preserve that information::
80
81   2131 ms in: get alarms: 0 0
82   Sec alarm flags 10 at 252914407 ~ 1978-01-06 06:00:07 Fri 006
83   Min alarm flags e at 252374400 ~ 1977-12-31 00:00:00 Sat 365
84
85The second-resolution alarm was signalled, and processed by the
86application at 7.002 s into the run, as scheduled (plus callback
87latency).  The callback uses the counter alarm API to schedule a second
88alarm in 10 seconds::
89
90   Sec signaled at 7002 ms, param 0x20000048, delay 1; set 7
91
92The counter API callback is called at the correct time::
93
94   Counter callback at 17001 ms, id 0, ticks 1563516017, ud 0x20000048
95
96From here on the sample sleeps except when the minute-resolution alarm
97fires, at which point it displays the RTC time; the
98nanosecond-resolution offset in seconds between the RTC time and the
99local time; the local time from ``k_uptime_get()``; and the aggregate
100error between local and RTC time measured in parts-per-million::
101
102   2019-07-19 06:01:00 Fri 200: adj 0.002000000, uptime 0:01:00.002, clk err 34 ppm
103   2019-07-19 06:02:00 Fri 200: adj 0.003000000, uptime 0:02:00.004, clk err 25 ppm
104   2019-07-19 06:03:00 Fri 200: adj 0.005000000, uptime 0:03:00.005, clk err 28 ppm
105   2019-07-19 06:04:00 Fri 200: adj 0.006000000, uptime 0:04:00.007, clk err 25 ppm
106   2019-07-19 06:05:00 Fri 200: adj 0.008000000, uptime 0:05:00.008, clk err 26 ppm
107
108The output shows that the Zephyr system clock is running about 25 ppm
109faster than civil time on this device.  This amount of error is expected
110for this target as the system time derives from a crystal oscillator
111with a similar accuracy.
112
113Building and Running
114********************
115
116Wire a Chronodot to one of the supported boards as specified in the
117corresponding devicetree overlay.
118
119* Particle Xenon
120
121  .. zephyr-app-commands::
122     :zephyr-app: samples/drivers/counter/maxim_ds3231
123     :board: particle-xenon
124     :goals: build
125     :compact:
126
127* NXP Freedom K64F
128
129  .. zephyr-app-commands::
130     :zephyr-app: samples/drivers/counter/maxim_ds3231
131     :board: frdm_k64f
132     :goals: build
133     :compact:
134
135* ST Nucleo L476RG
136
137  .. zephyr-app-commands::
138     :zephyr-app: samples/drivers/counter/maxim_ds3231
139     :board: nucleo_l476rg
140     :goals: build
141     :compact:
142
143* EFR32 Mighty Gecko Thunderboard Sense 2
144
145  .. zephyr-app-commands::
146     :zephyr-app: samples/drivers/counter/maxim_ds3231
147     :board: efr32mg_sltb004a
148     :goals: build
149     :compact:
150
151.. _DS3231:
152   https://www.maximintegrated.com/en/products/analog/real-time-clocks/DS3231.html
153.. _Chronodot:
154   http://macetech.com/store/index.php?main_page=product_info&products_id=8
155