DS3231.c

/*
 * DS3231.c
 *
 * STM32 HAL driver for the DS3231 I2C real-time clock. See DS3231.h for the
 * overview, error handling, wiring and thread-safety notes.
 *
 *  Created on: Oct 7, 2026
 *      Author: johng
 */
 
#include "DS3231.h"
 
/* Register addresses and bits, from the DS3231 datasheet register map. */
#define REG_SECONDS         0x00U  /* first of the seven timekeeping registers 00h-06h */
#define REG_STATUS          0x0FU  /* control/status register */
#define TIME_REG_COUNT      7U     /* seconds, minutes, hours, day, date, month, year */
#define HOURS_12H_BIT       0x40U  /* hours register: 1 = 12-hour mode */
#define HOURS_PM_BIT        0x20U  /* hours register, 12-hour mode: 1 = PM */
#define STATUS_OSF          0x80U  /* status register: oscillator stop flag */
#define STATUS_EN32KHZ      0x08U  /* status register: 32 kHz output enable */
#define STATUS_ALARM_FLAGS  0x03U  /* status register: A2F and A1F */
#define STATUS_FIXED_ZERO   0x70U  /* status register bits 6:4 always read 0 */
 
/* I2C error codes that a second attempt can fix (HAL_I2C_GetError()). */
#define I2C_TRANSIENT_ERRORS (HAL_I2C_ERROR_BERR | HAL_I2C_ERROR_ARLO | HAL_I2C_ERROR_AF | \
                              HAL_I2C_ERROR_OVR | HAL_I2C_ERROR_TIMEOUT)
 
static uint8_t decToBcd(uint8_t value)
{
    return (uint8_t)(((value / 10U) << 4) | (value % 10U));
}
 
static uint8_t bcdToDec(uint8_t value)
{
    return (uint8_t)(((value >> 4) * 10U) + (value & 0x0FU));
}
 
static bool isBcd(uint8_t value)
{
    return ((value >> 4) <= 9U) && ((value & 0x0FU) <= 9U);
}
 
static bool isLeapYear(uint16_t year)
{
    return ((year % 4U) == 0U && (year % 100U) != 0U) || ((year % 400U) == 0U);
}
 
static uint8_t daysInMonth(uint16_t year, uint8_t month)
{
    static const uint8_t days[12] = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
 
    if (month == 2U && isLeapYear(year)) {
        return 29U;
    }
    return days[month - 1U];
}
 
static int32_t daysFromCivil(int32_t year, int32_t month, int32_t day)
{
    int32_t y = (month <= 2) ? year - 1 : year;
    int32_t era = y / 400;                                   /* years are >= 2000 here, so no negative division */
    int32_t yearOfEra = y - era * 400;
    int32_t dayOfYear = (153 * (month + ((month > 2) ? -3 : 9)) + 2) / 5 + day - 1;
    int32_t dayOfEra = yearOfEra * 365 + yearOfEra / 4 - yearOfEra / 100 + dayOfYear;
 
    return era * 146097 + dayOfEra - 719468;
}
 
static void civilFromDays(int32_t days, uint16_t *year, uint8_t *month, uint8_t *day)
{
    int32_t z = days + 719468;
    int32_t era = z / 146097;
    int32_t dayOfEra = z - era * 146097;
    int32_t yearOfEra = (dayOfEra - dayOfEra / 1460 + dayOfEra / 36524 - dayOfEra / 146096) / 365;
    int32_t dayOfYear = dayOfEra - (365 * yearOfEra + yearOfEra / 4 - yearOfEra / 100);
    int32_t mp = (5 * dayOfYear + 2) / 153;
    int32_t d = dayOfYear - (153 * mp + 2) / 5 + 1;
    int32_t m = (mp < 10) ? mp + 3 : mp - 9;
    int32_t y = yearOfEra + era * 400 + ((m <= 2) ? 1 : 0);
 
    *year = (uint16_t)y;
    *month = (uint8_t)m;
    *day = (uint8_t)d;
}
 
static uint8_t weekdayOf(uint16_t year, uint8_t month, uint8_t day)
{
    int32_t days = daysFromCivil(year, month, day);
 
    /* 1970-01-01 was a Thursday, which is 4 when Monday is 1. */
    return (uint8_t)(((days + 3) % 7) + 1);
}
 
static bool isTransient(I2C_HandleTypeDef *hi2c, HAL_StatusTypeDef status)
{
    if (status == HAL_BUSY || status == HAL_TIMEOUT) {
        return true;
    }
    if (status == HAL_ERROR) {
        return (HAL_I2C_GetError(hi2c) & I2C_TRANSIENT_ERRORS) != 0U;
    }
    return false;
}
 
