Merge pull request #1 from CDFER/1.2.0

1.2.0

LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2019 lewis he
+Copyright (c) 2023 Chris Dirks
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,55 +1,67 @@
-pcf8563-RTC
-=====================================
-A library to interace esp chips with the NXP PCF8563 Real time clock (RTC) in the arduino (c++) Framework.
+# pcf8563-RTC
+
+The `pcf8563-RTC` library is designed to interface ESP chips with the NXP PCF8563 Real-Time Clock (RTC) within the Arduino (C++) Framework.
 
 ## Features
-- use multiple I2C Busses -> rtc.begin(Wire1);
-- works with timezones (RTC is set to UTC)
-https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv
-- set System (ESP32) time from RTC (assumes RTC is set to UTC/GMT)
-- set RTC time from System (epoch)
-- Set RTC time using wifi example
+
+- Supports multiple I2C buses: `rtc.begin(Wire1);`
+- Timezone support (RTC is set to UTC)
+  - [List of timezones](https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv)
+- Sets the system (ESP32) time from the RTC (assumes RTC is set to UTC/GMT)
+- Sets the RTC time from the system (epoch)
+- Example of setting RTC time using WiFi
 
 ## Warnings
-- not all functions are implemented
-- not compatible with Lewis he's Library
-- only tested with the esp32
-- under active development
 
-### Setup
-```c++
+- Not all functions are implemented
+- Not compatible with Lewis' library
+- Only tested with the ESP32 and S2 variants
+- Currently under development
+
+## Example ESP32 Code
+
+```cpp
 #include "pcf8563.h"
 #include "time.h"
+
 PCF8563_Class rtc;
-const char *time_zone = "NZST-12NZDT,M9.5.0,M4.1.0/3";	// https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv
+const char *time_zone = "NZST-12NZDT,M9.5.0,M4.1.0/3"; // [List of timezones](https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv)
 
 Wire.begin();
 rtc.begin(Wire);
 setenv("TZ", time_zone, 1);
 tzset();
 rtc.syncToSystem();
 ```
-### Loop
-```c++
+
+```cpp
 struct tm timeinfo;
 getLocalTime(&timeinfo);
 Serial.print(&timeinfo, "%d/%m/%y %H:%M:%S");
 ```
 
-## 🖼️ Schematic
+## Schematic
+
 ![Schematic](/images/schematic.png)
