ErriezDS1307.cpp

Go to the documentation of this file.

/*
 * MIT License
 *
 * Copyright (c) 2020 Erriez
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

#if defined(__AVR__) || defined(ARDUINO_ARCH_SAM)
#include <avr/pgmspace.h>
#else
#include <pgmspace.h>
#endif

#include <Wire.h>

#include "ErriezDS1307.h"

bool ErriezDS1307::begin()
{
    uint8_t regDayWeek;

    // Read seconds register
    if (!readBuffer(DS1307_REG_DAY_WEEK, &regDayWeek, 1)) {
        return false;
    }

    // Check zero bits in day week register
    if (regDayWeek & 0xF8) {
        return false;
    }

    // DS1307 detected
    return true;
}

bool ErriezDS1307::isRunning()
{
    // Return status CH (Clock Halt) bit from seconds register
    if (readRegister(DS1307_REG_SECONDS) & (1 << DS1307_SEC_CH)) {
        // RTC clock stopped
        return false;
    } else {
        // RTC clock is running
        return true;
    }
}

bool ErriezDS1307::clockEnable(bool enable)
{
    uint8_t regSeconds;

    // Read seconds register
    regSeconds = readRegister(DS1307_REG_SECONDS);

    // Set or clear HT bit
    if (enable) {
        // Clear to enable
        regSeconds &= ~(1 << DS1307_SEC_CH);
    } else {
        // Set to disable
        regSeconds |= (1 << DS1307_SEC_CH);
    }

    // Write seconds register
    return writeRegister(DS1307_REG_SECONDS, regSeconds);
}

time_t ErriezDS1307::getEpoch()
{
    struct tm dt;
    time_t t;

    // Read time structure
    if (!read(&dt)) {
        // RTC read failed
        return 0;
    }

    // Convert date/time struct tm to time_t
    t = mktime(&dt);

    // An offset is needed for AVR target
#ifdef ARDUINO_ARCH_AVR
    t += UNIX_OFFSET;
#endif

    // Return Unix epoch UTC
    return t;
}

bool ErriezDS1307::setEpoch(time_t t)
{
    struct tm *dt;

    // Subtract UNIX offset for AVR targets
#ifdef ARDUINO_ARCH_AVR
    t -= UNIX_OFFSET;
#endif

    // Convert time_t to date/time struct tm
    dt = gmtime(&t);

    // Write date/time to RTC
    return write(dt);
}

bool ErriezDS1307::read(struct tm *dt)
{
    uint8_t buffer[7];

    // Read clock date and time registers
    if (!readBuffer(0x00, buffer, sizeof(buffer))) {
        memset(dt, 0, sizeof(struct tm));
        return false;
    }

    // Clear dt
    memset(dt, 0, sizeof(struct tm));

    // Convert BCD buffer to Decimal
    dt->tm_sec = bcdToDec(buffer[0] & 0x7F);
    dt->tm_min = bcdToDec(buffer[1] & 0x7F);
    dt->tm_hour = bcdToDec(buffer[2] & 0x3F);
    dt->tm_wday = bcdToDec(buffer[3] & 0x07);
    dt->tm_mday = bcdToDec(buffer[4] & 0x3F);
    dt->tm_mon = bcdToDec(buffer[5] & 0x1F);
    dt->tm_year = bcdToDec(buffer[6]) + 100; // 2000-1900

    // Month: 0..11
    if (dt->tm_mon) {
        dt->tm_mon--;
    }

    // Day of the week: 0=Sunday
    if (dt->tm_wday) {
        dt->tm_wday--;
    }

    // Check buffer for valid data
    if ((dt->tm_sec > 59) || (dt->tm_min > 59) || (dt->tm_hour > 23) ||
        (dt->tm_mday < 1) || (dt->tm_mday > 31) || (dt->tm_mon > 11) || (dt->tm_year > 199) ||
        (dt->tm_wday > 6))
    {
        return false;
    }

    return true;
}

bool ErriezDS1307::write(const struct tm *dt)
{
    uint8_t buffer[7];

    // Encode date time from decimal to BCD
    buffer[0] = decToBcd(dt->tm_sec) & 0x7F; // Clear CH bit in seconds register
    buffer[1] = decToBcd(dt->tm_min) & 0x7F;
    buffer[2] = decToBcd(dt->tm_hour) & 0x3F;
    buffer[3] = decToBcd(dt->tm_wday + 1) & 0x07;
    buffer[4] = decToBcd(dt->tm_mday) & 0x3F;
    buffer[5] = decToBcd(dt->tm_mon + 1) & 0x1F;
    buffer[6] = decToBcd(dt->tm_year % 100);

    // Write BCD encoded buffer to RTC registers
    return writeBuffer(0x00, buffer, sizeof(buffer));
}

bool ErriezDS1307::setTime(uint8_t hour, uint8_t min, uint8_t sec)
{
    struct tm dt;

    read(&dt);
    dt.tm_hour = hour;
    dt.tm_min = min;
    dt.tm_sec = sec;
    return write(&dt);
}

bool ErriezDS1307::getTime(uint8_t *hour, uint8_t *min, uint8_t *sec)
{
    uint8_t buffer[3];

    // Read RTC time registers
    if (!readBuffer(0x00, buffer, sizeof(buffer))) {
        return false;
    }

    // Convert BCD buffer to Decimal
    *sec = bcdToDec(buffer[0] & 0x7F); // Without CH bit from seconds register
    *min = bcdToDec(buffer[1] & 0x7F);
    *hour = bcdToDec(buffer[2] & 0x3F);

    // Check buffer for valid data
    if ((*sec > 59) || (*min > 59) || (*hour > 23)) {
        // Invalid time
        *sec = 0x00;
        *min = 0x00;
        *hour = 0x00;

        return false;
    }

    return true;
}

bool ErriezDS1307::setDateTime(uint8_t hour, uint8_t min, uint8_t sec,
                               uint8_t mday, uint8_t mon, uint16_t year,
                               uint8_t wday)
{
    struct tm dt;

    // Prepare struct tm
    dt.tm_hour = hour;
    dt.tm_min = min;
    dt.tm_sec = sec;
    dt.tm_mday = mday;
    dt.tm_mon = mon - 1;
    dt.tm_year = year - 1900;
    dt.tm_wday = wday;

    // Write date/time to RTC
    return write(&dt);
}

bool ErriezDS1307::getDateTime(uint8_t *hour, uint8_t *min, uint8_t *sec,
                               uint8_t *mday, uint8_t *mon, uint16_t *year,
                               uint8_t *wday)
{
    struct tm dt;

    // Read date/time from RTC
    if (!read(&dt)) {
        return false;
    }

    // Set return values
    *hour = dt.tm_hour;
    *min = dt.tm_min;
    *sec = dt.tm_sec;
    *mday = dt.tm_mday;
    *mon = dt.tm_mon + 1;
    *year = dt.tm_year + 1900;
    *wday = dt.tm_wday;

    return true;
}

bool ErriezDS1307::setSquareWave(SquareWave squareWave)
{
    // Write control register
    return writeBuffer(DS1307_REG_CONTROL, &squareWave, sizeof(squareWave));
}

uint8_t ErriezDS1307::bcdToDec(uint8_t bcd)
{
    return (uint8_t)(10 * ((bcd & 0xF0) >> 4) + (bcd & 0x0F));
}

uint8_t ErriezDS1307::decToBcd(uint8_t dec)
{
    return (uint8_t)(((dec / 10) << 4) | (dec % 10));
}

uint8_t ErriezDS1307::readRegister(uint8_t reg)
{
    uint8_t value = 0;

    // Read buffer with one 8-bit unsigned value
    readBuffer(reg, &value, 1);

    return value;
}

bool ErriezDS1307::writeRegister(uint8_t reg, uint8_t value)
{
    // Write buffer with one 8-bit unsigned value
    return writeBuffer(reg, &value, 1);
}

bool ErriezDS1307::writeBuffer(uint8_t reg, void *buffer, uint8_t writeLen)
{
    // Start I2C transfer by writing the I2C address, register number and optional buffer
    Wire.beginTransmission(DS1307_ADDR);
    Wire.write(reg);
    for (uint8_t i = 0; i < writeLen; i++) {
        Wire.write(((uint8_t *)buffer)[i]);
    }
    if (Wire.endTransmission(true) != 0) {
        return false;
    }

    return true;
}

bool ErriezDS1307::readBuffer(uint8_t reg, void *buffer, uint8_t readLen)
{
    // Start I2C transfer by writing the I2C address and register number
    Wire.beginTransmission(DS1307_ADDR);
    Wire.write(reg);
    // Generate a repeated start, followed by a read buffer
    if (Wire.endTransmission(false) != 0) {
        return false;
    }
    Wire.requestFrom((uint8_t)DS1307_ADDR, readLen);
    for (uint8_t i = 0; i < readLen; i++) {
        ((uint8_t *)buffer)[i] = (uint8_t)Wire.read();
    }

    return true;
}