Implement getting time from RTC if NTP is not available

Deni90 · Deni90 · commit 871e562489bd · 2025-10-03T23:47:14.000+02:00
- Implement an I2C OOP wrapper around ESP-IDF's i2c_master
- Implement get/set time for DS3231 RTC
- Integrate RTC handling to NixieClock
diff --git a/firmware/main/CMakeLists.txt b/firmware/main/CMakeLists.txt
@@ -10,6 +10,8 @@ idf_component_register(
     SRCS
         bcd_2_decimal_decoder.cpp
         config_store.cpp
+        ds3231.cpp
+        i2c_bus.cpp
         in14_nixie_tube.cpp
         led_controller.cpp
         led_info.cpp
diff --git a/firmware/main/ds3231.cpp b/firmware/main/ds3231.cpp
@@ -0,0 +1,53 @@
+/******************************************************************************
+ * File:    ds3231.h
+ * Author:  Daniel Knezevic
+ * Year:    2025
+ * Brief:   Definitions for the DS3231 real-time clock driver.
+ ******************************************************************************/
+
+#include "ds3231.h"
+
+static constexpr uint8_t kAddr = 0x68;
+static constexpr u_int32_t kFreq = 400000;   // Hz
+static constexpr uint8_t kTimeReg = 0x00;
+
+Ds3231::Ds3231(I2cBus& bus) : mBus(bus) {}
+
+void Ds3231::initialize() {
+    ESP_ERROR_CHECK(mBus.addDevice(kAddr, kFreq, &mDevHandle));
+}
+
+bool Ds3231::getTime(struct tm* tm) {
+    uint8_t reg = kTimeReg;
+    uint8_t buf[7];
+    if (mBus.read(mDevHandle, &reg, 1, buf, sizeof(buf)) != ESP_OK) {
+        return false;
+    }
+    tm->tm_sec = bcd2dec(buf[0]);
+    tm->tm_min = bcd2dec(buf[1]);
+    tm->tm_hour = bcd2dec(buf[2]);
+    tm->tm_mday = bcd2dec(buf[4]);
+    tm->tm_mon = bcd2dec(buf[5]) - 1;
+    tm->tm_year = bcd2dec(buf[6]) + 100;
+    return true;
+}
+
+bool Ds3231::setTime(const struct tm* tm) {
+    uint8_t buf[8];
+    buf[0] = kTimeReg;   // register address
+    buf[1] = dec2bcd(tm->tm_sec);
+    buf[2] = dec2bcd(tm->tm_min);
+    buf[3] = dec2bcd(tm->tm_hour);
+    buf[4] = 0;   // weekday (not used)
+    buf[5] = dec2bcd(tm->tm_mday);
+    buf[6] = dec2bcd(tm->tm_mon + 1);
+    buf[7] = dec2bcd(tm->tm_year - 100);
+    if (mBus.write(mDevHandle, buf, sizeof(buf)) != ESP_OK) {
+        return false;
+    }
+    return true;
+}
+
+uint8_t Ds3231::bcd2dec(uint8_t val) { return (val >> 4) * 10 + (val & 0x0F); }
+
+uint8_t Ds3231::dec2bcd(uint8_t val) { return ((val / 10) << 4) | (val % 10); }
diff --git a/firmware/main/i2c_bus.cpp b/firmware/main/i2c_bus.cpp
@@ -0,0 +1,57 @@
+/******************************************************************************
+ * File:    i2c_bus.cpp
+ * Author:  Daniel Knezevic
+ * Year:    2025
+ * Brief:   Object-oriented wrapper around the ESP-IDF I2C master driver
+ ******************************************************************************/
+
+#include "i2c_bus.h"
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+I2cBus::I2cBus(i2c_port_t port, gpio_num_t sda, gpio_num_t scl)
+    : mPort(port), mSda(sda), mScl(scl), mBus(nullptr) {}
+
+I2cBus::~I2cBus() {
+    if (mBus) {
+        i2c_del_master_bus(mBus);
+        mBus = nullptr;
+    }
+}
+
+esp_err_t I2cBus::initialize() {
+    i2c_master_bus_config_t config = {};
+    config.i2c_port = mPort;
+    config.sda_io_num = mSda;
+    config.scl_io_num = mScl;
+    config.clk_source = I2C_CLK_SRC_DEFAULT;
+    config.glitch_ignore_cnt = 7;
+    config.flags = {.enable_internal_pullup = true};
+    return i2c_new_master_bus(&config, &mBus);
+}
+
+esp_err_t I2cBus::addDevice(uint8_t address, uint32_t freq,
+                            i2c_master_dev_handle_t* dev) {
+    i2c_device_config_t dev_cfg = {.device_address = address,
+                                   .scl_speed_hz = freq};
+    return i2c_master_bus_add_device(mBus, &dev_cfg, dev);
+}
+
+esp_err_t I2cBus::write(i2c_master_dev_handle_t dev, const uint8_t* data,
+                        size_t len, uint32_t timeout_ms) {
+    return i2c_master_transmit(dev, data, len, pdMS_TO_TICKS(timeout_ms));
+}
+
+esp_err_t I2cBus::read(i2c_master_dev_handle_t dev, const uint8_t* reg,
+                       size_t reg_len, uint8_t* data, size_t data_len,
+                       uint32_t timeout_ms) {
+    // If reg_len == 0, just read
+    if (reg_len > 0) {
+        esp_err_t ret =
+            i2c_master_transmit(dev, reg, reg_len, pdMS_TO_TICKS(timeout_ms));
+        if (ret != ESP_OK)
+            return ret;
+    }
+    return i2c_master_receive(dev, data, data_len, pdMS_TO_TICKS(timeout_ms));
+}
diff --git a/firmware/main/include/ds3231.h b/firmware/main/include/ds3231.h
@@ -0,0 +1,50 @@
+/******************************************************************************
+ * File:    ds3231.h
+ * Author:  Daniel Knezevic
+ * Year:    2025
+ * Brief:   Declarations for the DS3231 real-time clock driver.
+ ******************************************************************************/
+
+#ifndef ds3231_h
+#define ds3231_h
+
+#include "i2c_bus.h"
+
+#include <ctime>
+
+class Ds3231 {
+  public:
+    /**
+     * @brief Construct the DS3231 driver using a shared I2C bus.
+     * @param i2c Reference to an initialized I2C object.
+     */
+    Ds3231(I2cBus& bus);
+
+    /**
+     * @brief Initialize the module
+     */
+    void initialize();
+
+    /**
+     * @brief Read current time and date from the RTC.
+     * @param[out] timeinfo Pointer to a struct tm to receive the data.
+     * @return true on success, false otherwise.
+     */
+    bool getTime(struct tm* timeinfo);
+
+    /**
+     * @brief Set the RTC to the supplied time and date.
+     * @param[in] timeinfo Pointer to struct tm containing the desired time.
+     * @return true on success, false otherwise.
+     */
+    bool setTime(const struct tm* timeinfo);
+
+  private:
+    uint8_t bcd2dec(uint8_t val);
+    uint8_t dec2bcd(uint8_t val);
+
+    I2cBus& mBus;
+    i2c_master_dev_handle_t mDevHandle;
+};
+
+#endif   // ds3231_h
diff --git a/firmware/main/include/i2c_bus.h b/firmware/main/include/i2c_bus.h
@@ -0,0 +1,105 @@
+/******************************************************************************
+ * File:    i2c_bus.h
+ * Author:  Daniel Knezevic
+ * Year:    2025
+ * Brief:   Object-oriented wrapper around the ESP-IDF I2C master driver
+ ******************************************************************************/
+
+#ifndef i2c_bus_h
+#define i2c_bus_h
+
+#include "driver/i2c_master.h"
+#include "esp_err.h"
+
+class I2cBus {
+  public:
+    /**
+     * @brief Construct a new I2cBus instance.
+     *
+     * @param port I2C hardware port number (e.g., I2C_NUM_0 or I2C_NUM_1).
+     * @param sda GPIO pin number used for the SDA line.
+     * @param scl GPIO pin number used for the SCL line.
+     */
+    I2cBus(i2c_port_t port, gpio_num_t sda, gpio_num_t scl);
+
+    /**
+     * @brief Destructor for the I2cBus.
+     *
+     * Automatically deletes the I2C master bus if it was initialized.
+     */
+    ~I2cBus();
+
+    /**
+     * @brief Initialize the I2C master bus.
+     *
+     * Configures the I2C master bus with internal pull-ups and default clock
+     * source. Must be called before adding devices or performing transactions.
+     *
+     * @return
+     *  - ESP_OK on success
+     *  - ESP_ERR_INVALID_ARG if parameters are invalid
+     *  - ESP_ERR_NO_MEM if allocation fails
+     *  - Other error codes from the ESP-IDF I2C driver
+     */
+    esp_err_t initialize();
+
+    /**
+     * @brief Add a device to the I2C bus.
+     *
+     * Each device can use its own SCL frequency. The returned device handle
+     * can be used in subsequent read/write operations.
+     *
+     * @param address 7-bit I2C device address.
+     * @param freq SCL clock frequency in Hz (e.g., 100000 or 400000).
+     * @param dev Pointer to a handle that receives the device handle.
+     * @return
+     *  - ESP_OK on success
+     *  - ESP_ERR_INVALID_ARG or ESP_FAIL on failure
+     */
+    esp_err_t addDevice(uint8_t address, uint32_t freq,
+                        i2c_master_dev_handle_t* dev);
+
+    /**
+     * @brief Write a data buffer to an I2C device.
+     *
+     * @param dev Device handle obtained from addDevice().
+     * @param data Pointer to data buffer to transmit.
+     * @param len Number of bytes to send.
+     * @param timeout_ms Timeout for the operation, in milliseconds.
+     * @return
+     *  - ESP_OK on success
+     *  - ESP_FAIL, ESP_ERR_TIMEOUT, or ESP_ERR_INVALID_STATE on failure
+     */
+    esp_err_t write(i2c_master_dev_handle_t dev, const uint8_t* data,
+                    size_t len, uint32_t timeout_ms = 1000);
+
+    /**
+     * @brief Read data from an I2C device, optionally after writing a register
+     * address.
+     *
+     * Performs a combined write-read transaction if @p reg_len > 0.
+     *
+     * @param dev Device handle obtained from addDevice().
+     * @param reg Optional pointer to the register address buffer (can be
+     * nullptr).
+     * @param reg_len Length of the register address buffer in bytes (0 for no
+     * write phase).
+     * @param data Pointer to buffer for storing received data.
+     * @param data_len Number of bytes to read.
+     * @param timeout_ms Timeout for the operation, in milliseconds.
+     * @return
+     *  - ESP_OK on success
+     *  - ESP_FAIL, ESP_ERR_TIMEOUT, or ESP_ERR_INVALID_STATE on failure
+     */
+    esp_err_t read(i2c_master_dev_handle_t dev, const uint8_t* reg,
+                   size_t reg_len, uint8_t* data, size_t data_len,
+                   uint32_t timeout_ms = 1000);
+
+  private:
+    i2c_port_t mPort;
+    gpio_num_t mSda;
+    gpio_num_t mScl;
+    i2c_master_bus_handle_t mBus;
+};
+
+#endif   // i2c_bus_h
diff --git a/firmware/main/include/nixie_clock.h b/firmware/main/include/nixie_clock.h
@@ -8,6 +8,8 @@
 #include "freertos/task.h"
 
 #include "clock_iface.h"
+#include "ds3231.h"
+#include "i2c_bus.h"
 #include "in14_nixie_tube.h"
 #include "led_controller.h"
 #include "sleep_info.h"
@@ -35,11 +37,13 @@ class NixieClock : public IClock {
     void setupCaptivePortal();
     void startMdnsService(const WifiInfo& wifiInfo);
     void initializeSNTP();
+    static void timeSyncNotificationCallback(struct timeval* tv);
     bool isInSleepMode();
     static void loopTask(void* param);
     bool startShowCurrentTimeTask(void);
     static void showCurrentTimeTask(void* param);
     void handleSleepMode();
+    time_t timegmRtc(struct tm* tm);
 
     LedController mLedController;
     In14NixieTube mNixieTube;
@@ -48,5 +52,7 @@ class NixieClock : public IClock {
     SleepInfo mSleepInfo;
     TimeInfo mTimeInfo;
     TaskHandle_t mShowCurrentTimeTaskHandle;
+    I2cBus mI2c;
+    Ds3231 mRtc;
 };
 #endif   // nixie_clock_h
diff --git a/firmware/main/nixie_clock.cpp b/firmware/main/nixie_clock.cpp
