deps: the pin advances to the identity check that reads its own sibling

libavr 93d8b0e. The check is handed the sibling build tree now and asks its build system whether the image is current, so a comparison against a tree the run did not build skips rather than passing. Gated at the pin. Its own gate builds both modes, so the comparison still happens.

Co-Authored-By: Claude Opus 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,8 +1,11 @@
-*.h         eol=lf
+# Line endings are the repository's, not the editing machine's: this checkout
-*.hpp       eol=lf
+# is reached from two hosts, and a file rewritten by a Windows tool comes back
-*.c         eol=lf
+# with every line changed unless something says otherwise. Naming the source
-*.cpp       eol=lf
+# extensions left Markdown, Python, shell and CMake to whatever the writing
-.git*       eol=lf
+# tool defaulted to, which is CRLF on one of the two.
+* text=auto eol=lf
+
+# Atmel Studio writes these and expects them back.
 *.vcxproj*  eol=crlf
 *.cppproj   eol=crlf
 *.sln       eol=crlf

.gitignore

@@ -1,4 +1,5 @@
 build/
+local/
 .cache/
 
 # Atmel Studio: generated per machine, its build outputs, and per-user state

.vscode/extensions.json

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

.vscode/settings.json

@@ -0,0 +1,36 @@
+{
+	// 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.
+	"clangd.arguments": [
+		"--compile-commands-dir=${workspaceFolder}/build/atmega328p-generated",
+		"--query-driver=**avr-g++*",
+		"--header-insertion=never"
+	],
+
+	// 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**: a committed file may not name a path that is true of one
+	// machine (libavr guidance rule 50), so the gitignored local/machine.cmake
+	// at this repository's root is where a checkout says where its toolchain
+	// is - one file, and it answers for both hosts.
+	"cmake.useCMakePresets": "always",
+	"cmake.configureOnOpen": true,
+	"cmake.options.statusBarVisibility": "compact",
+
+	"files.watcherExclude": {
+		"**/build/**": true,
+		"**/libavr/**": true
+	},
+
+	"files.associations": {
+		".clangd": "yaml",
+		".clang-format": "yaml"
+	}
+}

CMakeLists.txt

@@ -12,7 +12,7 @@ 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")
+	message(FATAL_ERROR "libavr not found at ${LIBAVR_ROOT} - run: git submodule update --init libavr")
 endif()
 add_subdirectory(${LIBAVR_ROOT} libavr-build)
 
@@ -20,6 +20,10 @@ 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()

README.md

@@ -11,7 +11,7 @@ using bus = dev::i2c<{.frequency = 100_kHz}>;
 using rtc = ds3231::device<bus>;
 
 auto now = rtc::read_clock();       // result<date_time>
-(void)rtc::set_alarm1({}, ds3231::alarm1_rate::once_per_second);
+auto armed = rtc::set_alarm1({}, ds3231::alarm1_rate::once_per_second);
 ```
 
 `example/main.cpp` is the full tour. libavr rides as the `libavr/` submodule,
@@ -25,15 +25,36 @@ cmake --build --preset attiny85-generated
 ```
 
 Presets cover attiny85/atmega328p in both libavr modes (generated and
-reflect). The legacy yazoalfa-based driver lives on the `master` branch.
+reflect); `ctest` runs the consteval battery over the BCD, the hours
+register's two formats, the weekday and the alarm rate encodings, and holds
+the example to its stated size — **1480 B** on the mega328P and **1270 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 — 1242 B on the ATmega328P,
+**byte-identical `.text`** against the CMake build (`check-flags.py` below is
-1212 B on the ATtiny85 — with the flags mirrored by hand. CMake remains the
+what holds the flag sets equal, so the sizes are the presets' own), with the
-build system.
+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

example/main.cpp

@@ -5,7 +5,7 @@ using namespace avr::literals;
 
 // One source for the tiny85 (open-drain software I2C on the USI pins) and
 // the mega328P (TWI hardware). On first power-up the clock is seeded and
-// alarm 1 armed; then the LED mirrors the seconds parity — a stuck LED
+// alarm 1 armed; then the LED mirrors the seconds parity - a stuck LED
 // means bus errors.
 using dev = avr::device<{.clock = 8_MHz}>;
 using bus = dev::i2c<{.frequency = 100_kHz}>;
@@ -17,16 +17,21 @@ int main()
 	avr::init<bus, led>();
 
 	if (auto stopped = rtc::oscillator_stopped(); stopped.value_or(false)) {
-		(void)rtc::write_clock({{2026, 1, 1}, {12, 0, 0}});
+		// A failed seed leaves the LED dark before the loop ever runs - the
-		(void)rtc::set_alarm1({}, ds3231::alarm1_rate::once_per_second);
+		// same signal a stuck bus gives it below.
-		(void)rtc::clear_oscillator_stopped();
+		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())
+		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))
+		}
-			(void)rtc::clear_alarm1();
+		if (auto fired = rtc::alarm1_fired(); fired.value_or(false) && !rtc::clear_alarm1()) {
+			led::clear(); // a clear that failed holds the LED dark, like any bus error
+		}
 		dev::delay<100_ms>();
 	}
 }

