### Initialize DS1302 RTC Chip

Source: https://context7.com/treboada/ds1302/llms.txt

Initialize the DS1302 chip by calling the init() method within the setup() function. This must be done before any other RTC operations.

```cpp
#include <Arduino.h>
#include <Ds1302.h>

Ds1302 rtc(2, 3, 4);

void setup() {
    Serial.begin(9600);

    // Initialize the RTC - required before any other operations
    rtc.init();

    Serial.println("RTC initialized successfully");
}

void loop() {
    // RTC is now ready for use
}
```

--------------------------------

### Instantiate Ds1302 with GPIO Pins

Source: https://context7.com/treboada/ds1302/llms.txt

Create a new Ds1302 instance by specifying the GPIO pins for the CE, SCLK, and I/O connections. This setup is required before initializing the RTC chip.

```cpp
#include <Arduino.h>
#include <Ds1302.h>

// Define pins for DS1302 connection
const uint8_t PIN_ENA = 2;  // CE (Chip Enable)
const uint8_t PIN_CLK = 3;  // SCLK (Serial Clock)
const uint8_t PIN_DAT = 4;  // I/O (Data)

// Create RTC instance with pin configuration
Ds1302 rtc(PIN_ENA, PIN_CLK, PIN_DAT);

void setup() {
    // Instance is ready to be initialized
}
```

--------------------------------

### Getting Current Date and Time

Source: https://context7.com/treboada/ds1302/llms.txt

This section explains how to retrieve the current date and time from the DS1302 chip using the `getDateTime()` function, which populates a provided `DateTime` structure.

```APIDOC
## getDateTime()

### Description
Retrieves the current date and time from the DS1302 chip. The function populates the provided `DateTime` structure pointer with all time components read atomically to prevent race conditions.

### Method
`getDateTime(Ds1302::DateTime* dt)`

### Endpoint
N/A (Library functions)

### Parameters
#### Output Parameter
- **dt** (Ds1302::DateTime*) - Output - Pointer to a `DateTime` structure that will be populated with the current date and time.

### Request Example
```cpp
#include <Arduino.h>
#include <Ds1302.h>

Ds1302 rtc(2, 3, 4);

const char* WeekDays[] = {
    "Monday", "Tuesday", "Wednesday", "Thursday",
    "Friday", "Saturday", "Sunday"
};

void setup() {
    Serial.begin(9600);
    rtc.init();
}

void loop() {
    // Create DateTime structure to receive current time
    Ds1302::DateTime now;

    // Read current date/time from RTC
    rtc.getDateTime(&now);

    // Format and display the time
    char buffer[32];
    sprintf(buffer, "20%%02d-%%02d-%%02d %%02d:%%02d:%%02d",
        now.year,    // 00-99
        now.month,   // 01-12
        now.day,     // 01-31
        now.hour,    // 00-23
        now.minute,  // 00-59
        now.second   // 00-59
    );

    Serial.print(buffer);
    Serial.print(" ");
    Serial.println(WeekDays[now.dow - 1]);  // dow is 1-7

    delay(1000);
}
```

### Response
#### Success Response (Populated DateTime Structure)
- **year** (uint8_t) - Year (0-99).
- **month** (uint8_t) - Month (1-12).
- **day** (uint8_t) - Day of the month (1-31).
- **hour** (uint8_t) - Hour (0-23).
- **minute** (uint8_t) - Minute (0-59).
- **second** (uint8_t) - Second (0-59).
- **dow** (uint8_t) - Day of the week (1-7).

#### Response Example
```
2024-12-25 14:30:45 Wednesday
```
```

--------------------------------

### DS1302 Constructor and Initialization

Source: https://context7.com/treboada/ds1302/llms.txt

This section details how to create an instance of the Ds1302 class and initialize the RTC chip. It requires specifying the GPIO pins for Chip Enable (CE), Serial Clock (SCLK), and Data (I/O). The init() method must be called once in setup() before any other operations.

