/**
 * @file sweep.h
 * @brief Hardware-agnostic periodic staircase sweep (see sweep_config_t).
 */

#ifndef SWEEP_H
#define SWEEP_H

#include <stdbool.h>
#include <stdint.h>

#include "app_types.h"

/**
 * @brief Sweep state advanced from the periodic tick interrupt.
 */
typedef struct sweep_t {
    uint8_t enabled;
    uint16_t min_code;
    uint16_t max_code;
    uint16_t step_code;
    uint32_t step_ticks;
    uint32_t pause_ticks;
    uint32_t next_code;
    uint32_t countdown_ticks;
} sweep_t;

/**
 * @brief Validate the sweep parameters and start from `min_code` on the next tick.
 *
 * The `enabled` field of @p config is not consulted: whether to start is the caller's decision.
 *
 * @return false (sweep left stopped) if bounds, step or period are invalid.
 */
bool sweep_start(sweep_t *sweep, const sweep_config_t *config, uint32_t tick_us);

void sweep_stop(sweep_t *sweep);

/**
 * @brief Advance the sweep by one tick.
 *
 * @return true when `*out_code` holds a new value that must be written to the output.
 */
bool sweep_tick(sweep_t *sweep, uint16_t *out_code);

#endif /* SWEEP_H */