An ESP-IDF driver for the RTC module DS3231, built on the i2c_master API. Future versions may add support for other DS3231 features. All features of this driver are tested on an ESP32-S3 board, including new ones that will be added in future releases.
Features
- Read and set time with struct tm from the standard library time.h.
- 12-hour and 24-hour formats.
- Two alarms with all match modes of the chip, alarm interrupts.
- Square wave output with selectable frequency.
- 32 kHz output.
- Read temperature and get/set aging.
- Run and stop the oscillator when running on battery.
- Uses an I2C bus handle provided by the application, so that it can be easily shared with other devices.
- Thread safe: the driver can be used from multiple FreeRTOS tasks.
- Time and date registers are read and written with a single I2C transaction, so there are no rollover errors between seconds, minutes, and hours.
Requirements
Installation
idf.py add-dependency "antonholovchenko35/ds3231"
Documentation
The API reference is available at https://antonholovchenko35.github.io/esp-idf-ds3231/
Thread safety
The driver can be called from multiple FreeRTOS tasks without extra locking in the application because each I2C access is either single transaction, which is protected by i2c_master driver, or a read-modify-write operation, which is protected by the driver's internal mutex. If the mutex cannot be taken within DS3231_LOCK_TIMEOUT_MS (1000 ms), the function returns ESP_ERR_TIMEOUT.
Notes
- Support 2000-2099 years only.
- tm_isdst of the struct tm is always set to 0, because the driver treats the time stored in the RTC as UTC.
- tm_hour is always 0-23, in both formats. In 12-hour mode the driver does the AM/PM conversion.
- The alarm hour format must match the current time format.
- Alarm interrupts and the square wave share INT/SQW pin, so you should call ds3231_squarewave_disable() before using alarm interrupts.
- After an alarm fires, the INT pin stays low until the flag is cleared by the ds3231_alarm_clear_flags().
- ds3231_set_time() also sets the format of saved time and turns off the OSF bit. Because the driver treats the time stored in the RTC as UTC, pass UTC to this function as well.
- OSF flag is not reliable without battery.
- ds3231_create() and ds3231_delete() are not thread safe. Don't call ds3231_delete() while other tasks may still use the handle.
- A sequence of calls, such as ds3231_get_time_valid() followed by ds3231_set_time(), is not atomic, so if several tasks can run the same sequence, protect it in the application.
- The I2C address 0x68 and bus speed 100 kHz are fixed.
Usage
i2c_master_bus_config_t bus_cfg = {
.i2c_port = -1,
.sda_io_num = I2C_SDA_GPIO,
.scl_io_num = I2C_SCL_GPIO,
.clk_source = I2C_CLK_SRC_DEFAULT,
.glitch_ignore_cnt = 7,
.flags.enable_internal_pullup = true
};
i2c_master_bus_handle_t i2c_bus;
ESP_ERROR_CHECK(i2c_new_master_bus(&bus_cfg, &i2c_bus));
bool time_valid;
struct tm timeinfo = {
.tm_year = 2026 - 1900,
.tm_mon = 0,
.tm_mday = 1,
.tm_hour = 23,
.tm_min = 58,
.tm_sec = 0,
.tm_wday = 4
};
ESP_LOGI(TAG, "Time was invalid, set to default");
}
struct tm timeinfo = {0};
while (1){
ESP_LOGI(TAG, "%04d-%02d-%02d %02d:%02d:%02d",
timeinfo.tm_year + 1900, timeinfo.tm_mon + 1, timeinfo.tm_mday,
timeinfo.tm_hour, timeinfo.tm_min, timeinfo.tm_sec);
vTaskDelay(pdMS_TO_TICKS(1000));
}
Public API for the DS3231 RTC driver.
ds3231_time_format_t
Time format of the device.
Definition ds3231.h:25
@ DS3231_TIME_FORMAT_24H
Definition ds3231.h:27
esp_err_t ds3231_get_time(ds3231_handle_t ds3231_handle, struct tm *timeinfo, ds3231_time_format_t *format)
Get the current date and time.
esp_err_t ds3231_create(i2c_master_bus_handle_t i2c_bus, ds3231_handle_t *ds3231_handle)
Initialize device handle.
esp_err_t ds3231_get_time_valid(ds3231_handle_t ds3231_handle, bool *time_valid)
Check validity of the time module saved.
void * ds3231_handle_t
Handle of a DS3231 device.
Definition ds3231.h:86
esp_err_t ds3231_get_time_format(ds3231_handle_t ds3231_handle, ds3231_time_format_t *timeformat)
Get the current time format.
esp_err_t ds3231_set_time(ds3231_handle_t ds3231_handle, struct tm timeinfo, ds3231_time_format_t format)
Set current date time.
See examples for complete projects.
Examples
- basic_24h - sets and reads time in 24-hour format.
- basic_12h - sets and reads time in 12-hour format.
Bug reports and feedback
If you find a bug, an inaccuracy in the documentation, or behavior that doesn't match the DS3231 dataheet, please open an issue. When reporting bugs, please include:
- version of the driver and the ESP-IDF version
- the target chip
- minimal code that reproduce the problem
- the log output, if there's any
AI assistance
Because I forgot about it, the CHANGELOG entries up to v0.4.0 were written with the help of an AI assistant (Claude by Anthropic) from the git history, then reviewed by me. All code is written by me.
License
MIT, see LICENSE