```APIDOC
## Constructor and init()

### Description
Creates a new Ds1302 instance with the specified GPIO pin configuration and initializes the DS1302 chip. The init() method must be called once in `setup()` before using any other RTC functions.

### Method
Constructor and `init()`

### Endpoint
N/A (Library functions)

### Parameters
#### Constructor Parameters
- **PIN_ENA** (uint8_t) - Required - GPIO pin for CE (Chip Enable).
- **PIN_CLK** (uint8_t) - Required - GPIO pin for SCLK (Serial Clock).
- **PIN_DAT** (uint8_t) - Required - GPIO pin for I/O (Data).

#### init() Parameters
None

### Request Example
```cpp
#include <Arduino.h>
#include <Ds1302.h>

// Define pins for DS1302 connection
const uint8_t PIN_ENA = 2;  // CE (Chip Enable)
const uint8_t PIN_CLK = 3;  // SCLK (Serial Clock)
const uint8_t PIN_DAT = 4;  // I/O (Data)

// Create RTC instance with pin configuration
Ds1302 rtc(PIN_ENA, PIN_CLK, PIN_DAT);

void setup() {
    Serial.begin(9600);
    // Initialize the RTC - required before any other operations
    rtc.init();
    Serial.println("RTC initialized successfully");
}

void loop() {
    // RTC is now ready for use
}
```

### Response
#### Success Response
Initialization is successful if no errors are thrown.

#### Response Example
```
RTC initialized successfully
```
```

--------------------------------

### Interactive Time Setting via Serial

Source: https://context7.com/treboada/ds1302/llms.txt

This example shows how to set the RTC time by receiving a formatted string (YYMMDDWhhmmss) over the serial port. Ensure the serial monitor is configured to send data without a newline character.

```cpp
#include <Arduino.h>
#include <Ds1302.h>

Ds1302 rtc(2, 3, 4);  // ENA, CLK, DAT pins

uint8_t parseDigits(char* str, uint8_t count) {
    uint8_t val = 0;
    while (count-- > 0) {
        val = (val * 10) + (*str++ - '0');
    }
    return val;
}

void setup() {
    rtc.init();
    Serial.begin(9600);
    Serial.println("DS1302 RTC Time Setter");
    Serial.println("Enter time as YYMMDDWhhmmss");
    Serial.println("Example: 2401151093000 = 2024-01-15 Monday 09:30:00");
}

void loop() {
    static char buffer[13];
    static uint8_t idx = 0;

    // Process complete input
    if (idx == 13) {
        Ds1302::DateTime dt;
        dt.year = parseDigits(buffer, 2);
        dt.month = parseDigits(buffer + 2, 2);
        dt.day = parseDigits(buffer + 4, 2);
        dt.dow = parseDigits(buffer + 6, 1);
        dt.hour = parseDigits(buffer + 7, 2);
        dt.minute = parseDigits(buffer + 9, 2);
        dt.second = parseDigits(buffer + 11, 2);

        rtc.setDateTime(&dt);

        Serial.print("Time set to: 20");
        Serial.print(dt.year);
        Serial.print("-");
        Serial.print(dt.month);
        Serial.print("-");
        Serial.print(dt.day);
        Serial.print(" ");
        Serial.print(dt.hour);
        Serial.print(":");
        Serial.print(dt.minute);
        Serial.print(":");
        Serial.println(dt.second);

        idx = 0;
    }

    // Read serial input
    if (Serial.available()) {
        buffer[idx++] = Serial.read();
    }
}

// Serial Input: 2401151093000
// Output: Time set to: 2024-1-15 9:30:0

```

--------------------------------

### start() - Restart RTC Oscillator

Source: https://context7.com/treboada/ds1302/llms.txt

Restarts the DS1302 oscillator without modifying the current time values. The clock will resume from where it was when halted, allowing time-keeping to continue from the preserved state.

```APIDOC
## start()

### Description
Restarts the DS1302 oscillator without modifying the current time values. The clock will resume from where it was when halted, allowing time-keeping to continue from the preserved state.

### Method
```cpp
void start()
```

### Endpoint
N/A (This is a method of the Ds1302 object)

### Parameters
None

### Response
This function does not return a value. Success is indicated by the RTC oscillator running, verifiable with `isHalted()`.
```

--------------------------------

### Start DS1302 Oscillator

Source: https://context7.com/treboada/ds1302/llms.txt

