#ifndef INA219_H
#define INA219_H

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

/*
 * ina219.h — INA219 power monitor driver (Issue #214)
 *
 * I2C1 driver for motor current/voltage/power monitoring.
 * Supports 2 sensors (left/right motor) on I2C1 (PB8=SCL, PB9=SDA).
 *
 * INA219 specs:
 *   - I2C addresses: 0x40–0x4F (configurable via address pins)
 *   - Bus voltage: 0–26V, 4mV/LSB
 *   - Shunt voltage: ±327mV, 10µV/LSB
 *   - Current: derived from shunt voltage (calibration-dependent)
 *   - Power: (Bus V × Current) / internal gain
 *
 * Typical usage for motor monitoring:
 *   - 0.1Ω shunt resistor → ~3.27A max (at ±327mV)
 *   - Calibration: set max expected current, driver calculates LSB
 *   - Read functions return actual voltage/current/power values
 */

/* INA219 sensors (2 motors) */
typedef enum {
    INA219_LEFT_MOTOR  = 0,  /* Address 0x40 */
    INA219_RIGHT_MOTOR = 1,  /* Address 0x41 */
    INA219_COUNT
} INA219Sensor;

/* INA219 measurement data */
typedef struct {
    uint16_t bus_voltage_mv;     /* Bus voltage in mV (0–26000) */
    int16_t  shunt_voltage_uv;   /* Shunt voltage in µV (±327000) */
    int16_t  current_ma;         /* Current in mA (signed) */
    uint32_t power_mw;           /* Power in mW */
} INA219Data;

/*
 * ina219_init()
 *
 * Initialize I2C1 and both INA219 sensors (left + right motor).
 * Performs auto-calibration for typical motor current monitoring.
 * Call once at startup after i2c1_init().
 */
void ina219_init(void);

/*
 * ina219_calibrate(sensor, max_current_ma, shunt_ohms_milli)
 *
 * Manually calibrate a sensor for expected max current and shunt resistance.
 * Calculates internal calibration register value.
 *
 * Example:
 *   ina219_calibrate(INA219_LEFT_MOTOR, 5000, 100);  // 5A max, 0.1Ω shunt
 */
void ina219_calibrate(INA219Sensor sensor, uint16_t max_current_ma, uint16_t shunt_ohms_milli);

/*
 * ina219_read(sensor, data)
 *
 * Read all measurements from a sensor (voltage, current, power).
 * Blocks until measurements are ready (typically <1ms at default ADC resolution).
 *
 * Returns: true if read successful, false on I2C error.
 */
bool ina219_read(INA219Sensor sensor, INA219Data *data);

/*
 * ina219_read_bus_voltage_mv(sensor, voltage_mv)
 *
 * Read bus voltage only (faster than full read).
 * Returns: true if successful.
 */
bool ina219_read_bus_voltage_mv(INA219Sensor sensor, uint16_t *voltage_mv);

/*
 * ina219_read_current_ma(sensor, current_ma)
 *
 * Read current only (requires prior calibration).
 * Returns: true if successful.
 */
bool ina219_read_current_ma(INA219Sensor sensor, int16_t *current_ma);

/*
 * ina219_read_power_mw(sensor, power_mw)
 *
 * Read power consumption only.
 * Returns: true if successful.
 */
bool ina219_read_power_mw(INA219Sensor sensor, uint32_t *power_mw);

/*
 * ina219_alert_enable(sensor, current_limit_ma)
 *
 * Enable alert pin when current exceeds limit (overcurrent protection).
 * Alert pin: GPIO, active high, open-drain output.
 */
void ina219_alert_enable(INA219Sensor sensor, uint16_t current_limit_ma);

/*
 * ina219_alert_disable(sensor)
 *
 * Disable alert for a sensor.
 */
void ina219_alert_disable(INA219Sensor sensor);

/*
 * ina219_reset(sensor)
 *
 * Perform soft reset on a sensor (clears all registers to default).
 */
void ina219_reset(INA219Sensor sensor);

#endif /* INA219_H */