boards: shields: Add Adafruit PCF8523 real-time clock shield

Product image from https://learn.adafruit.com/assets/103710

Tested with the command mentioned in the index.rst file.

Compile-testing of the overlay file is done in CI via the
drivers/rtc sample.

Signed-off-by: Jonas Berg <[email protected]>

Author: pyhys

boards/shields/adafruit_pcf8523/Kconfig.shield

@@ -0,0 +1,5 @@
+# Copyright (c) 2025 Jonas Berg
+# SPDX-License-Identifier: Apache-2.0
+
+config SHIELD_ADAFRUIT_PCF8523
+	def_bool $(shields_list_contains,adafruit_pcf8523)

boards/shields/adafruit_pcf8523/adafruit_pcf8523.overlay

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2025 Jonas Berg
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	aliases {
+		rtc = &adafruit_pcf8523;
+	};
+};
+
+&zephyr_i2c {
+	status = "okay";
+
+	adafruit_pcf8523: pcf8523@68 {
+		status = "okay";
+		compatible = "nxp,pcf8523";
+		reg = <0x68>;
+		battery-switch-over = "standard";
+	};
+};

boards/shields/adafruit_pcf8523/doc/adafruit_pcf8523.webp

@@ -0,0 +1,63 @@
+.. _adafruit_pcf8523:
+
+Adafruit PCF8523 Shield
+#######################
+
+Overview
+********
+
+The `Adafruit PCF8523 Real Time Clock Shield`_ features
+an `NXP PCF8523 Real-Time clock`_ and two Qwiic connectors.
+It has a CR1220 3 Volt back-up coin-cell battery.
+
+.. figure:: adafruit_pcf8523.webp
+   :align: center
+   :alt: Adafruit PCF8523 Shield
+
+   Adafruit PCF8523 Shield (Credit: Adafruit)
+
+
+Requirements
+************
+
+This shield can be used with boards which provide an I2C connector, for
+example STEMMA QT or Qwiic connectors.
+The target board must define a ``zephyr_i2c`` node label.
+See :ref:`shields` for more details.
+
+
+Pin Assignments
+===============
+
++--------------+----------------------------------------------------------+
+| Shield Pin   | Function                                                 |
++==============+==========================================================+
+| SDA          | PCF8523 I2C SDA. Also connected to the Qwiic connector.  |
++--------------+----------------------------------------------------------+
+| SCL          | PCF8523 I2C SCL. Also connected to the Qwiic connector.  |
++--------------+----------------------------------------------------------+
+| SQW          | PCF8523 INT/CLK interrupt output or square wave output   |
++--------------+----------------------------------------------------------+
+
+To use the interrupt output from the PCF8523, you need to connect a wire from
+the shield SQW output to a suitable GPIO on your microcontroller board, and to
+modify the devicetree settings. See :dtcompatible:`nxp,pcf8523` for options.
+
+
+Programming
+***********
+
+Set ``--shield adafruit_pcf8523`` when you invoke ``west build``. For example
+when running the :zephyr:code-sample:`rtc` sample:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/drivers/rtc
+   :board: adafruit_qt_py_rp2040
+   :shield: adafruit_pcf8523
+   :goals: build
+
+.. _Adafruit PCF8523 Real Time Clock Shield:
+   https://learn.adafruit.com/adafruit-pcf8523-real-time-clock
+
+.. _NXP PCF8523 Real-Time clock:
+   https://www.nxp.com/products/analog-and-mixed-signal/real-time-clocks/100-na-real-time-clock-calendar-with-battery-backup:PCF8523

boards/shields/adafruit_pcf8523/doc/index.rst

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright (c) 2025, Jonas Berg
+
+shield:
+  name: adafruit_pcf8523
+  full_name: Adafruit PCF8523 Real Time Clock Shield
+  vendor: adafruit
+  supported_features:
+    - rtc

boards/shields/adafruit_pcf8523/shield.yml

@@ -23,7 +23,10 @@ tests:
   sample.drivers.rtc.shields:
     platform_allow:
       - adafruit_qt_py_rp2040/rp2040
+      - adafruit_metro_rp2040/rp2040
     integration_platforms:
       - adafruit_qt_py_rp2040/rp2040
+      - adafruit_metro_rp2040/rp2040
     extra_args:
       - platform:adafruit_qt_py_rp2040/rp2040:SHIELD="sparkfun_rv8803"
+      - platform:adafruit_metro_rp2040/rp2040:SHIELD="adafruit_pcf8523"