Restarts the DS1302 oscillator without changing current time values. The clock resumes from its halted state. Use this after calling halt() to resume timekeeping.

```cpp
#include <Arduino.h>
#include <Ds1302.h>

Ds1302 rtc(2, 3, 4);

void setup() {
    Serial.begin(9600);
    rtc.init();

    // Check and restart if halted
    if (rtc.isHalted()) {
        Serial.println("RTC was halted, restarting oscillator...");
        rtc.start();
        Serial.println("Oscillator restarted - clock is now running");
    }

    // Verify it's running
    Serial.print("Is halted: ");
    Serial.println(rtc.isHalted() ? "Yes" : "No");
}

void loop() {
    Ds1302::DateTime now;
    rtc.getDateTime(&now);

    Serial.print(now.hour);
    Serial.print(":");
    Serial.print(now.minute);
    Serial.print(":");
    Serial.println(now.second);

    delay(1000);
}
```

--------------------------------

### Set DS1302 Date and Time

Source: https://context7.com/treboada/ds1302/llms.txt

Use this function to write a new date and time to the DS1302 chip. It disables write protection, writes atomically, and re-enables protection. This also starts the oscillator if it was halted.

```cpp
#include <Arduino.h>
#include <Ds1302.h>

Ds1302 rtc(2, 3, 4);

void setup() {
    Serial.begin(9600);
    rtc.init();

    // Set RTC to specific date/time
    Ds1302::DateTime dt = {
        .year = 24,              // 2024
        .month = Ds1302::MONTH_JAN,
        .day = 15,
        .hour = 9,
        .minute = 30,
        .second = 0,
        .dow = Ds1302::DOW_MON
    };

    rtc.setDateTime(&dt);
    Serial.println("RTC time has been set!");

    // Verify by reading back
    Ds1302::DateTime verify;
    rtc.getDateTime(&verify);

    Serial.print("Verified: ");
    Serial.print(verify.year);
    Serial.print("/");
    Serial.print(verify.month);
    Serial.print("/");
    Serial.println(verify.day);
}

void loop() {}
```

--------------------------------

### Get Current DateTime from DS1302

Source: https://context7.com/treboada/ds1302/llms.txt

Retrieve the current date and time from the DS1302 chip into a DateTime structure. This method uses burst-mode reading to ensure atomic data retrieval and prevent race conditions.

```cpp
#include <Arduino.h>
#include <Ds1302.h>

Ds1302 rtc(2, 3, 4);

const char* WeekDays[] = {
    "Monday", "Tuesday", "Wednesday", "Thursday",
    "Friday", "Saturday", "Sunday"
};

void setup() {
    Serial.begin(9600);
    rtc.init();
}

void loop() {
    // Create DateTime structure to receive current time
    Ds1302::DateTime now;

    // Read current date/time from RTC
    rtc.getDateTime(&now);

    // Format and display the time
    char buffer[32];
    sprintf(buffer, "20%02d-%02d-%02d %02d:%02d:%02d",
        now.year,    // 00-99
        now.month,   // 01-12
        now.day,     // 01-31
        now.hour,    // 00-23
        now.minute,  // 00-59
        now.second   // 00-59
    );

    Serial.print(buffer);
    Serial.print(" ");
    Serial.println(WeekDays[now.dow - 1]);  // dow is 1-7

    delay(1000);
}

// Output: 2024-12-25 14:30:45 Wednesday
```

--------------------------------

### setDateTime() - Set RTC Time

Source: https://context7.com/treboada/ds1302/llms.txt

Writes a new date and time to the DS1302 chip using burst-mode writing. This function disables write protection, writes all time registers atomically, and then re-enables write protection. It also starts the oscillator if it was halted.

