ds1307.h

Go to the documentation of this file.

//   Copyright 2016-2023 Jean-Francois Poilpret
//
//   Licensed under the Apache License, Version 2.0 (the "License");
//   you may not use this file except in compliance with the License.
//   You may obtain a copy of the License at
//
//       http://www.apache.org/licenses/LICENSE-2.0
//
//   Unless required by applicable law or agreed to in writing, software
//   distributed under the License is distributed on an "AS IS" BASIS,
//   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//   See the License for the specific language governing permissions and
//   limitations under the License.
 
 
#ifndef DS1307_H
#define DS1307_H
 
#include "../array.h"
#include "../bits.h"
#include "../i2c.h"
#include "../functors.h"
#include "../future.h"
#include "../utilities.h"
#include "../i2c_device.h"
#include "../i2c_device_utilities.h"
 
// Device driver guidelines:
// - Template on MANAGER, subclass of I2CDevice
// - define types aliases PARENT and FUTURE
// - constructor shall pass one of i2c::Mode i2c::I2C_STANDARD or i2c::I2C_FAST
//   to inherited constructor, in order tos pecify the BEST mode supported by this driver
// - Define FUTURE subclass (inside device class) for every future requiring input (constant, or user-provided)
//   naming convention: MethodNameFuture
// - FUTURE subclass shall have explicit constructor with mandatory input arguments (no default)
// - each async API method returns int (error code) and takes a reference to specific future as unique argument
// - each async API shall have a matching sync API with same name but different prototype:
//   direct input arguments, reference to output arguments, bool return (true if OK)
//   each sync API calls the matching async API after creating the proper Future on the stack
//   then it calls await() or get() on the future before returning.
 
namespace devices
{
    namespace rtc
    {
    }
}
 
namespace devices::rtc
{
    enum class WeekDay : uint8_t
    {
        SUNDAY = 1,
        MONDAY,
        TUESDAY,
        WEDNESDAY,
        THURSDAY,
        FRIDAY,
        SATURDAY
    };
 
    struct tm
    {
        uint8_t tm_sec = 0;
        uint8_t tm_min = 0;
        uint8_t tm_hour = 0;
        WeekDay tm_wday = WeekDay(0);
        uint8_t tm_mday = 0;
        uint8_t tm_mon = 0;
        uint8_t tm_year = 0;
    };
 
    enum class SquareWaveFrequency : uint8_t
    {
        FREQ_1HZ = 0x00,
        FREQ_4096HZ = 0x01,
        FREQ_8192HZ = 0x02,
        FREQ_32768HZ = 0x03
    };
 
    template<typename MANAGER>
    class DS1307 : public i2c::I2CDevice<MANAGER>
    {
    private:
        using PARENT = i2c::I2CDevice<MANAGER>;
        template<typename OUT, typename IN> using FUTURE = typename PARENT::template FUTURE<OUT, IN>;
 
        template<uint8_t REGISTER, typename T = uint8_t, typename FUNCTOR = functor::Identity<T>>
        using TReadRegisterFuture = i2c::TReadRegisterFuture<MANAGER, REGISTER, T, FUNCTOR>;
        template<uint8_t REGISTER, typename T = uint8_t, typename FUNCTOR = functor::Identity<T>>
        using TWriteRegisterFuture = i2c::TWriteRegisterFuture<MANAGER, REGISTER, T, FUNCTOR>;
 
        static constexpr const uint8_t DEVICE_ADDRESS = 0x68 << 1;
        static constexpr const uint8_t RAM_START = 0x08;
        static constexpr const uint8_t RAM_END = 0x40;
        static constexpr const uint8_t RAM_SIZE = RAM_END - RAM_START;
        static constexpr const uint8_t TIME_ADDRESS = 0x00;
        static constexpr const uint8_t CLOCK_HALT = 0x80;
        static constexpr const uint8_t CONTROL_ADDRESS = 0x07;
 
        class ControlRegister
        {
        public:
            static constexpr ControlRegister create_output_level(bool level)
            {
                return ControlRegister(level ? OUT_MASK : 0);
            }
            static constexpr ControlRegister create_square_wave_enable(SquareWaveFrequency frequency)
            {
                return ControlRegister(SQWE_MASK | uint8_t(frequency));
            }
 
        private:
            explicit ControlRegister(uint8_t data = 0) : data_{data} {}
 
            static constexpr uint8_t FREQUENCY_MASK = bits::BV8(0, 1);
            static constexpr uint8_t SQWE_MASK = bits::BV8(4);
            static constexpr uint8_t OUT_MASK = bits::BV8(7);
 
            uint8_t data_ = 0;
        };
 
