.. zephyr:code-sample:: ds3231 :name: DS3231 TCXO RTC :relevant-api: counter_interface Interact with a DS3231 real-time clock using the counter API and dedicated driver API. 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: https://www.adafruit.com/product/255