static DS3231_Status_t transfer(DS3231_t *dev, bool write, uint8_t reg, uint8_t *buffer, uint16_t length)
{
    uint8_t attempt;
 
    for (attempt = 1U; attempt <= dev->maxAttempts; attempt++) {
        HAL_StatusTypeDef status;
 
        if (write) {
            status = HAL_I2C_Mem_Write(dev->hi2c, DS3231_I2C_ADDRESS, reg, I2C_MEMADD_SIZE_8BIT,
                                       buffer, length, DS3231_I2C_TIMEOUT_MS);
        } else {
            status = HAL_I2C_Mem_Read(dev->hi2c, DS3231_I2C_ADDRESS, reg, I2C_MEMADD_SIZE_8BIT,
                                      buffer, length, DS3231_I2C_TIMEOUT_MS);
        }
 
        if (status == HAL_OK) {
            return DS3231_OK;
        }
 
        dev->lastStatus = status;
 
        if (!isTransient(dev->hi2c, status)) {
            break;
        }
        HAL_Delay(1);
    }
 
    Error_Handler();
    return DS3231_ERR_BUS;
}
 
bool ds3231IsTimeValid(const DS3231_TIME_t *time)
{
    if (time == NULL) {
        return false;
    }
    if (time->year < DS3231_YEAR_MIN || time->year > DS3231_YEAR_MAX) {
        return false;
    }
    if (time->month < 1U || time->month > 12U) {
        return false;
    }
    if (time->day < 1U || time->day > daysInMonth(time->year, time->month)) {
        return false;
    }
    return (time->hour <= 23U) && (time->minute <= 59U) && (time->second <= 59U);
}
 
DS3231_Status_t ds3231TimeToEpoch(const DS3231_TIME_t *time, uint32_t *epochSeconds)
{
    int32_t days;
 
    if (epochSeconds == NULL || !ds3231IsTimeValid(time)) {
        return DS3231_ERR_PARAM;
    }
 
    days = daysFromCivil(time->year, time->month, time->day);
    *epochSeconds = ((uint32_t)days * 86400U) + ((uint32_t)time->hour * 3600U) +
                    ((uint32_t)time->minute * 60U) + time->second;
    return DS3231_OK;
}
 
DS3231_Status_t ds3231EpochToTime(uint32_t epochSeconds, DS3231_TIME_t *time)
{
    uint32_t secondsOfDay;
    int32_t days;
 
    if (time == NULL || epochSeconds < DS3231_EPOCH_MIN || epochSeconds > DS3231_EPOCH_MAX) {
        return DS3231_ERR_PARAM;
    }
 
    days = (int32_t)(epochSeconds / 86400U);
    secondsOfDay = epochSeconds % 86400U;
 
    civilFromDays(days, &time->year, &time->month, &time->day);
    time->weekday = (uint8_t)(((days + 3) % 7) + 1);
    time->hour = (uint8_t)(secondsOfDay / 3600U);
    time->minute = (uint8_t)((secondsOfDay % 3600U) / 60U);
    time->second = (uint8_t)(secondsOfDay % 60U);
    return DS3231_OK;
}
 
DS3231_Status_t ds3231Init(DS3231_t *dev, I2C_HandleTypeDef *hi2c, uint8_t maxAttempts)
{
    HAL_StatusTypeDef status;
    uint8_t statusRegister;
 
    if (dev == NULL || hi2c == NULL) {
        return DS3231_ERR_PARAM;
    }
 
    dev->hi2c = hi2c;
    dev->maxAttempts = (maxAttempts == 0U) ? (uint8_t)DS3231_DEFAULT_MAX_ATTEMPTS : maxAttempts;
    dev->lastStatus = HAL_OK;
 
    status = HAL_I2C_IsDeviceReady(hi2c, DS3231_I2C_ADDRESS, dev->maxAttempts, DS3231_I2C_TIMEOUT_MS);
    if (status != HAL_OK) {
        dev->lastStatus = status;
        return DS3231_ERR_NOT_FOUND;
    }
 
    if (transfer(dev, false, REG_STATUS, &statusRegister, 1U) != DS3231_OK) {
        return DS3231_ERR_BUS;
    }
    if ((statusRegister & STATUS_FIXED_ZERO) != 0U) {
        return DS3231_ERR_NOT_FOUND;
    }
    return DS3231_OK;
}
 