        // Conversion functors for datetime (BCD Vs binary)
        class DatetimeConverterToDevice
        {
        public:
            using ARG_TYPE = tm;
            using RES_TYPE = tm;
            RES_TYPE operator()(const ARG_TYPE& datetime) const
            {
                tm dt;
                dt.tm_sec = utils::binary_to_bcd(datetime.tm_sec);
                dt.tm_min = utils::binary_to_bcd(datetime.tm_min);
                dt.tm_hour = utils::binary_to_bcd(datetime.tm_hour);
                dt.tm_mday = utils::binary_to_bcd(datetime.tm_mday);
                dt.tm_mon = utils::binary_to_bcd(datetime.tm_mon);
                dt.tm_year = utils::binary_to_bcd(datetime.tm_year);
                return dt;
            }
        };
 
        class DatetimeConverterFromDevice
        {
        public:
            using ARG_TYPE = tm;
            using RES_TYPE = tm;
            RES_TYPE operator()(const ARG_TYPE& datetime) const
            {
                tm dt;
                // convert DS1307 output (BCD) to integer type
                dt.tm_sec = utils::bcd_to_binary(datetime.tm_sec);
                dt.tm_min = utils::bcd_to_binary(datetime.tm_min);
                dt.tm_hour = utils::bcd_to_binary(datetime.tm_hour);
                dt.tm_mday = utils::bcd_to_binary(datetime.tm_mday);
                dt.tm_mon = utils::bcd_to_binary(datetime.tm_mon);
                dt.tm_year = utils::bcd_to_binary(datetime.tm_year);
                return dt;
            }
        };
 
    public:
        explicit DS1307(MANAGER& manager) : PARENT{manager, DEVICE_ADDRESS, i2c::I2C_STANDARD, true} {}
 
        static constexpr uint8_t ram_size()
        {
            return RAM_SIZE;
        }
 
        // Asynchronous API
        //==================
        using SetDatetimeFuture = TWriteRegisterFuture<TIME_ADDRESS, tm, DatetimeConverterToDevice>;
 
        int set_datetime(SetDatetimeFuture& future)
        {
            return this->async_write(future);
        }
 
        using GetDatetimeFuture = TReadRegisterFuture<TIME_ADDRESS, tm, DatetimeConverterFromDevice>;
 
        int get_datetime(GetDatetimeFuture& future)
        {
            return this->async_read(future);
        }
 
        template<uint8_t SIZE_>
        class SetRamFuture : public FUTURE<void, containers::array<uint8_t, SIZE_ + 1>>
        {
            using PARENT = FUTURE<void, containers::array<uint8_t, SIZE_ + 1>>;
            using IN = typename PARENT::IN;
 
            static IN build_array(uint8_t address, const uint8_t (&data)[SIZE_])
            {
                IN input;
                input[0] = static_cast<uint8_t>(address + RAM_START);
                input.set(1, data);
                return input;
            }
 
        public:
            explicit SetRamFuture(uint8_t address, const uint8_t (&data)[SIZE_])
            : PARENT{build_array(address, data)}
            {
                static_assert(SIZE_ <= RAM_SIZE, "SIZE_ template paraneter must be less than RAM_SIZE!");
            }
 
            bool is_input_valid() const
            {
                return ((this->get_input()[0] + SIZE_) <= RAM_END);
            }
        };
 
        template<uint8_t SIZE> int set_ram(SetRamFuture<SIZE>& future)
        {
            if (!future.is_input_valid())
                return errors::EINVAL;
            return this->async_write(future);
        }
 
        class SetRam1Future : public FUTURE<void, containers::array<uint8_t, 2>>
        {
            using PARENT = FUTURE<void, containers::array<uint8_t, 2>>;
        public:
            explicit SetRam1Future(uint8_t address, uint8_t data)
                :   PARENT{{static_cast<uint8_t>(address + RAM_START), data}} {}
 
            bool is_input_valid() const
            {
                return (this->get_input()[0] < RAM_END);
            }
        };
 
        int set_ram(SetRam1Future& future)
        {
            if (!future.is_input_valid())
                return errors::EINVAL;
            return this->async_write(future);
        }
 
        template<uint8_t SIZE_>
        class GetRamFuture : public FUTURE<containers::array<uint8_t, SIZE_>, uint8_t>
        {
            using PARENT = FUTURE<containers::array<uint8_t, SIZE_>, uint8_t>;
        public:
            explicit GetRamFuture(uint8_t address) : PARENT{static_cast<uint8_t>(address + RAM_START)}
            {
                static_assert(SIZE_ <= RAM_SIZE, "SIZE_ template paraneter must be less than RAM_SIZE!");
            }
 
