Engine

A control structure that acts like the conductor of an orchestra, managing an ensemble of units. It handles their initialization, updates, and timing, ensuring that all components remain synchronized.

By default, all units are automatically added to the primary engine which can be accessed using the global object Plaquette. By using secondary engines you can organize and optimize your code, allowing for multi-tasking, grouping units, switching between ensembles of units, and save power by running engines at lower frequency.

Usage

To create and use an engine, simply declare it:

Engine myEngine;

You will need to call the engine’s begin() function at initialization, and then its step() function at a regular pace.

To assign units to a specific engine, add it as the last parameter at construction:

SquareWave wave(1.0, 0.2, myEngine); // Use myEngine instead of the default

Each engine provides its own time measurements:

float sec = myEngine.seconds();        // Time since engine started, in seconds
uint32_t ms = myEngine.milliSeconds(); // Time in milliseconds
uint64_t us = myEngine.microSeconds(); // Time in microseconds

For more in-depth explanations and examples please read Using Secondary Engines.

Example

This example demonstrates the use of a secondary engine on an Arduino Uno or Nano using timer2 interrupt.

#include <Plaquette.h>

Engine timerEngine; // The secondary timer engine.

Metronome serialMetro(1.0); // Metronome (primary engine).

Metronome toggleMetro(0.25, timerEngine); // Metronome (timer engine).
DigitalOut led(LED_BUILTIN, timerEngine); // Built-in LED (timer engine).

// Primary engine begin().
void begin() {
  timerEngine.begin(); // Begin timer engine.
  timerSetup();        // Initialize timer interrupt timer2.
}

// Primary engine step().
void step() {
  if (serialMetro)
    println("step");
}

// Timer2 interrupt: will be called at 1kHz frequency.
ISR(TIMER2_COMPA_vect) {
  timerEngine.step(); // Step engine.

  if (toggleMetro) // Toggle LED on metro bang.
    led.toggle();
}

// Timer2 setup for 1kHz on AVR.
void timerSetup() {
  // Stop Timer2
  TCCR2A = 0;
  TCCR2B = 0;
  TCNT2  = 0;

  // Set compare match register for 1 kHz increments
  // 16 MHz / (prescaler * 1000) - 1 = OCR2A
  OCR2A = 124;

  TCCR2A |= (1 << WGM21); // CTC mode (Clear Timer on Compare Match)
  TCCR2B |= (1 << CS22) | (1 << CS20); // Set prescaler to 128
  TIMSK2 |= (1 << OCIE2A); // Enable Timer2 compare interrupt

  sei(); // Enable global interrupts
}

Reference

class Engine

The main Plaquette static class containing all the units.

Public Functions

inline void begin(unsigned long baudrate = PLAQUETTE_SERIAL_BAUD_RATE): Function to be used within the PlaquetteLib context (needs to be called at top of setup() method).

inline void step(): Function to be used within the PlaquetteLib context (needs to be called at top of loop() method).

inline size_t nUnits(): Returns the current number of units.

float seconds(bool referenceTime = true) const

Returns time in seconds.

Optional parameter allows to ask for reference time (default) which will yield the same value through one iteration of step(), or “real” time which will return the current total running time.

Parameters:: referenceTime – determines whether the function returns the reference time or the real time
Returns:: the time in seconds

uint32_t milliSeconds(bool referenceTime = true) const

Returns time in milliseconds.

Optional parameter allows to ask for reference time (default) which will yield the same value through one iteration of step(), or “real” time which will return the current total running time.

Parameters:: referenceTime – determines whether the function returns the reference time or the real time
Returns:: the time in milliseconds

uint64_t microSeconds(bool referenceTime = true) const

Returns time in microseconds.

Optional parameter allows to ask for reference time (default) which will yield the same value through one iteration of step(), or “real” time which will return the current total running time.

Parameters:: referenceTime – determines whether the function returns the reference time or the real time
Returns:: the time in microseconds

inline unsigned long nSteps() const: Returns number of steps.

void sampleRate(float sampleRate): Sets sample rate to a fixed value, thus disabling auto sampling rate.

void samplePeriod(float samplePeriod): Sets sample period to a fixed value, thus disabling auto sampling rate.

inline float sampleRate() const: Returns sample rate.

inline float samplePeriod() const: Returns sample period.

inline bool isPrimary() const: Returns true if this Engine is the main.

Public Static Functions

static Engine &primary(): Returns the main instance of Plaquette.

Engine

Usage

Example

Reference

See Also