Switch library to PCF8563, a similar RTC to PCF8523

.. but not so similar that we want to support them in the same library.

Author: jepler

README.rst

@@ -1,35 +1,32 @@
 
-Introduction to Adafruit's PCF8523 Real Time Clock (RTC) Library
+Introduction to Adafruit's PCF8563 Real Time Clock (RTC) Library
 ================================================================
 
-.. image:: https://readthedocs.org/projects/adafruit-circuitpython-pcf8523/badge/?version=latest
-    :target: https://circuitpython.readthedocs.io/projects/pcf8523/en/latest/
+.. image:: https://readthedocs.org/projects/adafruit-circuitpython-pcf8563/badge/?version=latest
+    :target: https://circuitpython.readthedocs.io/projects/pcf8563/en/latest/
     :alt: Documentation Status
 
 .. image :: https://img.shields.io/discord/327254708534116352.svg
     :target: https://discord.gg/nBQh6qu
     :alt: Discord
 
-.. image:: https://github.com/adafruit/Adafruit_CircuitPython_PCF8523/workflows/Build%20CI/badge.svg
-    :target: https://github.com/adafruit/Adafruit_CircuitPython_PCF8523/actions/
+.. image:: https://github.com/adafruit/Adafruit_CircuitPython_PCF8563/workflows/Build%20CI/badge.svg
+    :target: https://github.com/adafruit/Adafruit_CircuitPython_PCF8563/actions/
     :alt: Build Status
 
 This is a great battery-backed real time clock (RTC) that allows your
 microcontroller project to keep track of time even if it is reprogrammed,
 or if the power is lost. Perfect for datalogging, clock-building, time
-stamping, timers and alarms, etc. Equipped with PCF8523 RTC - it can
+stamping, timers and alarms, etc. Equipped with PCF8563 RTC - it can
 run from 3.3V or 5V power & logic!
 
-The PCF8523 is simple and inexpensive but not a high precision device.
-It may lose or gain up to two seconds a day. For a high-precision,
+The PCF8563 is simple and inexpensive but not a high precision device.
+It may lose or gain multiple seconds a day. For a high-precision,
 temperature compensated alternative, please check out the
 `DS3231 precision RTC. <https://www.adafruit.com/products/3013>`_
 If you need a DS1307 for compatibility reasons, check out our
 `DS1307 RTC breakout <https://www.adafruit.com/products/3296>`_.
 
-.. image:: _static/3295-00.jpg
-    :alt: PCF8523 Breakout Board
-
 Dependencies
 =============
 
@@ -42,17 +39,17 @@ This is easily achieved by downloading
 Installing from PyPI
 ====================
 On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
-PyPI <https://pypi.org/project/adafruit-circuitpython-pcf8523/>`_. To install for current user:
+PyPI <https://pypi.org/project/adafruit-circuitpython-pcf8563/>`_. To install for current user:
 
 .. code-block:: shell
 
-    pip3 install adafruit-circuitpython-pcf8523
+    pip3 install adafruit-circuitpython-pcf8563
 
 To install system-wide (this may be required in some cases):
 
 .. code-block:: shell
 
-    sudo pip3 install adafruit-circuitpython-pcf8523
+    sudo pip3 install adafruit-circuitpython-pcf8563
 
 To install in a virtual environment in your current project:
 
@@ -61,7 +58,7 @@ To install in a virtual environment in your current project:
     mkdir project-name && cd project-name
     python3 -m venv .env
     source .env/bin/activate
-    pip3 install adafruit-circuitpython-pcf8523
+    pip3 install adafruit-circuitpython-pcf8563
 
 
 Usage Notes
@@ -75,7 +72,7 @@ Of course, you must import the library to use it:
 .. code:: python
 
     import busio
-    import adafruit_pcf8523
+    import adafruit_pcf8563
     import time
 
 All the Adafruit RTC libraries take an instantiated and active I2C object
@@ -101,7 +98,7 @@ the RTC object:
 
 .. code:: python
 
-    rtc = adafruit_pcf8523.PCF8523(i2c_bus)
+    rtc = adafruit_pcf8563.PCF8563(i2c_bus)
 
 Date and time
 -------------