include/ds3231/ds3231.hpp

@@ -3,6 +3,7 @@
 #include <array>
 #include <cstdint>
 #include <expected>
+#include <span>
 
 #include <libavr/i2c.hpp>
 
@@ -42,6 +43,18 @@ enum class alarm1_rate : std::uint8_t {
 	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,
@@ -69,8 +82,9 @@ constexpr std::uint8_t hours_from_reg(std::uint8_t reg)
 	if (reg & 0x40) {
 		auto hour = from_bcd(reg & 0x1f);
 		bool pm = reg & 0x20;
-		if (hour == 12)
+		if (hour == 12) {
 			return pm ? 12 : 0;
+		}
 		return static_cast<std::uint8_t>(pm ? hour + 12 : hour);
 	}
 	return from_bcd(reg & 0x3f);
@@ -80,21 +94,29 @@ constexpr std::uint8_t hours_from_reg(std::uint8_t reg)
 // this maps Sunday to 1.
 constexpr std::uint8_t weekday(std::uint16_t year, std::uint8_t month, std::uint8_t day)
 {
-	constexpr std::uint8_t offsets[]{0, 3, 2, 5, 0, 3, 5, 1, 4, 6, 2, 4};
+	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)
+	if (month < 3) {
 		--year;
+	}
 	return static_cast<std::uint8_t>((year + year / 4 - year / 100 + year / 400 + offsets[month - 1] + day) % 7 + 1);
 }
 
 } // namespace detail
 
-// Maxim DS3231 RTC on any libavr i2c master (register map: datasheet
+// The one bus address a DS3231 answers on - hardwired in the die, no
-// 19-5170 Table 1). Every call is one bus transaction; errors surface as
+// address pins (datasheet 19-5170, "I2C interface").
-// std::expected. Weekday registers maintain themselves from the date when
+inline constexpr std::uint8_t bus_address = 0x68;
-// SetWeekday is on.
+
-template <typename Bus, bool SetWeekday = true>
+// Maxim DS3231 RTC on any libavr i2c bus (register map: datasheet
+// 19-5170 Table 1): the master role is taken from the bus's own
+// resolution, so a declared `dev::i2c<...>` is handed over whole. Every
+// call 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 {
-	using dev = avr::i2c::device<Bus, 0x68>;
+	static constexpr bool computes_weekday = Weekday == weekday_source::computed;
+
+	using dev = avr::i2c::device<typename Bus::master, bus_address>;
 
 	static constexpr std::uint8_t reg_clock = 0x00;
 	static constexpr std::uint8_t reg_alarm1 = 0x07;
