Updated to version 1.1.1 - Improved time format support, added Python tools, and updated documentation

Author: mcu-electronics

CHANGELOG.md

@@ -0,0 +1,36 @@
+# CHANGELOG - RTC_DS1307_Library
+
+This file documents the most important changes in each version of the **RTC_DS1307_Library**.
+
+---
+
+## [1.1.1] - 2025-01-30
+### Improvements and New Features
+- Support for 12h/24h: You can now switch between time formats using the `SET_FORMAT` command.
+- Added two Python tools in `tools/`:
+  - `rtc_sync.py`: Synchronizes the RTC with the system time (UTC or Local).
+  - `local_test.py`: Detects the system timezone and displays UTC and local time.
+- Added datasheet:
+  - `DS1307_Maxim.pdf`
+
+### Bug Fixes
+- Fixed an issue with setting the year field when updating the date.
+
+---
+
+## [1.0.0] - 2025-01-27
+### Initial Release
+- Compatibility with **Arduino, ESP32, and ESP8266**.
+- Basic functionality:
+  - Read and write time on the DS1307.
+  - Configure and read internal RAM memory.
+  - Control the clock output (`SQW`).
+  - Support for synchronization with `TimeLib`.
+
+---
+
+Versioning Format:  
+This changelog follows the [SemVer](https://semver.org/lang/en/) scheme with **MAJOR.MINOR.PATCH** versions:
+- `MAJOR`: Incompatible changes with previous versions.
+- `MINOR`: New backward-compatible features.
+- `PATCH`: Bug fixes or minor improvements.

README.md

@@ -2,61 +2,87 @@
 
 The **RTC_DS1307_Library** allows easy interaction with the DS1307 Real-Time Clock (RTC) module, offering advanced functions for managing time and additional configurations such as square wave output and NV-RAM.
 
+## What's New in v1.1.1
+
+This release includes significant improvements and new features:
+
+- **Added support for 12-hour and 24-hour time formats.** You can now switch between these formats using the `SET_FORMAT` command.
+- **Added two Python tools in the `tools/` directory:**
+  - `rtc_sync.py`: Synchronizes the RTC with the system time (supports UTC and local time).
+  - `local_test.py`: Detects the system timezone and displays UTC and local times.
+- **Updated documentation.** The repository now includes three versions of the DS1307 datasheet (`Dallas`, `Maxim`, and `Spanish`).
+
 ## Features
+
 - Configuration and retrieval of time in Unix timestamp format.
+- Support for both **12-hour and 24-hour formats** with AM/PM indication.
 - Reading and writing to the DS1307's battery-backed RAM.
 - Control of square wave output with configurable frequencies (1Hz, 4kHz, 8kHz, and 32kHz).
 - Support for synchronization with the [TimeLib](https://github.com/PaulStoffregen/Time) library.
-- Compatible with Arduino, ESP32, and ESP8266.
+- Compatible with **Arduino, ESP32, and ESP8266**.
 
 ## Installation
+
+### **Option 1: Arduino Library Manager (Recommended)**
+
+The library is available directly in the **Arduino Library Manager**.
+
+1. Open the **Arduino IDE**.
+2. Go to `Sketch -> Include Library -> Manage Libraries...`.
+3. Search for **RTC_DS1307_Library**.
+4. Click **Install**.
+
+### **Option 2: Manual Installation**
+
 1. Download this repository as a ZIP file.
 2. Open the Arduino IDE.
 3. Go to `Sketch -> Include Library -> Add .ZIP Library...`.
 4. Select the downloaded ZIP file.
 5. The library is now ready to use.
 
 ## Basic Example
-This example demonstrates how to initialize the DS1307 module, configure it with the current time, and continuously read the time. It is ideal for verifying the basic functionality of the RTC and establishing a foundation for more advanced projects.
+
+This minimal example demonstrates how to initialize the DS1307 module and retrieve the current time:
 
 ```cpp
 #include <Wire.h>
 #include <DS1307Lib.h>
-#include <TimeLib.h>
 
 void setup() {
   Serial.begin(9600);
   Wire.begin();
-
-  if (!RTC.begin()) {
-    Serial.println("DS1307 not detected");
-    while (1);
-  }
-
-  // Configure the RTC with the current time
-  RTC.set(now());
+  RTC.begin();
 }
 
 void loop() {
-  // Read and display the current time
-  time_t currentTime = RTC.get();
-  Serial.print("Current time: ");
-  Serial.println(currentTime);
+  Serial.println(RTC.get());
   delay(1000);
 }
 ```
 
-## Contributions
-If you encounter an issue or have ideas to improve this library:
-1. Create an **issue** in the repository.
-2. You can also submit a **pull request** with your suggestions.
+## New Commands
+
+- **SET_FORMAT**: Switch between 12-hour and 24-hour formats.
+  ```
+  SET_FORMAT 12  // Sets the RTC to 12-hour mode
+  SET_FORMAT 24  // Sets the RTC to 24-hour mode
+  ```
+- **Python Tools for Synchronization**
+  - `rtc_sync.py COM5 utc`  Syncs the RTC with system UTC time.
+  - `rtc_sync.py COM5 local`  Syncs the RTC with system local time.
 
 ## License
+
 This library is distributed under the GNU Lesser General Public License (LGPL) version 3. See the `COPYING.LESSER.txt` file for more details.
 
 ## Additional Resources
-- [DS1307 Datasheet](docs/DS1307_datasheet.pdf)
+
+- [DS1307 Datasheet - Dallas](docs/DS1307_Dallas.pdf)
+- [DS1307 Datasheet - Maxim](docs/DS1307_Maxim.pdf)
+- [DS1307 Datasheet (Spanish)](docs/DS1307_Dallas_es.pdf)
 - Included examples:
   - `RTC_ClockOut.ino`: Configuring the square wave output.
   - `RTC_Ram.ino`: Reading and writing to the RTC's RAM.
-  - `RTC_Time.ino`: Configuring and reading time.
+  - `RTC_Time.ino`: Configuring and reading time.
+  - `RTC_Full.ino`: Complete example with all features.
+

docs/DS1307_datasheet.pdf renamed to docs/DS1307_Dallas.pdf

@@ -64,13 +64,15 @@ void setup() {
   Serial.begin(9600);
   while (!Serial);   // Wait for serial port to be ready (needed on boards like Leonardo)
 
-  // Set A3 pin as input
+  // Set A3 pin as input for SQWOUT pin
   pinMode(A3, INPUT);
   // Set LED_BUILTIN as output
   pinMode(LED_BUILTIN, OUTPUT);
 
-  // Optionally synchronize with RTC; here we mostly focus on clock out usage.
-  setSyncProvider(RTC.get);
+  RTC.begin();
+  if (timeStatus() != timeSet) {
+      Serial.println("Unable to sync with the RTC");
+  }
 }
 
 // ---------------------- loop() ----------------------

docs/DS1307_datasheet_es.pdf renamed to docs/DS1307_Dallas_es.pdf

@@ -15,6 +15,7 @@
  * - SET_UNIX: Set the RTC time using a Unix timestamp.
  * - GET_TIME: Retrieve the current time in human-readable format.
  * - GET_UNIX: Retrieve the current time as a Unix timestamp.
+ * - SET_FORMAT: Command to switch between 12-hour and 24-hour formats.
  * - SET_CLOCKOUT: Configure the clock output pin with various settings.
  * - READ_RAM: Read a block of bytes from the DS1307's battery-backed RAM.
  * - WRITE_RAM: Write a block of bytes to the DS1307's battery-backed RAM.
@@ -59,6 +60,7 @@ void processSetTime(String params);
 void processSetTimeUnix(String params);
 void sendUnixTimestamp(String params);
 void sendCurrentTime(String params = "");
+void processSetHourFormat(String params); 
 void processSetClockOut(String params);
 void processCheckRTC(String params);
 void processReadRAM(String params);
@@ -70,6 +72,7 @@ Command commandTable[] = {
   {"SET_UNIX", processSetTimeUnix},
   {"GET_UNIX", sendUnixTimestamp},
   {"GET_TIME", sendCurrentTime},
+  {"SET_FORMAT",  processSetHourFormat},
   {"SET_CLOCKOUT", processSetClockOut},
   {"CHECK_RTC", processCheckRTC},
   {"READ_RAM", processReadRAM},
@@ -82,17 +85,14 @@ const int commandCount = sizeof(commandTable) / sizeof(Command); // Number of co
 void setup() {
   Serial.begin(9600); // Set up serial communication at 9600 baud
   while (!Serial);    // Wait for the serial port to be ready (necessary for boards like Leonardo)
-  // Set pin A3 as input
+  // Set A3 pin as input for SQWOUT pin
   pinMode(A3, INPUT);
-  // Set the built-in LED pin as output
+  // Set LED_BUILTIN as output
   pinMode(LED_BUILTIN, OUTPUT);
 
-  // Set up the synchronization function
-  setSyncProvider(RTC.get);
+  RTC.begin();
   if (timeStatus() != timeSet) {
       Serial.println("Unable to sync with the RTC");
-  } else {
-      Serial.println("RTC has been synchronized");
   }
 }
 
@@ -138,7 +138,9 @@ void loop() {
 
 // Auxiliary function implementations
 
-// Processes the SET_TIME command (human-readable format)
+/**
+ * SET_TIME - Sets time in human-readable format: "YYYY/MM/DD HH:MM:SS"
+ */
 void processSetTime(String timeString) {
   int year, month, day, hour, minute, second;
   if (sscanf(timeString.c_str(), "%d/%d/%d %d:%d:%d", &year, &month, &day, &hour, &minute, &second) == 6) {
@@ -150,7 +152,9 @@ void processSetTime(String timeString) {
   }
 }
 
-// Processes the SET_TIMEU command (Unix timestamp)
+/**
+ * SET_UNIX - Sets time based on a Unix timestamp
+ */
 void processSetTimeUnix(String unixString) {
   unsigned long unixTime = unixString.toInt(); // Convert the string to a long integer
   if (unixTime > 0) {
@@ -205,20 +209,39 @@ void processCheckRTC(String params) {
   }
 }
 
-// Sends the current time in a human-readable format
+/**
+ * GET_TIME - Prints the current time in "YYYY/MM/DD HH:MM:SS"
+ */
 void sendCurrentTime(String params) {
-  Serial.print(year());
-  Serial.print("/");
-  Serial.print(month());
-  Serial.print("/");
-  Serial.print(day());
-  Serial.print(" ");
-  Serial.print(hour());
-  printDigits(minute());
-  printDigits(second());
-  Serial.println();
+    RTC.readHourFormat(); // Update format configuration
+
+    Serial.print(year());
+    Serial.print("/");
+    Serial.print(month());
+    Serial.print("/");
+    Serial.print(day());
+    Serial.print(" ");
+
+    int h = hour(); // Get the hour in 24h format
+
+    if (RTC.is12HourFormat) {
+        RTC.isPMFlag = isPM(h); // Determine if it's AM or PM
+        int hour12 = (h == 0) ? 12 : (h > 12 ? h - 12 : h); // Convert 0->12 AM, 13->1 PM, etc.
+
+        Serial.print(hour12);
+        printDigits(minute());
+        printDigits(second());
+        Serial.println(RTC.isPMFlag ? " PM" : " AM");
+    } else {
+        Serial.print(h);
+        printDigits(minute());
+        printDigits(second());
+        Serial.println();
+    }
 }
 
+
+
 // Sends the current time as a Unix timestamp
 void sendUnixTimestamp(String params) {
   time_t currentTime = RTC.get(); // Get the current time from the RTC
@@ -237,6 +260,23 @@ void printDigits(int digits) {
   Serial.print(digits); // Print the number
 }
 
+
+
+/**
+ * SET_FORMAT - Set hour format (12/24)
+ * Usage: "SET_FORMAT 12" or "SET_FORMAT 24"
+ */
+void processSetHourFormat(String params) {
+    if (params.equals("12") || params.equals("24")) {
+        RTC.readHourFormat();
+        RTC.is12HourFormat = params.equals("12");
+        RTC.writeHourFormat();
+        sendCurrentTime();    // Print the newly set time
+    } else {
+        Serial.println("ERROR");
+    }
+}
+
 /*
   processReadRAM:
   - Parameters: "ADDHex lengthDecimal"

docs/DS1307_Maxim.pdf

@@ -64,15 +64,15 @@ void setup() {
   Serial.begin(9600);
   while (!Serial);   // Wait for serial port to be ready (needed on boards like Leonardo)
 
-  // A3 is used as input to read the SQW/OUT pin of the DS1307 (clock out signal).
-  pinMode(A3, INPUT);  
-  // LED_BUILTIN is used here as an indicator for the clock out signal.
-  // The loop() function will read A3 and mirror its state onto the LED.
+  // Set A3 pin as input for SQWOUT pin
+  pinMode(A3, INPUT);
+  // Set LED_BUILTIN as output
   pinMode(LED_BUILTIN, OUTPUT);
 
-  // Optional: set up TimeLib's synchronization with DS1307
-  // (Not strictly required for RAM operations, but included for consistency)
-  setSyncProvider(RTC.get);
+  RTC.begin();
+  if (timeStatus() != timeSet) {
+      Serial.println("Unable to sync with the RTC");
+  }
 }
 
 // ---------------------- loop() ----------------------