@@ -145,7 +142,7 @@ Contributing
 ============
 
 Contributions are welcome! Please read our `Code of Conduct
-<https://github.com/adafruit/Adafruit_CircuitPython_PCF8523/blob/master/CODE_OF_CONDUCT.md>`_
+<https://github.com/adafruit/Adafruit_CircuitPython_PCF8563/blob/master/CODE_OF_CONDUCT.md>`_
 before contributing to help this project stay welcoming.
 
 Documentation

adafruit_pcf8523.py renamed to adafruit_pcf8563.py

@@ -21,10 +21,10 @@
 # THE SOFTWARE.
 
 """
-`adafruit_pcf8523` - PCF8523 Real Time Clock module
+`adafruit_pcf8563` - PCF8563 Real Time Clock module
 ====================================================
 
-This library supports the use of the PCF8523-based RTC in CircuitPython. It
+This library supports the use of the PCF8563-based RTC in CircuitPython. It
 contains a base RTC class used by all Adafruit RTC libraries. This base
 class is inherited by the chip-specific subclasses.
 
@@ -40,9 +40,8 @@ class is inherited by the chip-specific subclasses.
 
 **Hardware:**
 
-* Adafruit `Adalogger FeatherWing - RTC + SD Add-on <https://www.adafruit.com/products/2922>`_
-  (Product ID: 2922)
-* Adafruit `PCF8523 RTC breakout <https://www.adafruit.com/products/3295>`_ (Product ID: 3295)
++* Seeeduino `XIAO Expansion Board - Works With Adafruit QT Py <https://www.adafruit.com/product/5033>`_
++  (Product ID: 5033)
 
 **Software and Dependencies:**
 
@@ -53,56 +52,47 @@ class is inherited by the chip-specific subclasses.
 **Notes:**
 
 #. Milliseconds are not supported by this RTC.
-#. Datasheet: http://cache.nxp.com/documents/data_sheet/PCF8523.pdf
+#. Datasheet: http://cache.nxp.com/documents/data_sheet/PCF8563.pdf
 
 """
 
 __version__ = "0.0.0-auto.0"
-__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_PCF8523.git"
+__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_PCF8563.git"
 
 from adafruit_bus_device.i2c_device import I2CDevice
 from adafruit_register import i2c_bit
-from adafruit_register import i2c_bits
 from adafruit_register import i2c_bcd_alarm
 from adafruit_register import i2c_bcd_datetime
 
-STANDARD_BATTERY_SWITCHOVER_AND_DETECTION = 0b000
-BATTERY_SWITCHOVER_OFF = 0b111
+import time
 
+class PCF8563:
+    """Interface to the PCF8563 RTC."""
 
-class PCF8523:
-    """Interface to the PCF8523 RTC."""
-
-    lost_power = i2c_bit.RWBit(0x03, 7)
-    """True if the device has lost power since the time was set."""
-
-    power_management = i2c_bits.RWBits(3, 0x02, 5)
-    """Power management state that dictates battery switchover, power sources
-    and low battery detection. Defaults to BATTERY_SWITCHOVER_OFF (0b000)."""
-
+    datetime_compromised = i2c_bit.RWBit(0x2, 7)
+    """True if the clock integrity is compromised."""
+    
     # The False means that day comes before weekday in the registers. The 0 is
     # that the first day of the week is value 0 and not 1.
-    datetime_register = i2c_bcd_datetime.BCDDateTimeRegister(0x03, False, 0)
+    datetime_register = i2c_bcd_datetime.BCDDateTimeRegister(0x02, False, 0)
     """Current date and time."""
 
     # The False means that day and weekday share a register. The 0 is that the
     # first day of the week is value 0 and not 1.
     alarm = i2c_bcd_alarm.BCDAlarmTimeRegister(
-        0x0A, has_seconds=False, weekday_shared=False, weekday_start=0
+        0x09, has_seconds=False, weekday_shared=False, weekday_start=0
     )
-    """Alarm time for the first alarm."""
+    """Alarm time for the alarm."""
 
