#ifndef RGB_FSM_H
#define RGB_FSM_H

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

/*
 * rgb_fsm.h — RGB Status LED State Machine (Issue #290)
 *
 * Manages an 8-LED WS2812 NeoPixel ring with 8 operational states.
 * Each state has a specific color pattern and animation.
 *
 * States:
 *   BOOT     — Blue pulse (startup sequence, 0.5 Hz)
 *   IDLE     — Green breathe (standby, smooth 0.5 Hz pulse)
 *   ARMED    — Solid green (ready to move)
 *   NAV      — Cyan spin (autonomous navigation active, rotating pattern)
 *   ERROR    — Red flash (fault detected, 2 Hz blink)
 *   LOW_BATT — Orange blink (battery low, 1 Hz blink)
 *   CHARGING — Green fill (charging, progressive LEDs filling)
 *   ESTOP    — Red solid (emergency stop, full red, no animation)
 *
 * Transitions via UART command from Jetson.
 * Non-blocking operation with tick-based timing.
 */

/* LED State Machine States */
typedef enum {
    LED_STATE_BOOT = 0,
    LED_STATE_IDLE,
    LED_STATE_ARMED,
    LED_STATE_NAV,
    LED_STATE_ERROR,
    LED_STATE_LOW_BATT,
    LED_STATE_CHARGING,
    LED_STATE_ESTOP,
    LED_STATE_COUNT
} LedState;

/* RGB Color (8-bit per channel) */
typedef struct {
    uint8_t r;  /* Red (0-255) */
    uint8_t g;  /* Green (0-255) */
    uint8_t b;  /* Blue (0-255) */
} RgbColor;

/*
 * rgb_fsm_init()
 *
 * Initialize LED state machine:
 * - PB4 as TIM3_CH1 PWM output for WS2812 driver
 * - Configure TIM3 for 800 kHz PWM frequency
 * - Set initial state to BOOT
 * - Initialize all LEDs to off
 */
void rgb_fsm_init(void);

/*
 * rgb_fsm_set_state(state)
 *
 * Transition to a new LED state immediately.
 * Resets animation timing for the new state.
 *
 * Arguments:
 *   - state: Target LED state (LedState enum)
 *
 * Returns: true if state changed, false if already in that state
 */
bool rgb_fsm_set_state(LedState state);

/*
 * rgb_fsm_get_state()
 *
 * Get current LED state.
 *
 * Returns: Current LED state (LedState enum)
 */
LedState rgb_fsm_get_state(void);

/*
 * rgb_fsm_tick(now_ms)
 *
 * Update function called periodically (recommended: every 10-50ms).
 * Processes animations and timing for current state.
 * Updates LED strip via PWM.
 *
 * Arguments:
 *   - now_ms: Current time in milliseconds (from HAL_GetTick() or similar)
 */
void rgb_fsm_tick(uint32_t now_ms);

/*
 * rgb_fsm_set_color(led_index, color)
 *
 * Set color of a specific LED (for testing and manual control).
 * Bypasses current animation.
 *
 * Arguments:
 *   - led_index: 0-7 (LED ring has 8 LEDs)
 *   - color: RgbColor with R, G, B values (0-255)
 *
 * Returns: true if set, false if index out of range
 */
bool rgb_fsm_set_color(uint8_t led_index, RgbColor color);

/*
 * rgb_fsm_all_off()
 *
 * Turn off all LEDs immediately.
 * Useful for shutdown or error conditions.
 */
void rgb_fsm_all_off(void);

/*
 * rgb_fsm_get_animation_frame()
 *
 * Get current animation progress (0-255).
 * Useful for testing and debugging animation timing.
 *
 * Returns: Current frame value for animation (0-255 represents full cycle)
 */
uint8_t rgb_fsm_get_animation_frame(void);

#endif /* RGB_FSM_H */