Skip to content

Version 2.0.0: a namespace, Status and Result, the template's checks (OIL 3) - #6

Merged
theAndreas merged 2 commits into
mainfrom
v2
Nov 10, 2026
Merged

theAndreas merged 2 commits into
mainfrom
v2

Conversation

@theAndreas

Copy link
Copy Markdown
Owner

The third step of OIL.md: the API of version 2.0.0, as decided on 2026-11-10. It breaks every name on purpose, so that a sketch of version 1 fails to compile rather than behaving otherwise without notice; there are no aliases. The release itself, with its version number and the Library Manager, is OIL 4.

What changes for a sketch

  • Everything lies in the library's namespace and follows the naming of the template, as the other libraries do. The README has a table from each name of version 1 to its successor.
  • A call that can refuse says why, in a status of the library's own: whether it did what it was asked, the reason if not, and the reason in a few words for printing, kept in flash. It has no conversion to true or false, as the old return value had the trap of being true on an error. Reading the time returns the time and its status together. Dropping a status is a warning; the library offers a way to say that it is dropped on purpose.
  • The PWM no longer takes a pin, as there was only ever one.
  • Setting a period or a duty before the timer is set up is refused, and stopping a timer that does not run says so.
  • The first callback after a start comes after a period, not at once. The core's start-up code runs Timer2 before the sketch begins, which leaves the overflow flag set, and enabling the interrupt with it set called the callback immediately. This was in version 1 as well; it was found from the datasheet and the core's source, and is not checked on hardware.
  • The timer object is made when compiling, without code at start-up.

How it is built

The library drives an 8-bit timer whose registers are a parameter, as the coding style asks and as XmegaTimer does it; Timer2 is the one instance a sketch uses. A test makes a timer of its own, so the tests no longer need a process each. The last exceptions to the template's clang-tidy checks are gone: every check holds for the library now.

What was measured

  • make check passes from a clean build: 64 tests by GCC, by clang, under the sanitizers and with coverage, among them the tests of the clocks at 1, 16 and 20 MHz; lint, clang-tidy with every group, cppcheck, each header on its own for the host and the board, Doxygen, arduino-lint, the examples. Coverage of the library: 100 % of the lines.
  • The two tests of the overflow flag fail without its fix.
  • On the board, the timer object lies in zero-initialized memory, and the list of start-up constructors is empty.
  • Flash and RAM on the Uno: the basic example 1298 / 20 bytes, from 1372 / 26; the example that reads the time 3168 / 199, from 2894 / 211, as it now prints why a call was refused.
  • Not on hardware, and not in simavr, which does not model this timer mode (OIL 5).

🤖 Generated with Claude Code

theAndreas and others added 2 commits November 10, 2026 22:28
The API of OIL 3, a clean break without aliases for the old names:

- timer_two::Timer<Registers> drives an 8-bit Timer/Counter in phase correct PWM; its
  registers are a parameter (CodingStyle H-3). timer2.h hands in Timer/Counter2, and timer2,
  the one object a sketch uses, is made when compiling, without a constructor at run time
  (M-5); the overflow interrupt calls it.
- Google's names: Begin(), SetPeriod(), Start(), Stop(), Resume(), AttachInterrupt(),
  DetachInterrupt(), EnablePwm(), SetPwmDuty(), DisablePwm(), Read(), GetState(); constants
  are constexpr, StandardTypes.h is gone.
- A refusal is a Status of an enum class Error, Read() returns a Result, as MaxMatrix has
  them: no conversion to bool, the texts in flash. Stop() returns why it did nothing, and
  SetPeriod() and SetPwmDuty() are refused before Begin().
- The PWM takes no pin, as there is only pin 3.

One more bug, from the datasheet and the core's init(), which runs Timer2 before setup(): the
flag of an overflow stays set while the interrupt is off, so the first callback came at once
when Start() enabled it. It is cleared first now, also when a callback is attached to a
running timer.

The tests make a timer of their own each, on the mock's registers set back in SetUp(), and no
longer need a process each; the mock's counter can step on every n-th read, as a prescaler
makes the CPU read a value several times. Coverage of src/: 100 % of the lines.

src/.clang-tidy goes, and the exceptions in examples/.clang-tidy: every check of the template
holds for the library now.

Flash and RAM on the Uno: Basics 1298 / 20 bytes, from 1372 / 26; Read 3168 / 199, from
2894 / 211, as it prints why a call was refused now. The README says what changed for a
sketch, with a table from version 1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@theAndreas
theAndreas merged commit 10f9315 into main Nov 10, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant