====== Valves, Pumps & Actuation ======

The **Actuation Layer** defines all AOFS-compliant devices that perform actions on the farm.  
This includes irrigation pumps, valves, gates, and optionally generator start/stop controls.  

All actuators must comply with AOFS **safety, logging, and operational rules**, even if the system operates offline.

===== 1. Core Actuators =====

  * **Pumps**  
    * Controls water delivery from sources to storage tanks or irrigation manifolds.  
    * Must support:
      * Start/stop commands from [[architecture:field_controller:start|Field Controller]].  
      * Safety interlocks (tank FULL/LOW, low voltage, pressure limits).  
      * Optional energy-aware operation: integrate with [[electrical:start|Power & Energy Sensors]] to adjust schedule or warn operators.
  
  * **Valves**  
    * Operate irrigation zones, distribution manifolds, or auxiliary water lines.  
    * Must support:
      * Open/close commands from Field Controller.  
      * Flow or pressure monitoring feedback from [[sensors:start|Water Monitoring Sensors]].  
      * Fail-safe closure in case of errors, power loss, or critical alarms.
  
  * **Optional Generator Start / Stop**  
    * See [[electrical:start#optional-generator-integration|Optional Generator Integration]].  
    * Can be automatic (remote start) or manual (operator alert).  
    * Must respect safety interlocks and event prioritization.

===== 2. Actuation Control Principles =====

  * **Local Authority:**  
    * All critical actuation commands are decided by the Field Controller.  
    * No remote system may bypass fail-safes or directly actuate pumps/valves.  

  * **Fail-Safe Operation:**  
    * Hardware and software protections prevent flooding, over-irrigation, pump damage, or valve misoperation.  
    * Actuators must respond to [[sensors:start|Sensors]] such as LOW/FULL tank switches, flow/pressure limits, and emergency stop signals.

  * **Energy-Aware Operation (Optional):**  
    * Actuators may integrate with [[electrical:start#optional-energy-aware-operation|Energy-Aware Operation Module]].  
    * Event execution can be:
      * Delayed or skipped if insufficient energy is available.  
      * Prioritized based on urgency or operator-defined importance.  
    * System may alert operators if an actuator is consuming **more power than expected**, indicating possible maintenance needs (e.g., clogged pipe).

===== 3. Scheduling & Automation =====

  * **Event-Based Operation:**  
    * Pumps and valves operate according to **scheduled irrigation events** defined in the Field Controller.  
    * Can be triggered manually by operators or via automation rules.

  * **Integration with Sensors:**  
    * Actuators rely on [[sensors:start|Sensors & Environmental Monitoring]] for safe and efficient operation:  
      * Soil moisture thresholds  
      * Tank levels  
      * Pressure and flow rates  
      * Optional power measurements

  * **Manual Override:**  
    * Operators can manually actuate pumps or valves, respecting hardware safety interlocks.  
    * Manual events are logged and visible to Farm/HQ controllers.

===== 4. Logging & Documentation =====

  * All actuator events **must be logged locally** on the Field Controller:
    * Event type (pump start/stop, valve open/close, generator start/stop)  
    * Timestamp  
    * Operator ID (if manual)  
    * Relevant sensor readings at the time of actuation (flow, pressure, battery, energy)  

  * Logs are **synchronized with Farm and HQ Controllers** when connectivity is available.  
  * Supports analytics, energy assessment, and audit for compliance purposes.

===== 5. Optional Modules & Extensions =====

  * AOFS modules may define additional actuator types:
    * Greenhouse vents, fans, heaters, nutrient dosing pumps  
    * Livestock feeders, water dispensers  
    * Poultry egg collection or environmental actuators  

  * Any custom actuator must:
    * Integrate with Field Controller fail-safes.  
    * Support logging and optional energy-aware prioritization.  
    * Follow AOFS modular interface rules.

===== 6. Optional Energy-Aware Operation =====

  * AOFS controllers **may** measure power consumption of pumps, valves, and other actuators while running.  
  * Controllers **may** estimate battery drain or energy availability for upcoming scheduled irrigation events.  
  * AOFS supports **event prioritization**:
    * Each scheduled irrigation or actuator event can be assigned an **urgency or importance level** by operators.  
    * If insufficient energy is available:
      * Low-priority events can be **delayed or skipped**.  
      * High-priority events are executed **as soon as sufficient energy is available**.  
      * Optional alerts notify operators of skipped or delayed events.  
  * AOFS can provide **proactive scheduling guidance** (optional):
    * When the operator attempts to schedule an irrigation or actuator event, the system **may simulate expected energy usage and availability**.  
    * The controller can then **warn the operator**: "Based on current energy estimates, you will most likely not have enough power for this event."  
    * Operators may then adjust **priority, timing, or load** before committing the schedule.  
  * All energy measurements, prioritization decisions, and resulting operational logs **may be recorded** for later analysis:
    * Enables visualization of energy usage and event execution history.  
    * Helps operators determine if additional batteries, solar panels, or load rescheduling are needed.  
  * Optional anomaly detection:
    * Alerts operators if an actuator consumes more power than expected (e.g., clogged pipe, stuck valve).

===== 7. Manual Fallback Mode =====

AOFS supports **manual fallback operation** for farms without fully automated actuators.  

  * **Purpose:**  
    * Ensure irrigation and critical farm operations can continue when automatic valves or pumps are unavailable.  
    * Maintain safety, compliance, and event logging even with manual operation.  

  * **Operation:**  
    * Field Controller generates **step-by-step instructions** for operators:
      * Which pump to switch on/off.  
      * Which valve to set to open/closed or partial position.  
      * Timing recommendations based on **irrigation schedule, soil moisture, tank levels, and weather conditions**.  
    * Operators must **confirm completion of each step** in the controller interface.  

  * **Logging & Documentation:**  
    * All manual actions **must be logged**:
      * Operator ID  
      * Action taken (pump/valve)  
      * Timestamp  
      * Relevant sensor readings at the time (tank level, flow, battery voltage, etc.)  
    * Logs are synchronized with Farm/HQ controllers whenever connectivity is available.  

  * **Benefits:**  
    * Allows farms to **comply with AOFS even with low-tech equipment**.  
    * Ensures operators follow optimized schedules and safety procedures.  
    * Enables full **auditing and analytics** later when automation is introduced.  

===== 8. References =====

  * [[sensors:start|Sensors & Environmental Monitoring]]  
  * [[electrical:start|Electrical & Power Control Interfaces]]  
  * [[operations:start|Operational Logic & Decision Hierarchy]]  
  * [[hydraulics:start|Hydraulic & Water Systems]]  
  * [[electrical:start#optional-generator-integration|Optional Generator Integration]]  
  * [[electrical:start#optional-energy-aware-operation|Optional Energy-Aware Operation]]