#ifndef MOTOR_DRIVER_H
#define MOTOR_DRIVER_H

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

/*
 * SaltyLab Motor Driver
 *
 * Sits between the balance PID and the raw hoverboard UART driver.
 * Responsibilities:
 *   - Differential drive mixing: speed = balance_cmd, steer mixed in
 *   - Steer ramping to avoid sudden yaw torque disturbing balance
 *   - Headroom clamping: |speed| + |steer| <= MOTOR_CMD_MAX
 *   - Emergency stop: immediate zero + latch until explicitly cleared
 *
 * Balance PID output is NOT ramped — it needs full immediate authority.
 * Only the steer channel is ramped.
 *
 * Call motor_driver_update() at the ESC send rate (50Hz / every 20ms).
 */

typedef struct {
    int16_t steer_actual;   /* Ramped steer command currently sent */
    bool    estop;          /* Emergency stop latched */
} motor_driver_t;

void motor_driver_init(motor_driver_t *m);

/*
 * Update and send to ESC.
 *   balance_cmd : PID output, -1000..+1000
 *   steer_cmd   : desired yaw/steer, -1000..+1000 (future RC/autonomous input)
 *   now         : HAL_GetTick() timestamp (ms) for ramp delta-time
 */
void motor_driver_update(motor_driver_t *m,
                         int16_t balance_cmd,
                         int16_t steer_cmd,
                         uint32_t now);

/* Latch emergency stop — sends zero immediately */
void motor_driver_estop(motor_driver_t *m);

/* Clear emergency stop latch (only call from armed/ready context) */
void motor_driver_estop_clear(motor_driver_t *m);

#endif