1  Introduction
  2  =============
  3  
  4  .. image:: https://readthedocs.org/projects/adafruit-micropython-ds3231/badge/?version=latest
  5      :target: https://circuitpython.readthedocs.io/projects/ds3231/en/latest/
  6      :alt: Documentation Status
  7  
  8  .. image :: https://img.shields.io/discord/327254708534116352.svg
  9      :target: https://adafru.it/discord
 10      :alt: Discord
 11  
 12  .. image:: https://github.com/adafruit/Adafruit_CircuitPython_DS3231/workflows/Build%20CI/badge.svg
 13      :target: https://github.com/adafruit/Adafruit_CircuitPython_DS3231/actions/
 14      :alt: Build Status
 15  
 16  The datasheet for the DS3231 explains that this part is an
 17  "Extremely Accurate I²C-Integrated RTC/TCXO/Crystal". And,
 18  hey, it does exactly what it says on the tin! This Real Time
 19  Clock (RTC) is the most precise you can get in a small, low
 20  power package.
 21  
 22  Most RTCs use an external 32kHz timing crystal that is used
 23  to keep time with low current draw. And that's all well and
 24  good, but those crystals have slight drift, particularly when
 25  the temperature changes (the temperature changes the oscillation
 26  frequency very very very slightly but it does add up!) This
 27  RTC is in a beefy package because the crystal is inside the
 28  chip! And right next to the integrated crystal is a temperature
 29  sensor. That sensor compensates for the frequency changes by
 30  adding or removing clock ticks so that the timekeeping stays
 31  on schedule.
 32  
 33  This is the finest RTC you can get, and now we have it in a
 34  compact, breadboard-friendly breakout. With a coin cell
 35  plugged into the back, you can get years of precision
 36  timekeeping, even when main power is lost. Great for
 37  datalogging and clocks, or anything where you need to
 38  really know the time.
 39  
 40  .. image:: ../docs/_static/3013-01.jpg
 41      :alt: DS3231 Product Image
 42  
 43  Dependencies
 44  =============
 45  This driver depends on:
 46  
 47  * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
 48  * `Bus Device <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
 49  * `Register <https://github.com/adafruit/Adafruit_CircuitPython_Register>`_
 50  
 51  Please ensure all dependencies are available on the CircuitPython filesystem.
 52  This is easily achieved by downloading
 53  `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 54  
 55  Installing from PyPI
 56  ====================
 57  
 58  On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
 59  PyPI <https://pypi.org/project/adafruit-circuitpython-ds3231/>`_. To install for current user:
 60  
 61  .. code-block:: shell
 62  
 63      pip3 install adafruit-circuitpython-ds3231
 64  
 65  To install system-wide (this may be required in some cases):
 66  
 67  .. code-block:: shell
 68  
 69      sudo pip3 install adafruit-circuitpython-ds3231
 70  
 71  To install in a virtual environment in your current project:
 72  
 73  .. code-block:: shell
 74  
 75      mkdir project-name && cd project-name
 76      python3 -m venv .env
 77      source .env/bin/activate
 78      pip3 install adafruit-circuitpython-ds3231
 79  
 80  Usage Notes
 81  ===========
 82  
 83  Basics
 84  ------
 85  
 86  Of course, you must import the library to use it:
 87  
 88  .. code:: python
 89  
 90      import busio
 91      import adafruit_ds3231
 92      import time
 93  
 94  All the Adafruit RTC libraries take an instantiated and active I2C object
 95  (from the ``busio`` library) as an argument to their constructor. The way to
 96  create an I2C object depends on the board you are using. For boards with labeled
 97  SCL and SDA pins, you can:
 98  
 99  .. code:: python
100  
101      from board import *
102  
103  You can also use pins defined by the onboard ``microcontroller`` through the
104  ``microcontroller.pin`` module.
105  
106  Now, to initialize the I2C bus:
107  
108  .. code:: python
109  
110      myI2C = busio.I2C(SCL, SDA)
111  
112  Once you have created the I2C interface object, you can use it to instantiate
113  the RTC object:
114  
115  .. code:: python
116  
117      rtc = adafruit_ds3231.DS3231(myI2C)
118  
119  Date and time
120  -------------
121  
122  To set the time, you need to set ``datetime`` to a ``time.struct_time`` object:
123  
124  .. code:: python
125  
126      rtc.datetime = time.struct_time((2017,1,9,15,6,0,0,9,-1))
127  
128  After the RTC is set, you retrieve the time by reading the ``datetime``
129  attribute and access the standard attributes of a struct_time such as ``tm_year``,
130  ``tm_hour`` and ``tm_min``.
131  
132  .. code:: python
133  
134      t = rtc.datetime
135      print(t)
136      print(t.tm_hour, t.tm_min)
137  
138  Alarm
139  -----
140  
141  To set the time, you need to set ``alarm1`` or ``alarm2`` to a tuple with a
142  ``time.struct_time`` object and string representing the frequency such as "hourly":
143  
144  .. code:: python
145  
146      rtc.alarm1 = (time.struct_time((2017,1,9,15,6,0,0,9,-1)), "daily")
147  
148  After the RTC is set, you retrieve the alarm status by reading the corresponding
149  ``alarm1_status`` or ``alarm2_status`` attributes. Once True, set it back to False
150  to reset.
151  
152  .. code:: python
153  
154      if rtc.alarm1_status:
155          print("wake up!")
156          rtc.alarm1_status = False
157  
158  Contributing
159  ============
160  
161  Contributions are welcome! Please read our `Code of Conduct
162  <https://github.com/adafruit/Adafruit_CircuitPython_DS3231/blob/master/CODE_OF_CONDUCT.md>`_
163  before contributing to help this project stay welcoming.
164  
165  Documentation
166  =============
167  
168  For information on building library documentation, please check out `this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.