deps: the pin advances to the reviewed libavr, and the clock example is 6 B smaller

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.clang-format

@@ -1,13 +1,15 @@
 ---
 BasedOnStyle: LLVM
+Standard: Latest
 ColumnLimit: 120
 IndentWidth: 4
 TabWidth: 4
 UseTab: ForIndentation
 AlignEscapedNewlines: DontAlign
 AllowShortFunctionsOnASingleLine: Empty
-AlwaysBreakTemplateDeclarations: true
+BreakTemplateDeclarations: Yes
 BreakBeforeBraces: Custom
 BraceWrapping:
   AfterFunction: true
+InsertBraces: true
 ...

.clangd

@@ -0,0 +1,32 @@
+# Editor accommodations for the second frontend. No compilation database is
+# named here: this driver is made to be vendored, and this file travels with
+# it - a consumer's own database then covers these headers, at the consumer's
+# chip. The checkout that is opened as a folder names its build tree in
+# .vscode/settings.json instead.
+CompileFlags:
+  Add:
+    # clang has no 24-bit integer and GCC's are keywords, not macros, so the
+    # editor needs a stand-in for avr::uint24_t. The next width up is the only
+    # one available - clang rejects _BitInt(24) on this target.
+    - -D__uint24=unsigned long
+    - -D__int24=long
+    # clangd forwards the driver's system includes but not its own header
+    # directory, so <stdint.h> resolves to avr-libc's, which still gates the
+    # limit and constant macros on the C++98 opt-in.
+    - -D__STDC_LIMIT_MACROS
+    - -D__STDC_CONSTANT_MACROS
+    # isr::emit spells a vector number into [[gnu::signal(N)]], which clang
+    # rejects rather than ignores - enough of them in one TU to reach the
+    # default limit of 19 inside the headers and truncate the parse.
+    - -ferror-limit=0
+  Remove:
+    # The build promotes warnings for the compiler that has to be right about
+    # them; in the editor the flag paints a second frontend's opinions in the
+    # colour reserved for things that do not compile.
+    - -Werror
+Diagnostics:
+  Suppress:
+    # clang's AVR `signal` attribute takes no arguments and it knows none of
+    # progmem, naked or OS_main. A misspelling is what the build is for.
+    - attribute_wrong_number_arguments
+    - unknown-attributes

.gitattributes

@@ -1,9 +1,8 @@
-*.h         eol=lf
+# Line endings are the repository's, not the editing tool's (libavr guidance
-*.hpp       eol=lf
+# rule 50): a file rewritten by a Windows tool must not come back with every
-*.c         eol=lf
+# line changed.
-*.cpp       eol=lf
+* text=auto eol=lf
-.git*       eol=lf
+
-*.vcxproj*  eol=crlf
+# Atmel Studio writes these and expects them back.
 *.cppproj   eol=crlf
-*.sln       eol=crlf
 *.atsln     eol=crlf

.gitignore

