tiny_led_matrix/
timer.rs

1//! The interface that [`Display`] needs to work with a timer.
2//!
3//! [`Display`]: crate::display::Display
4
5
6/// The interface that [`Display`] needs to work with a timer.
7///
8/// The timer should count _ticks_ of a fixed size.
9///
10/// It should reset itself after the number of ticks passed to
11/// `initialise_cycle()` have elapsed (the _primary cycle_), and signal an
12/// interrupt.
13///
14/// It should also provide a _secondary alarm_ which can be programmed to
15/// signal an interrupt at a specified point during the primary cycle.
16///
17/// If you provide a 'no-op' implementation of the secondary-alarm features,
18/// the effect will be a display which treats brightness level 9 as on and all
19/// other levels as off.
20///
21/// # Choosing the tick length
22///
23/// The cycle length is in fact always 375 ticks, so the display will be fully
24/// refreshed after `MATRIX_ROWS`×375 ticks. Aiming for around 60 refreshes
25/// per second is common.
26///
27/// For example, if there are three matrix rows you might use a tick period of
28/// 16µs. Then the display will be refreshed every 18ms, or about 55 times a
29/// second (this is the refresh rate used for the [micro:bit runtime][dal] and
30/// the [micro:bit MicroPython port][micropython]).
31///
32///
33/// [dal]: https://lancaster-university.github.io/microbit-docs/
34/// [micropython]: https://microbit-micropython.readthedocs.io/
35/// [`Display`]: crate::display::Display
36
37pub trait DisplayTimer {
38
39    /// Initialises the timer.
40    ///
41    /// This is intended to be called once, before using the display.
42    ///
43    /// The `ticks` parameter is the number of ticks in the primary cycle.
44    ///
45    /// Leaves the secondary alarm disabled.
46    fn initialise_cycle(&mut self, ticks: u16);
47
48    /// Enables the secondary alarm.
49    ///
50    /// After this is called, an interrupt should be generated each time the
51    /// tick last passed to [`program_secondary()`]is reached.
52    ///
53    /// [`program_secondary()`]: DisplayTimer::program_secondary
54    fn enable_secondary(&mut self);
55
56    /// Disables the secondary alarm.
57    ///
58    /// After this is called, no more interrupts should be generated from the
59    /// secondary alarm until it is enabled again.
60    fn disable_secondary(&mut self);
61
62    /// Specifies the tick to use for the secondary alarm.
63    ///
64    /// Note that `ticks` represents the time after the start of the primary
65    /// cycle (not the time after the previous secondary signal).
66    fn program_secondary(&mut self, ticks: u16);
67
68    /// Checks whether a new primary cycle has begun since the last call to
69    /// this method.
70    fn check_primary(&mut self) -> bool;
71
72    /// Checks whether the secondary alarm has signalled an interrupt since
73    /// the last call to this method.
74    fn check_secondary(&mut self) -> bool;
75
76}
77