DS3231_Status_t ds3231GetTime(DS3231_t *dev, DS3231_TIME_t *time)
{
    uint8_t raw[TIME_REG_COUNT];
    uint8_t hours;
    uint8_t month;
    uint8_t i;
 
    if (dev == NULL || time == NULL) {
        return DS3231_ERR_PARAM;
    }
 
    if (transfer(dev, false, REG_SECONDS, raw, TIME_REG_COUNT) != DS3231_OK) {
        return DS3231_ERR_BUS;
    }
 
    /* Mask the unused bits and the century bit, then make sure every field is BCD. */
    raw[0] &= 0x7FU;
    raw[1] &= 0x7FU;
    raw[4] &= 0x3FU;
    raw[5] &= 0x1FU;
    for (i = 0U; i < TIME_REG_COUNT; i++) {
        if (i == 2U || i == 3U) {
            continue; /* hours are checked below, the day-of-week register is not used */
        }
        if (!isBcd(raw[i])) {
            return DS3231_ERR_INVALID_DATA;
        }
    }
 
    if ((raw[2] & HOURS_12H_BIT) != 0U) {
        uint8_t hours12 = (uint8_t)(raw[2] & 0x1FU);
 
        if (!isBcd(hours12)) {
            return DS3231_ERR_INVALID_DATA;
        }
        hours12 = bcdToDec(hours12);
        if (hours12 < 1U || hours12 > 12U) {
            return DS3231_ERR_INVALID_DATA;
        }
        hours = (uint8_t)((hours12 % 12U) + (((raw[2] & HOURS_PM_BIT) != 0U) ? 12U : 0U));
    } else {
        if (!isBcd((uint8_t)(raw[2] & 0x3FU))) {
            return DS3231_ERR_INVALID_DATA;
        }
        hours = bcdToDec((uint8_t)(raw[2] & 0x3FU));
    }
 
    month = bcdToDec(raw[5]);
 
    time->second = bcdToDec(raw[0]);
    time->minute = bcdToDec(raw[1]);
    time->hour = hours;
    time->day = bcdToDec(raw[4]);
    time->month = month;
    time->year = (uint16_t)(DS3231_YEAR_MIN + bcdToDec(raw[6]));
    time->weekday = 0U;
 
    if (!ds3231IsTimeValid(time)) {
        return DS3231_ERR_INVALID_DATA;
    }
    time->weekday = weekdayOf(time->year, time->month, time->day);
    return DS3231_OK;
}
 
DS3231_Status_t ds3231SetTime(DS3231_t *dev, const DS3231_TIME_t *time)
{
    uint8_t raw[TIME_REG_COUNT];
 
    if (dev == NULL || !ds3231IsTimeValid(time)) {
        return DS3231_ERR_PARAM;
    }
 
    raw[0] = decToBcd(time->second);
    raw[1] = decToBcd(time->minute);
    raw[2] = decToBcd(time->hour);                 /* 12/24 bit left 0: 24-hour mode */
    raw[3] = weekdayOf(time->year, time->month, time->day);
    raw[4] = decToBcd(time->day);
    raw[5] = decToBcd(time->month);                /* century bit left 0 */
    raw[6] = decToBcd((uint8_t)(time->year - DS3231_YEAR_MIN));
 
    return transfer(dev, true, REG_SECONDS, raw, TIME_REG_COUNT);
}
 
DS3231_Status_t ds3231GetEpoch(DS3231_t *dev, uint32_t *epochSeconds)
{
    DS3231_TIME_t time;
    DS3231_Status_t result;
 
    if (epochSeconds == NULL) {
        return DS3231_ERR_PARAM;
    }
 
    result = ds3231GetTime(dev, &time);
    if (result != DS3231_OK) {
        return result;
    }
    return ds3231TimeToEpoch(&time, epochSeconds);
}
 
DS3231_Status_t ds3231SetEpoch(DS3231_t *dev, uint32_t epochSeconds)
{
    DS3231_TIME_t time;
    DS3231_Status_t result;
 
    result = ds3231EpochToTime(epochSeconds, &time);
    if (result != DS3231_OK) {
        return result;
    }
    return ds3231SetTime(dev, &time);
}
 
DS3231_Status_t ds3231IsOscillatorStopped(DS3231_t *dev, bool *stopped)
{
    uint8_t statusRegister;
 
    if (dev == NULL || stopped == NULL) {
        return DS3231_ERR_PARAM;
    }
 
    if (transfer(dev, false, REG_STATUS, &statusRegister, 1U) != DS3231_OK) {
        return DS3231_ERR_BUS;
    }
    *stopped = (statusRegister & STATUS_OSF) != 0U;
    return DS3231_OK;
}
 
DS3231_Status_t ds3231ClearOscillatorStopFlag(DS3231_t *dev)
{
    uint8_t statusRegister;
 
    if (dev == NULL) {
        return DS3231_ERR_PARAM;
    }
 
    if (transfer(dev, false, REG_STATUS, &statusRegister, 1U) != DS3231_OK) {
        return DS3231_ERR_BUS;
    }
 
    statusRegister = (uint8_t)((statusRegister & STATUS_EN32KHZ) | STATUS_ALARM_FLAGS);
    return transfer(dev, true, REG_STATUS, &statusRegister, 1U);
}