1  
  2  Introduction
  3  ============
  4  
  5  .. image:: https://readthedocs.org/projects/adafruit-circuitpython-ds1307/badge/?version=latest
  6      :target: https://circuitpython.readthedocs.io/projects/ds1307/en/latest/
  7      :alt: Documentation Status
  8  
  9  .. image :: https://img.shields.io/discord/327254708534116352.svg
 10      :target: https://adafru.it/discord
 11      :alt: Discord
 12  
 13  .. image:: https://github.com/adafruit/Adafruit_CircuitPython_DS1307/workflows/Build%20CI/badge.svg
 14      :target: https://github.com/adafruit/Adafruit_CircuitPython_DS1307/actions/
 15      :alt: Build Status
 16  
 17  This is a great battery-backed real time clock (RTC) that allows your
 18  microcontroller project to keep track of time even if it is reprogrammed,
 19  or if the power is lost. Perfect for datalogging, clock-building,
 20  time stamping, timers and alarms, etc. The DS1307 is the most popular
 21  RTC - but it requires 5V power to work.
 22  
 23  The DS1307 is simple and inexpensive but not a high precision device. It may
 24  lose or gain up to two seconds a day. For a high-precision, temperature
 25  compensated alternative, please check out the
 26  `DS3231 precision RTC <https://www.adafruit.com/products/3013/>`_.
 27  If you do not need a DS1307, or you need a 3.3V-power/logic capable RTC
 28  please check out our affordable
 29  `PCF8523 RTC breakout <https://www.adafruit.com/products/3295>`_.
 30  
 31  .. image:: ../docs/_static/3296-00.jpg
 32      :alt: DS1307
 33  
 34  Dependencies
 35  =============
 36  This driver depends on:
 37  
 38  * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
 39  * `Bus Device <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
 40  * `Register <https://github.com/adafruit/Adafruit_CircuitPython_Register>`_
 41  
 42  Please ensure all dependencies are available on the CircuitPython filesystem.
 43  This is easily achieved by downloading
 44  `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 45  
 46  Installing from PyPI
 47  =====================
 48  On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
 49  PyPI <https://pypi.org/project/adafruit-circuitpython-ds1307/>`_. To install for current user:
 50  
 51  .. code-block:: shell
 52  
 53      pip3 install adafruit-circuitpython-ds1307
 54  
 55  To install system-wide (this may be required in some cases):
 56  
 57  .. code-block:: shell
 58  
 59      sudo pip3 install adafruit-circuitpython-ds1307
 60  
 61  To install in a virtual environment in your current project:
 62  
 63  .. code-block:: shell
 64  
 65      mkdir project-name && cd project-name
 66      python3 -m venv .env
 67      source .env/bin/activate
 68      pip3 install adafruit-circuitpython-ds1307
 69  
 70  Usage Notes
 71  ===========
 72  
 73  Of course, you must import the library to use it:
 74  
 75  .. code:: python
 76  
 77      import busio
 78      import adafruit_ds1307
 79      import time
 80  
 81  All the Adafruit RTC libraries take an instantiated and active I2C object
 82  (from the ``busio`` library) as an argument to their constructor. The way to
 83  create an I2C object depends on the board you are using. For boards with labeled
 84  SCL and SDA pins, you can:
 85  
 86  .. code:: python
 87  
 88      from board import *
 89  
 90  You can also use pins defined by the onboard ``microcontroller`` through the
 91  ``microcontroller.pin`` module.
 92  
 93  Now, to initialize the I2C bus:
 94  
 95  .. code:: python
 96  
 97      myI2C = busio.I2C(SCL, SDA)
 98  
 99  Once you have created the I2C interface object, you can use it to instantiate
100  the RTC object:
101  
102  .. code:: python
103  
104      rtc = adafruit_ds1307.DS1307(myI2C)
105  
106  To set the time, you need to set ``datetime`` to a `time.struct_time` object:
107  
108  .. code:: python
109  
110      rtc.datetime = time.struct_time((2017,1,9,15,6,0,0,9,-1))
111  
112  After the RTC is set, you retrieve the time by reading the ``datetime``
113  attribute and access the standard attributes of a struct_time such as ``tm_year``,
114  ``tm_hour`` and ``tm_min``.
115  
116  .. code:: python
117  
118      t = rtc.datetime
119      print(t)
120      print(t.tm_hour, t.tm_min)
121  
122  Contributing
123  ============
124  
125  Contributions are welcome! Please read our `Code of Conduct
126  <https://github.com/adafruit/Adafruit_CircuitPython_DS1307/blob/master/CODE_OF_CONDUCT.md>`_
127  before contributing to help this project stay welcoming.
128  
129  Documentation
130  =============
131  
132  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>`_.