#ifndef BUZZER_H
#define BUZZER_H

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

/*
 * buzzer.h — Piezo buzzer melody driver (Issue #253)
 *
 * STM32F722 driver for piezo buzzer on PA8 using TIM1 PWM.
 * Plays predefined melodies and tones with non-blocking queue.
 *
 * Pin: PA8 (TIM1_CH1, alternate function AF1)
 * PWM Frequency: 1kHz-5kHz base, modulated for melody
 * Volume: Controlled via PWM duty cycle (50-100%)
 */

/* Musical note frequencies (Hz) — standard equal temperament */
typedef enum {
    NOTE_REST = 0,      /* Silence */
    NOTE_C4 = 262,      /* Middle C */
    NOTE_D4 = 294,
    NOTE_E4 = 330,
    NOTE_F4 = 349,
    NOTE_G4 = 392,
    NOTE_A4 = 440,      /* A4 concert pitch */
    NOTE_B4 = 494,
    NOTE_C5 = 523,
    NOTE_D5 = 587,
    NOTE_E5 = 659,
    NOTE_F5 = 698,
    NOTE_G5 = 784,
    NOTE_A5 = 880,
    NOTE_B5 = 988,
    NOTE_C6 = 1047,
} Note;

/* Note duration (milliseconds) */
typedef enum {
    DURATION_WHOLE = 2000,      /* 4 beats @ 120 BPM */
    DURATION_HALF = 1000,       /* 2 beats */
    DURATION_QUARTER = 500,     /* 1 beat */
    DURATION_EIGHTH = 250,      /* 1/2 beat */
    DURATION_SIXTEENTH = 125,   /* 1/4 beat */
} Duration;

/* Melody sequence: array of (note, duration) pairs, terminated with {0, 0} */
typedef struct {
    Note frequency;
    Duration duration_ms;
} MelodyNote;

/* Predefined melodies */
typedef enum {
    MELODY_STARTUP,         /* Startup jingle: ascending tones */
    MELODY_LOW_BATTERY,     /* Warning: two descending beeps */
    MELODY_ERROR,           /* Alert: rapid error beep */
    MELODY_DOCKING_COMPLETE /* Success: cheerful chime */
} MelodyType;

/* Get predefined melody sequence */
extern const MelodyNote melody_startup[];
extern const MelodyNote melody_low_battery[];
extern const MelodyNote melody_error[];
extern const MelodyNote melody_docking_complete[];

/*
 * buzzer_init()
 *
 * Initialize buzzer driver:
 * - PA8 as TIM1_CH1 PWM output
 * - TIM1 configured for 1kHz base frequency
 * - PWM duty cycle for volume control
 */
void buzzer_init(void);

/*
 * buzzer_play_melody(melody_type)
 *
 * Queue a predefined melody for playback.
 * Non-blocking: returns immediately, melody plays asynchronously.
 * Multiple calls queue melodies in sequence.
 *
 * Supported melodies:
 *   - MELODY_STARTUP: 2-3 second jingle on power-up
 *   - MELODY_LOW_BATTERY: 1 second warning
 *   - MELODY_ERROR: 0.5 second alert beep
 *   - MELODY_DOCKING_COMPLETE: 1-1.5 second success chime
 *
 * Returns: true if queued, false if queue full
 */
bool buzzer_play_melody(MelodyType melody_type);

/*
 * buzzer_play_custom(notes)
 *
 * Queue a custom melody sequence.
 * Notes array must be terminated with {NOTE_REST, 0}.
 * Useful for error codes or custom notifications.
 *
 * Returns: true if queued, false if queue full
 */
bool buzzer_play_custom(const MelodyNote *notes);

/*
 * buzzer_play_tone(frequency, duration_ms)
 *
 * Queue a simple single tone.
 * Useful for beeps and alerts.
 *
 * Arguments:
 *   - frequency: Note frequency (Hz), 0 for silence
 *   - duration_ms: Tone duration in milliseconds
 *
 * Returns: true if queued, false if queue full
 */
bool buzzer_play_tone(uint16_t frequency, uint16_t duration_ms);

/*
 * buzzer_stop()
 *
 * Stop current playback and clear queue.
 * Buzzer returns to silence immediately.
 */
void buzzer_stop(void);

/*
 * buzzer_is_playing()
 *
 * Returns: true if melody/tone is currently playing, false if idle
 */
bool buzzer_is_playing(void);

/*
 * buzzer_tick(now_ms)
 *
 * Update function called periodically (recommended: every 10ms in main loop).
 * Manages melody timing and PWM frequency transitions.
 * Must be called regularly for non-blocking operation.
 *
 * Arguments:
 *   - now_ms: current time in milliseconds (from HAL_GetTick() or similar)
 */
void buzzer_tick(uint32_t now_ms);

#endif /* BUZZER_H */