// =============================================================================
//  rudder_actuator.h -- rudder actuator driver (Sprint 1 stub)
// =============================================================================
//
//  Drives the rudder pump/motor via DO1 (port direction), DO2 (starboard
//  direction), and DO3 (master power relay). The actual command output is
//  produced by the inner PID loop (Sprint 2). In Sprint 1 this module:
//
//      - Exposes a `rudder_command(int8_t pwm_pct)` API.
//      - Refuses to act if the rudder is at its mechanical limit (DI2/DI3).
//      - Refuses to act if master power is off (DO3 LOW).
//      - Refuses to act if the system is in STANDBY (Sprint 1 default).
//
//  All three "refuse" conditions are safety-critical: they remain in place
//  for every subsequent sprint.
// =============================================================================

#pragma once

#include <cstdint>

namespace arautopilot::hal {

/// Configure DO1/DO2/DO3 as outputs and drive them all LOW.
void rudder_actuator_init();

/// Engage the master power relay (DO3 HIGH). Required before any
/// rudder_command() call has effect.
void rudder_actuator_power_on();

/// Drop the master power relay and stop both directions. Idempotent.
void rudder_actuator_power_off();

/// Send a signed command to the actuator:
///     pwm_pct =   0 -> both direction outputs LOW (rudder freewheels)
///     pwm_pct > 0  -> drive STARBOARD (DO2 HIGH)
///     pwm_pct < 0  -> drive PORT (DO1 HIGH)
///
/// Sprint 1 stub: only the direction outputs are toggled, no PWM modulation
/// (intensity ignored). Sprint 2 will replace the body with a real LEDC PWM.
///
/// Returns true if the command was actually applied; false if a safety
/// interlock blocked it (limit switch, power off, or standby mode).
bool rudder_command(int8_t pwm_pct);

/// True if the master power relay is currently engaged.
bool rudder_actuator_is_powered();

/// True if either limit switch is asserted.
bool rudder_actuator_at_limit();

}  // namespace arautopilot::hal
