// p7_coffre — unlocking actuator for the Zacus final chest (P7).
//
// When CONFIG_ZACUS_P7_COFFRE_ENABLE=n (default) all three functions are
// empty stubs (init returns ESP_OK, unlock/lock are no-ops) so callers do
// not need #ifdef guards.
//
// When enabled, call p7_coffre_init() once at boot, then p7_coffre_unlock()
// when STEP_FINAL_WIN is reached.  p7_coffre_lock() re-arms between games.
//
// Actuator selection and GPIO are configured via Kconfig (menuconfig or
// sdkconfig):
//   SERVO  – LEDC TIMER_2 / CHANNEL_2, 50 Hz, 13-bit duty cycle.
//   RELAY  – plain GPIO output with optional one-shot pulse.

#pragma once

#include "esp_err.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Initialise the P7 coffre actuator.
 *
 * Servo: configures LEDC timer + channel and moves to the locked position.
 * Relay: configures the GPIO as output and asserts the rest (inactive) state.
 * Idempotent — safe to call more than once.
 *
 * When CONFIG_ZACUS_P7_COFFRE_ENABLE=n this is a stub that returns ESP_OK.
 *
 * @return ESP_OK on success, or a driver error code.
 */
esp_err_t p7_coffre_init(void);

/**
 * @brief Unlock the coffre (STEP_FINAL_WIN reached).
 *
 * Servo: moves to CONFIG_ZACUS_P7_SERVO_UNLOCK_DEG.
 * Relay: energises the coil; if CONFIG_ZACUS_P7_RELAY_PULSE_MS > 0 the coil
 *        is de-energised after that many milliseconds (blocking call on the
 *        caller's task — keep short; 800 ms default).
 *
 * When CONFIG_ZACUS_P7_COFFRE_ENABLE=n this is a no-op.
 */
void p7_coffre_unlock(void);

/**
 * @brief Re-arm the coffre to the locked position (between games).
 *
 * Servo: moves back to CONFIG_ZACUS_P7_SERVO_LOCK_DEG.
 * Relay: de-energises the coil (if not already de-energised by the pulse).
 *
 * When CONFIG_ZACUS_P7_COFFRE_ENABLE=n this is a no-op.
 */
void p7_coffre_lock(void);

#ifdef __cplusplus
}
#endif
