| .. _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: |
| https://www.adafruit.com/product/255 |