Crate embedded_time

embedded-time provides a comprehensive library of Duration and Rate types as well as a Clock abstractions for hardware timers/clocks and the associated Instant type for in embedded systems.

Additionally, an implementation of software timers is provided that work seemlessly with all the types in this crate.

The approach taken is similar to the C++ chrono library. Durations and Rates are fixed-point values as in they are comprised of integer and scaling factor values. The scaling factor is a const Fraction. One benefit of this structure is that it avoids unnecessary arithmetic. For example, if the Duration type is Milliseconds, a call to the Duration::integer() method simply returns the integer part directly which in the case is the number of milliseconds represented by the Duration. Conversion arithmetic is only performed when explicitly converting between time units (eg. Milliseconds --> Seconds).

In addition, a wide range of rate-type types are available including Hertz, BitsPerSecond, Baud, etc.

A Duration type can be converted to a Rate type and vica-versa.

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 instants. The time that has elapsed since an instant. A span of time.

Rate: A measure of events per time such as frequency, data-rate, etc.

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 T = u64;
    type ImplError = ();
    const SCALING_FACTOR: Fraction = Fraction::new(1, 16_000_000);

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

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

// duration is the difference between the instants
let duration = instant2.duration_since(&instant1);
assert!(duration.is_ok());

// convert to _named_ duration
let duration = Microseconds::<u64>::try_from(duration.unwrap());
assert_eq!(instant1 + duration.unwrap(), instant2);

Re-exports

pub use clock::Clock;

pub use duration::Duration;

pub use rate::Rate;

Modules

clock	Abstraction for hardware timers/clocks
duration	Duration types/units
rate	Rate-based types/units

Structs

Fraction	A fractional value
Instant	Represents an instant of time relative to a specific Clock
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