@@ -110,12 +132,11 @@ class device {
 	[[nodiscard]] static result<date_time> read_clock()
 	{
 		std::array<std::uint8_t, 7> raw;
-		if (auto s = dev::read_regs(reg_clock, raw); !s)
+		if (auto s = dev::read_regs(reg_clock, raw); !s) {
 			return std::unexpected(s.error());
+		}
 		date_time now;
-		now.second = detail::from_bcd(raw[0] & 0x7f);
+		static_cast<time_of_day &>(now) = decode_time(raw);
-		now.minute = detail::from_bcd(raw[1] & 0x7f);
-		now.hour = detail::hours_from_reg(raw[2]);
 		now.day = detail::from_bcd(raw[4] & 0x3f);
 		now.month = detail::from_bcd(raw[5] & 0x1f);
 		now.year = static_cast<std::uint16_t>(2000 + detail::from_bcd(raw[6]));
@@ -125,87 +146,98 @@ class device {
 	[[nodiscard]] static result<date> read_date()
 	{
 		auto now = read_clock();
-		if (!now)
+		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(reg_clock, raw); !s)
+		if (auto s = dev::read_regs(reg_clock, raw); !s) {
 			return std::unexpected(s.error());
-		return time_of_day{detail::hours_from_reg(raw[2]), detail::from_bcd(raw[1] & 0x7f),
+		}
-		                   detail::from_bcd(raw[0] & 0x7f)};
+		return decode_time(raw);
 	}
 
 	[[nodiscard]] static status write_clock(const date_time &now)
 	{
-		std::array<std::uint8_t, 7> raw{detail::to_bcd(now.second),
+		if constexpr (!computes_weekday) {
-		                                detail::to_bcd(now.minute),
+			// Two transactions, because the weekday register sits between the
-		                                detail::to_bcd(now.hour),
+			// time and the date and this mode may not write it.
-		                                SetWeekday ? detail::weekday(now.year, now.month, now.day) : std::uint8_t{1},
+			if (auto s = write_time(now); !s) {
-		                                detail::to_bcd(now.day),
+				return s;
-		                                detail::to_bcd(now.month),
+			}
-		                                detail::to_bcd(static_cast<std::uint8_t>(now.year % 100))};
+			return write_date(now);
-		return dev::write_regs(reg_clock, raw);
+		} else {
+			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 % 100))};
+			return dev::write_regs(reg_clock, raw);
+		}
 	}
 
 	[[nodiscard]] static status write_date(const date &value)
 	{
-		if constexpr (SetWeekday) {
+		if constexpr (computes_weekday) {
-			std::array<std::uint8_t, 4> raw{detail::weekday(value.year, value.month, value.day),
+			std::array raw{detail::weekday(value.year, value.month, value.day), detail::to_bcd(value.day),
-			                                detail::to_bcd(value.day), detail::to_bcd(value.month),
+			               detail::to_bcd(value.month), detail::to_bcd(static_cast<std::uint8_t>(value.year % 100))};
-			                                detail::to_bcd(static_cast<std::uint8_t>(value.year % 100))};
 			return dev::write_regs(reg_clock + 3, raw);
 		} else {
-			std::array<std::uint8_t, 3> raw{detail::to_bcd(value.day), detail::to_bcd(value.month),
+			std::array raw{detail::to_bcd(value.day), detail::to_bcd(value.month),
-			                                detail::to_bcd(static_cast<std::uint8_t>(value.year % 100))};
+			               detail::to_bcd(static_cast<std::uint8_t>(value.year % 100))};
 			return dev::write_regs(reg_clock + 4, raw);
 		}
 	}
 
 	[[nodiscard]] static status write_time(const time_of_day &value)
 	{
-		std::array<std::uint8_t, 3> raw{detail::to_bcd(value.second), detail::to_bcd(value.minute),
+		std::array raw{detail::to_bcd(value.second), detail::to_bcd(value.minute), detail::to_bcd(value.hour)};
-		                                detail::to_bcd(value.hour)};
 		return dev::write_regs(reg_clock, 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, bool enable_interrupt = true)
+	[[nodiscard]] static status set_alarm1(const date_time &at, alarm1_rate rate,
+	                                       alarm_interrupt interrupt = alarm_interrupt::on)
 	{
 		auto m = static_cast<std::uint8_t>(rate);
-		std::array<std::uint8_t, 4> raw{
+		std::array raw{static_cast<std::uint8_t>(detail::to_bcd(at.second) | ((m & 1) << 7)),
-		    static_cast<std::uint8_t>(detail::to_bcd(at.second) | ((m & 1) << 7)),
+		               static_cast<std::uint8_t>(detail::to_bcd(at.minute) | (((m >> 1) & 1) << 7)),
-		    static_cast<std::uint8_t>(detail::to_bcd(at.minute) | (((m >> 1) & 1) << 7)),
+		               static_cast<std::uint8_t>(detail::to_bcd(at.hour) | (((m >> 2) & 1) << 7)),
-		    static_cast<std::uint8_t>(detail::to_bcd(at.hour) | (((m >> 2) & 1) << 7)),
+		               static_cast<std::uint8_t>(day_date(at.day, rate == alarm1_rate::weekday_time_match) |
-		    static_cast<std::uint8_t>(day_date(at.day, rate == alarm1_rate::weekday_time_match) |
+		                                         (((m >> 3) & 1) << 7))};
-		                              (((m >> 3) & 1) << 7))};
+		if (auto s = dev::write_regs(reg_alarm1, raw); !s) {
-		if (auto s = dev::write_regs(reg_alarm1, raw); !s)
 			return s;
-		return enable_interrupt ? enable_alarm_interrupt(a1ie) : status{};
+		}
+		return set_alarm_interrupt(a1ie, interrupt);
 	}
 
-	[[nodiscard]] static status set_alarm2(const date_time &at, alarm2_rate rate, bool enable_interrupt = true)
+	[[nodiscard]] static status set_alarm2(const date_time &at, alarm2_rate rate,
+	                                       alarm_interrupt interrupt = alarm_interrupt::on)
 	{
 		auto m = static_cast<std::uint8_t>(rate);
-		std::array<std::uint8_t, 3> raw{
+		std::array raw{static_cast<std::uint8_t>(detail::to_bcd(at.minute) | ((m & 1) << 7)),
-		    static_cast<std::uint8_t>(detail::to_bcd(at.minute) | ((m & 1) << 7)),
+		               static_cast<std::uint8_t>(detail::to_bcd(at.hour) | (((m >> 1) & 1) << 7)),
-		    static_cast<std::uint8_t>(detail::to_bcd(at.hour) | (((m >> 1) & 1) << 7)),
+		               static_cast<std::uint8_t>(day_date(at.day, rate == alarm2_rate::weekday_time_match) |
-		    static_cast<std::uint8_t>(day_date(at.day, rate == alarm2_rate::weekday_time_match) |
+		                                         (((m >> 2) & 1) << 7))};
-		                              (((m >> 2) & 1) << 7))};
+		if (auto s = dev::write_regs(reg_alarm2, raw); !s) {
-		if (auto s = dev::write_regs(reg_alarm2, raw); !s)
 			return s;
-		return enable_interrupt ? enable_alarm_interrupt(a2ie) : status{};
+		}
+		return set_alarm_interrupt(a2ie, interrupt);
 	}
 
 	[[nodiscard]] static result<date_time> read_alarm1()
 	{
 		std::array<std::uint8_t, 4> raw;
-		if (auto s = dev::read_regs(reg_alarm1, raw); !s)
+		if (auto s = dev::read_regs(reg_alarm1, raw); !s) {
 			return std::unexpected(s.error());
+		}
 		date_time at{};
 		at.second = detail::from_bcd(raw[0] & 0x7f);
 		at.minute = detail::from_bcd(raw[1] & 0x7f);
@@ -217,8 +249,9 @@ class device {
 	[[nodiscard]] static result<date_time> read_alarm2()
 	{
 		std::array<std::uint8_t, 3> raw;
-		if (auto s = dev::read_regs(reg_alarm2, raw); !s)
+		if (auto s = dev::read_regs(reg_alarm2, raw); !s) {
 			return std::unexpected(s.error());
+		}
 		date_time at{};
 		at.minute = detail::from_bcd(raw[0] & 0x7f);
 		at.hour = detail::hours_from_reg(raw[1] & 0x7f);
@@ -258,45 +291,83 @@ class device {
 		return clear_flag(osf);
 	}
 
-	// Die temperature in quarter °C (updated every 64 s by the device).
+	// 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(reg_temp, raw); !s)
+		if (auto s = dev::read_regs(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(a1ie, alarm_interrupt::on);
+	}
+	[[nodiscard]] static status mute_alarm1()
+	{
+		return set_alarm_interrupt(a1ie, alarm_interrupt::off);
+	}
+	[[nodiscard]] static status listen_alarm2()
+	{
+		return set_alarm_interrupt(a2ie, alarm_interrupt::on);
+	}
+	[[nodiscard]] static status mute_alarm2()
+	{
+		return set_alarm_interrupt(a2ie, alarm_interrupt::off);
+	}
+
   private:
+	// Seconds, minutes and hours decode the same way wherever they are read
+	// from - the high bit of the first two is reserved, and the hours register
+	// carries its own 12/24-hour flag.
+	static constexpr time_of_day decode_time(std::span<const std::uint8_t> clock)
+	{
+		return {detail::hours_from_reg(clock[2]), detail::from_bcd(clock[1] & 0x7f), detail::from_bcd(clock[0] & 0x7f)};
+	}
+
 	static constexpr std::uint8_t day_date(std::uint8_t day, bool weekday_mode)
 	{
-		if (weekday_mode)
+		if (weekday_mode) {
 			return static_cast<std::uint8_t>(0x40 | (day & 0x0f));
+		}
 		return detail::to_bcd(day) & std::uint8_t{0x3f};
 	}
 
-	static status enable_alarm_interrupt(std::uint8_t enable_bit)
+	// INTCN routes the alarms to INT/SQW and BBSQW is the square wave that
+	// would otherwise drive it, 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(reg_control);
-		if (!control)
+		if (!control) {
 			return std::unexpected(control.error());
-		return dev::write_reg(reg_control, static_cast<std::uint8_t>((*control & ~bbsqw) | intcn | enable_bit));
+		}
+		const auto wired = static_cast<std::uint8_t>((*control & ~bbsqw) | intcn | enable_bit);
+		const auto muted = static_cast<std::uint8_t>(*control & ~enable_bit);
+		return dev::write_reg(reg_control, interrupt == alarm_interrupt::on ? wired : muted);
 	}
 
 	static result<bool> flag_set(std::uint8_t bit)
 	{
 		auto flags = dev::read_reg(reg_status);
-		if (!flags)
+		if (!flags) {
 			return std::unexpected(flags.error());
+		}
 		return (*flags & bit) != 0;
 	}
 
 	static status clear_flag(std::uint8_t bit)
 	{
 		auto flags = dev::read_reg(reg_status);
-		if (!flags)
+		if (!flags) {
 			return std::unexpected(flags.error());
+		}
 		return dev::write_reg(reg_status, static_cast<std::uint8_t>(*flags & ~bit));
 	}
 };

test/CMakeLists.txt

@@ -0,0 +1,27 @@
+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 1480)
+elseif(LIBAVR_MCU STREQUAL "attiny85")
+	libavr_size_claim_test(clock 1270)
+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. Nothing in this
+# suite is host-gated today, and this is what keeps that a property of the
+# suite rather than of whoever adds the next check.
+libavr_skip_unverified()

test/consteval.cpp

@@ -0,0 +1,82 @@
+// 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, and the alarm rate encodings as the datasheet
+// tabulates them.
+
+#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 rate encodings (19-5170 Table 2), transcribed: the low bits are
+// A1M4..A1M1 in register order and the high one is DY/DT. A rate is the mask
+// pattern its row names, and a transcription slip here arms the wrong alarm.
+using ds3231::alarm1_rate;
+static_assert(static_cast<std::uint8_t>(alarm1_rate::once_per_second) == 0b01111);
+static_assert(static_cast<std::uint8_t>(alarm1_rate::seconds_match) == 0b01110);
+static_assert(static_cast<std::uint8_t>(alarm1_rate::minutes_seconds_match) == 0b01100);
+static_assert(static_cast<std::uint8_t>(alarm1_rate::time_match) == 0b01000);
+static_assert(static_cast<std::uint8_t>(alarm1_rate::date_time_match) == 0b00000);
+static_assert(static_cast<std::uint8_t>(alarm1_rate::weekday_time_match) == 0b10000);
+
+using ds3231::alarm2_rate;
+static_assert(static_cast<std::uint8_t>(alarm2_rate::once_per_minute) == 0b0111);
+static_assert(static_cast<std::uint8_t>(alarm2_rate::minutes_match) == 0b0110);
+static_assert(static_cast<std::uint8_t>(alarm2_rate::time_match) == 0b0100);
+static_assert(static_cast<std::uint8_t>(alarm2_rate::date_time_match) == 0b0000);
+static_assert(static_cast<std::uint8_t>(alarm2_rate::weekday_time_match) == 0b1000);
+
+// Alarm 2 has no seconds register, so its mask bits are one place lower than
+// alarm 1's throughout - the property that makes one distribution loop wrong
+// for the other.
+static_assert(static_cast<std::uint8_t>(alarm2_rate::once_per_minute) ==
+              static_cast<std::uint8_t>(alarm1_rate::once_per_second) >> 1);
+static_assert(static_cast<std::uint8_t>(alarm2_rate::weekday_time_match) ==
+              static_cast<std::uint8_t>(alarm1_rate::weekday_time_match) >> 1);
+
+} // 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) because the order in it
+# is subtle and was got wrong by hand more than once - the mode-identity checks
+# read the sibling mode's tree, so a build-then-test-per-preset run compares 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" "$@"