#ifndef ESC_BACKEND_H
#define ESC_BACKEND_H

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

/*
 * ESC Backend Abstraction Layer
 *
 * Provides a pluggable interface for different ESC implementations:
 *   - Hoverboard (EFeru FOC firmware, UART @ 115200)
 *   - VESC (via UART @ 921600, with balance mode) — future
 *
 * Allows motor_driver.c to remain ESC-agnostic. Backend selection
 * via ESC_BACKEND compile-time define in config.h.
 *
 * Issue #388: ESC abstraction layer
 * Blocks Issue #383: VESC integration
 */

/* Telemetry snapshot from ESC (polled on-demand) */
typedef struct {
    int16_t  speed;         /* Motor speed (PWM duty or RPM, backend-dependent) */
    int16_t  steer;         /* Steering position (0 = centered) */
    uint16_t voltage_mv;    /* Battery voltage in millivolts */
    int16_t  current_ma;    /* Motor current in milliamps (signed: discharge/charge) */
    int16_t  temperature_c; /* ESC temperature in °C */
    uint16_t fault;         /* Fault code (backend-specific) */
} esc_telemetry_t;

/* Virtual function table for ESC backends */
typedef struct {
    /* Initialize ESC hardware and UART (called once at startup) */
    void (*init)(void);

    /* Send motor command to ESC (called at ~50Hz from motor_driver_update)
     *   speed: -1000..+1000 (forward/reverse)
     *   steer: -1000..+1000 (left/right)
     */
    void (*send)(int16_t speed, int16_t steer);

    /* Emergency stop: send zero and disable output
     * (called from safety or mode manager)
     */
    void (*estop)(void);

    /* Query current ESC state
     * Returns latest telemetry snapshot (may be cached/stale on some backends).
     * Safe to call from any context (non-blocking).
     */
    void (*get_telemetry)(esc_telemetry_t *out);

    /* Optional: resume from estop (not all backends use this) */
    void (*resume)(void);
} esc_backend_t;

/*
 * Register a backend implementation at runtime.
 * Typically called during init sequence before motor_driver_init().
 */
void esc_backend_register(const esc_backend_t *backend);

/*
 * Get the currently active backend.
 * Returns pointer to vtable; nullptr if no backend registered.
 */
const esc_backend_t *esc_backend_get(void);

/*
 * High-level convenience wrappers (match motor_driver.c interface).
 * These call through the active backend if registered.
 */
void esc_init(void);
void esc_send(int16_t speed, int16_t steer);
void esc_estop(void);
void esc_resume(void);
void esc_get_telemetry(esc_telemetry_t *out);

#endif /* ESC_BACKEND_H */