#ifndef LVC_H
#define LVC_H

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

/*
 * lvc.h -- Low Voltage Cutoff (LVC) protection (Issue #613)
 *
 * 3-stage battery voltage protection using battery_read_mv():
 *
 *   LVC_WARNING  (21.0 V) -- periodic buzzer alert; full power maintained
 *   LVC_CRITICAL (19.8 V) -- faster buzzer; motor commands scaled to 50%
 *   LVC_CUTOFF   (18.6 V) -- error buzzer; motors disabled; latched until reboot
 *
 * Recovery uses LVC_HYSTERESIS_MV to prevent threshold chatter.
 * CUTOFF is one-way: once latched, only a power-cycle clears it.
 *
 * Integration:
 *   lvc_init()                   -- call once during system init
 *   lvc_tick(now_ms, vbat_mv)    -- call each main loop tick (1 kHz)
 *   lvc_get_power_scale()        -- returns 0/50/100; apply to motor speed
 *   lvc_is_cutoff()              -- true when motors must be disabled
 */

typedef enum {
    LVC_NORMAL   = 0,  /* Vbat >= WARNING threshold  */
    LVC_WARNING  = 1,  /* Vbat <  21.0 V -- alert only */
    LVC_CRITICAL = 2,  /* Vbat <  19.8 V -- 50% power  */
    LVC_CUTOFF   = 3,  /* Vbat <  18.6 V -- motors off  */
} LvcState;

void     lvc_init(void);
void     lvc_tick(uint32_t now_ms, uint32_t vbat_mv);
LvcState lvc_get_state(void);
uint8_t  lvc_get_power_scale(void);  /* 100 = full, 50 = critical, 0 = cutoff */
bool     lvc_is_cutoff(void);

#endif /* LVC_H */