155 lines
5.3 KiB
ReStructuredText
155 lines
5.3 KiB
ReStructuredText
.. _maxim-ds3231-sample:
|
|
|
|
Maxim DS3231 TCXO RTC Sample Application
|
|
########################################
|
|
|
|
Overview
|
|
********
|
|
|
|
The `DS3231`_ temperature-compensated real-time clock is a
|
|
high-precision (2 ppm) battery backed clock that maintains civil time
|
|
and supports alarms. The `Chronodot`_ breakout board can be used to
|
|
test it.
|
|
|
|
Annotated Example Output
|
|
************************
|
|
|
|
The sample first displays the boot banner, board identifier and
|
|
frequency of the local clock used for synchronization, and whether the
|
|
DS3231 has recorded a loss-of-oscillator::
|
|
|
|
***** Booting Zephyr OS build zephyr-v1.14.0-2409-g322d53aedaa0 *****
|
|
DS3231 on particle_xenon syncclock 1000 Hz
|
|
.
|
|
DS3231 has not experienced an oscillator fault
|
|
|
|
Next, information about the device as a counter is displayed. The
|
|
counter value is read, and its value formatted as the date, time, day of
|
|
week, and day of year (19 July 2019 is a Friday, and is the 200th day of
|
|
2019)::
|
|
|
|
Counter at 0x20001a58
|
|
Max top value: 4294967295 (ffffffff)
|
|
2 channels
|
|
1 Hz
|
|
Top counter value: 4294967295 (ffffffff)
|
|
Now 1563512509: 2019-07-19 05:01:49 Fri 200
|
|
|
|
The DS3231 control and status register values are displayed::
|
|
|
|
DS3231 ctrl 04 ; ctrl_stat 08
|
|
|
|
Next, if the sample application option ``CONFIG_APP_SET_ALIGNED_CLOCK``
|
|
is set, the civil time will be advanced to the start of the next hour,
|
|
and the clock will be set to align that time with the time of the boot,
|
|
which in the output below is 34 ms in the past. The time required to
|
|
synchronize the clock is 967 ms, and the whole second value of one
|
|
second past the hour is written at 1000 ms local uptime::
|
|
|
|
Set 2019-07-19 06:00:00.034000000 Fri 200 at 34 ms past: 0
|
|
Synchronize final: 0 0 in 967 ms
|
|
wrote sync 0: 1563516001 0 at 1000
|
|
|
|
Then a synchronization point is read. This takes 894 ms (it must align
|
|
to an RTC one-second rollover)::
|
|
|
|
Synchronize init: 0
|
|
Synchronize complete in 894 ms: 0 0
|
|
.
|
|
read sync 0: 1563516002 0 at 2000
|
|
|
|
The alarm configuration is read from non-volatile memory and displayed.
|
|
See the ``maxim_ds3231.h`` for interpretation of the integer value and
|
|
flags::
|
|
|
|
Alarm 1 flags 0 at 254034017: 0
|
|
Alarm 2 flags e at 252374400: 0
|
|
|
|
Five seconds is added to the current time and the civil time
|
|
representation displayed. The second-resolution alarm is configured to
|
|
fire at that time on the current day-of-week. The minute-resolution
|
|
alarm is configured to fire once per minute::
|
|
|
|
Min Sec base time: 2019-07-19 06:00:07 Fri 200
|
|
Set sec alarm 90 at 1563516007 ~ 2019-07-19 06:00:07 Fri 200: 5
|
|
Set min alarm flags f at 1563516007 ~ 2019-07-19 06:00:07 Fri 200: 7
|
|
|
|
We're now 2.131 ms into the run, at which point the alarms are read back
|
|
and displayed. Alarms do not include date but can include day-of-week
|
|
or day-of-month; the date is selected to preserve that information::
|
|
|
|
2131 ms in: get alarms: 0 0
|
|
Sec alarm flags 10 at 252914407 ~ 1978-01-06 06:00:07 Fri 006
|
|
Min alarm flags e at 252374400 ~ 1977-12-31 00:00:00 Sat 365
|
|
|
|
The second-resolution alarm was signalled, and processed by the
|
|
application at 7.002 s into the run, as scheduled (plus callback
|
|
latency). The callback uses the counter alarm API to schedule a second
|
|
alarm in 10 seconds::
|
|
|
|
Sec signaled at 7002 ms, param 0x20000048, delay 1; set 7
|
|
|
|
The counter API callback is called at the correct time::
|
|
|
|
Counter callback at 17001 ms, id 0, ticks 1563516017, ud 0x20000048
|
|
|
|
From here on the sample sleeps except when the minute-resolution alarm
|
|
fires, at which point it displays the RTC time; the
|
|
nanosecond-resolution offset in seconds between the RTC time and the
|
|
local time; the local time from ``k_uptime_get()``; and the aggregate
|
|
error between local and RTC time measured in parts-per-million::
|
|
|
|
2019-07-19 06:01:00 Fri 200: adj 0.002000000, uptime 0:01:00.002, clk err 34 ppm
|
|
2019-07-19 06:02:00 Fri 200: adj 0.003000000, uptime 0:02:00.004, clk err 25 ppm
|
|
2019-07-19 06:03:00 Fri 200: adj 0.005000000, uptime 0:03:00.005, clk err 28 ppm
|
|
2019-07-19 06:04:00 Fri 200: adj 0.006000000, uptime 0:04:00.007, clk err 25 ppm
|
|
2019-07-19 06:05:00 Fri 200: adj 0.008000000, uptime 0:05:00.008, clk err 26 ppm
|
|
|
|
The output shows that the Zephyr system clock is running about 25 ppm
|
|
faster than civil time on this device. This amount of error is expected
|
|
for this target as the system time derives from a crystal oscillator
|
|
with a similar accuracy.
|
|
|
|
Building and Running
|
|
********************
|
|
|
|
Wire a Chronodot to one of the supported boards as specified in the
|
|
corresponding devicetree overlay.
|
|
|
|
* Particle Xenon
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/drivers/counter/maxim_ds3231
|
|
:board: particle-xenon
|
|
:goals: build
|
|
:compact:
|
|
|
|
* NXP Freedom K64F
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/drivers/counter/maxim_ds3231
|
|
:board: frdm_k64f
|
|
:goals: build
|
|
:compact:
|
|
|
|
* ST Nucleo L476RG
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/drivers/counter/maxim_ds3231
|
|
:board: nucleo_l476rg
|
|
:goals: build
|
|
:compact:
|
|
|
|
* EFR32 Mighty Gecko Thunderboard Sense 2
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/drivers/counter/maxim_ds3231
|
|
:board: efr32mg_sltb004a
|
|
:goals: build
|
|
:compact:
|
|
|
|
.. _DS3231:
|
|
https://www.maximintegrated.com/en/products/analog/real-time-clocks/DS3231.html
|
|
.. _Chronodot:
|
|
http://macetech.com/store/index.php?main_page=product_info&products_id=8
|