Crate embedded_time

embedded-time provides a comprehensive library for implementing Clock abstractions over hardware to generate Instants and using Durations (Seconds, Milliseconds, etc) in embedded systems. The approach is similar to the C++ chrono library. A Duration consists of an integer (whose type is chosen by the user to be either u32 or u64) as well as a const fraction (Period) where the integer value multiplied by the fraction is the Duration in seconds. Put another way, the ratio is the precision of the LSbit of the integer. This structure avoids unnecessary arithmetic. For example, if the Duration type is Milliseconds, a call to the Duration::count() method simply returns the stored integer value directly which is the number of milliseconds being represented. Conversion arithmetic is only performed when explicitly converting between time units.

In addition frequency-type types are available including Hertz (u32) and it's reciprocal Period (u32/u32 seconds).

Definitions

Clock: Any entity that periodically counts (ie an external or peripheral hardware timer/counter). Generally, this needs to be monotonic. A wrapping clock is considered monotonic in this context as long as it fulfills the other requirements.

Wrapping Clock: A clock that when at its maximum value, the next count is the minimum value.

Timer: An entity that counts toward an expiration.

Instant: A specific instant in time ("time-point") read from a clock.

Duration: The difference of two instances. The time that has elapsed since an instant. A span of time.

Notes

Some parts of this crate were derived from various sources:

• RTIC
• time (Specifically the time::NumbericalDuration implementations for primitive integers)

Example Usage

struct SomeClock;
impl embedded_time::Clock for SomeClock {
    type Rep = u64;
    const PERIOD: Period = <Period>::new(1, 16_000_000);
    type ImplError = ();

    fn now(&self) -> Result<Instant<Self>, embedded_time::clock::Error<Self::ImplError>> {
        // ...
    }
}

let mut clock = SomeClock;
let instant1 = clock.now().unwrap();
// ...
let instant2 = clock.now().unwrap();
assert!(instant1 < instant2);    // instant1 is *before* instant2

// duration is the difference between the instances
let duration: Result<Microseconds<u64>, _> = instant2.duration_since(&instant1);

assert!(duration.is_ok());
assert_eq!(instant1 + duration.unwrap(), instant2);

Re-exports

pub use clock::Clock;

Modules

clock	Clock abstractions
duration	Duration types/units creation and conversion.
units	Time-based units of measure (Milliseconds, Hertz, etc)

Structs

Instant	Represents an instant of time relative to a specific Clock
Period	A fractional time period
Timer	A Timer counts toward an expiration, can be polled for elapsed and remaining time, and can be one-shot or continuous/periodic.

Enums

ConversionError	Conversion errors
TimeError	Crate errors

Traits

Error

General error-type trait implemented for all error types in this crate