-- uses a cr1220 coincell (though almost any 3v lithium coincell should work)
-- to not discharge the battery too fast disable output clock and alarms
-- Low backup current: typical 0.25 uA at 3.0 V (theoretical not tested)
-- currently I'm testing with 4.7kohm pullups on sda and scl
-- currently the crystal I'm using is a Seiko Epson Q13FC1350000400 (+-20ppm)
-- in theory this setup will drift by a maximum of ~11mins per year (https://www.analog.com/en/design-center/interactive-design-tools/real-time-clock-calculator.html)
-- in theory a 37mAh cr1220 battery will last ~14 years without any charging (incl battery self discharge)
-- 3.3V -> diode -> resistor charging of a coincell from 3.3v is hotly debated as to wether is good, ok, or horificly bad idea. I have not had any issuses but your mileage may vary
-- be careful with pcb placement (have the crystal as close to the RTC chip a possible and souround it with ground planes connected with vias)
-
-## Based on the awesome work of Lewis he
-Origin created by Lewis he in 2019
-https://github.com/lewisxhe/PCF8563_Library
-
-MIT license
+
+- Uses a CR1220 coincell (though almost any 3V lithium coincell should work)
+- To prevent battery discharge, disable output clock and alarms
+- Low backup current: typically 0.25uA at 3.0V (theoretical, not tested)
+- Currently testing with 4.7kohm pull-ups on SDA and SCL
+- Currently using a Seiko Epson Q13FC1350000400 crystal (+-20ppm)
+- In theory, this setup will drift by a maximum of ~11 minutes per year ([Real-Time Clock Calculator](https://www.analog.com/en/design-center/interactive-design-tools/real-time-clock-calculator.html))
+- In theory, a 37mAh CR1220 battery will last ~14 years without any charging (including battery self-discharge)
+- Charging a coincell from 3.3V through a diode and resistor is a topic of debate. It is important to exercise caution and consider individual circumstances. Using a 200-ohm resistor should limit the current to a maximum of 12mA, while a 1k-ohm resistor should limit it to a maximum of 2.6mA.
+- Be careful with PCB placement; ensure the crystal is placed as close to the RTC chip as possible and surrounded by ground planes connected with vias
+
+## Acknowledgments
+
+This library is based on the original work of Lewis He, created in 2019.
+
+[GitHub Repository](https://github.com/lewisxhe/PCF8563_Library)
+
+## License
+
+This library is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information.
+
+Please note that not all functions are implemented, and the library is under active development. For more information on how to use the library, refer to the documentation and examples provided.

keywords.txt

@@ -1,58 +1,51 @@
 #######################################
-# Syntax Coloring Map For Arduino library for NXP-PCF8563 By lewis He
-# github:https://github.com/lewisxhe
+# Syntax Coloring Map
 #######################################
 
 #######################################
 # Datatypes (KEYWORD1)
 #######################################
-RTC_Date	KEYWORD1
-RTC_Alarm	KEYWORD1
-PCF8563_Class	KEYWORD1
+RTC_Date       KEYWORD1
+RTC_Alarm      KEYWORD1
+PCF8563_Class  KEYWORD1
 
 #######################################
 # Methods and Functions (KEYWORD2)
 #######################################
-
-begin  KEYWORD2
-setDateTime	KEYWORD2
-getDateTime	KEYWORD2
-getAlarm	KEYWORD2
-enableAlarm	KEYWORD2
-disableAlarm	KEYWORD2
-alarmActive	KEYWORD2
-resetAlarm	KEYWORD2
-setAlarm	KEYWORD2
-setAlarmByWeekDay	KEYWORD2
-setAlarmByHours	KEYWORD2
-setAlarmByDays	KEYWORD2
-setAlarmByMinutes	KEYWORD2
-isTimerEnable	KEYWORD2
-isTimerActive	KEYWORD2
-enableTimer	KEYWORD2
-disableTimer	KEYWORD2
-setTimer	KEYWORD2
-clearTimer	KEYWORD2
-enableCLK	KEYWORD2
-disableCLK	KEYWORD2
-formatDateTime	KEYWORD2
-getDayOfWeek	KEYWORD2
-
-#######################################
-# Instances (KEYWORD2)
-#######################################
-
+begin                   KEYWORD2
+setDateTime             KEYWORD2
+getDateTime             KEYWORD2
+getAlarm                KEYWORD2
+enableAlarm             KEYWORD2
+disableAlarm            KEYWORD2
+alarmActive             KEYWORD2
+resetAlarm              KEYWORD2
+setAlarm                KEYWORD2
+setAlarmByWeekDay       KEYWORD2
+setAlarmByHours         KEYWORD2
+setAlarmByDays          KEYWORD2
+setAlarmByMinutes       KEYWORD2
+isTimerEnable           KEYWORD2
+isTimerActive           KEYWORD2
+enableTimer             KEYWORD2
+disableTimer            KEYWORD2
+setTimer                KEYWORD2
+clearTimer              KEYWORD2
+enableCLK               KEYWORD2
+disableCLK              KEYWORD2
+formatDateTime          KEYWORD2
+getDayOfWeek            KEYWORD2
 
 #######################################
 # Constants (LITERAL1)
 #######################################
-PCF8563_CLK_32_768KHZ	LITERAL1
-PCF8563_CLK_1024KHZ	LITERAL1
-PCF8563_CLK_32HZ	LITERAL1
-PCF8563_CLK_1HZ	LITERAL1
-PCF_TIMEFORMAT_HM	LITERAL1
-PCF_TIMEFORMAT_HMS	LITERAL1
-PCF_TIMEFORMAT_YYYY_MM_DD	LITERAL1
-PCF_TIMEFORMAT_MM_DD_YYYY	LITERAL1
-PCF_TIMEFORMAT_DD_MM_YYYY	LITERAL1
-PCF_TIMEFORMAT_YYYY_MM_DD_H_M_S	LITERAL1
+PCF8563_CLK_32_768KHZ             LITERAL1
+PCF8563_CLK_1024KHZ               LITERAL1
+PCF8563_CLK_32HZ                  LITERAL1
+PCF8563_CLK_1HZ                   LITERAL1
+PCF_TIMEFORMAT_HM                 LITERAL1
+PCF_TIMEFORMAT_HMS                LITERAL1
+PCF_TIMEFORMAT_YYYY_MM_DD         LITERAL1
+PCF_TIMEFORMAT_MM_DD_YYYY         LITERAL1
+PCF_TIMEFORMAT_DD_MM_YYYY         LITERAL1
+PCF_TIMEFORMAT_YYYY_MM_DD_H_M_S   LITERAL1

library.json

@@ -1,12 +1,25 @@
 {
   "name": "pcf8563-rtc",
-  "keywords": "rtc, clock",
-  "description": "A library for the PCF8563",
-  "repository":
-  {
+  "version": "1.2.0",
+  "description": "An Arduino library for interfacing ESP chips with PCF8563 Real Time Clock using the I2C protocol.",
+  "keywords": [
+    "rtc",
+    "clock",
+    "pcf8563",
+    "nxt",
+    "i2c"
+  ],
+  "repository": {
     "type": "git",
     "url": "https://github.com/CDFER/pcf8563-RTC.git"
   },
+  "author": {
+    "name": "Chris Dirks",
+    "url": "https://keastudios.co.nz/about.htm",
+    "maintainer": true
+  },
+  "license": "Other",
+  "homepage": "https://github.com/CDFER/pcf8563-RTC",
   "frameworks": "arduino",
-  "platforms": "espressif32"
-}
+  "platforms": "*"
+}

library.properties

@@ -1,5 +1,5 @@
 name=pcf8563-RTC
-version=1.1.0
+version=1.2.0
 author=Chris Dirks (@CDFER)
 maintainer= Chris Dirks (@CDFER)
 sentence=Arduino library for NXP PCF8563 RTC chip.