-    alarm_interrupt = i2c_bit.RWBit(0x00, 1)
+    alarm_interrupt = i2c_bit.RWBit(0x01, 1)
     """True if the interrupt pin will output when alarm is alarming."""
 
     alarm_status = i2c_bit.RWBit(0x01, 3)
     """True if alarm is alarming. Set to False to reset."""
 
-    battery_low = i2c_bit.ROBit(0x02, 2)
-    """True if the battery is low and should be replaced."""
-
     def __init__(self, i2c_bus):
-        self.i2c_device = I2CDevice(i2c_bus, 0x68)
+        time.sleep(.05)
+        self.i2c_device = I2CDevice(i2c_bus, 0x51)
 
         # Try and verify this is the RTC we expect by checking the timer B
         # frequency control bits which are 1 on reset and shouldn't ever be
@@ -112,9 +102,6 @@ def __init__(self, i2c_bus):
         with self.i2c_device as i2c:
             i2c.write_then_readinto(buf, buf, out_end=1, in_start=1)
 
-        if (buf[1] & 0b00000111) != 0b00000111:
-            raise ValueError("Unable to find PCF8523 at i2c address 0x68.")
-
     @property
     def datetime(self):
         """Gets the current date and time or sets the current date and time then starts the
@@ -124,5 +111,5 @@ def datetime(self):
     @datetime.setter
     def datetime(self, value):
         # Automatically sets lost_power to false.
-        self.power_management = STANDARD_BATTERY_SWITCHOVER_AND_DETECTION
         self.datetime_register = value
+        self.datetime_compromised = False

docs/api.rst

@@ -1,3 +1,3 @@
 
-.. automodule:: adafruit_pcf8523
+.. automodule:: adafruit_pcf8563
    :members:

docs/conf.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Adafruit PCF8523 RTC Library documentation build configuration file, created by
+# Adafruit PCF8563 RTC Library documentation build configuration file, created by
 # sphinx-quickstart on Fri Nov 11 21:37:36 2016.
 #
 # This file is execfile()d with the current directory set to its
@@ -54,7 +54,7 @@
 master_doc = "index"
 
 # General information about the project.
-project = "Adafruit PCF8523 RTC Library"
+project = "Adafruit PCF8563 RTC Library"
 copyright = "2016, Philip Moyer"
 author = "Philip Moyer"
 
@@ -153,7 +153,7 @@
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
 #
-# html_title = u'Adafruit PCF8523 RTC Library v1.0'
+# html_title = u'Adafruit PCF8563 RTC Library v1.0'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #
@@ -252,7 +252,7 @@
 # html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-# htmlhelp_basename = 'AdafruitsPCF8523RTCLibrarydoc'
+# htmlhelp_basename = 'AdafruitsPCF8563RTCLibrarydoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -277,8 +277,8 @@
 latex_documents = [
     (
         master_doc,
-        "AdafruitPCF8523RTCLibrary.tex",
-        "Adafruit PCF8523 RTC Library Documentation",
+        "AdafruitPCF8563RTCLibrary.tex",
+        "Adafruit PCF8563 RTC Library Documentation",
         "Philip Moyer",
         "manual",
     ),
@@ -324,8 +324,8 @@
 man_pages = [
     (
         master_doc,
-        "AdafruitPCF8523RTCLibrary23rtclibrary",
-        "Adafruit PCF8523 RTC Library Documentation",
+        "AdafruitPCF8563RTCLibrary23rtclibrary",
+        "Adafruit PCF8563 RTC Library Documentation",
         [author],
         1,
     )
@@ -344,10 +344,10 @@
 texinfo_documents = [
     (
         master_doc,
-        "AdafruitPCF8523RTCLibrary",
-        "Adafruit PCF8523 RTC Library Documentation",
+        "AdafruitPCF8563RTCLibrary",
+        "Adafruit PCF8563 RTC Library Documentation",
         author,
-        "AdafruitPCF8523RTCLibrary",
+        "AdafruitPCF8563RTCLibrary",
         "One line description of project.",
         "Miscellaneous",
     ),

docs/examples.rst

@@ -1,6 +1,6 @@
 Demo
 ----
 
-.. literalinclude:: ../examples/pcf8523_simpletest.py
-    :caption: examples/pcf8523_simpletest.py
+.. literalinclude:: ../examples/pcf8563_simpletest.py
+    :caption: examples/pcf8563_simpletest.py
     :linenos:

docs/index.rst

@@ -20,22 +20,15 @@ Table of Contents
 
     api
 
-.. toctree::
-    :caption: Tutorials
-
-    Adafruit PCF8523 Real Time Clock <https://learn.adafruit.com/adafruit-pcf8523-real-time-clock?view=all>
-    Adafruit Adalogger FeatherWing <https://learn.adafruit.com/adafruit-adalogger-featherwing?view=all>
-
 .. toctree::
     :caption: Related Products
 
-    Adafruit PCF8523 Real Time Clock Breakout <https://www.adafruit.com/product/3295>
-    Adafruit Adalogger FeatherWing - RTC + SD <https://www.adafruit.com/product/2922>
+    Seeeduino `XIAO Expansion Board - Works With Adafruit QT Py <https://www.adafruit.com/product/5033>`_
 
 .. toctree::
     :caption: Other Links
 
-    Download <https://github.com/adafruit/Adafruit_CircuitPython_PCF8523/releases/latest>
+    Download <https://github.com/adafruit/Adafruit_CircuitPython_PCF8563/releases/latest>
     CircuitPython Reference Documentation <https://circuitpython.readthedocs.io>
     CircuitPython Support Forum <https://forums.adafruit.com/viewforum.php?f=60>
     Discord Chat <https://adafru.it/discord>

examples/pcf8523_simpletest.py renamed to examples/pcf8563_simpletest.py

@@ -1,24 +1,19 @@
-# Simple demo of reading and writing the time for the PCF8523 real-time clock.
+# Simple demo of reading and writing the time for the PCF8563 real-time clock.
 # Change the if False to if True below to set the time, otherwise it will just
 # print the current date and time every second.  Notice also comments to adjust
 # for working with hardware vs. software I2C.
 
 import time
 import board
+import busio
 
-# 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_pcf8523
+import adafruit_pcf8563
 
 # Change to the appropriate I2C clock & data pins here!
-i2c_bus = io.I2C(board.SCL, board.SDA)
+i2c_bus = busio.I2C(board.SCL, board.SDA)
 
 # Create the RTC instance:
-rtc = adafruit_pcf8523.PCF8523(i2c_bus)
+rtc = adafruit_pcf8563.PCF8563(i2c_bus)
 
 # Lookup table for names of days (nicer printing).
 days = ("Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday")
@@ -37,8 +32,13 @@
 # pylint: enable-msg=using-constant-test
 # pylint: enable-msg=bad-whitespace
 
+
 # Main loop:
 while True:
+    if rtc.datetime_compromised:
+        print("RTC unset")
+    else:
+        print("RTC reports time is valid")
     t = rtc.datetime
     # print(t)     # uncomment for debugging
     print(

setup.py

@@ -19,14 +19,14 @@
     long_description = f.read()
 
 setup(
-    name="adafruit-circuitpython-pcf8523",
+    name="adafruit-circuitpython-pcf8563",
     use_scm_version=True,
     setup_requires=["setuptools_scm"],
-    description="CircuitPython library for PCF8523 real time clock.",
+    description="CircuitPython library for PCF8563 real time clock.",
     long_description=long_description,
     long_description_content_type="text/x-rst",
     # The project's main homepage.
-    url="https://github.com/adafruit/Adafruit_CircuitPython_PCF8523",
+    url="https://github.com/adafruit/Adafruit_CircuitPython_PCF8563",
     # Author details
     author="Adafruit Industries",
     author_email="[email protected]",
@@ -49,8 +49,8 @@
         "Programming Language :: Python :: 3.5",
     ],
     # What does your project relate to?
-    keywords="adafruit pcf8523 real time clock rtc breakout hardware micropython circuitpython",
+    keywords="adafruit pcf8563 real time clock rtc breakout hardware micropython circuitpython",
     # You can just specify the packages manually here if your project is
     # simple. Or you can use find_packages().
-    py_modules=["adafruit_pcf8523"],
+    py_modules=["adafruit_pcf8563"],
 )