Skip to content

Commit

Permalink
Merge pull request #34 from jposada202020/improving_docs
Browse files Browse the repository at this point in the history
improving_docs
  • Loading branch information
jposada202020 authored Apr 25, 2021
2 parents 3061645 + 3eb5a93 commit b63c904
Show file tree
Hide file tree
Showing 4 changed files with 56 additions and 32 deletions.
28 changes: 12 additions & 16 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -85,51 +85,47 @@ Basics

Of course, you must import the library to use it:

.. code:: python
.. code:: python3
import busio
import adafruit_ds3231
import time
All the Adafruit RTC libraries take an instantiated and active I2C object
(from the ``busio`` library) as an argument to their constructor. The way to
(from the ``board`` library) as an argument to their constructor. The way to
create an I2C object depends on the board you are using. For boards with labeled
SCL and SDA pins, you can:

.. code:: python
.. code:: python3
from board import *
You can also use pins defined by the onboard ``microcontroller`` through the
``microcontroller.pin`` module.
import board
Now, to initialize the I2C bus:

.. code:: python
.. code:: python3
myI2C = busio.I2C(SCL, SDA)
i2c = board.I2C()
Once you have created the I2C interface object, you can use it to instantiate
the RTC object:

.. code:: python
.. code:: python3
rtc = adafruit_ds3231.DS3231(myI2C)
rtc = adafruit_ds3231.DS3231(i2c)
Date and time
-------------

To set the time, you need to set ``datetime`` to a ``time.struct_time`` object:

.. code:: python
.. code:: python3
rtc.datetime = time.struct_time((2017,1,9,15,6,0,0,9,-1))
After the RTC is set, you retrieve the time by reading the ``datetime``
attribute and access the standard attributes of a struct_time such as ``tm_year``,
``tm_hour`` and ``tm_min``.

.. code:: python
.. code:: python3
t = rtc.datetime
print(t)
Expand All @@ -141,15 +137,15 @@ Alarm
To set the time, you need to set ``alarm1`` or ``alarm2`` to a tuple with a
``time.struct_time`` object and string representing the frequency such as "hourly":

.. code:: python
.. code:: python3
rtc.alarm1 = (time.struct_time((2017,1,9,15,6,0,0,9,-1)), "daily")
After the RTC is set, you retrieve the alarm status by reading the corresponding
``alarm1_status`` or ``alarm2_status`` attributes. Once True, set it back to False
to reset.

.. code:: python
.. code:: python3
if rtc.alarm1_status:
print("wake up!")
Expand Down
45 changes: 41 additions & 4 deletions adafruit_ds3231.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
# SPDX-License-Identifier: MIT

"""
`adafruit_ds3231` - DS3231 Real Time Clock module
`adafruit_ds3231`
=================================================
CircuitPython library to support DS3231 Real Time Clock (RTC).
Expand All @@ -26,12 +26,14 @@
**Software and Dependencies:**
* Adafruit CircuitPython firmware for the ESP8622 and M0-based boards:
https://github.com/adafruit/circuitpython/releases
* Adafruit CircuitPython firmware for the supported boards:
https://circuitpython.org/downloads
* Adafruit's Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register
* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
**Notes:**
#. Milliseconds are not supported by this RTC.
Expand All @@ -49,7 +51,42 @@

# pylint: disable-msg=too-few-public-methods
class DS3231:
"""Interface to the DS3231 RTC."""
"""Interface to the DS3231 RTC.
:param ~busio.I2C i2c: The I2C bus the device is connected to
**Quickstart: Importing and using the device**
Here is an example of using the :class:`DS3231` class.
First you will need to import the libraries to use the sensor
.. code-block:: python
import time
import board
import adafruit_ds3231
Once this is done you can define your `board.I2C` object and define your sensor object
.. code-block:: python
i2c = board.I2C() # uses board.SCL and board.SDA
rtc = adafruit_ds3231.DS3231(i2c)
Now you can give the current time to the device.
.. code-block:: python
t = time.struct_time((2017, 10, 29, 15, 14, 15, 0, -1, -1))
rtc.datetime = t
You can access the current time accessing the :attr:`datetime` attribute.
.. code-block:: python
current_time = rtc.datetime
"""

lost_power = i2c_bit.RWBit(0x0F, 7)
"""True if the device has lost power since the time was set."""
Expand Down
2 changes: 2 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ Table of Contents
.. toctree::
:caption: Tutorials

Adafruit DS3231 Precision RTC Breakout Learning Guide <https://learn.adafruit.com/adafruit-ds3231-precision-rtc-breakout/>

.. toctree::
:caption: Related Products

Expand Down
13 changes: 1 addition & 12 deletions examples/ds3231_simpletest.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,9 @@

import time
import board

# For hardware I2C (M0 boards) use this line:
import busio as io

# Or for software I2C (ESP8266) use this line instead:
# import bitbangio as io

import adafruit_ds3231


i2c = io.I2C(board.SCL, board.SDA) # Change to the appropriate I2C clock & data
# pins here!

# Create the RTC instance:
i2c = board.I2C() # uses board.SCL and board.SDA
rtc = adafruit_ds3231.DS3231(i2c)

# Lookup table for names of days (nicer printing).
Expand Down

0 comments on commit b63c904

Please sign in to comment.