unit_PCF8563.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_RTC_UNIT_PCF8563_HPP
#define M5_UNIT_RTC_UNIT_PCF8563_HPP
 
#include <M5UnitComponent.hpp>
#include "unit_PCF8563_types.hpp"
 
namespace m5 {
namespace unit {
 
class UnitPCF8563 : public Component {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitPCF8563, 0x51);
 
public:
    using irq_callback_t = void (*)();
 
    struct config_t {
        int16_t int_pin{-1};
        bool polling{true};
        pcf8563::ClockOutput clkout{pcf8563::ClockOutput::None};
        uint32_t polling_interval{500};
        irq_callback_t on_alarm{nullptr};
        irq_callback_t on_timer{nullptr};
    };
 
    explicit UnitPCF8563(const uint8_t addr = DEFAULT_ADDRESS) : Component(addr)
    {
    }
    virtual ~UnitPCF8563()
    {
    }
 
    virtual bool begin() override;
    virtual void update(const bool force = false) override;
 
 
    inline config_t config() const
    {
        return _cfg;
    }
    inline void config(const config_t& cfg)
    {
        _cfg = cfg;
    }
 
    // ============================================================
    // M5UnitUnified style API
 
 
    bool readTime(pcf8563::rtc_time_t& time);
    bool writeTime(const pcf8563::rtc_time_t& time);
    bool readDate(pcf8563::rtc_date_t& date);
    bool writeDate(const pcf8563::rtc_date_t& date);
    bool readDateTime(pcf8563::rtc_datetime_t& dt);
    bool writeDateTime(const pcf8563::rtc_datetime_t& dt);
    bool readDateTime(struct tm& t);
    bool writeDateTime(const struct tm& t);
 
 
    bool writeAlarm(const pcf8563::rtc_time_t& time, const pcf8563::rtc_date_t& date);
    bool readAlarm(pcf8563::rtc_time_t& time, pcf8563::rtc_date_t& date);
    bool readAlarmInterrupt(bool& enabled);
    bool writeAlarmInterrupt(const bool enabled);
    bool readAlarmFlag(bool& fired);
    bool clearAlarmFlag();
 
    uint32_t writeTimer(const uint32_t msec, const bool repeat = false);
    bool readTimerControl(bool& enabled, pcf8563::TimerClock& clock);
    bool writeTimerControl(const bool enabled, const pcf8563::TimerClock clock);
    bool readTimerValue(uint8_t& count);
    bool writeTimerValue(const uint8_t count);
    bool readTimerInterrupt(bool& enabled);
    bool writeTimerInterrupt(const bool enabled);
    bool readTimerFlag(bool& fired);
    bool clearTimerFlag();
    bool readTimerPeriodic(bool& periodic);
    bool writeTimerPeriodic(const bool periodic);
 
 
    bool readStop(bool& stopped);
    bool writeStop(const bool stop);
 
 
    bool readVoltLow(bool& low);
 
    // ============================================================
    // M5Unified M5.RTC compatible API
    // Available when M5Unified.hpp or RTC_Base.hpp is included before this header.
#if defined(__M5_RTC_BASE_H__) || defined(__M5UNIFIED_HPP__)
 
 
    inline bool getDateTime(m5::rtc_date_t* date, m5::rtc_time_t* time)
    {
        pcf8563::rtc_date_t d;
        pcf8563::rtc_time_t t;
        if (!read_datetime(date ? &d : nullptr, time ? &t : nullptr)) {
            return false;
        }
        if (date) {
            *date = {d.year, d.month, d.date, d.weekDay};
        }
        if (time) {
            *time = {t.hours, t.minutes, t.seconds};
        }
        return true;
    }
    inline bool setDateTime(const m5::rtc_date_t* date, const m5::rtc_time_t* time)
    {
        pcf8563::rtc_date_t d;
        pcf8563::rtc_time_t t;
        if (date) {
            d = {date->year, date->month, date->date, date->weekDay};
        }
        if (time) {
            t = {time->hours, time->minutes, time->seconds};
        }
        return write_datetime(date ? &d : nullptr, time ? &t : nullptr);
    }
 
    inline bool getDateTime(m5::rtc_datetime_t* dt)
    {
        return dt ? getDateTime(&dt->date, &dt->time) : false;
    }
    inline bool getDate(m5::rtc_date_t* date)
    {
        return getDateTime(date, nullptr);
    }
    inline bool getTime(m5::rtc_time_t* time)
    {
        return getDateTime(nullptr, time);
    }
 
