interval_timer.hpp

Go to the documentation of this file.

#ifndef SBL_CORE_PATTERNS_TIMING_INTERVAL_TIMER_HPP_
#define SBL_CORE_PATTERNS_TIMING_INTERVAL_TIMER_HPP_
 
/**
 * @file interval_timer.hpp
 * @brief Generic interrupt-driven interval timing for precise events
 * @ingroup patterns
 * 
 * Provides generic interval timing using hardware timer interrupts.
 * No domain-specific logic - just precise microsecond interval generation.
 * Applications handle their own domain logic (BPM, frequencies, etc).
 */
 
#include <sbl/hal/hardware_timer.hpp>
#include <sbl/primitives/math/integer_math.hpp>
 
namespace sbl {
namespace core {
namespace patterns {
namespace timing {
 
/**
 * @brief Generic interrupt-driven interval timer
 * 
 * Provides precise interval timing using hardware timer interrupts.
 * No musical or domain-specific logic - just generic interval generation.
 * Applications convert their domain values (BPM, frequencies) to microseconds.
 * 
 * Usage:
 * 1. Construct with timer instance
 * 2. Set interval in microseconds and start()
 * 3. Poll hasTriggered() in main loop
 * 4. Interrupt handling is automatic via registry
 * 
 * @tparam TimerImpl Hardware timer implementation
 */
template<typename TimerImpl>
class IntervalTimer {
public:
    /**
     * @brief Construct interval timer
     * @param timer_instance Hardware timer instance to use
     */
    explicit IntervalTimer(uint32_t timer_instance) 
        : timerInstance_(timer_instance), intervalMicros_(1000000), // Default 1Hz
          running_(false), triggered_(false) {
        
        // Initialize hardware timer
        sbl::core::hal::HardwareTimer<TimerImpl>::initialize(timerInstance_);
    }
    
    /**
     * @brief Set interval in microseconds
     * @param interval_us Interval duration in microseconds
     * 
     * Generic timing - no domain-specific logic.
     * Applications convert their values to microseconds:
     * - Audio: sample_rate -> (1,000,000 / sample_rate) us
     * - BPM: bpm -> (60,000,000 / bpm) us  
     * - Hz: freq -> (1,000,000 / freq) us
     */
    void setIntervalMicros(uint32_t interval_us) {
        intervalMicros_ = interval_us;
        
        if (running_) {
            // Reconfigure timer immediately if already running
            sbl::core::hal::HardwareTimer<TimerImpl>::configure(
                timerInstance_, intervalMicros_, sbl::core::hal::TimerMode::Periodic);
        }
    }
    
    /**
     * @brief Get current interval in microseconds
     * @return Current interval duration
     */
    uint32_t getIntervalMicros() const {
        return intervalMicros_;
    }
    
    /**
     * @brief Start the interval timer
     */
    void start() {
        if (!running_) {
            using HwTimer = sbl::core::hal::HardwareTimer<TimerImpl>;
            using TimerRegistry = sbl::core::hal::TimerInterruptRegistry<>;
            
            // Configure timer for periodic interrupts
            HwTimer::configure(timerInstance_, intervalMicros_, 
                             sbl::core::hal::TimerMode::Periodic);
            
            // Register static interrupt handler
            registerInstance(timerInstance_, this);
            TimerRegistry::registerHandler(timerInstance_, 
                sbl::core::hal::TimerInterrupt::Update,
                &IntervalTimer::staticInterruptHandler);
            
            // Enable interrupt and start timer
            HwTimer::enableInterrupt(timerInstance_, 
                sbl::core::hal::TimerInterrupt::Update,
                sbl::core::hal::InterruptPriority::High);
            
            HwTimer::reset(timerInstance_);
            HwTimer::start(timerInstance_);
            
            running_ = true;
            triggered_ = false;
        }
    }
    
    /**
     * @brief Stop the interval timer
     */
    void stop() {
        if (running_) {
            using HwTimer = sbl::core::hal::HardwareTimer<TimerImpl>;
            using TimerRegistry = sbl::core::hal::TimerInterruptRegistry<>;
            
            HwTimer::stop(timerInstance_);
            HwTimer::disableInterrupt(timerInstance_, 
                sbl::core::hal::TimerInterrupt::Update);
            
            // Unregister handler
            TimerRegistry::unregisterHandler(timerInstance_, 
                sbl::core::hal::TimerInterrupt::Update);
            unregisterInstance(timerInstance_);
            
            running_ = false;
            triggered_ = false;
        }
    }
    
    /**
     * @brief Check if timer is running
     * @return true if running, false if stopped
     */
    bool isRunning() const {
        return running_ && sbl::core::hal::HardwareTimer<TimerImpl>::isRunning(timerInstance_);
    }
    
    /**
     * @brief Check if interval has triggered
     * @return true if interval occurred since last check
     * 
     * This is a one-shot check - returns true once per trigger.
     * Call from main loop for event handling.
     */
    bool hasTriggered() {
        if (triggered_) {
            triggered_ = false;  // Clear flag after reading
            return true;
        }
        return false;
    }
    
    /**
     * @brief Timer interrupt handler - call from ISR
     * 
     * Called automatically via interrupt registry.
     * Just sets internal flag - no callbacks or complex logic in ISR.
     */
    void handleTimerInterrupt() {
        triggered_ = true;
    }
 
private:
    // Static interrupt handler for registry
    static void staticInterruptHandler() {
        // Find which timer instance triggered and call its handler
        // This is a simplified approach - in production you'd get the
        // timer instance from the interrupt vector
        for (uint8_t i = 0; i < 8; ++i) {
            if (instances_[i] && 
                sbl::core::hal::HardwareTimer<TimerImpl>::isInterruptPending(
                    i, sbl::core::hal::TimerInterrupt::Update)) {
                
                // Clear interrupt flag
                sbl::core::hal::HardwareTimer<TimerImpl>::clearInterrupt(
                    i, sbl::core::hal::TimerInterrupt::Update);
                    
                // Call instance handler
                instances_[i]->handleTimerInterrupt();
            }
        }
    }
    
    // Static instance registry for interrupt handling
    static void registerInstance(uint32_t timer_instance, IntervalTimer* instance) {
        if (timer_instance < 8) {  // Max 8 timer instances
            instances_[timer_instance] = instance;
        }
    }
    
    static void unregisterInstance(uint32_t timer_instance) {
        if (timer_instance < 8) {
            instances_[timer_instance] = nullptr;
        }
    }
    
    static IntervalTimer* instances_[8];  // Static instance registry
    
    uint32_t timerInstance_;
    uint32_t intervalMicros_;
    bool running_;
    volatile bool triggered_;  // Volatile for ISR/main loop communication
};
 
} // namespace timing
} // namespace patterns
} // namespace core
} // namespace sbl
 
// Static member definitions
template<typename TimerImpl>
IntervalTimer<TimerImpl>* IntervalTimer<TimerImpl>::instances_[8] = {};
 
#endif // SBL_CORE_PATTERNS_TIMING_INTERVAL_TIMER_HPP_