@@ -1,11 +1,10 @@
-.vs
+build/
-Release
+local/
-Debug
+.cache/
-*.componentinfo.xml
+
-*.elf
+# Atmel Studio: generated per machine, its build outputs, and per-user state
-*.o
+ide/*/*.componentinfo.xml
-*.hex
+ide/*/Debug/
-*.srec
+ide/*/Release/
-*.eeprom
+ide/.vs/
-*.lss
+ide/*.log
-*.map

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "libavr"]
+	path = libavr
+	url = ../libavr.git

.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+	"recommendations": [
+		"llvm-vs-code-extensions.vscode-clangd",
+		"ms-vscode.cmake-tools"
+	]
+}

.vscode/settings.json

@@ -0,0 +1,39 @@
+{
+	// clangd is the language server; the cpptools engine would parse every file
+	// a second time and disagree, since nothing tells it about a cross
+	// compiler.
+	"C_Cpp.intelliSenseEngine": "disabled",
+
+	// --query-driver lets clangd ask the cross compiler for its own system
+	// includes and target. The database is named here rather than in .clangd
+	// because that file travels with the driver into a consumer's submodule,
+	// where a build tree of this repo's own need not exist. It sits one level
+	// above the trees, and CMake Tools copies the selected preset's into it on
+	// every configure: the database carries `-mmcu`, so a fixed tree would
+	// check the driver against one chip.
+	"clangd.arguments": [
+		"--compile-commands-dir=${workspaceFolder}/build",
+		"--query-driver=**avr-g++*",
+		"--header-insertion=never"
+	],
+	"cmake.copyCompileCommands": "${workspaceFolder}/build/compile_commands.json",
+
+	// The presets are the build interface, and the toolchain file inside the
+	// libavr submodule is the one place the compiler is chosen. No prefix is
+	// named here: the gitignored local/machine.cmake at this repository's root
+	// is where a checkout says where its toolchain is (libavr guidance rule 50).
+	"cmake.useCMakePresets": "always",
+	"cmake.configureOnOpen": true,
+	"cmake.options.statusBarVisibility": "compact",
+
+	"files.watcherExclude": {
+		"**/build/**": true,
+		"**/local/**": true,
+		"**/libavr/**": true
+	},
+
+	"files.associations": {
+		".clangd": "yaml",
+		".clang-format": "yaml"
+	}
+}

CMakeLists.txt

@@ -0,0 +1,29 @@
+cmake_minimum_required(VERSION 3.28)
+
+project(ds3231 LANGUAGES CXX)
+
+# libavr rides as the pinned submodule; LIBAVR_ROOT (cache or environment)
+# overrides it for tandem development against a working tree. The toolchain
+# file comes from the submodule via CMakePresets.json either way.
+if(NOT LIBAVR_ROOT AND DEFINED ENV{LIBAVR_ROOT})
+	set(LIBAVR_ROOT $ENV{LIBAVR_ROOT})
+endif()
+if(NOT LIBAVR_ROOT)
+	set(LIBAVR_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/libavr)
+endif()
+if(NOT EXISTS ${LIBAVR_ROOT}/CMakeLists.txt)
+	message(FATAL_ERROR "libavr not found at ${LIBAVR_ROOT} - run: git submodule update --init libavr")
+endif()
+add_subdirectory(${LIBAVR_ROOT} libavr-build)
+
+add_library(ds3231 INTERFACE)
+target_include_directories(ds3231 INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/include)
+target_link_libraries(ds3231 INTERFACE libavr)
+
+include(${LIBAVR_ROOT}/cmake/checks.cmake)
+
+if(PROJECT_IS_TOP_LEVEL)
+	add_subdirectory(example)
+	enable_testing()
+	add_subdirectory(test)
+endif()

CMakePresets.json

@@ -0,0 +1,43 @@
+{
+	"version": 8,
+	"configurePresets": [
+		{
+			"name": "base",
+			"hidden": true,
+			"generator": "Ninja",
+			"binaryDir": "${sourceDir}/build/${presetName}",
+			"toolchainFile": "${sourceDir}/libavr/cmake/avr-toolchain.cmake",
+			"cacheVariables": {
+				"CMAKE_BUILD_TYPE": "Release",
+				"CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
+				"CMAKE_COLOR_DIAGNOSTICS": "ON"
+			}
+		},
+		{
+			"name": "attiny85-generated",
+			"inherits": "base",
+			"cacheVariables": { "LIBAVR_MCU": "attiny85", "LIBAVR_REFLECT": "OFF" }
+		},
+		{
+			"name": "attiny85-reflect",
+			"inherits": "base",
+			"cacheVariables": { "LIBAVR_MCU": "attiny85", "LIBAVR_REFLECT": "ON" }
+		},
+		{
+			"name": "atmega328p-generated",
+			"inherits": "base",
+			"cacheVariables": { "LIBAVR_MCU": "atmega328p", "LIBAVR_REFLECT": "OFF" }
+		},
+		{
+			"name": "atmega328p-reflect",
+			"inherits": "base",
+			"cacheVariables": { "LIBAVR_MCU": "atmega328p", "LIBAVR_REFLECT": "ON" }
+		}
+	],
+	"buildPresets": [
+		{ "name": "attiny85-generated", "configurePreset": "attiny85-generated" },
+		{ "name": "attiny85-reflect", "configurePreset": "attiny85-reflect" },
+		{ "name": "atmega328p-generated", "configurePreset": "atmega328p-generated" },
+		{ "name": "atmega328p-reflect", "configurePreset": "atmega328p-reflect" }
+	]
+}

README.md

@@ -0,0 +1,97 @@
+# ds3231
+
+Maxim DS3231 RTC driver on [libavr](https://git.blackmark.me/avr/libavr):
+clock and alarm read/write, alarm interrupts, oscillator-stop detection,
+die temperature. One source runs on every libavr chip — TWI hardware on
+the mega328P, open-drain software I2C on the tinies. All bus errors
+surface as `std::expected`.
+
+```cpp
+using bus = dev::i2c<{.frequency = 100_kHz}>;
+using rtc = ds3231::device<bus>;
+
+auto now = rtc::read_clock();       // result<date_time>
+auto armed = rtc::set_alarm1({}, ds3231::alarm1_rate::once_per_second);
+```
+
+`example/main.cpp` is a complete program. libavr rides as the `libavr/` submodule,
+pinned to the commit this driver builds against; `LIBAVR_ROOT` (cache or
+environment) overrides it for development against a working tree:
+
+```sh
+git submodule update --init libavr
+cmake --preset attiny85-generated
+cmake --build --preset attiny85-generated
+```
+
+Presets cover attiny85/atmega328p in both libavr modes (generated and
+reflect); `ctest` runs the consteval battery over the BCD, the hours
+register's two formats, the weekday, the alarm registers each rate writes and
+the control and status write-backs, and holds the example to its stated size —
+**1462 B** on the mega328P and **1256 B** on the tiny85, byte-identical across
+the two modes. The legacy
+yazoalfa-based driver lives on the `master` branch.
+
+The weekday register is derived from the date by default. A program that
+assigns its own meaning to the device's 1..7 takes ownership of it, and no
+write here touches it:
+
+```cpp
+using rtc = ds3231::device<bus, ds3231::weekday_source::external>;
+```
+
+An alarm arms its INT/SQW output unless told otherwise, and can be muted and
+re-wired without re-arming:
+
+```cpp
+auto quiet = rtc::set_alarm2(at, ds3231::alarm2_rate::minutes_match,
+                             ds3231::alarm_interrupt::off);
+auto again = rtc::listen_alarm2();
+```
+
+## Atmel Studio
+
+`master` carries a Studio solution, so this branch does too: `ide/ds3231.atsln`
+builds `example/main.cpp` for both parts the presets cover, each to a
+**byte-identical `.text`** against the CMake build (`check-flags.py` below is
+what holds the flag sets equal, so the sizes are the presets' own), with the
+flags mirrored by hand. CMake remains the build system.
+
+`avrdevice` is a project-level property in Studio, so a part means a project, not
+a configuration: `ide/atmega328p/` and `ide/attiny85/`. They need separate
+directories rather than separate names — Studio builds into `<project
+dir>/<Configuration>` whatever `OutputDirectory` says, so two projects sharing
+one directory would also share one `example/main.o`, and building one after the
+other without a rebuild would link the other part's object.
+
+Studio finds libavr in the **submodule** at
+`$(MSBuildProjectDirectory)\..\..\libavr\include` — correct by construction,
+and anchored to the project because a plain relative path is resolved against
+the generated makefile's directory (the configuration's output directory), not
+the project's. There is no `LIBAVR_ROOT` escape hatch: a variable exported in a
+shell is invisible to Studio launched from the Start menu — which is what the
+submodule answers. It also needs a GCC 16.1 toolchain registered as flavour
+`avr-g++-16.1.0`, nothing older reaching `-std=c++26`.
+
+One generated file is required before the project will load, and one command
+checks the flags have not drifted (both from libavr's `tools/atmelstudio/`):
+
+```sh
+for mcu in atmega328p attiny85; do
+    case $mcu in atmega328p) device=ATmega328P;; attiny85) device=ATtiny85;; esac
+    python libavr/tools/atmelstudio/componentinfo.py \
+        "ide/$mcu/ds3231-$mcu.componentinfo.xml" --device "$device"
+    python libavr/tools/atmelstudio/check-flags.py --solution ide/ds3231.atsln \
+        --project "ds3231-$mcu" \
+        --compile-commands "build/$mcu-generated/compile_commands.json" \
+        --log "build/as-$mcu.log"
+done
+```
+
+One reference describes one part, hence `--project`. Release is what the gate
+compares, the presets defining no debug build; Debug carries the `-Og
+-gdwarf-4` pair libavr's own debug preset uses.
+
+Differences from legacy: weekday-rate alarms set the DY bit (the legacy
+driver always cleared it), each register block is read or written in one
+coherent bus transaction, and errors are reported instead of ignored.

alarms.hpp

@@ -1,24 +0,0 @@
-#pragma once
-
-#include <stdint.h>
-
-namespace rtc {
-
-enum class Alarm1Rate : uint8_t {
-	ONCE_PER_S = 0b1111,
-	WHEN_S_MATCH = 0b1110,
-	WHEN_M_S_MATCH = 0b1100,
-	WHEN_H_M_S_MATCH = 0b1000,
-	WHEN_DATE_H_M_S_MATCH = 0b00000,
-	WHEN_DAY_H_N_S_MATCH = 0b10000,
-};
-
-enum class Alarm2Rate : uint8_t {
-	ONCE_PER_M = 0b111,
-	WHEN_M_MATCH = 0b110,
-	WHEN_H_M_MATCH = 0b100,
-	WHEN_DATE_H_M_MATCH = 0b0000,
-	WHEN_DAY_H_N_MATCH = 0b1000,
-};
-
-} // namespace rtc

ds3231.hpp

@@ -1,392 +0,0 @@
-#pragma once
-
-#include "../clock.hpp"
-
-#include <stddef.h>
-
-#include "../i2c/i2c.hpp"
-#include "../util/type.hpp"
-
-#include "registers.hpp"
-
-namespace rtc {
-
-struct Date {
-	uint16_t year;
-	uint8_t month;
-	uint8_t day;
-
-	inline bool operator==(const Date &rhs) const
-	{
-		if (day != rhs.day)
-			return false;
-		if (month != rhs.month)
-			return false;
-		if (year != rhs.year)
-			return false;
-		return true;
-	}
-
-	inline bool operator!=(const Date &rhs)
-	{
-		return !(*this == rhs);
-	}
-};
-
-struct Time {
-	uint8_t hour;
-	uint8_t minute;
-	uint8_t second;
-
-	inline bool operator==(const Time &rhs) const
-	{
-		if (second != rhs.second)
-			return false;
-		if (minute != rhs.minute)
-			return false;
-		if (hour != rhs.hour)
-			return false;
-		return true;
-	}
-
-	inline bool operator!=(const Time &rhs)
-	{
-		return !(*this == rhs);
-	}
-};
-
-struct DateTime : Date, Time {
-	inline bool operator==(const DateTime &rhs) const
-	{
-		if (second != rhs.second)
-			return false;
-		if (minute != rhs.minute)
-			return false;
-		if (hour != rhs.hour)
-			return false;
-		if (day != rhs.day)
-			return false;
-		if (month != rhs.month)
-			return false;
-		if (year != rhs.year)
-			return false;
-		return true;
-	}
-
-	inline bool operator!=(const DateTime &rhs)
-	{
-		return !(*this == rhs);
-	}
-};
-
-template <typename I2cDriver, bool SetDayOfWeek = true>
-class DS3231 {
-	using i2c_t = i2c::I2c<I2cDriver>;
-
-  public:
-	static constexpr auto I2C_ADDRESS = 0x68;
-
-	static constexpr auto TIME_REG_ADDR = 0x00;
-	static constexpr auto ALARM1_REG_ADDR = 0x07;
-	static constexpr auto ALARM2_REG_ADDR = 0x0B;
-	static constexpr auto CONTROL_REG_ADDR = 0x0E;
-	static constexpr auto CONTROL_STATUS_REG_ADDR = 0x0F;
-	static constexpr auto AGING_OFFSET_REG_ADDR = 0x10;
-	static constexpr auto TEMP_REG_ADDR = 0x11;
-
-	// Construction does not call init and is only available for convenience
-	DS3231() = default;
-
-	// Moving and copying ds3231 objects is not supported
-	DS3231(const DS3231 &) = delete;
-	DS3231(DS3231 &&) = delete;
-	DS3231 &operator=(const DS3231 &) = delete;
-	DS3231 &operator=(DS3231 &&) = delete;
-
-	static inline void init()
-	{
-		i2c_t::init();
-	}
-
-	static auto getDate()
-	{
-		const auto timeReg = readRegister<TIME_REG_ADDR>();
-
-		Date date;
-		date.year = timeReg.getYear();
-		date.month = timeReg.getMonth();
-		date.day = timeReg.getDate();
-		return date;
-	}
-	static auto getTime()
-	{
-		const auto timeReg = readRegister<TIME_REG_ADDR>();
-
-		Time time;
-		time.hour = timeReg.getHours();
-		time.minute = timeReg.getMinutes();
-		time.second = timeReg.getSeconds();
-		return time;
-	}
-	static auto getDateTime()
-	{
-		const auto timeReg = readRegister<TIME_REG_ADDR>();
-
-		DateTime dateTime;
-		dateTime.year = timeReg.getYear();
-		dateTime.month = timeReg.getMonth();
-		dateTime.day = timeReg.getDate();
-		dateTime.hour = timeReg.getHours();
-		dateTime.minute = timeReg.getMinutes();
-		dateTime.second = timeReg.getSeconds();
-		return dateTime;
-	}
-
-	static DateTime getAlarm1()
-	{
-		return getAlarmHelper<ALARM1_REG_ADDR>();
-	}
-	static DateTime getAlarm2()
-	{
-		return getAlarmHelper<ALARM2_REG_ADDR>();
-	}
-
-	static void setDate(const Date &date)
-	{
-		detail::TimeReg timeReg;
-		timeReg.setYear(date.year);
-		timeReg.setMonth(date.month);
-		timeReg.setDate(date.day);
-		if constexpr (SetDayOfWeek)
-			timeReg.setDay(calcDayOfWeek(date.year, date.month, date.day) + 1);
-
-		constexpr auto DATE_START_OFFSET = offsetof(detail::TimeReg, day);
-		constexpr auto DATE_END_OFFSET = offsetof(detail::TimeReg, year);
-
-		writePartialRegister<DATE_START_OFFSET, DATE_END_OFFSET>(timeReg);
-	}
-	static void setTime(const Time &time)
-	{
-		detail::TimeReg timeReg;
-		timeReg.setHours(time.hour);
-		timeReg.setMinutes(time.minute);
-		timeReg.setSeconds(time.second);
-
-		constexpr auto TIME_START_OFFSET = offsetof(detail::TimeReg, seconds);
-		constexpr auto TIME_END_OFFSET = offsetof(detail::TimeReg, hours);
-
-		writePartialRegister<TIME_START_OFFSET, TIME_END_OFFSET>(timeReg);
-	}
-	static void setDateTime(const DateTime &dateTime)
-	{
-		detail::TimeReg timeReg;
-		timeReg.setYear(dateTime.year);
-		timeReg.setMonth(dateTime.month);
-		timeReg.setDate(dateTime.day);
-		if constexpr (SetDayOfWeek)
-			timeReg.setDay(calcDayOfWeek(dateTime.year, dateTime.month, dateTime.day) + 1);
-
-		timeReg.setHours(dateTime.hour);
-		timeReg.setMinutes(dateTime.minute);
-		timeReg.setSeconds(dateTime.second);
-
-		constexpr auto START_OFFSET = offsetof(detail::TimeReg, seconds);
-		constexpr auto END_OFFSET = offsetof(detail::TimeReg, year);
-
-		writePartialRegister<START_OFFSET, END_OFFSET>(timeReg);
-	}
-
-	static void setAlarm1(const DateTime &alarmTime, const Alarm1Rate &alarmRate, bool enableInterrupt = true)
-	{
-		setAlarmHelper(alarmTime, alarmRate);
-		if (enableInterrupt)
-			enableInterruptHelper<detail::ControlRegFlags::A1IE>();
-	}
-	static void setAlarm2(const DateTime &alarmTime, const Alarm2Rate &alarmRate, bool enableInterrupt = true)
-	{
-		setAlarmHelper(alarmTime, alarmRate);
-		if (enableInterrupt)
-			enableInterruptHelper<detail::ControlRegFlags::A2IE>();
-	}
-
-	static bool checkAlarm1()
-	{
-		return checkAlarmHelper<detail::ControlStatusRegFlags::A1F>();
-	}
-	static bool checkAlarm2()
-	{
-		return checkAlarmHelper<detail::ControlStatusRegFlags::A2F>();
-	}
-
-	static void clearAlarm1()
-	{
-		clearAlarmHelper<detail::ControlStatusRegFlags::A1F>();
-	}
-	static void clearAlarm2()
-	{
-		clearAlarmHelper<detail::ControlStatusRegFlags::A2F>();
-	}
-
-  private:
-	template <uint8_t Address, typename Register>
-	static Register readRegisterHelper()
-	{
-		i2c_t::template start<I2C_ADDRESS>(false);
-		i2c_t::write(Address);
-		i2c_t::stop();
-
-		Register reg;
-		i2c_t::template start<I2C_ADDRESS>(true);
-		i2c_t::template readBytes<sizeof(Register)>(reinterpret_cast<uint8_t *>(&reg));
-		i2c_t::stop();
-		return reg;
-	}
-
-	template <uint8_t Address>
-	static auto readRegister()
-	{
-		if constexpr (Address == TIME_REG_ADDR) {
-			return readRegisterHelper<Address, detail::TimeReg>();
-		} else if constexpr (Address == ALARM1_REG_ADDR) {
-			return readRegisterHelper<Address, detail::Alarm1Reg>();
-		} else if constexpr (Address == ALARM2_REG_ADDR) {
-			return readRegisterHelper<Address, detail::Alarm2Reg>();
-		} else if constexpr (Address == CONTROL_REG_ADDR) {
-			return readRegisterHelper<Address, detail::ControlReg>();
-		} else if constexpr (Address == CONTROL_STATUS_REG_ADDR) {
-			return readRegisterHelper<Address, detail::ControlStatusReg>();
-		} else if constexpr (Address == AGING_OFFSET_REG_ADDR) {
-			return readRegisterHelper<Address, detail::AgingOffsetReg>();
-		} else if constexpr (Address == TEMP_REG_ADDR) {
-			return readRegisterHelper<Address, detail::TempReg>();
-		} else {
-			static_assert(util::always_false_v<decltype(Address)>, "Invalid register address");
-		}
-	}
-
-	template <uint8_t StartOffset, uint8_t EndOffset, typename Register>
-	static void writePartialRegister(const Register &reg)
-	{
-		constexpr auto getRegisterAddress = []() {
-			if constexpr (util::is_same_v<Register, detail::TimeReg>) {
-				return TIME_REG_ADDR;
-			} else if constexpr (util::is_same_v<Register, detail::Alarm1Reg>) {
-				return ALARM1_REG_ADDR;
-			} else if constexpr (util::is_same_v<Register, detail::Alarm2Reg>) {
-				return ALARM2_REG_ADDR;
-			} else if constexpr (util::is_same_v<Register, detail::ControlReg>) {
-				return CONTROL_REG_ADDR;
-			} else if constexpr (util::is_same_v<Register, detail::ControlStatusReg>) {
-				return CONTROL_STATUS_REG_ADDR;
-			} else if constexpr (util::is_same_v<Register, detail::AgingOffsetReg>) {
-				return AGING_OFFSET_REG_ADDR;
-			} else if constexpr (util::is_same_v<Register, detail::TempReg>) {
-				return TEMP_REG_ADDR;
-			} else {
-				static_assert(util::always_false_v<Register>, "Invalid register type");
-			}
-		};
-
-		constexpr auto ADDRESS = getRegisterAddress();
-
-		static_assert(StartOffset <= EndOffset, "Invalid offset range");
-		static_assert(StartOffset < sizeof(Register), "Start offset out of bounds");
-		static_assert(EndOffset < sizeof(Register), "End offset out of bounds");
-
-		constexpr auto WRITE_SIZE = EndOffset + 1 - StartOffset;
-		static_assert(StartOffset + WRITE_SIZE <= sizeof(Register), "Writing out of bounds");
-
-		i2c_t::template start<I2C_ADDRESS>(false);
-		i2c_t::write(ADDRESS + StartOffset);
-		i2c_t::template writeBytes<WRITE_SIZE>(reinterpret_cast<const uint8_t *>(&reg) + StartOffset);
-		i2c_t::stop();
-	}
-
-	template <typename Register>
-	static void writeRegister(const Register &reg)
-	{
-		writePartialRegister<0, sizeof(Register) - 1>(reg);
-	}
-
-	template <uint8_t Address>
-	static inline auto getAlarmHelper()
-	{
-		constexpr auto IsAlarm1 = Address == ALARM1_REG_ADDR;
-		static_assert(IsAlarm1 || Address == ALARM2_REG_ADDR, "Must use valid alarm address");
-
-		const auto alarmReg = readRegister<Address>();
-
-		DateTime alarmTime = {};
-		alarmReg.getDate(alarmTime.day);
-		alarmTime.hour = alarmReg.getHours();
-		alarmTime.minute = alarmReg.getMinutes();
-		if constexpr (IsAlarm1)
-			alarmTime.second = alarmReg.getSeconds();
-
-		return alarmTime;
-	}
-
-	template <typename AlarmRate>
-	static inline void setAlarmHelper(const DateTime &alarmTime, const AlarmRate &alarmRate)
-	{
-		constexpr auto IsAlarm1 = util::is_same_v<AlarmRate, Alarm1Rate>;
-		static_assert(IsAlarm1 || util::is_same_v<AlarmRate, Alarm2Rate>, "Must use valid alarm rate");
-
-		using alarm_reg_t = util::conditional_t<IsAlarm1, detail::Alarm1Reg, detail::Alarm2Reg>;
-
-		alarm_reg_t alarmReg;
-		alarmReg.setAlarmRate(alarmRate);
-		alarmReg.setDate(alarmTime.day);
-		alarmReg.setHours(alarmTime.hour);
-		alarmReg.setMinutes(alarmTime.minute);
-		if constexpr (IsAlarm1)
-			alarmReg.setSeconds(alarmTime.second);
-		writeRegister(alarmReg);
-	}
-
-	template <detail::ControlRegFlags AlarmFlag>
-	static inline void enableInterruptHelper()
-	{
-		constexpr auto IsAlarm1Flag = AlarmFlag == detail::ControlRegFlags::A1IE;
-		constexpr auto IsAlarm2Flag = AlarmFlag == detail::ControlRegFlags::A2IE;
-		static_assert(IsAlarm1Flag || IsAlarm2Flag, "Must use valid alarm flag");
-
-		auto controlReg = readRegister<CONTROL_REG_ADDR>();
-		using Flags = typename decltype(controlReg)::Flags;
-		controlReg &= ~Flags::BBSQW;
-		controlReg |= Flags::INTCN | AlarmFlag;
-		writeRegister(controlReg);
-	}
-
-	template <detail::ControlStatusRegFlags AlarmFlag>
-	static inline bool checkAlarmHelper()
-	{
-		constexpr auto IsAlarm1Flag = AlarmFlag == detail::ControlStatusRegFlags::A1F;
-		constexpr auto IsAlarm2Flag = AlarmFlag == detail::ControlStatusRegFlags::A2F;
-		static_assert(IsAlarm1Flag || IsAlarm2Flag, "Must use valid alarm flag");
-
-		const auto alarmStatus = readRegister<CONTROL_STATUS_REG_ADDR>();
-		return alarmStatus == AlarmFlag;
-	}
-
-	template <detail::ControlStatusRegFlags AlarmFlag>
-	static inline void clearAlarmHelper()
-	{
-		constexpr auto IsAlarm1Flag = AlarmFlag == detail::ControlStatusRegFlags::A1F;
-		constexpr auto IsAlarm2Flag = AlarmFlag == detail::ControlStatusRegFlags::A2F;
-		static_assert(IsAlarm1Flag || IsAlarm2Flag, "Must use valid alarm flag");
-
-		auto controlStatusReg = readRegister<CONTROL_STATUS_REG_ADDR>();
-		controlStatusReg &= ~AlarmFlag;
-		writeRegister(controlStatusReg);
-	}
-
-	static uint8_t calcDayOfWeek(uint16_t year, uint8_t month, uint16_t day)
-	{
-		day += month < 3 ? year-- : year - 2;
-		const auto dayOfWeek = (23 * month / 9 + day + 4 + year / 4 - year / 100 + year / 400);
-		return dayOfWeek % 7;
-	}
-};
-
-} // namespace rtc

example/CMakeLists.txt

@@ -0,0 +1,3 @@
+add_executable(clock main.cpp)
+target_link_libraries(clock PRIVATE ds3231)
+add_custom_command(TARGET clock POST_BUILD COMMAND ${CMAKE_SIZE} $<TARGET_FILE:clock>)

example/main.cpp

@@ -0,0 +1,33 @@
+#include <ds3231/ds3231.hpp>
+#include <libavr/libavr.hpp>
+
+using namespace avr::literals;
+
+// One source for the tiny85 (open-drain software I2C on the USI pins) and
+// the mega328P (TWI hardware).
+using dev = avr::device<{.clock = 8_MHz}>;
+using bus = dev::i2c<{.frequency = 100_kHz}>;
+using rtc = ds3231::device<bus>;
+using led = dev::output<avr::pb3>;
+
+int main()
+{
+	avr::init<bus, led>();
+
+	if (auto stopped = rtc::oscillator_stopped(); stopped.value_or(false)) {
+		const bool seeded = rtc::write_clock({{2026, 1, 1}, {12, 0, 0}}) &&
+		                    rtc::set_alarm1({}, ds3231::alarm1_rate::once_per_second) &&
+		                    rtc::clear_oscillator_stopped();
+		led::write(seeded);
+	}
+
+	while (true) {
+		if (auto now = rtc::read_clock(); now.has_value()) {
+			led::write(now->second % 2 == 0);
+		}
+		if (auto fired = rtc::alarm1_fired(); fired.value_or(false) && !rtc::clear_alarm1()) {
+			led::clear();
+		}
+		dev::delay<100_ms>();
+	}
+}

flags.hpp

@@ -1,88 +0,0 @@
-#pragma once
-
-namespace rtc {
-
-namespace detail {
-
-template <typename FlagsT>
-struct [[gnu::packed]] FlagsImpl
-{
-	static_assert(sizeof(FlagsT) == sizeof(uint8_t), "Must use uint8_t enum class flags");
-
-	uint8_t data = 0;
-	using Flags = FlagsT;
-
-	FlagsImpl() : data(0) {}
-	FlagsImpl(const Flags &flag) : data(static_cast<uint8_t>(flag)) {}
-
-	FlagsImpl(const FlagsImpl &other) : data(other.data) {}
-	FlagsImpl(const FlagsImpl &&) = delete;
-
-	FlagsImpl &operator=(const FlagsImpl &rhs)
-	{
-		data = rhs.data;
-		return *this;
-	}
-	FlagsImpl &operator=(const FlagsImpl &&) = delete;
-
-	FlagsImpl &operator=(const FlagsT &rhs)
-	{
-		data = static_cast<uint8_t>(rhs);
-		return *this;
-	}
-
-	FlagsImpl &operator|=(const FlagsT &flag)
-	{
-		data |= static_cast<uint8_t>(flag);
-		return *this;
-	}
-
-	FlagsImpl &operator|=(const uint8_t &flag)
-	{
-		data |= flag;
-		return *this;
-	}
-
-	FlagsImpl &operator&=(const FlagsT &flag)
-	{
-		data &= static_cast<uint8_t>(flag);
-		return *this;
-	}
-
-	FlagsImpl &operator&=(const uint8_t &flag)
-	{
-		data &= flag;
-		return *this;
-	}
-
-	FlagsImpl &operator~()
-	{
-		data = ~data;
-		return *this;
-	}
-
-	bool operator==(const FlagsT &flag) const
-	{
-		return data & static_cast<uint8_t>(flag);
-	}
-};
-
-template <typename FlagsT>
-FlagsT operator|(const FlagsT &lhs, const FlagsT &rhs)
-{
-	const auto lhsInt = static_cast<uint8_t>(lhs);
-	const auto rhsInt = static_cast<uint8_t>(rhs);
-	return static_cast<FlagsT>(lhsInt | rhsInt);
-}
-
-template <typename FlagsT>
-FlagsT operator&(const FlagsT &lhs, const FlagsT &rhs)
-{
-	const auto lhsInt = static_cast<uint8_t>(lhs);
-	const auto rhsInt = static_cast<uint8_t>(rhs);
-	return static_cast<FlagsT>(lhsInt & rhsInt);
-}
-
-} // namespace detail
-
-} // namespace rtc

ide/atmega328p/ds3231-atmega328p.cppproj

@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="14.0">
+  <PropertyGroup>
+    <SchemaVersion>2.0</SchemaVersion>
+    <ProjectVersion>7.0</ProjectVersion>
+    <ToolchainName>com.Atmel.AVRGCC8.CPP</ToolchainName>
+    <ProjectGuid>7b3e5a41-9c26-4d18-8f52-6a0d31c74be9</ProjectGuid>
+    <avrdevice>ATmega328P</avrdevice>
+    <avrdeviceseries>none</avrdeviceseries>
+    <OutputType>Executable</OutputType>
+    <Language>CPP</Language>
+    <OutputFileName>$(MSBuildProjectName)</OutputFileName>
+    <OutputFileExtension>.elf</OutputFileExtension>
+    <OutputDirectory>$(MSBuildProjectDirectory)\$(Configuration)</OutputDirectory>
+    <AssemblyName>ds3231-atmega328p</AssemblyName>
+    <Name>ds3231-atmega328p</Name>
+    <RootNamespace>ds3231</RootNamespace>
+    <ToolchainFlavour>avr-g++-16.1.0</ToolchainFlavour>
+    <KeepTimersRunning>true</KeepTimersRunning>
+    <OverrideVtor>false</OverrideVtor>
+    <CacheFlash>true</CacheFlash>
+    <ProgFlashFromRam>true</ProgFlashFromRam>
+    <RamSnippetAddress>0x20000000</RamSnippetAddress>
+    <UncachedRange />
+    <preserveEEPROM>true</preserveEEPROM>
+    <OverrideVtorValue>exception_table</OverrideVtorValue>
+    <BootSegment>2</BootSegment>
+    <ResetRule>0</ResetRule>
+    <eraseonlaunchrule>0</eraseonlaunchrule>
+    <EraseKey />
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
+    <ToolchainSettings>
+      <AvrGccCpp>
+        <avrgcc.common.Device>-mmcu=atmega328p</avrgcc.common.Device>
+        <avrgcc.common.outputfiles.hex>True</avrgcc.common.outputfiles.hex>
+        <avrgcc.common.outputfiles.lss>True</avrgcc.common.outputfiles.lss>
+        <avrgcc.common.outputfiles.eep>True</avrgcc.common.outputfiles.eep>
+        <avrgcc.common.outputfiles.srec>True</avrgcc.common.outputfiles.srec>
+        <avrgcc.common.outputfiles.usersignatures>False</avrgcc.common.outputfiles.usersignatures>
+        <avrgcccpp.compiler.symbols.DefSymbols>
+          <ListValues>
+            <Value>NDEBUG</Value>
+          </ListValues>
+        </avrgcccpp.compiler.symbols.DefSymbols>
+        <avrgcccpp.compiler.directories.IncludePaths>
+          <ListValues>
+            <Value>$(MSBuildProjectDirectory)\..\..\include</Value>
+            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
+          </ListValues>
+        </avrgcccpp.compiler.directories.IncludePaths>
+        <avrgcccpp.compiler.optimization.level>Optimize for size (-Os)</avrgcccpp.compiler.optimization.level>
+        <avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>
+        <avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>
+        <avrgcccpp.compiler.warnings.AllWarnings>True</avrgcccpp.compiler.warnings.AllWarnings>
+        <avrgcccpp.compiler.miscellaneous.OtherFlags>-std=c++26 -Wextra -mrelax -fno-exceptions -fno-rtti -fno-threadsafe-statics</avrgcccpp.compiler.miscellaneous.OtherFlags>
+        <avrgcccpp.linker.optimization.GarbageCollectUnusedSections>True</avrgcccpp.linker.optimization.GarbageCollectUnusedSections>
+        <avrgcccpp.linker.miscellaneous.LinkerFlags>-mrelax</avrgcccpp.linker.miscellaneous.LinkerFlags>
+      </AvrGccCpp>
+    </ToolchainSettings>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
+    <ToolchainSettings>
+      <AvrGccCpp>
+        <avrgcc.common.Device>-mmcu=atmega328p</avrgcc.common.Device>
+        <avrgcc.common.outputfiles.hex>True</avrgcc.common.outputfiles.hex>
+        <avrgcc.common.outputfiles.lss>True</avrgcc.common.outputfiles.lss>
+        <avrgcc.common.outputfiles.eep>True</avrgcc.common.outputfiles.eep>
+        <avrgcc.common.outputfiles.srec>True</avrgcc.common.outputfiles.srec>
+        <avrgcc.common.outputfiles.usersignatures>False</avrgcc.common.outputfiles.usersignatures>
+        <avrgcccpp.compiler.symbols.DefSymbols>
+          <ListValues>
+            <Value>DEBUG</Value>
+          </ListValues>
+        </avrgcccpp.compiler.symbols.DefSymbols>
+        <avrgcccpp.compiler.directories.IncludePaths>
+          <ListValues>
+            <Value>$(MSBuildProjectDirectory)\..\..\include</Value>
+            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
+          </ListValues>
+        </avrgcccpp.compiler.directories.IncludePaths>
+        <avrgcccpp.compiler.optimization.level>Optimize debugging experience (-Og)</avrgcccpp.compiler.optimization.level>
+        <avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>
+        <avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>
+        <avrgcccpp.compiler.warnings.AllWarnings>True</avrgcccpp.compiler.warnings.AllWarnings>
+        <avrgcccpp.compiler.miscellaneous.OtherFlags>-std=c++26 -Wextra -mrelax -fno-exceptions -fno-rtti -fno-threadsafe-statics -gdwarf-4</avrgcccpp.compiler.miscellaneous.OtherFlags>
+        <avrgcccpp.linker.optimization.GarbageCollectUnusedSections>True</avrgcccpp.linker.optimization.GarbageCollectUnusedSections>
+        <avrgcccpp.linker.miscellaneous.LinkerFlags>-mrelax</avrgcccpp.linker.miscellaneous.LinkerFlags>
+      </AvrGccCpp>
+    </ToolchainSettings>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="..\..\example\main.cpp">
+      <SubType>compile</SubType>
+      <Link>example\main.cpp</Link>
+    </Compile>
+    <Compile Include="..\..\include\ds3231\ds3231.hpp">
+      <SubType>compile</SubType>
+      <Link>include\ds3231\ds3231.hpp</Link>
+    </Compile>
+  </ItemGroup>
+  <ItemGroup>
+    <Folder Include="example" />
+    <Folder Include="include" />
+    <Folder Include="include\ds3231" />
+  </ItemGroup>
+  <Import Project="$(AVRSTUDIO_EXE_PATH)\Vs\Compiler.targets" />
+</Project>

ide/attiny85/ds3231-attiny85.cppproj

@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="14.0">
+  <PropertyGroup>
+    <SchemaVersion>2.0</SchemaVersion>
+    <ProjectVersion>7.0</ProjectVersion>
+    <ToolchainName>com.Atmel.AVRGCC8.CPP</ToolchainName>
+    <ProjectGuid>1d84c0f7-52b9-4a63-b7e1-9f2c48d5a306</ProjectGuid>
+    <avrdevice>ATtiny85</avrdevice>
+    <avrdeviceseries>none</avrdeviceseries>
+    <OutputType>Executable</OutputType>
+    <Language>CPP</Language>
+    <OutputFileName>$(MSBuildProjectName)</OutputFileName>
+    <OutputFileExtension>.elf</OutputFileExtension>
+    <OutputDirectory>$(MSBuildProjectDirectory)\$(Configuration)</OutputDirectory>
+    <AssemblyName>ds3231-attiny85</AssemblyName>
+    <Name>ds3231-attiny85</Name>
+    <RootNamespace>ds3231</RootNamespace>
+    <ToolchainFlavour>avr-g++-16.1.0</ToolchainFlavour>
+    <KeepTimersRunning>true</KeepTimersRunning>
+    <OverrideVtor>false</OverrideVtor>
+    <CacheFlash>true</CacheFlash>
+    <ProgFlashFromRam>true</ProgFlashFromRam>
+    <RamSnippetAddress>0x20000000</RamSnippetAddress>
+    <UncachedRange />
+    <preserveEEPROM>true</preserveEEPROM>
+    <OverrideVtorValue>exception_table</OverrideVtorValue>
+    <BootSegment>2</BootSegment>
+    <ResetRule>0</ResetRule>
+    <eraseonlaunchrule>0</eraseonlaunchrule>
+    <EraseKey />
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
+    <ToolchainSettings>
+      <AvrGccCpp>
+        <avrgcc.common.Device>-mmcu=attiny85</avrgcc.common.Device>
+        <avrgcc.common.outputfiles.hex>True</avrgcc.common.outputfiles.hex>
+        <avrgcc.common.outputfiles.lss>True</avrgcc.common.outputfiles.lss>
+        <avrgcc.common.outputfiles.eep>True</avrgcc.common.outputfiles.eep>
+        <avrgcc.common.outputfiles.srec>True</avrgcc.common.outputfiles.srec>
+        <avrgcc.common.outputfiles.usersignatures>False</avrgcc.common.outputfiles.usersignatures>
+        <avrgcccpp.compiler.symbols.DefSymbols>
+          <ListValues>
+            <Value>NDEBUG</Value>
+          </ListValues>
+        </avrgcccpp.compiler.symbols.DefSymbols>
+        <avrgcccpp.compiler.directories.IncludePaths>
+          <ListValues>
+            <Value>$(MSBuildProjectDirectory)\..\..\include</Value>
+            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
+          </ListValues>
+        </avrgcccpp.compiler.directories.IncludePaths>
+        <avrgcccpp.compiler.optimization.level>Optimize for size (-Os)</avrgcccpp.compiler.optimization.level>
+        <avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>
+        <avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>
+        <avrgcccpp.compiler.warnings.AllWarnings>True</avrgcccpp.compiler.warnings.AllWarnings>
+        <avrgcccpp.compiler.miscellaneous.OtherFlags>-std=c++26 -Wextra -mrelax -fno-exceptions -fno-rtti -fno-threadsafe-statics</avrgcccpp.compiler.miscellaneous.OtherFlags>
+        <avrgcccpp.linker.optimization.GarbageCollectUnusedSections>True</avrgcccpp.linker.optimization.GarbageCollectUnusedSections>
+        <avrgcccpp.linker.miscellaneous.LinkerFlags>-mrelax</avrgcccpp.linker.miscellaneous.LinkerFlags>
+      </AvrGccCpp>
+    </ToolchainSettings>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
+    <ToolchainSettings>
+      <AvrGccCpp>
+        <avrgcc.common.Device>-mmcu=attiny85</avrgcc.common.Device>
+        <avrgcc.common.outputfiles.hex>True</avrgcc.common.outputfiles.hex>
+        <avrgcc.common.outputfiles.lss>True</avrgcc.common.outputfiles.lss>
+        <avrgcc.common.outputfiles.eep>True</avrgcc.common.outputfiles.eep>
+        <avrgcc.common.outputfiles.srec>True</avrgcc.common.outputfiles.srec>
+        <avrgcc.common.outputfiles.usersignatures>False</avrgcc.common.outputfiles.usersignatures>
+        <avrgcccpp.compiler.symbols.DefSymbols>
+          <ListValues>
+            <Value>DEBUG</Value>
+          </ListValues>
+        </avrgcccpp.compiler.symbols.DefSymbols>
+        <avrgcccpp.compiler.directories.IncludePaths>
+          <ListValues>
+            <Value>$(MSBuildProjectDirectory)\..\..\include</Value>
+            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
+          </ListValues>
+        </avrgcccpp.compiler.directories.IncludePaths>
+        <avrgcccpp.compiler.optimization.level>Optimize debugging experience (-Og)</avrgcccpp.compiler.optimization.level>
+        <avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>
+        <avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>
+        <avrgcccpp.compiler.warnings.AllWarnings>True</avrgcccpp.compiler.warnings.AllWarnings>
+        <avrgcccpp.compiler.miscellaneous.OtherFlags>-std=c++26 -Wextra -mrelax -fno-exceptions -fno-rtti -fno-threadsafe-statics -gdwarf-4</avrgcccpp.compiler.miscellaneous.OtherFlags>
+        <avrgcccpp.linker.optimization.GarbageCollectUnusedSections>True</avrgcccpp.linker.optimization.GarbageCollectUnusedSections>
+        <avrgcccpp.linker.miscellaneous.LinkerFlags>-mrelax</avrgcccpp.linker.miscellaneous.LinkerFlags>
+      </AvrGccCpp>
+    </ToolchainSettings>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="..\..\example\main.cpp">
+      <SubType>compile</SubType>
+      <Link>example\main.cpp</Link>
+    </Compile>
+    <Compile Include="..\..\include\ds3231\ds3231.hpp">
+      <SubType>compile</SubType>
+      <Link>include\ds3231\ds3231.hpp</Link>
+    </Compile>
+  </ItemGroup>
+  <ItemGroup>
+    <Folder Include="example" />
+    <Folder Include="include" />
+    <Folder Include="include\ds3231" />
+  </ItemGroup>
+  <Import Project="$(AVRSTUDIO_EXE_PATH)\Vs\Compiler.targets" />
+</Project>

ide/ds3231.atsln

@@ -0,0 +1,28 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Atmel Studio Solution File, Format Version 11.00
+VisualStudioVersion = 14.0.23107.0
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{E66E83B9-2572-4076-B26E-6BE79FF3018A}") = "ds3231-atmega328p", "atmega328p\ds3231-atmega328p.cppproj", "{7B3E5A41-9C26-4D18-8F52-6A0D31C74BE9}"
+EndProject
+Project("{E66E83B9-2572-4076-B26E-6BE79FF3018A}") = "ds3231-attiny85", "attiny85\ds3231-attiny85.cppproj", "{1D84C0F7-52B9-4A63-B7E1-9F2C48D5A306}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|AVR = Debug|AVR
+		Release|AVR = Release|AVR
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{7B3E5A41-9C26-4D18-8F52-6A0D31C74BE9}.Debug|AVR.ActiveCfg = Debug|AVR
+		{7B3E5A41-9C26-4D18-8F52-6A0D31C74BE9}.Debug|AVR.Build.0 = Debug|AVR
+		{7B3E5A41-9C26-4D18-8F52-6A0D31C74BE9}.Release|AVR.ActiveCfg = Release|AVR
+		{7B3E5A41-9C26-4D18-8F52-6A0D31C74BE9}.Release|AVR.Build.0 = Release|AVR
+		{1D84C0F7-52B9-4A63-B7E1-9F2C48D5A306}.Debug|AVR.ActiveCfg = Debug|AVR
+		{1D84C0F7-52B9-4A63-B7E1-9F2C48D5A306}.Debug|AVR.Build.0 = Debug|AVR
+		{1D84C0F7-52B9-4A63-B7E1-9F2C48D5A306}.Release|AVR.ActiveCfg = Release|AVR
+		{1D84C0F7-52B9-4A63-B7E1-9F2C48D5A306}.Release|AVR.Build.0 = Release|AVR
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+EndGlobal

include/ds3231/ds3231.hpp

@@ -0,0 +1,399 @@
+#pragma once
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <expected>
+#include <span>
+#include <utility>
+
+#include <libavr/i2c.hpp>
+
+namespace ds3231 {
+
+using avr::i2c::error;
+using avr::i2c::status;
+template <typename T>
+using result = std::expected<T, error>;
+
+struct date {
+	std::uint16_t year; // 2000..2099
+	std::uint8_t month; // 1..12
+	std::uint8_t day;   // 1..31 (weekday 1..7 in weekday-alarm reads)
+	friend constexpr bool operator==(const date &, const date &) = default;
+};
+
+struct time_of_day {
+	std::uint8_t hour; // 0..23
+	std::uint8_t minute;
+	std::uint8_t second;
+	friend constexpr bool operator==(const time_of_day &, const time_of_day &) = default;
+};
+
+struct date_time : date, time_of_day {
+	friend constexpr bool operator==(const date_time &, const date_time &) = default;
+};
+
+// Alarm match rates (datasheet Table 2). Alarm 2 has no seconds register
+// and fires at :00 of the matching minute.
+enum class alarm1_rate : std::uint8_t {
+	once_per_second = 0b01111,
+	seconds_match = 0b01110,
+	minutes_seconds_match = 0b01100,
+	time_match = 0b01000,
+	date_time_match = 0b00000,
+	weekday_time_match = 0b10000,
+};
+
+// Who owns the weekday register. The device counts 1..7 with a free epoch and
+// maintains nothing itself, so either this driver derives it from the date on
+// every write, or the register belongs to the program and no write here
+// touches it - which is what a caller that assigns its own meaning to those
+// seven values needs.
+enum class weekday_source : std::uint8_t { computed, external };
+
+// Whether arming an alarm also wires its INT/SQW output. `off` is not
+// silence about the bit - it clears A1IE/A2IE, so an alarm armed with the
+// interrupt on and re-armed with it off stops driving the pin.
+enum class alarm_interrupt : std::uint8_t { off, on };
+
+enum class alarm2_rate : std::uint8_t {
+	once_per_minute = 0b0111,
+	minutes_match = 0b0110,
+	time_match = 0b0100,
+	date_time_match = 0b0000,
+	weekday_time_match = 0b1000,
+};
+
+namespace detail {
+
+// The register map, datasheet 19-5170 Figure 1.
+inline constexpr std::uint8_t reg_seconds = 0x00, reg_day = 0x03, reg_date = 0x04;
+inline constexpr std::uint8_t reg_alarm1 = 0x07, reg_alarm2 = 0x0b;
+inline constexpr std::uint8_t reg_control = 0x0e, reg_status = 0x0f, reg_temp = 0x11;
+
+inline constexpr std::uint8_t alarm_mask = 0x80, day_of_week = 0x40;
+inline constexpr std::uint8_t twelve_hour = 0x40, pm = 0x20;
+inline constexpr std::uint8_t century = 0x80;
+inline constexpr std::uint8_t a1ie = 0x01, a2ie = 0x02, intcn = 0x04;
+inline constexpr std::uint8_t a1f = 0x01, a2f = 0x02, osf = 0x80;
+
+inline constexpr std::uint16_t first_year = 2000;
+
+constexpr std::uint8_t to_bcd(std::uint8_t value)
+{
+	return static_cast<std::uint8_t>(((value / 10) << 4) | (value % 10));
+}
+
+constexpr std::uint8_t from_bcd(std::uint8_t value)
+{
+	return static_cast<std::uint8_t>((value >> 4) * 10 + (value & 0x0f));
+}
+
+// Writes always use the 24-hour form; reads accept either.
+constexpr std::uint8_t hours_from_reg(std::uint8_t reg)
+{
+	if (reg & twelve_hour) {
+		const auto hour = from_bcd(reg & ~(alarm_mask | twelve_hour | pm));
+		const bool after_noon = reg & pm;
+		if (hour == 12) {
+			return after_noon ? 12 : 0;
+		}
+		return static_cast<std::uint8_t>(after_noon ? hour + 12 : hour);
+	}
+	return from_bcd(reg & ~(alarm_mask | twelve_hour));
+}
+
+// Sakamoto's method; the device counts weekdays 1..7 with a free epoch,
+// this maps Sunday to 1.
+constexpr std::uint8_t weekday(std::uint16_t year, std::uint8_t month, std::uint8_t day)
+{
+	static constexpr auto offsets = std::to_array<std::uint8_t>({0, 3, 2, 5, 0, 3, 5, 1, 4, 6, 2, 4});
+	if (month < 3) {
+		--year;
+	}
+	return static_cast<std::uint8_t>((year + year / 4 - year / 100 + year / 400 + offsets[month - 1] + day) % 7 + 1);
+}
+
+constexpr time_of_day time_from_registers(std::span<const std::uint8_t> raw)
+{
+	return {hours_from_reg(raw[2]), from_bcd(raw[1] & ~alarm_mask), from_bcd(raw[0] & ~alarm_mask)};
+}
+
+// Rate bit n is the mask bit of the alarm's n-th register and the bit above
+// them is DY/DT (Table 2). Alarm 2 has no seconds register, so its registers
+// are alarm 1's last three.
+inline constexpr std::size_t alarm1_registers = reg_alarm2 - reg_alarm1;
+inline constexpr std::size_t alarm2_registers = reg_control - reg_alarm2;
+
+template <std::size_t Count>
+constexpr std::array<std::uint8_t, Count> alarm_registers(const date_time &at, std::uint8_t rate)
+{
+	const bool weekday_mode = (rate >> Count) & 1;
+	const std::array<std::uint8_t, alarm1_registers> fields{
+	    to_bcd(at.second),
+	    to_bcd(at.minute),
+	    to_bcd(at.hour),
+	    weekday_mode ? static_cast<std::uint8_t>(day_of_week | at.day) : to_bcd(at.day),
+	};
+	return [&]<std::size_t... I>(std::index_sequence<I...>) {
+		return std::array{
+		    static_cast<std::uint8_t>(fields[alarm1_registers - Count + I] | (((rate >> I) & 1) ? alarm_mask : 0))...};
+	}(std::make_index_sequence<Count>{});
+}
+
+constexpr std::uint8_t control_with(std::uint8_t control, std::uint8_t enable_bit, alarm_interrupt interrupt)
+{
+	if (interrupt == alarm_interrupt::on) {
+		return static_cast<std::uint8_t>(control | intcn | enable_bit);
+	}
+	return static_cast<std::uint8_t>(control & ~enable_bit);
+}
+
+// A1F and A2F ignore a written 1, so writing the other one as 1 cannot lose it.
+constexpr std::uint8_t status_clearing(std::uint8_t status, std::uint8_t flag)
+{
+	return static_cast<std::uint8_t>((status | a1f | a2f) & ~flag);
+}
+
+} // namespace detail
+
+// The one bus address a DS3231 answers on - hardwired in the die, no
+// address pins (datasheet 19-5170, "I2C interface").
+inline constexpr std::uint8_t bus_address = 0x68;
+
+// Maxim DS3231 RTC on any libavr i2c bus: the master role is taken from the
+// bus's own resolution, so a declared `dev::i2c<...>` is handed over whole.
+// Every read is one bus transaction; errors surface as std::expected. Weekday
+// registers are derived from the date unless the program owns them.
+template <typename Bus, weekday_source Weekday = weekday_source::computed>
+class device {
+	static constexpr bool computes_weekday = Weekday == weekday_source::computed;
+
+	using dev = avr::i2c::device<typename Bus::master, bus_address>;
+
+  public:
+	[[nodiscard]] static result<date_time> read_clock()
+	{
+		std::array<std::uint8_t, 7> raw;
+		if (auto s = dev::read_regs(detail::reg_seconds, raw); !s) {
+			return std::unexpected(s.error());
+		}
+		date_time now;
+		static_cast<time_of_day &>(now) = detail::time_from_registers(raw);
+		now.day = detail::from_bcd(raw[4]);
+		now.month = detail::from_bcd(raw[5] & ~detail::century);
+		now.year = static_cast<std::uint16_t>(detail::first_year + detail::from_bcd(raw[6]));
+		return now;
+	}
+
+	[[nodiscard]] static result<date> read_date()
+	{
+		auto now = read_clock();
+		if (!now) {
+			return std::unexpected(now.error());
+		}
+		return static_cast<date>(*now);
+	}
+
+	[[nodiscard]] static result<time_of_day> read_time()
+	{
+		std::array<std::uint8_t, 3> raw;
+		if (auto s = dev::read_regs(detail::reg_seconds, raw); !s) {
+			return std::unexpected(s.error());
+		}
+		return detail::time_from_registers(raw);
+	}
+
+	[[nodiscard]] static status write_clock(const date_time &now)
+	{
+		if constexpr (computes_weekday) {
+			std::array raw{detail::to_bcd(now.second),
+			               detail::to_bcd(now.minute),
+			               detail::to_bcd(now.hour),
+			               detail::weekday(now.year, now.month, now.day),
+			               detail::to_bcd(now.day),
+			               detail::to_bcd(now.month),
+			               detail::to_bcd(static_cast<std::uint8_t>(now.year - detail::first_year))};
+			return dev::write_regs(detail::reg_seconds, raw);
+		} else {
+			// Two transactions, because the weekday register sits between the
+			// time and the date and this mode may not write it.
+			if (auto s = write_time(now); !s) {
+				return s;
+			}
+			return write_date(now);
+		}
+	}
+
+	[[nodiscard]] static status write_date(const date &value)
+	{
+		const auto year = detail::to_bcd(static_cast<std::uint8_t>(value.year - detail::first_year));
+		if constexpr (computes_weekday) {
+			std::array raw{detail::weekday(value.year, value.month, value.day), detail::to_bcd(value.day),
+			               detail::to_bcd(value.month), year};
+			return dev::write_regs(detail::reg_day, raw);
+		} else {
+			std::array raw{detail::to_bcd(value.day), detail::to_bcd(value.month), year};
+			return dev::write_regs(detail::reg_date, raw);
+		}
+	}
+
+	[[nodiscard]] static status write_time(const time_of_day &value)
+	{
+		std::array raw{detail::to_bcd(value.second), detail::to_bcd(value.minute), detail::to_bcd(value.hour)};
+		return dev::write_regs(detail::reg_seconds, raw);
+	}
+
+	// Alarm times use .day as the date of month, or as weekday 1..7 with
+	// the weekday_time_match rates.
+	[[nodiscard]] static status set_alarm1(const date_time &at, alarm1_rate rate,
+	                                       alarm_interrupt interrupt = alarm_interrupt::on)
+	{
+		return set_alarm<detail::alarm1_registers>(detail::reg_alarm1, at, std::to_underlying(rate), detail::a1ie,
+		                                           interrupt);
+	}
+
+	[[nodiscard]] static status set_alarm2(const date_time &at, alarm2_rate rate,
+	                                       alarm_interrupt interrupt = alarm_interrupt::on)
+	{
+		return set_alarm<detail::alarm2_registers>(detail::reg_alarm2, at, std::to_underlying(rate), detail::a2ie,
+		                                           interrupt);
+	}
+
+	[[nodiscard]] static result<date_time> read_alarm1()
+	{
+		return read_alarm<detail::alarm1_registers>(detail::reg_alarm1);
+	}
+
+	[[nodiscard]] static result<date_time> read_alarm2()
+	{
+		return read_alarm<detail::alarm2_registers>(detail::reg_alarm2);
+	}
+
+	[[nodiscard]] static result<bool> alarm1_fired()
+	{
+		return flag_set(detail::a1f);
+	}
+
+	[[nodiscard]] static result<bool> alarm2_fired()
+	{
+		return flag_set(detail::a2f);
+	}
+
+	[[nodiscard]] static status clear_alarm1()
+	{
+		return clear_flag(detail::a1f);
+	}
+
+	[[nodiscard]] static status clear_alarm2()
+	{
+		return clear_flag(detail::a2f);
+	}
+
+	// True after the oscillator was ever stopped (first power-up, battery
+	// ran out): the clock needs to be set.
+	[[nodiscard]] static result<bool> oscillator_stopped()
+	{
+		return flag_set(detail::osf);
+	}
+
+	[[nodiscard]] static status clear_oscillator_stopped()
+	{
+		return clear_flag(detail::osf);
+	}
+
+	// Die temperature in quarter C (updated every 64 s by the device).
+	[[nodiscard]] static result<std::int16_t> temperature_quarters()
+	{
+		std::array<std::uint8_t, 2> raw;
+		if (auto s = dev::read_regs(detail::reg_temp, raw); !s) {
+			return std::unexpected(s.error());
+		}
+		return static_cast<std::int16_t>((static_cast<std::int16_t>(static_cast<std::int8_t>(raw[0])) << 2) |
+		                                 (raw[1] >> 6));
+	}
+
+	// The alarms' INT/SQW wiring on its own, for a caller that arms once and
+	// mutes later. Alarm 1 and alarm 2 share INTCN, so muting one leaves the
+	// other's route intact.
+	[[nodiscard]] static status listen_alarm1()
+	{
+		return set_alarm_interrupt(detail::a1ie, alarm_interrupt::on);
+	}
+
+	[[nodiscard]] static status mute_alarm1()
+	{
+		return set_alarm_interrupt(detail::a1ie, alarm_interrupt::off);
+	}
+
+	[[nodiscard]] static status listen_alarm2()
+	{
+		return set_alarm_interrupt(detail::a2ie, alarm_interrupt::on);
+	}
+
+	[[nodiscard]] static status mute_alarm2()
+	{
+		return set_alarm_interrupt(detail::a2ie, alarm_interrupt::off);
+	}
+
+  private:
+	template <std::size_t Count>
+	static status set_alarm(std::uint8_t reg, const date_time &at, std::uint8_t rate, std::uint8_t enable_bit,
+	                        alarm_interrupt interrupt)
+	{
+		if (auto s = dev::write_regs(reg, detail::alarm_registers<Count>(at, rate)); !s) {
+			return s;
+		}
+		return set_alarm_interrupt(enable_bit, interrupt);
+	}
+
+	template <std::size_t Count>
+	static result<date_time> read_alarm(std::uint8_t reg)
+	{
+		std::array<std::uint8_t, Count> raw;
+		if (auto s = dev::read_regs(reg, raw); !s) {
+			return std::unexpected(s.error());
+		}
+		constexpr auto first = detail::alarm1_registers - Count;
+		date_time at{};
+		if constexpr (first == 0) {
+			at.second = detail::from_bcd(raw[0] & ~detail::alarm_mask);
+		}
+		at.minute = detail::from_bcd(raw[1 - first] & ~detail::alarm_mask);
+		at.hour = detail::hours_from_reg(raw[2 - first]);
+		at.day = detail::from_bcd(raw[3 - first] & ~(detail::alarm_mask | detail::day_of_week));
+		return at;
+	}
+
+	// INTCN routes the alarms to INT/SQW, so arming an alarm's interrupt takes
+	// the pin and muting it gives up only that alarm's claim on it.
+	static status set_alarm_interrupt(std::uint8_t enable_bit, alarm_interrupt interrupt)
+	{
+		auto control = dev::read_reg(detail::reg_control);
+		if (!control) {
+			return std::unexpected(control.error());
+		}
+		return dev::write_reg(detail::reg_control, detail::control_with(*control, enable_bit, interrupt));
+	}
+
+	static result<bool> flag_set(std::uint8_t bit)
+	{
+		auto flags = dev::read_reg(detail::reg_status);
+		if (!flags) {
+			return std::unexpected(flags.error());
+		}
+		return (*flags & bit) != 0;
+	}
+
+	static status clear_flag(std::uint8_t bit)
+	{
+		auto flags = dev::read_reg(detail::reg_status);
+		if (!flags) {
+			return std::unexpected(flags.error());
+		}
+		return dev::write_reg(detail::reg_status, detail::status_clearing(*flags, bit));
+	}
+};
+
+} // namespace ds3231

registers.hpp

@@ -1,413 +0,0 @@
-#pragma once
-
-#include <stdint.h>
-
-#include "alarms.hpp"
-#include "flags.hpp"
-
-namespace rtc {
-
-namespace detail {
-
-//////////////////////////////////////////////////////////////////////////
-
-template <uint8_t Mask = 0xFF>
-static inline uint8_t toBcd(const uint8_t &data)
-{
-	return ((data / 10 * 16) + (data % 10)) & Mask;
-}
-
-template <uint8_t Mask = 0xFF>
-static inline uint8_t fromBcd(const uint8_t &data)
-{
-	const auto maskedData = data & Mask;
-	return ((maskedData / 16 * 10) + (maskedData % 16));
-}
-
-static inline uint8_t convertTo24Hour(const uint8_t &hoursReg)
-{
-	constexpr auto FLAG_12_HOUR = 6;
-	constexpr auto FLAG_PM = 5;
-
-	const bool time12HourFormat = (hoursReg >> FLAG_12_HOUR) & 1;
-
-	if (time12HourFormat) {
-		const auto pmFlag = (hoursReg >> FLAG_PM) & 1;
-		constexpr auto HOUR_12_MASK = 0b00011111;
-		const auto hour12 = fromBcd<HOUR_12_MASK>(hoursReg);
-		if (hour12 == 12 && !pmFlag)
-			return 0;
-		return hour12 + pmFlag ? 12 : 0;
-	} else // 24 hour format
-	{
-		constexpr auto HOUR_MASK = 0b00111111;
-		return fromBcd<HOUR_MASK>(hoursReg);
-	}
-}
-
-template <uint8_t Mask = 0b01111111>
-static inline uint8_t getMaskedBcd(const uint8_t &reg)
-{
-	return fromBcd<Mask>(reg);
-}
-
-template <uint8_t Mask = 0b01111111>
-static inline void setMaskedBcd(uint8_t &reg, const uint8_t &value)
-{
-	reg &= ~Mask;
-	reg |= toBcd<Mask>(value);
-}
-
-static inline bool getEncodedDay(uint8_t &value, const uint8_t &reg)
-{
-	constexpr auto DAY_FLAG = 6;
-	if ((reg >> DAY_FLAG) & 1) {
-		constexpr auto DAY_MASK = 0b00001111;
-		value = reg & DAY_MASK;
-		return true;
-	}
-
-	return false;
-}
-
-static inline bool getEncodedDate(uint8_t &value, const uint8_t &reg)
-{
-	constexpr auto DAY_FLAG = 6;
-	if (!((reg >> DAY_FLAG) & 1)) {
-		value = getMaskedBcd<0b00111111>(reg);
-		return true;
-	}
-
-	return false;
-}
-
-static inline void setEncodedDay(uint8_t &reg, const uint8_t &value)
-{
-	constexpr auto DAY_MASK = 0b11110000;
-	reg &= DAY_MASK;
-	reg |= value & DAY_MASK;
-	constexpr auto DAY_FLAG = 6;
-	reg |= (1 << DAY_FLAG);
-}
-
-static inline void setEncodedDate(uint8_t &reg, const uint8_t &value)
-{
-	setMaskedBcd<0b00111111>(reg, value);
-	constexpr auto DAY_FLAG = 6;
-	reg &= ~(1 << DAY_FLAG);
-}
-
-//////////////////////////////////////////////////////////////////////////
-
-struct [[gnu::packed]] TimeReg
-{
-	uint8_t seconds = 0;
-	uint8_t minutes = 0;
-	uint8_t hours = 0;
-	uint8_t day = 1; // Range 1-7 according to datasheet
-	uint8_t date = 0;
-	uint8_t month_century = 0;
-	uint8_t year = 0;
-
-	//////////////////////////////////////////////////////////////////////////
-
-	inline uint8_t getSeconds() const
-	{
-		return getMaskedBcd(seconds);
-	}
-	inline uint8_t getMinutes() const
-	{
-		return getMaskedBcd(minutes);
-	}
-	inline uint8_t getHours() const
-	{
-		return convertTo24Hour(hours);
-	}
-	inline uint8_t getDay() const
-	{
-		return getMaskedBcd<0b00000111>(day);
-	}
-	inline uint8_t getDate() const
-	{
-		return getMaskedBcd<0b00111111>(date);
-	}
-	inline uint8_t getMonth() const
-	{
-		return getMaskedBcd<0b00011111>(month_century);
-	}
-	inline bool getCentury() const
-	{
-		constexpr auto CENTURY_FLAG = 7;
-		return (month_century >> CENTURY_FLAG) & 1;
-	}
-	inline uint16_t getYear() const
-	{
-		return 2000 + fromBcd(year);
-	}
-
-	//////////////////////////////////////////////////////////////////////////
-
-	inline void setSeconds(uint8_t seconds)
-	{
-		setMaskedBcd(this->seconds, seconds);
-	}
-	inline void setMinutes(uint8_t minutes)
-	{
-		setMaskedBcd(this->minutes, minutes);
-	}
-	inline void setHours(uint8_t hours)
-	{
-		setMaskedBcd(this->hours, hours);
-	}
-	inline void setDay(uint8_t day)
-	{
-		this->day = day & 0b111;
-	}
-	inline void setDate(uint8_t date)
-	{
-		setMaskedBcd<0b00111111>(this->date, date);
-	}
-	inline void setMonth(uint8_t month)
-	{
-		setMaskedBcd<0b00011111>(month_century, month);
-	}
-	inline void setCentury(bool century)
-	{
-		constexpr auto CENTURY_POS = 7;
-		month_century &= ~(1 << CENTURY_POS);
-		month_century |= (century << CENTURY_POS);
-	}
-	inline void setYear(uint16_t year)
-	{
-		year = year % 100;
-		this->year = toBcd(year);
-	}
-};
-
-static_assert(sizeof(TimeReg) == 7, "Invalid time register size");
-
-//////////////////////////////////////////////////////////////////////////
-
-struct [[gnu::packed]] Alarm1Reg
-{
-	uint8_t seconds = 0;
-	uint8_t minutes = 0;
-	uint8_t hours = 0;
-	uint8_t day_date = 0;
-
-	//////////////////////////////////////////////////////////////////////////
-
-	inline uint8_t getSeconds() const
-	{
-		return getMaskedBcd(seconds);
-	}
-	inline uint8_t getMinutes() const
-	{
-		return getMaskedBcd(minutes);
-	}
-	inline uint8_t getHours() const
-	{
-		return convertTo24Hour(hours);
-	}
-	inline bool getDay(uint8_t & day) const
-	{
-		return getEncodedDay(day, day_date);
-	}
-	inline bool getDate(uint8_t & date) const
-	{
-		return getEncodedDate(date, day_date);
-	}
-	inline Alarm1Rate getAlarmRate() const
-	{
-		constexpr auto M_FLAG = 7;
-		const auto m1 = (seconds >> M_FLAG) & 1;
-		const auto m2 = (minutes >> M_FLAG) & 1;
-		const auto m3 = (hours >> M_FLAG) & 1;
-		const auto m4 = (day_date >> M_FLAG) & 1;
-		const auto m = (m4 << 3) | (m3 << 2) | (m2 << 1) | (m1 << 0);
-		if (m == 0) {
-			constexpr auto DAY_FLAG = 6;
-			const auto dayFormat = ((day_date >> DAY_FLAG) & 1) << 4;
-			return static_cast<Alarm1Rate>(dayFormat);
-		}
-		return static_cast<Alarm1Rate>(m);
-	}
-
-	//////////////////////////////////////////////////////////////////////////
-
-	inline void setSeconds(uint8_t seconds)
-	{
-		setMaskedBcd(this->seconds, seconds);
-	}
-	inline void setMinutes(uint8_t minutes)
-	{
-		setMaskedBcd(this->minutes, minutes);
-	}
-	inline void setHours(uint8_t hours)
-	{
-		setMaskedBcd(this->hours, hours);
-	}
-	inline void setDay(uint8_t day)
-	{
-		setEncodedDay(day_date, day);
-	}
-	inline void setDate(uint8_t date)
-	{
-		setEncodedDate(day_date, date);
-	}
-	inline void setAlarmRate(const Alarm1Rate &alarmRate)
-	{
-		const auto alarmRateFlags = static_cast<uint8_t>(alarmRate);
-		constexpr auto M_FLAG = 7;
-		seconds &= ~(1 << M_FLAG);
-		seconds |= (alarmRateFlags & 1) << M_FLAG;
-		minutes &= ~(1 << M_FLAG);
-		minutes |= ((alarmRateFlags >> 1) & 1) << M_FLAG;
-		hours &= ~(1 << M_FLAG);
-		hours |= ((alarmRateFlags >> 2) & 1) << M_FLAG;
-		day_date &= ~(1 << M_FLAG);
-		day_date |= ((alarmRateFlags >> 3) & 1) << M_FLAG;
-	}
-};
-
-static_assert(sizeof(Alarm1Reg) == 4, "Invalid alarm1 register size");
-
-//////////////////////////////////////////////////////////////////////////
-
-struct [[gnu::packed]] Alarm2Reg
-{
-	uint8_t minutes = 0;
-	uint8_t hours = 0;
-	uint8_t day_date = 0;
-
-	//////////////////////////////////////////////////////////////////////////
-
-	inline uint8_t getMinutes() const
-	{
-		return getMaskedBcd(minutes);
-	}
-	inline uint8_t getHours() const
-	{
-		return convertTo24Hour(hours);
-	}
-	inline bool getDay(uint8_t & day) const
-	{
-		return getEncodedDay(day, day_date);
-	}
-	inline bool getDate(uint8_t & date) const
-	{
-		return getEncodedDate(date, day_date);
-	}
-	inline Alarm2Rate getAlarmRate() const
-	{
-		constexpr auto M_FLAG = 7;
-		const auto m2 = (minutes >> M_FLAG) & 1;
-		const auto m3 = (hours >> M_FLAG) & 1;
-		const auto m4 = (day_date >> M_FLAG) & 1;
-		const auto m = (m4 << 2) | (m3 << 1) | (m2 << 0);
-		if (m == 0) {
-			constexpr auto DAY_FLAG = 6;
-			const auto dayFormat = ((day_date >> DAY_FLAG) & 1) << 3;
-			return static_cast<Alarm2Rate>(dayFormat);
-		}
-		return static_cast<Alarm2Rate>(m);
-	}
-
-	//////////////////////////////////////////////////////////////////////////
-
-	inline void setMinutes(uint8_t minutes)
-	{
-		setMaskedBcd(this->minutes, minutes);
-	}
-	inline void setHours(uint8_t hours)
-	{
-		setMaskedBcd(this->hours, hours);
-	}
-	inline void setDay(uint8_t day)
-	{
-		setEncodedDay(day_date, day);
-	}
-	inline void setDate(uint8_t date)
-	{
-		setEncodedDate(day_date, date);
-	}
-	inline void setAlarmRate(const Alarm2Rate &alarmRate)
-	{
-		const auto alarmRateFlags = static_cast<uint8_t>(alarmRate);
-		constexpr auto M_FLAG = 7;
-		minutes &= ~(1 << M_FLAG);
-		minutes |= (alarmRateFlags & 1) << M_FLAG;
-		hours &= ~(1 << M_FLAG);
-		hours |= ((alarmRateFlags >> 1) & 1) << M_FLAG;
-		day_date &= ~(1 << M_FLAG);
-		day_date |= ((alarmRateFlags >> 2) & 1) << M_FLAG;
-	}
-};
-
-static_assert(sizeof(Alarm2Reg) == 3, "Invalid alarm2 register size");
-
-//////////////////////////////////////////////////////////////////////////
-
-enum class ControlRegFlags : uint8_t {
-	N_EOSC = 1 << 7,
-	BBSQW = 1 << 6,
-	CONV = 1 << 5,
-	RS2 = 1 << 4,
-	RS1 = 1 << 3,
-	INTCN = 1 << 2,
-	A2IE = 1 << 1,
-	A1IE = 1 << 0,
-};
-
-static inline uint8_t operator~(const ControlRegFlags &flag)
-{
-	return ~static_cast<uint8_t>(flag);
-}
-
-struct [[gnu::packed]] ControlReg : FlagsImpl<ControlRegFlags>{};
-
-static_assert(sizeof(ControlReg) == 1, "Invalid control register size");
-
-//////////////////////////////////////////////////////////////////////////
-
-enum class ControlStatusRegFlags : uint8_t {
-	OSF = 1 << 7,
-	EN32KHZ = 1 << 3,
-	BSY = 1 << 2,
-	A2F = 1 << 1,
-	A1F = 1 << 0,
-};
-
-static inline uint8_t operator~(const ControlStatusRegFlags &flag)
-{
-	return ~static_cast<uint8_t>(flag);
-}
-
-struct [[gnu::packed]] ControlStatusReg : FlagsImpl<ControlStatusRegFlags>{};
-
-static_assert(sizeof(ControlStatusReg) == 1, "Invalid control/status register size");
-
-//////////////////////////////////////////////////////////////////////////
-
-struct [[gnu::packed]] AgingOffsetReg
-{
-	uint8_t data = 0;
-};
-
-static_assert(sizeof(AgingOffsetReg) == 1, "Invalid aging offset register size");
-
-//////////////////////////////////////////////////////////////////////////
-
-struct [[gnu::packed]] TempReg
-{
-	uint8_t msb_temp = 0;
-	uint8_t lsb_temp = 0;
-};
-
-static_assert(sizeof(TempReg) == 2, "Invalid temperature register size");
-
-//////////////////////////////////////////////////////////////////////////
-
-} // namespace detail
-
-} // namespace rtc

test/CMakeLists.txt

@@ -0,0 +1,25 @@
+libavr_format_test()
+
+# The example's size is stated in the README, per chip, and a library advance
+# that moves it silently is what this catches.
+if(LIBAVR_MCU STREQUAL "atmega328p")
+	libavr_size_claim_test(clock 1462)
+elseif(LIBAVR_MCU STREQUAL "attiny85")
+	libavr_size_claim_test(clock 1256)
+endif()
+
+# The README says the two modes emit the same image, and only a tree with
+# both built can say whether they do.
+libavr_mode_identity_test(clock)
+
+# The battery is a compile: a static_assert that fails is the failure. It is a
+# target rather than only a ctest so a plain build catches a regression too.
+add_library(consteval_tests OBJECT consteval.cpp)
+target_link_libraries(consteval_tests PRIVATE ds3231)
+
+add_test(NAME ds3231.consteval
+         COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target consteval_tests)
+
+# A check this host cannot run reads as Skipped rather than Failed: the marker
+# a stubbed launcher prints, over every test registered here.
+libavr_skip_unverified()

test/consteval.cpp

@@ -0,0 +1,111 @@
+// Compile-only battery, built with the cross compiler so the target's 16-bit
+// int is exercised. Everything in this driver that is arithmetic rather than a
+// bus transaction lives here: the BCD both ways, the hours register's two
+// formats, Sakamoto's weekday, the alarm registers each rate writes, and the
+// control and status values written back.
+
+#include <array>
+#include <cstdint>
+
+#include <ds3231/ds3231.hpp>
+
+namespace {
+
+using ds3231::detail::from_bcd;
+using ds3231::detail::hours_from_reg;
+using ds3231::detail::to_bcd;
+
+// BCD is a round trip over every value the registers hold, and the encoding is
+// the datasheet's: tens in the high nibble, units in the low one.
+consteval bool bcd_round_trips()
+{
+	for (std::uint8_t value = 0; value < 100; ++value) {
+		const std::uint8_t packed = to_bcd(value);
+		if (from_bcd(packed) != value) {
+			return false;
+		}
+		if ((packed >> 4) != value / 10 || (packed & 0x0f) != value % 10) {
+			return false;
+		}
+	}
+	return true;
+}
+static_assert(bcd_round_trips());
+
+// The hours register (19-5170 Table 1): bit 6 selects 12-hour mode and bit 5
+// is then PM. Both noons and both midnights are the cases a naive decode gets
+// wrong - 12 AM is hour 0 and 12 PM is hour 12, neither of which is 12 + 12.
+static_assert(hours_from_reg(to_bcd(0)) == 0);   // 24-hour midnight
+static_assert(hours_from_reg(to_bcd(13)) == 13); // 24-hour afternoon
+static_assert(hours_from_reg(to_bcd(23)) == 23);
+static_assert(hours_from_reg(0x40 | to_bcd(12)) == 0);         // 12 AM
+static_assert(hours_from_reg(0x40 | 0x20 | to_bcd(12)) == 12); // 12 PM
+static_assert(hours_from_reg(0x40 | to_bcd(1)) == 1);          // 1 AM
+static_assert(hours_from_reg(0x40 | 0x20 | to_bcd(1)) == 13);  // 1 PM
+static_assert(hours_from_reg(0x40 | 0x20 | to_bcd(11)) == 23); // 11 PM
+
+// Sakamoto's method, against dates a calendar can be checked against rather
+// than against this implementation run twice. Sunday is 1.
+using ds3231::detail::weekday;
+static_assert(weekday(2000, 1, 1) == 7);  // Saturday
+static_assert(weekday(2024, 1, 1) == 2);  // Monday
+static_assert(weekday(2024, 2, 29) == 5); // Thursday, the leap day
+static_assert(weekday(2024, 3, 1) == 6);  // Friday, the day after it
+static_assert(weekday(2100, 3, 1) == 2);  // Monday - 2100 is not a leap year
+static_assert(weekday(2026, 8, 12) == 4); // Wednesday
+
+// The alarm registers each rate writes (19-5170 Table 2): bit 7 of the n-th
+// register is AxM(n+1), and DY/DT is bit 6 of the day register. Rows are read
+// off the table, so a slip in the rate values or in their distribution over
+// the registers arms the wrong alarm here first.
+using ds3231::alarm1_rate;
+using ds3231::alarm2_rate;
+using ds3231::detail::alarm_registers;
+constexpr ds3231::date_time at{{2026, 1, 15}, {12, 30, 45}};
+constexpr ds3231::date_time on_weekday{{2026, 1, 3}, {7, 5, 0}};
+
+template <typename Rate>
+constexpr auto alarm1(const ds3231::date_time &value, Rate rate)
+{
+	return alarm_registers<ds3231::detail::alarm1_registers>(value, static_cast<std::uint8_t>(rate));
+}
+
+template <typename Rate>
+constexpr auto alarm2(const ds3231::date_time &value, Rate rate)
+{
+	return alarm_registers<ds3231::detail::alarm2_registers>(value, static_cast<std::uint8_t>(rate));
+}
+
+static_assert(alarm1(at, alarm1_rate::once_per_second) == std::to_array<std::uint8_t>({0xc5, 0xb0, 0x92, 0x95}));
+static_assert(alarm1(at, alarm1_rate::seconds_match) == std::to_array<std::uint8_t>({0x45, 0xb0, 0x92, 0x95}));
+static_assert(alarm1(at, alarm1_rate::minutes_seconds_match) == std::to_array<std::uint8_t>({0x45, 0x30, 0x92, 0x95}));
+static_assert(alarm1(at, alarm1_rate::time_match) == std::to_array<std::uint8_t>({0x45, 0x30, 0x12, 0x95}));
+static_assert(alarm1(at, alarm1_rate::date_time_match) == std::to_array<std::uint8_t>({0x45, 0x30, 0x12, 0x15}));
+static_assert(alarm1(on_weekday, alarm1_rate::weekday_time_match) ==
+              std::to_array<std::uint8_t>({0x00, 0x05, 0x07, 0x43}));
+
+static_assert(alarm2(at, alarm2_rate::once_per_minute) == std::to_array<std::uint8_t>({0xb0, 0x92, 0x95}));
+static_assert(alarm2(at, alarm2_rate::minutes_match) == std::to_array<std::uint8_t>({0x30, 0x92, 0x95}));
+static_assert(alarm2(at, alarm2_rate::time_match) == std::to_array<std::uint8_t>({0x30, 0x12, 0x95}));
+static_assert(alarm2(at, alarm2_rate::date_time_match) == std::to_array<std::uint8_t>({0x30, 0x12, 0x15}));
+static_assert(alarm2(on_weekday, alarm2_rate::weekday_time_match) == std::to_array<std::uint8_t>({0x05, 0x07, 0x43}));
+
+// A1F and A2F ignore a written 1 and OSF holds until written 0 (19-5170,
+// Status Register): clearing one alarm must write the other as 1, or an alarm
+// firing between the read and the write is lost.
+using ds3231::detail::status_clearing;
+static_assert(status_clearing(0x00, 0x01) == 0x02); // A2F set after the read survives
+static_assert(status_clearing(0x03, 0x02) == 0x01);
+static_assert(status_clearing(0x88, 0x01) == 0x8a); // OSF and EN32kHz kept as read
+static_assert(status_clearing(0x80, 0x80) == 0x03);
+
+// BBSQW keeps INT/SQW driven on battery for the alarm interrupt as well as the
+// square wave (19-5170, Control Register and rev. 4), so arming an alarm must
+// leave it as found.
+using ds3231::alarm_interrupt;
+using ds3231::detail::control_with;
+static_assert(control_with(0x40, 0x01, alarm_interrupt::on) == 0x45);
+static_assert(control_with(0x00, 0x02, alarm_interrupt::on) == 0x06);
+static_assert(control_with(0x47, 0x01, alarm_interrupt::off) == 0x46);
+
+} // namespace

tools/check.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# The task gate: every configure preset built, and only then every one tested.
+#
+# The loop itself is libavr's (tools/check-presets.sh): the mode-identity
+# checks read the sibling mode's tree, so a build-then-test-per-preset run
+# would compare a fresh image against a stale sibling. Anything this repository
+# needs beyond the presets is written after the call, where every tree is built
+# and tested.
+set -euo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+"${LIBAVR_ROOT:-libavr}/tools/check-presets.sh" "$@"