    inline bool setDateTime(const m5::rtc_datetime_t& dt)
    {
        return setDateTime(&dt.date, &dt.time);
    }
    inline bool setDateTime(const m5::rtc_datetime_t* dt)
    {
        return dt ? setDateTime(&dt->date, &dt->time) : false;
    }
    inline bool setDate(const m5::rtc_date_t* date)
    {
        return setDateTime(date, nullptr);
    }
    inline bool setDate(const m5::rtc_date_t& date)
    {
        return setDateTime(&date, nullptr);
    }
    inline bool setTime(const m5::rtc_time_t* time)
    {
        return setDateTime(nullptr, time);
    }
    inline bool setTime(const m5::rtc_time_t& time)
    {
        return setDateTime(nullptr, &time);
    }
 
    inline m5::rtc_time_t getTime()
    {
        pcf8563::rtc_time_t t{};
        readTime(t);
        return {t.hours, t.minutes, t.seconds};
    }
    inline m5::rtc_date_t getDate()
    {
        pcf8563::rtc_date_t d{};
        readDate(d);
        return {d.year, d.month, d.date, d.weekDay};
    }
    inline m5::rtc_datetime_t getDateTime()
    {
        pcf8563::rtc_datetime_t dt{};
        readDateTime(dt);
        return {{dt.date.year, dt.date.month, dt.date.date, dt.date.weekDay},
                {dt.time.hours, dt.time.minutes, dt.time.seconds}};
    }
 
    int setAlarmIRQ(const m5::rtc_date_t* date, const m5::rtc_time_t* time);
    inline int setAlarmIRQ(const m5::rtc_date_t& date, const m5::rtc_time_t& time)
    {
        return setAlarmIRQ(&date, &time);
    }
    inline int setAlarmIRQ(const m5::rtc_time_t& time)
    {
        return setAlarmIRQ(nullptr, &time);
    }
    int setAlarmIRQ(const int afterSeconds);
    uint32_t setTimerIRQ(const uint32_t timer_msec);
 
    inline bool getVoltLow()
    {
        bool low{};
        return readVoltLow(low) ? low : true;
    }
    inline bool getIRQstatus()
    {
        uint8_t val{};
        if (!read_control2(val)) {
            return false;
        }
        return (val & 0x0C) != 0;
    }
    inline void clearIRQ()
    {
        write_control2_bits(0x0C, 0x00);
    }
    void disableIRQ();
    void setSystemTimeFromRtc(struct timezone* tz = nullptr);
 
#endif  // defined(__M5_RTC_BASE_H__) || defined(__M5UNIFIED_HPP__)
 
protected:
    bool read_register(const uint8_t reg, uint8_t* buf, const size_t len);
    bool read_register8(const uint8_t reg, uint8_t& val);
    bool write_register(const uint8_t reg, const uint8_t* buf, const size_t len);
    bool write_register8(const uint8_t reg, const uint8_t val);
 
    bool read_datetime(pcf8563::rtc_date_t* date, pcf8563::rtc_time_t* time);
    bool write_datetime(const pcf8563::rtc_date_t* date, const pcf8563::rtc_time_t* time);
    bool read_control2(uint8_t& val);
    bool write_control2_bits(const uint8_t mask, const uint8_t bits);
 
private:
    static void IRAM_ATTR isr_handler(void* arg);
    void check_irq_flags();
 
    config_t _cfg{};
    volatile bool _isr_fired{};
};
 
namespace pcf8563 {
namespace command {
constexpr uint8_t CONTROL1_REG{0x00};
constexpr uint8_t CONTROL2_REG{0x01};
constexpr uint8_t SECONDS_REG{0x02};
constexpr uint8_t MINUTES_REG{0x03};
constexpr uint8_t HOURS_REG{0x04};
constexpr uint8_t DAYS_REG{0x05};
constexpr uint8_t WEEKDAYS_REG{0x06};
constexpr uint8_t MONTHS_REG{0x07};
constexpr uint8_t YEARS_REG{0x08};
constexpr uint8_t ALARM_MINUTES_REG{0x09};
constexpr uint8_t ALARM_HOURS_REG{0x0A};
constexpr uint8_t ALARM_DAY_REG{0x0B};
constexpr uint8_t ALARM_WEEKDAY_REG{0x0C};
constexpr uint8_t CLKOUT_CONTROL_REG{0x0D};
constexpr uint8_t TIMER_CONTROL_REG{0x0E};
constexpr uint8_t TIMER_REG{0x0F};
}  // namespace command
}  // namespace pcf8563
 
}  // namespace unit
}  // namespace m5
#endif