PqCore.h

/*
 * PqCore.h
 *
 * (c) 2015 Sofian Audry        :: info(@)sofianaudry(.)com
 * (c) 2015 Thomas O Fredericks :: tof(@)t-o-f(.)info
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
#ifndef PQ_CORE_H_
#define PQ_CORE_H_
 
#if (defined(ARDUINO) && ARDUINO >= 100) || defined(EPOXY_DUINO)
#include <Arduino.h>
#else
#include <WProgram.h>
#endif
 
#include "pq_math.h"
 
#include <stdint.h>
#include <float.h>
 
#include <limits.h>
 
#include "HybridArrayList.h"
#include "PqEvents.h"
#include "pq_globals.h"
#include "pq_constrain.h"
#include "pq_map.h"
#include "pq_phase_utils.h"
#include "pq_random.h"
#include "pq_time.h"
 
namespace pq {
 
enum {
  DIRECT,
  INVERTED,
  INTERNAL_PULLUP,
  SOURCE = DIRECT, // deprecated
  SINK = INVERTED  // deprecated
};
 
class Unit;
 
class Engine {
  friend class Unit;
 
public:
  Engine();
  ~Engine();
 
  void preBegin(unsigned long baudrate=PLAQUETTE_SERIAL_BAUD_RATE);
 
  void postBegin();
 
  inline void preStep();
 
  inline bool timeStep();
 
  inline void begin(unsigned long baudrate=PLAQUETTE_SERIAL_BAUD_RATE);
 
  inline bool step();
 
  inline void end();
 
  size_t nUnits() { return _unitsEndIndex - _unitsBeginIndex; }
 
  float seconds(bool referenceTime=true) const;
 
  uint32_t milliSeconds(bool referenceTime=true) const;
 
  uint64_t microSeconds(bool referenceTime=true) const;
 
  unsigned long nSteps() const { return _nSteps; }
 
  bool hasAutoSampleRate() const { return _autoSampleRate; }
 
  void autoSampleRate();
 
  void sampleRate(float sampleRate);
 
  void samplePeriod(float samplePeriod);
 
  float sampleRate() const { return _sampleRate; }
 
  float samplePeriod() const { return (_samplePeriod ? _samplePeriod : (_samplePeriod = frequencyToPeriod(_sampleRate))); }
 
  uint32_t deltaTimeMicroSeconds() const { return _deltaTimeMicroSeconds; }
 
  float deltaTimeSecondsTimesFixed32Max() const { return _deltaTimeSecondsTimesFixed32Max; }
 
  static Engine& primary();
 
  bool isPrimary() const { return this == &primary(); }
 
  bool randomTrigger(float timeWindow);
 
private:
  void add(Unit* component);
 
  void remove(Unit* component);
 
  // Internal use. Sets sample rate and sample period.
  inline void _setSampleRate(float sampleRate);
 
  // Internal use, needs to be called periodically. Updates _totalGlobalMicroSeconds.
  static micro_seconds_t _updateGlobalMicroSeconds();
 
private:
  // Shared static container containing all units. Static because it is shared between all engines.
  // Units from the primary engine are always located at the begnning, then units from other engines.
  static HybridArrayList<Unit*, PLAQUETTE_MAX_UNITS>& units();
 
  // Range of this engine's units within the _units array list.
  size_t _unitsBeginIndex; // begin index
  size_t _unitsEndIndex;   // end index (= _unitsBeginIndex + nUnits())
 
  // Sampling rate (ie. how many times per seconds step() is called).
  float _sampleRate;
 
  // Sampling period (ie. 1.0 / sampleRate()).
  mutable float _samplePeriod;
 
  // Whether the auto sample rate mode is activated.
  float _targetSampleRate;
 
  // Snapshot of time in seconds from current step.
  micro_seconds_t _microSeconds;
  // uint32_t _previousMicroSeconds; // This is the 32 first bits of microseconds used for inter-step calculations.
 
  // Target time for next step (when using sampleRate(float)).
  micro_seconds_t _targetTime;
 
  // Step state for state machine to manage sample rate.
  enum StepState {
    STEP_INIT,
    STEP_WAIT,
    STEP_WAIT_OVERFLOW
  };
 
  // Current step state.
  StepState _stepState;
 
  // Number of microseconds between steps.
  uint32_t _deltaTimeMicroSeconds;
 
  // Number of seconds between steps time FIXED_32_MAX.
  float _deltaTimeSecondsTimesFixed32Max;
 
  // Number of microseconds between steps.
  uint32_t _targetDeltaTimeMicroSeconds;
 
  // Number of steps accomplished.
  unsigned long _nSteps;
 
  // True if using auto sample rate mode.
  bool _autoSampleRate;
 
  // True if begin has been completed..
  bool _beginCompleted;
 
  // True during first run.
  bool _firstRun;
 
  // Used to keep track of events.
  EventManager _eventManager;
 
  // Global time in microseconds.
  static micro_seconds_t _totalGlobalMicroSeconds;
 
private:
  // Prevent copy-construction and assignment.
  Engine(const Engine&);
  Engine& operator=(const Engine&);
};
 
extern Engine& Plaquette;
 
unsigned long nSteps();
 
bool hasAutoSampleRate();
 
void autoSampleRate();
 
void sampleRate(float sampleRate);
 
void samplePeriod(float samplePeriod);
 
float sampleRate();
 
float samplePeriod();
 
bool randomTrigger(float timeWindow);
 
void beginSerial(unsigned long baudRate);
 
class Chainable {
  private:
    // Prevents assignation operations by making them private.
  Chainable& operator=(bool);
  Chainable& operator=(int);
  Chainable& operator=(float);
  Chainable& operator=(Chainable&);
 
  public:
  virtual float get() { return 0.0f; }
 
  operator float() { return get(); }
 
  virtual float mapTo(float toLow, float toHigh) { return constrain(get(), toLow, toHigh); } // default: just constrain
 
  virtual float put(float value) { return get(); } // do nothing by default (read-only)
 
  static bool  analogToDigital(float f) { return (f >= 0.5); }
 
  static float digitalToAnalog(bool b) { return (b ? 1.0f : 0.0f); }
 
  public:
  // NOTE: This operator is defined as explicit so that boolean expression like
  // "if (obj)" use the bool() operator while other expressions can use the float() operator.
  explicit operator bool() { return Chainable::analogToDigital(get()); }
};
 
class Unit : public Chainable {
  friend class Engine;
  friend class EventManager;
 
protected:
  virtual void begin() {}
  virtual void step() {}
 
public:
  // Clears all event listeners.
  virtual void clearEvents();
 
  float seconds() const { return _engine->seconds(); }
 
  uint32_t milliSeconds() const { return _engine->milliSeconds(); }
 
  uint64_t microSeconds() const { return _engine->microSeconds(); }
 
  unsigned long nSteps() const { return _engine->nSteps(); }
 
  float sampleRate() const { return _engine->sampleRate(); }
 
  float samplePeriod() const { return _engine->samplePeriod(); }
 
protected:
  Unit(Engine& engine = Engine::primary());
  virtual ~Unit();
 
  virtual bool eventTriggered(EventType eventType) { return false; }
 
  virtual void onEvent(EventCallback callback, EventType eventType);
 
private:
  // The engine that owns this unit.
  Engine* _engine;
 
protected:
  Engine* engine() const { return _engine; }
};
 
class DigitalUnit : public Unit {
protected:
  DigitalUnit(Engine& engine = Engine::primary()) : Unit(engine) {}
 
public:
  virtual bool isOn() { return false; }
 
  virtual bool isOff() { return !isOn(); }
 
  virtual int getInt() { return isOn() ? 1 : 0; }
 
  virtual float get() { return getInt(); }
 
  virtual bool on() { return putOn(true); }
 
  virtual bool off() { return putOn(false); }
 
  virtual float put(float value) {
    return Unit::digitalToAnalog(putOn(Unit::analogToDigital(value)));
  }
 
  virtual bool putOn(bool value) { return isOn(); } // do nothing by default (read-only)
 
  virtual float mapTo(float toLow, float toHigh) { return isOn() ? toHigh : toLow; }
 
  operator bool() { return isOn(); }
 
  // IMPORTANT: LEAVE COMMENTED
  // virtual operator int() { return getInt(); }
 
  // IMPORTANT: This operator is redefined as explicit to make default return a bool.
  explicit operator float() { return Unit::operator float(); }
};
 
class AnalogSource : public Unit {
public:
  AnalogSource(Engine& engine = Engine::primary()) : AnalogSource(0, engine) {}
  AnalogSource(float initialValue, Engine& engine = Engine::primary()) : Unit(engine) { _value = constrain01(initialValue); }
  virtual ~AnalogSource() {}
 
  virtual float get() { return _value; }
 
  virtual float mapTo(float toLow, float toHigh) { return mapFrom01(get(), toLow, toHigh); }
 
protected:
  float _value;
};
 
class DigitalSource : public DigitalUnit {
public:
  DigitalSource(Engine& engine = Engine::primary()) : DigitalSource(false, engine) {}
  DigitalSource(bool initialValue, Engine& engine = Engine::primary()) : DigitalUnit(engine), _onValue(initialValue), _prevOnValue(initialValue), _changeState(0) {}
 
  virtual bool isOn() { return _onValue; }
 
  virtual bool putOn(bool value) { return (_onValue = value); } // do nothing by default (read-only)
 
  virtual bool rose() { return changeState() > 0; }
 
  virtual bool fell() { return changeState() < 0; }
 
  virtual bool changed() { return changeState() != 0; }
 
  virtual bool toggle() { return putOn(!isOn()); }
 
  virtual int8_t changeState() { return _changeState; }
 
  virtual void onRise(EventCallback callback)   { onEvent(callback, EVENT_RISE); }
 
  virtual void onFall(EventCallback callback)   { onEvent(callback, EVENT_FALL); }
 
  virtual void onChange(EventCallback callback) { onEvent(callback, EVENT_CHANGE); }
 
protected:
  void _updateChangeState() {
    _changeState = (int8_t)_onValue - (int8_t)_prevOnValue;
    _prevOnValue = _onValue;
  }
 
  virtual bool eventTriggered(EventType eventType) {
    switch (eventType) {
      case EVENT_CHANGE: return changed();
      case EVENT_RISE:   return rose();
      case EVENT_FALL:   return fell();
      default:           return DigitalUnit::eventTriggered(eventType);
    }
  }
 
  // The value contained in the unit.
  bool    _onValue     : 1;
 
  // Previous value, used to compute change state.
  bool    _prevOnValue : 1;
 
  // The change state contained in the unit.
  int8_t  _changeState : 2;
 
  // Unused extra space.
  uint8_t _data        : 4;
};
 
// Value to unit operators ///////////////////////////////////////
 
// Base value to unit operator.
inline Chainable& operator>>(float value, Chainable& unit) {
  unit.put(value);
  return unit;
}
 
// NOTE: do not change the order of this operator (it needs to be set *after* the >>(float, Chainable&)).
inline Chainable& operator>>(Chainable& source, Chainable& sink) {
  return pq::operator>>(source.get(), sink);
}
 
inline Chainable& operator>>(double value, Chainable& unit) {
  return pq::operator>>((float)value, unit);
}
 
inline Chainable& operator>>(bool value, Chainable& unit) {
  return pq::operator>>(Chainable::digitalToAnalog(value), unit);
}
 
// This code is needed on the Curie and ARM chips.
// Otherwise it causes an ambiguous operator error.
#if defined(__arc__) || defined(__arm__)
inline Chainable& operator>>(int value, Chainable& unit) {
  return pq::operator>>((float)value, unit);
}
#endif
 
inline Chainable& operator>>(int8_t value, Chainable& unit) {
  return pq::operator>>((float)value, unit);
}
 
inline Chainable& operator>>(uint8_t value, Chainable& unit) {
  return pq::operator>>((float)value, unit);
}
 
inline Chainable& operator>>(int16_t value, Chainable& unit) {
  return pq::operator>>((float)value, unit);
}
 
inline Chainable& operator>>(uint16_t value, Chainable& unit) {
  return pq::operator>>((float)value, unit);
}
 
inline Chainable& operator>>(int32_t value, Chainable& unit) {
  return pq::operator>>((float)value, unit);
}
 
inline Chainable& operator>>(uint32_t value, Chainable& unit) {
  return pq::operator>>((float)value, unit);
}
 
inline Chainable& operator>>(int64_t value, Chainable& unit) {
  return pq::operator>>((float)value, unit);
}
 
inline Chainable& operator>>(uint64_t value, Chainable& unit) {
  return pq::operator>>((float)value, unit);
}
 
// // Unit to value operators ///////////////////////////////////////
// THIS PART IS COMMENTED OUT BECAUSE IT CAUSES AMBIGUOUS OPERATOR ERRORS
 
// inline bool& operator>>(DigitalUnit& unit, bool& value) {
//   return (value = unit.isOn());
// }
 
// // This code is needed on the Curie-based AVRs.
// #if defined(__arc__)
// inline int& operator>>(DigitalUnit& unit, int& value) {
//   return (value = unit.getInt());
// }
// #endif
 
// inline int8_t& operator>>(DigitalUnit& unit, int8_t& value) {
//   return (value = unit.getInt());
// }
 
// inline uint8_t& operator>>(DigitalUnit& unit, uint8_t& value) {
//   return (value = unit.getInt());
// }
 
// inline int16_t& operator>>(DigitalUnit& unit, int16_t& value) {
//   return (value = unit.getInt());
// }
 
// inline uint16_t& operator>>(DigitalUnit& unit, uint16_t& value) {
//   return (value = unit.getInt());
// }
 
// inline int32_t& operator>>(DigitalUnit& unit, int32_t& value) {
//   return (value = unit.getInt());
// }
 
// inline uint32_t& operator>>(DigitalUnit& unit, uint32_t& value) {
//   return (value = unit.getInt());
// }
 
// inline int64_t& operator>>(DigitalUnit& unit, int64_t& value) {
//   return (value = unit.getInt());
// }
 
// inline uint64_t& operator>>(DigitalUnit& unit, uint64_t& value) {
//   return (value = unit.getInt());
// }
 
// inline float& operator>>(Unit& unit, float& value) {
//   return (value = unit.get());
// }
 
// inline double& operator>>(Unit& unit, double& value) {
//   return (value = unit.get());
// }
 
class PinConfig {
public:
  PinConfig(uint8_t pin, uint8_t mode) : _pin(pin), _mode(mode) {}
  virtual ~PinConfig() {}
 
  uint8_t pin() const { return _pin; }
 
  uint8_t mode() const { return _mode; }
 
  virtual void mode(uint8_t mode) { _mode = mode; }
 
protected:
  // The attached pin.
  uint8_t _pin;
 
  // The mode (varies according to context).
  uint8_t _mode;
};
 
// Inline methods.
 
void Engine::preStep() {
  // Update every component.
  for (size_t i=_unitsBeginIndex; i != _unitsEndIndex; i++) {
    units()[i]->step();
  }
 
  // Look for events.
  _eventManager.step();
}
 
bool Engine::timeStep() {
  // Calculate true sample rate.
  _updateGlobalMicroSeconds();
 
  // Compute inter-step time.
  _deltaTimeMicroSeconds = _totalGlobalMicroSeconds.micros32.base - _microSeconds.micros32.base;
  float trueSampleRate = (_deltaTimeMicroSeconds ? SECONDS_TO_MICROS / _deltaTimeMicroSeconds : PLAQUETTE_MAX_SAMPLE_RATE);
 
  // If autoSampleRate is off: wait in order to synchronize seconds with real time.
  if (!_autoSampleRate) {
 
    // Initilize step state.
    if (_stepState == STEP_INIT) {
      // Target time = current time + 1/_targetSampleRate
      _targetTime = _microSeconds;
      _targetTime.micros32.base += _targetDeltaTimeMicroSeconds;
 
      // Check for overflow.
      if (_targetTime.micros32.base >= _microSeconds.micros32.base) { // if target time is in the future: no overflow.
        _stepState = STEP_WAIT;
      }
      else { // overflow
        _targetTime.micros32.overflows++;
        _stepState = STEP_WAIT_OVERFLOW;
      }
    }
 
    // Process waiting state: will return false if still waiting, otherwise will complete the function.
    if (_stepState == STEP_WAIT) {
      // Still needs to wait.
      if (_totalGlobalMicroSeconds.micros32.base < _targetTime.micros32.base)
        return false; // break
    }
    else { // stepState == STEP_WAIT_OVERFLOW
      // Still needs to wait.
      if (_totalGlobalMicroSeconds.micros64 < _targetTime.micros64)
        return false; // break
    }
 
    // Reset state.
    _stepState = STEP_INIT;
  }
 
  // Update sample rate and current time to "true" / actual values.
  _setSampleRate(trueSampleRate);
 
  // Calculate delta time in fixed point.
  uint64_t deltaTimeMicroSeconds64 = (uint64_t)_deltaTimeMicroSeconds;
  _deltaTimeSecondsTimesFixed32Max = ((deltaTimeMicroSeconds64 << 32) - deltaTimeMicroSeconds64) * MICROS_TO_SECONDS;
 
  // Sync reference time with global (true) time.
  _microSeconds = _totalGlobalMicroSeconds;
 
  // Increment step.
  _nSteps++;
 
  return true;
}
 
void Engine::begin(unsigned long baudrate) {
  preBegin(baudrate);
}
 
bool Engine::step() {
  // On first run: do a post-begin.
  if (_firstRun) { // the compiler should make this branching step effectively CPU-free
    postBegin();
    _firstRun = false;
    return false;
  }
 
  // Otherwise: do a step.
  else if (timeStep()) { // timeStep() will return false if we need to wait due to restrictive sampleRate(float)
    // Do the pre-step.
    preStep();
    return true;
  }
  else
    return false;
}
 
void Engine::_setSampleRate(float sampleRate) {
  _sampleRate = max(sampleRate, FLT_MIN); // cannot be zero
  _samplePeriod = 0; // set to zero to reset cache
}
 
} // namespace pq
 
#endif