```APIDOC
## setDateTime()

### Description
Writes a new date and time to the DS1302 chip using burst-mode writing. The function first disables write protection, writes all time registers atomically, then re-enables write protection. This also starts the oscillator if it was halted.

### Method
```cpp
void setDateTime(Ds1302::DateTime* dt)
```

### Parameters
#### Request Body
- **dt** (Ds1302::DateTime*) - Required - Pointer to a Ds1302::DateTime structure containing the new date and time values.
  - **year** (uint8_t) - Required - Year (e.g., 24 for 2024).
  - **month** (Ds1302::Month) - Required - Month (Ds1302::MONTH_JAN to Ds1302::MONTH_DEC).
  - **day** (uint8_t) - Required - Day of the month.
  - **hour** (uint8_t) - Required - Hour (0-23).
  - **minute** (uint8_t) - Required - Minute (0-59).
  - **second** (uint8_t) - Required - Second (0-59).
  - **dow** (Ds1302::DayOfWeek) - Required - Day of the week (Ds1302::DOW_SUN to Ds1302::DOW_SAT).

### Request Example
```cpp
Ds1302::DateTime dt = {
    .year = 24,
    .month = Ds1302::MONTH_JAN,
    .day = 15,
    .hour = 9,
    .minute = 30,
    .second = 0,
    .dow = Ds1302::DOW_MON
};
rpc.setDateTime(&dt);
```

### Response
This function does not return a value. Success is indicated by the absence of errors and the correct time being set when read back.
```

--------------------------------

### DateTime Structure and Setting Time

Source: https://context7.com/treboada/ds1302/llms.txt

This section describes the `DateTime` structure used to hold date and time components and how to set the RTC with a specific date and time.

```APIDOC
## DateTime Structure and setDateTime()

### Description
The `DateTime` structure holds all time and date components. The `setDateTime()` function allows you to set the RTC to a specific date and time.

### Method
`setDateTime(Ds1302::DateTime* dt)`

### Endpoint
N/A (Library functions)

### Parameters
#### Request Body (DateTime Structure)
- **year** (uint8_t) - Required - Year (0-99, representing 2000-2099).
- **month** (Ds1302::Month) - Required - Month (Ds1302::MONTH_JAN through Ds1302::MONTH_DEC).
- **day** (uint8_t) - Required - Day of the month (1-31).
- **hour** (uint8_t) - Required - Hour (0-23, 24-hour format).
- **minute** (uint8_t) - Required - Minute (0-59).
- **second** (uint8_t) - Required - Second (0-59).
- **dow** (Ds1302::DayOfWeek) - Required - Day of the week (Ds1302::DOW_MON through Ds1302::DOW_SUN, 1-7).

### Request Example
```cpp
#include <Arduino.h>
#include <Ds1302.h>

Ds1302 rtc(2, 3, 4);

void setup() {
    Serial.begin(9600);
    rtc.init();

    // Create a DateTime structure using designated initializers
    Ds1302::DateTime dt = {
        .year = 24,              // 2024
        .month = Ds1302::MONTH_DEC,  // December
        .day = 25,               // 25th
        .hour = 14,              // 2:00 PM
        .minute = 30,
        .second = 0,
        .dow = Ds1302::DOW_WED   // Wednesday
    };

    // Set the RTC with this datetime
    rtc.setDateTime(&dt);

    Serial.println("DateTime set to: 2024-12-25 14:30:00 Wednesday");
}

void loop() {}
```

### Response
#### Success Response
Setting the date and time is successful if no errors are thrown.

#### Response Example
```
DateTime set to: 2024-12-25 14:30:00 Wednesday
```
```

--------------------------------

### Set Current DateTime on DS1302

Source: https://context7.com/treboada/ds1302/llms.txt

Set the current date and time on the DS1302 chip using the DateTime structure. Use designated initializers for clarity and ensure the year is represented as 00-99 for 2000-2099.

```cpp
#include <Arduino.h>
#include <Ds1302.h>

Ds1302 rtc(2, 3, 4);

void setup() {
    Serial.begin(9600);
    rtc.init();

    // Create a DateTime structure using designated initializers
    Ds1302::DateTime dt = {
        .year = 24,              // 2024 (stores 00-99)
        .month = Ds1302::MONTH_DEC,  // December
        .day = 25,               // 25th
        .hour = 14,              // 2:00 PM (24-hour format)
        .minute = 30,
        .second = 0,
        .dow = Ds1302::DOW_WED   // Wednesday
    };

    // Set the RTC with this datetime
    rtc.setDateTime(&dt);

    Serial.println("DateTime set to: 2024-12-25 14:30:00 Wednesday");
}

void loop() {}
```

--------------------------------

