Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 19 additions & 4 deletions OIL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,12 @@ Status: `open`, `in progress`, `done`, `dropped` (with the reason in the item).

| # | Item | Depends on | Status | PR |
|---|------|------------|--------|----|
| 1 | On the template embedded-cpp-template | – | in progress | #4 |
| 2 | The known bugs, each shown by a test first | 1 | in progress | #5 |
| 3 | Version 2.0.0: a namespace, constants for macros, the template's checks | 2 | in progress | #6 |
| 4 | Release 2.0.0 and the Library Manager | 3 | open | |
| 1 | On the template embedded-cpp-template | – | done | #4 |
| 2 | The known bugs, each shown by a test first | 1 | done | #5 |
| 3 | Version 2.0.0: a namespace, constants for macros, the template's checks | 2 | done | #6 |
| 4 | Release 2.0.0 and the Library Manager | 3 | in progress | #7 |
| 5 | SelfCheck in simavr | 1 | open | |
| 6 | Only the AVRs whose Timer2 has OC2B on pin 3 | 3 | open | |

### 1 On the template embedded-cpp-template

Expand Down Expand Up @@ -111,3 +112,17 @@ come out the same in two programs. Reported with a program that shows it in

`SIMAVR_MCU` in `tools/project.sh` stays empty, and this item waits for a simavr release that
models phase correct PWM as the chip does; the template's image would then need it too.

### 6 Only the AVRs whose Timer2 has OC2B on pin 3

`library.properties` names every AVR with `architectures=avr`, and nothing in `src/` asks which
one it is compiled for; `Timer2Registers::kPwmPin` is 3, where the ATmega328P has OC2B. Found
on 2026-11-11 while going through the README for 4:

- The ATmega2560 of the Mega has OC2B on pin 9: the PWM comes out there, while `EnablePwm()`
makes pin 3 an output.
- The ATmega32U4 of the Leonardo has no Timer/Counter2: a sketch fails to compile on a register
it does not name, rather than on why.

Either the library refuses those chips with an `#error` that says why, or it hands each its pin;
which is to be decided. The README then names the boards it runs on.
47 changes: 40 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ Arduino Uno and Nano: the Timer2 counterpart of the Arduino library

The timer runs in phase correct PWM: the period, in microseconds, sets the top and the
prescaler; the overflow at the bottom calls a function of the sketch; and pin 3 gives a PWM
whose frequency follows the period. This takes Timer2 from `analogWrite()` on pins 3 and 11 and
from `tone()`.
of the same period, 1 kHz at 1000 us. Only pin 3: pin 11 is the output of the register that
holds the top, so it has no duty of its own. This takes Timer2 from `analogWrite()` on pins 3
and 11 and from `tone()`.

```cpp
#include <TimerTwo.h>
Expand All @@ -28,13 +29,26 @@ void loop() {}
This is [examples/Basics](examples/Basics/Basics.ino). [examples/Read](examples/Read/Read.ino)
checks each call and reads the time.

## Installation

In the Arduino IDE, the Library Manager finds TimerTwo by its name; with arduino-cli, it is
`arduino-cli lib install TimerTwo`. Each release on GitHub also carries the library as a .zip,
for *Sketch > Include Library > Add .ZIP Library*.

## API

Everything lies in the namespace `timer_two`; `timer2` is the timer. A call that can refuse
returns a `Status`, and changes nothing when it refuses: `IsOk()` says whether it did what it
was asked, `GetError()` why not, and `GetErrorText()` the same in a few words for
`Serial.print()`. A `Status` must not be dropped: where a sketch does not care, `Discard()` says
so. `Read()` returns a `Result`, the time or why there is none.
so. `Read()` returns a `Result`, the time or why there is none:

```cpp
timer_two::Result<timer_two::TimeType> const elapsed{timer_two::timer2.Read()};
if (elapsed.IsOk()) {
Serial.println(elapsed.GetValue()); // microseconds
}
```

| Call | What it does | Refuses with |
|---|---|---|
Expand All @@ -55,10 +69,27 @@ The callback runs in the interrupt: it should do little, as setting a flag that
and what it shares with `loop()` is `volatile`. Below 8 MHz the times are `uint32_t`, as the
longest period does not fit 16 bits; from 8 MHz they are `uint16_t`. Both are `TimeType`.

A period is met to a step of the counter, and never exceeded: one that is no whole number of
steps comes out short by less than a step. A step is up and down once, two cycles of the
prescaled clock; at 16 MHz an eighth of a microsecond below 32 us, 4 us at 1000 us, and 128 us
from 8192 us on.

## Flash and RAM

What the examples take on the Uno, as the last build measured it:

<!-- sizes -->
| Example | Flash, default | RAM, default |
|---|---|---|
| Basics | 1298 | 20 |
| Read | 3168 | 199 |
<!-- /sizes -->

## From version 1

Version 2.0.0 breaks every name, on purpose: a sketch of version 1 does not compile until it is
changed, rather than behaving otherwise without notice. There are no aliases for the old names.
Version 1 is the code before 2.0.0, which had no version number of its own. Version 2.0.0
breaks every name, on purpose: a sketch of version 1 does not compile until it is changed,
rather than behaving otherwise without notice. There are no aliases for the old names.

| Version 1 | Version 2.0.0 |
|---|---|
Expand Down Expand Up @@ -91,8 +122,10 @@ What also changed:

TimerTwo is built and checked as the projects made from
[embedded-cpp-template](https://github.com/theAndreas/embedded-cpp-template) are: `make` lists
every build and check, `make check` is what CI runs. [OIL.md](https://github.com/theAndreas/TimerTwo/blob/main/OIL.md) is what is planned, and
[AGENTS.md](https://github.com/theAndreas/TimerTwo/blob/main/AGENTS.md) what a contributor has to know.
every build and check, `make check` is what CI runs.
[OIL.md](https://github.com/theAndreas/TimerTwo/blob/main/OIL.md) is what is planned, and
[AGENTS.md](https://github.com/theAndreas/TimerTwo/blob/main/AGENTS.md) what a contributor has
to know.

## Licence

Expand Down
2 changes: 1 addition & 1 deletion library.properties
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name=TimerTwo
version=0.1.0
version=2.0.0
author=Andreas Burnickl
maintainer=Andreas Burnickl
sentence=Periodic interrupt, PWM and time readout on Timer2 of the ATmega328P.
Expand Down
Loading