ErriezDS1302.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.
 */

#include "ErriezDS1302.h"

ErriezDS1302::ErriezDS1302(uint8_t clkPin, uint8_t ioPin, uint8_t cePin)
{
#ifdef __AVR
    _clkPort = digitalPinToPort(clkPin);
    _ioPort = digitalPinToPort(ioPin);
    _cePort = digitalPinToPort(cePin);

    _clkBit = digitalPinToBitMask(clkPin);
    _ioBit = digitalPinToBitMask(ioPin);
    _ceBit = digitalPinToBitMask(cePin);
#else
    _clkPin = clkPin;
    _ioPin = ioPin;
    _cePin = cePin;
#endif
}

bool ErriezDS1302::begin()
{
    // Initialize pins
    DS1302_CLK_LOW();
    DS1302_IO_LOW();
    DS1302_CE_LOW();

    DS1302_CLK_OUTPUT();
    DS1302_IO_OUTPUT();
    DS1302_CE_OUTPUT();

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

    // Remove write protect
    writeRegister(DS1302_REG_WP, 0);

    // Check write protect bit
    if (readRegister(DS1302_REG_WP) & (1 << DS1302_BIT_WP)) {
        // Error: RTC write protect bit not cleared
        return false;
    }

    // DS1302 detected
    return true;
}

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

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

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

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

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

time_t ErriezDS1302::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 ErriezDS1302::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 ErriezDS1302::read(struct tm *dt)
{
    uint8_t buffer[DS1302_NUM_CLOCK_REGS];

    // 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_mday = bcdToDec(buffer[3] & 0x3F);
    dt->tm_mon = bcdToDec(buffer[4] & 0x1F);
    dt->tm_wday = bcdToDec(buffer[5] & 0x07);
    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 ErriezDS1302::write(const struct tm *dt)
{
    // Buffer including write protect = 0
    uint8_t buffer[DS1302_NUM_CLOCK_REGS + 1];

    // 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_mday) & 0x3F;
    buffer[4] = decToBcd(dt->tm_mon + 1) & 0x1F;
    buffer[5] = decToBcd(dt->tm_wday + 1) & 0x07;
    buffer[6] = decToBcd(dt->tm_year % 100);
    buffer[7] = 0; // Write protect register

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

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

    // Read date/time from RTC
    read(&dt);

    // Update time
    dt.tm_hour = hour;
    dt.tm_min = min;
    dt.tm_sec = sec;

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

bool ErriezDS1302::getTime(uint8_t *hour, uint8_t *min, uint8_t *sec)
{
    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;

    return true;
}

bool ErriezDS1302::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 ErriezDS1302::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;
}

void ErriezDS1302::writeByteRAM(uint8_t addr, uint8_t value)
{
    transferBegin();
    writeAddrCmd(DS1302_CMD_WRITE_RAM(addr));
    writeByte(value);
    transferEnd();
}

void ErriezDS1302::writeBufferRAM(uint8_t *buf, uint8_t len)
{
    transferBegin();
    writeAddrCmd(DS1302_CMD_WRITE_RAM_BURST);
    for (uint8_t i = 0; i < min((int)len, DS1302_NUM_RAM_REGS); i++) {
        writeByte(*buf++);
    }
    transferEnd();
}

uint8_t ErriezDS1302::readByteRAM(uint8_t addr)
{
    uint8_t value;

    transferBegin();
    writeAddrCmd(DS1302_CMD_READ_RAM(addr));
    value = readByte();
    transferEnd();

    return value;
}

void ErriezDS1302::readBufferRAM(uint8_t *buf, uint8_t len)
{
    transferBegin();
    writeAddrCmd(DS1302_CMD_READ_RAM_BURST);
    for (uint8_t i = 0; i < min((int)len, DS1302_NUM_RAM_REGS); i++) {
        *buf++ = readByte();
    }
    transferEnd();
}

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

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

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

    // Read 8-bit unsigned value from clock register
    transferBegin();
    writeAddrCmd(DS1302_CMD_READ_CLOCK_REG(reg));
    value = readByte();
    transferEnd();

    return value;
}

bool ErriezDS1302::writeRegister(uint8_t reg, uint8_t value)
{
    // Write 8-bit unsigned value to clock register
    transferBegin();
    writeAddrCmd((uint8_t)DS1302_CMD_WRITE_CLOCK_REG(reg));
    writeByte(value);
    transferEnd();

    return true;
}

bool ErriezDS1302::writeBuffer(uint8_t reg, void *buffer, uint8_t writeLen)
{
    if ((reg != 0) || (writeLen != (DS1302_NUM_CLOCK_REGS + 1))) {
        // Burst command requires all clock registers including write protect
        return false;
    }

    // Write buffer with clock burst command to clock registers
    transferBegin();
    writeAddrCmd(DS1302_CMD_WRITE_CLOCK_BURST);
    for (uint8_t i = 0; i < min((int)writeLen, DS1302_NUM_RAM_REGS); i++) {
        writeByte(((uint8_t *)buffer)[i]);
    }
    transferEnd();

    return true;
}

bool ErriezDS1302::readBuffer(uint8_t reg, void *buffer, uint8_t readLen)
{
    if (reg != 0) {
        // Burst command requires address 0
        return false;
    }

    // Read buffer with clock burst command from clock registers
    transferBegin();
    writeAddrCmd(DS1302_CMD_READ_CLOCK_BURST);
    for (uint8_t i = 0; i < min((int)readLen, DS1302_NUM_RAM_REGS); i++) {
        ((uint8_t *)buffer)[i] = readByte();
    }
    transferEnd();

    return true;
}

// -------------------------------------------------------------------------------------------------
// Private functions
// -------------------------------------------------------------------------------------------------
void ErriezDS1302::transferBegin()
{
    DS1302_CLK_LOW();
    DS1302_IO_LOW();
    DS1302_IO_OUTPUT();
    DS1302_CE_HIGH();
}

void ErriezDS1302::transferEnd()
{
    DS1302_CE_LOW();
}

void ErriezDS1302::writeAddrCmd(uint8_t value)
{
    // Write 8 bits to RTC
    for (uint8_t i = 0; i < 8; i++) {
        if (value & (1 << i)) {
            DS1302_IO_HIGH();
        } else {
            DS1302_IO_LOW();
        }
        DS1302_PIN_DELAY();
        DS1302_CLK_HIGH();
        DS1302_PIN_DELAY();

        if ((value & (1 << DS1302_BIT_READ)) && (i == 7)) {
            DS1302_IO_INPUT();
        } else {
            DS1302_CLK_LOW();
        }
    }
}

void ErriezDS1302::writeByte(uint8_t value)
{
    // Write 8 bits to RTC
    for (uint8_t i = 0; i < 8; i++) {
        if (value & 0x01) {
            DS1302_IO_HIGH();
        } else {
            DS1302_IO_LOW();
        }
        value >>= 1;
        DS1302_CLK_HIGH();
        DS1302_PIN_DELAY();
        DS1302_CLK_LOW();
    }
}

uint8_t ErriezDS1302::readByte()
{
    uint8_t value = 0;

    for (uint8_t i = 0; i < 8; i++) {
        DS1302_CLK_HIGH();
        DS1302_CLK_LOW();
        DS1302_PIN_DELAY();

        value >>= 1;
        if (DS1302_IO_READ()) {
            value |= 0x80;
        } else {
            value &= ~(0x80);
        }
    }

    return value;
}