### halt() - Stop RTC Oscillator

Source: https://context7.com/treboada/ds1302/llms.txt

Stops the DS1302 oscillator without modifying the current time values stored in the registers. This preserves the last known time while stopping the clock from advancing, useful for power-saving or pausing the RTC.

```APIDOC
## halt()

### Description
Stops the DS1302 oscillator without modifying the current time values stored in the registers. This preserves the last known time while stopping the clock from advancing, which is useful for power-saving or when the RTC needs to be paused.

### Method
```cpp
void halt()
```

### Endpoint
N/A (This is a method of the Ds1302 object)

### Parameters
None

### Response
This function does not return a value. Success is indicated by the RTC oscillator being stopped, verifiable with `isHalted()`.
```

--------------------------------

### isHalted() - Check if RTC is Halted

Source: https://context7.com/treboada/ds1302/llms.txt

Checks whether the DS1302 oscillator is currently stopped (halted). Returns true if the clock halt flag is set in the seconds register, indicating the RTC is not keeping time. Useful for detecting first-time power-up or battery failure.

```APIDOC
## isHalted()

### Description
Checks whether the DS1302 oscillator is currently stopped (halted). Returns true if the clock halt flag is set in the seconds register, meaning the RTC is not keeping time. This is useful for detecting first-time power-up or battery failure scenarios.

### Method
```cpp
bool isHalted()
```

### Endpoint
N/A (This is a method of the Ds1302 object)

### Parameters
None

### Response
#### Success Response (bool)
- **true**: If the RTC oscillator is halted.
- **false**: If the RTC oscillator is running.

### Response Example
```cpp
if (rtc.isHalted()) {
    Serial.println("RTC is halted!");
} else {
    Serial.println("RTC is running normally.");
}
```
```

--------------------------------

### Check if DS1302 Oscillator is Halted

Source: https://context7.com/treboada/ds1302/llms.txt

Checks if the DS1302 oscillator is stopped. Returns true if the clock halt flag is set, indicating the RTC is not keeping time. Useful for detecting first-time power-up or battery failure.

```cpp
#include <Arduino.h>
#include <Ds1302.h>

Ds1302 rtc(2, 3, 4);

void setup() {
    Serial.begin(9600);
    rtc.init();

    // Check if the RTC oscillator is running
    if (rtc.isHalted()) {
        Serial.println("RTC is halted! Clock is not running.");
        Serial.println("Setting default time to start the clock...");

        // Set a default time to start the oscillator
        Ds1302::DateTime dt = {
            .year = 24,
            .month = Ds1302::MONTH_JAN,
            .day = 1,
            .hour = 0,
            .minute = 0,
            .second = 0,
            .dow = Ds1302::DOW_MON
        };
        rtc.setDateTime(&dt);

        Serial.println("Clock started with default time.");
    } else {
        Serial.println("RTC is running normally.");
    }
}

void loop() {}
```

--------------------------------

### Halt DS1302 Oscillator

Source: https://context7.com/treboada/ds1302/llms.txt

Stops the DS1302 oscillator without altering the time registers. This preserves the last known time while pausing the clock, useful for power-saving or when the RTC needs to be paused.

```cpp
#include <Arduino.h>
#include <Ds1302.h>

Ds1302 rtc(2, 3, 4);

void setup() {
    Serial.begin(9600);
    rtc.init();

    // Read current time before halting
    Ds1302::DateTime before;
    rtc.getDateTime(&before);
    Serial.print("Time before halt: ");
    Serial.print(before.hour);
    Serial.print(":");
    Serial.print(before.minute);
    Serial.print(":");
    Serial.println(before.second);

    // Stop the oscillator
    rtc.halt();
    Serial.println("RTC halted - clock stopped");

    // Wait 5 seconds
    delay(5000);

    // Check time - should be unchanged
    Ds1302::DateTime after;
    rtc.getDateTime(&after);
    Serial.print("Time after 5s delay: ");
    Serial.print(after.hour);
    Serial.print(":");
    Serial.print(after.minute);
    Serial.print(":");
    Serial.println(after.second);

    Serial.print("Is halted: ");
    Serial.println(rtc.isHalted() ? "Yes" : "No");
}

void loop() {}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.