            bool is_input_valid() const
            {
                return ((this->get_input() + SIZE_) <= RAM_END);
            }
        };
 
        template<uint8_t SIZE> int get_ram(GetRamFuture<SIZE>& future)
        {
            if (!future.is_input_valid())
                return errors::EINVAL;
            return this->async_read(future);
        }
 
        class GetRam1Future : public FUTURE<uint8_t, uint8_t>
        {
            using PARENT = FUTURE<uint8_t, uint8_t>;
        public:
            explicit GetRam1Future(uint8_t address) : PARENT{static_cast<uint8_t>(address + RAM_START)} {}
 
            bool is_input_valid() const
            {
                return this->get_input() < RAM_END;
            }
        };
 
        int get_ram(GetRam1Future& future)
        {
            if (!future.is_input_valid())
                return errors::EINVAL;
            return this->async_read(future);
        }
 
        class HaltClockFuture : public TWriteRegisterFuture<TIME_ADDRESS>
        {
        public:
            // just write 0x80 at address 0
            HaltClockFuture() : TWriteRegisterFuture<TIME_ADDRESS>{CLOCK_HALT} {}
        };
 
        int halt_clock(HaltClockFuture& future)
        {
            return this->async_write(future);
        }
 
        class EnableOutputFuture : public TWriteRegisterFuture<CONTROL_ADDRESS, ControlRegister>
        {
            using PARENT = TWriteRegisterFuture<CONTROL_ADDRESS, ControlRegister>;
 
        public:
            explicit EnableOutputFuture(SquareWaveFrequency frequency) 
                : PARENT{ControlRegister::create_square_wave_enable(frequency)} {}
        };
 
        int enable_output(EnableOutputFuture& future)
        {
            return this->async_write(future);
        }
 
        class DisableOutputFuture : public TWriteRegisterFuture<CONTROL_ADDRESS, ControlRegister>
        {
            using PARENT = TWriteRegisterFuture<CONTROL_ADDRESS, ControlRegister>;
 
        public:
            explicit DisableOutputFuture(bool output_value) 
                : PARENT{ControlRegister::create_output_level(output_value)} {}
        };
 
        int disable_output(DisableOutputFuture& future)
        {
            return this->async_write(future);
        }
 
        // Synchronous API
        //=================
        bool set_datetime(const tm& datetime)
        {
            return this->template sync_write<SetDatetimeFuture>(datetime);
        }
 
        bool get_datetime(tm& datetime)
        {
            return this->template sync_read<GetDatetimeFuture>(datetime);
        }
 
        bool halt_clock()
        {
            return this->template sync_write<HaltClockFuture>();
        }
 
        bool enable_output(SquareWaveFrequency frequency = SquareWaveFrequency::FREQ_1HZ)
        {
            return this->template sync_write<EnableOutputFuture>(frequency);
        }
 
        bool disable_output(bool output_value = false)
        {
            return this->template sync_write<DisableOutputFuture>(output_value);
        }
 
        bool set_ram(uint8_t address, uint8_t data)
        {
            SetRam1Future future{address, data};
            if (set_ram(future) != 0) return false;
            return (future.await() == future::FutureStatus::READY);
        }
 
        uint8_t get_ram(uint8_t address)
        {
            GetRam1Future future{address};
            if (get_ram(future) != 0) return false;
            uint8_t data = 0;
            future.get(data);
            return data;
        }
 
        template<uint8_t SIZE> bool set_ram(uint8_t address, const uint8_t (&data)[SIZE])
        {
            SetRamFuture<SIZE> future{address, data};
            if (set_ram(future) != 0) return false;
            return (future.await() == future::FutureStatus::READY);
        }
 
        template<uint8_t SIZE> bool get_ram(uint8_t address, uint8_t (&data)[SIZE])
        {
            GetRamFuture<SIZE> future{address};
            if (get_ram(future) != 0) return false;
            typename GetRamFuture<SIZE>::OUT temp;
            if (!future.get(temp)) return false;
            memcpy(data, temp.data(), SIZE);
            return true;
        }
 
        template<typename T> bool set_ram(uint8_t address, const T& data)
        {
            uint8_t temp[sizeof(T)];
            utils::as_array<T>(data, temp);
            SetRamFuture<sizeof(T)> future{address, temp};
            if (set_ram(future) != 0) return false;
            return (future.await() == future::FutureStatus::READY);
        }
 
        template<typename T> bool get_ram(uint8_t address, T& data)
        {
            GetRamFuture<sizeof(T)> future{address};
            if (get_ram(future) != 0) return false;
            return future.get(reinterpret_cast<uint8_t&>(data));
        }
    };
}
 
#endif /* DS1307_H */