DS3231.h

Go to the documentation of this file.

/*
 * DS3231.h
 *
 * STM32 HAL driver for the Analog Devices (Maxim) DS3231 I2C real-time clock,
 * as found on the common ZS-042 breakout module.
 *
 * Written from the DS3231 datasheet: I2C address, timekeeping registers
 * 00h-06h, and the control/status register at 0Fh. It is an independent
 * implementation, not a port of anyone else's library.
 *
 *  Created on: Oct 7, 2026
 *      Author: johng
 */
 
#ifndef STM32_DS3231_DS3231_H_
#define STM32_DS3231_DS3231_H_
 
#include "main.h"
#include <stdbool.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define DS3231_I2C_ADDRESS          (0x68U << 1)
 
#define DS3231_DEFAULT_MAX_ATTEMPTS 3U
 
#define DS3231_I2C_TIMEOUT_MS       100U
 
#define DS3231_YEAR_MIN             2000U
 
#define DS3231_YEAR_MAX             2099U
 
#define DS3231_EPOCH_MIN            946684800U
 
#define DS3231_EPOCH_MAX            4102444799U
 
typedef enum {
    DS3231_OK = 0,            
    DS3231_ERR_PARAM,         
    DS3231_ERR_NOT_FOUND,     
    DS3231_ERR_INVALID_DATA,  
    DS3231_ERR_BUS            
} DS3231_Status_t;
 
typedef struct {
    uint16_t year;    
    uint8_t  month;   
    uint8_t  day;     
    uint8_t  weekday; 
    uint8_t  hour;    
    uint8_t  minute;  
    uint8_t  second;  
} DS3231_TIME_t;
 
typedef struct {
    I2C_HandleTypeDef *hi2c;       
    uint8_t            maxAttempts; 
    HAL_StatusTypeDef  lastStatus;  
} DS3231_t;
 
DS3231_Status_t ds3231Init(DS3231_t *dev, I2C_HandleTypeDef *hi2c, uint8_t maxAttempts);
DS3231_Status_t ds3231GetTime(DS3231_t *dev, DS3231_TIME_t *time);
DS3231_Status_t ds3231SetTime(DS3231_t *dev, const DS3231_TIME_t *time);
DS3231_Status_t ds3231GetEpoch(DS3231_t *dev, uint32_t *epochSeconds);
DS3231_Status_t ds3231SetEpoch(DS3231_t *dev, uint32_t epochSeconds);
DS3231_Status_t ds3231IsOscillatorStopped(DS3231_t *dev, bool *stopped);
DS3231_Status_t ds3231ClearOscillatorStopFlag(DS3231_t *dev);
 
bool            ds3231IsTimeValid(const DS3231_TIME_t *time);
DS3231_Status_t ds3231TimeToEpoch(const DS3231_TIME_t *time, uint32_t *epochSeconds);
DS3231_Status_t ds3231EpochToTime(uint32_t epochSeconds, DS3231_TIME_t *time);
 
#ifdef __cplusplus
}
#endif
 
#endif /* STM32_DS3231_DS3231_H_ */