====== Hydraulic & Water Systems ======

The **Hydraulics Layer** defines all physical water-handling components governed or monitored by AOFS controllers, including pumps, pipes, tanks, valves, and safety devices.

This layer is **safety-critical**.  
Hydraulic failures can cause flooding, crop loss, equipment damage, or long-term soil degradation.  
AOFS therefore treats hydraulics as a **first-class engineering domain**, not an implementation detail.

All AOFS-compliant deployments **must follow the principles and requirements defined here**.

===== 1. Scope & Authority =====

The Hydraulics Layer covers:

  * Water sources and intake systems
  * Storage tanks and reservoirs
  * Pumps and pumping stations
  * Distribution pipes and manifolds
  * Valves (automatic and manual)
  * Drainage and overflow paths

**Authority Rules:**
  * The **Field Controller** is the only system allowed to make authoritative hydraulic control decisions
  * Remote systems may configure schedules or parameters, but **may never bypass local hydraulic safety**
  * All hydraulic safety logic must function fully offline

===== 2. Core Design Principles =====

AOFS hydraulic systems must follow these non-negotiable principles:

  * **Fail-safe by default**  
    Loss of power, controller failure, or sensor failure must result in a safe hydraulic state
  * **Local autonomy**  
    Hydraulic operation must not depend on network connectivity
  * **Manual survivability**  
    The system must remain operable using manual valves and pumps
  * **Auditability**  
    All hydraulic actions must be logged, whether automatic or manual

===== 3. Water Sources =====

AOFS supports all sorts of water sources:

  * Boreholes / wells
  * Surface water (rivers, canals, dams)
  * Municipal supply
  * Rainwater harvesting
  * Recycled or treated water

**Requirements:**
  * Each source must be uniquely identified
  * Source availability and constraints must be configurable
  * Source switching (if supported) must be explicit and logged

Optional source-quality sensors (e.g. turbidity, EC) may be integrated but are not mandatory.

===== 4. Storage Tanks & Reservoirs =====

**Purpose:** Buffer water supply and protect pumps.

**Mandatory Requirements:**
  * LOW level sensor to prevent pump dry-run
  * FULL level sensor to prevent overflow
  * Defined overflow or spillway path

**Design Rules:**
  * Tank geometry and capacity must be documented
  * Overflow must never depend on powered components
  * Tank isolation valves must be accessible for manual operation

Tank level sensors are **safety-authoritative** and must directly enforce pump shutdown.

===== 5. Pumps =====

**Purpose:** Move water from source to storage or distribution.

**Pump Types:**
  * Submersible pumps
  * Surface centrifugal pumps
  * Booster pumps
  * Gravity-fed systems (no pump)

**AOFS Requirements:**
  * Each pump must have a unique identifier
  * Pump start/stop actions must be logged
  * Pump operation must be interlocked with:
    * Tank LOW level
    * Downstream pressure limits
    * Flow confirmation (if available)

**Safety Rules:**
  * Pumps must never run dry
  * Pumps must stop on over-pressure or zero-flow conditions
  * Manual pump operation must be explicitly logged when possible

===== 6. Distribution Network =====

**Purpose:** Deliver water from pumps or tanks to irrigation zones.

**Components:**
  * Main distribution lines
  * Manifolds
  * Zone pipelines
  * Filters and strainers

**Requirements:**
  * Flow meters on main and/or zoned lines
  * Pressure sensors on critical sections
  * Filters must be accessible for maintenance

**Design Considerations:**
  * Pipe sizing must match expected flow rates
  * Pressure losses must be documented
  * Air release and drain points are recommended

===== 7. Valves =====

AOFS explicitly supports **both automatic and manual valves**.

==== Automatic Valves ====

  * Electrically actuated (solenoid, motorized)
  * Controlled by the Field Controller
  * Valve open/close actions must be logged

**Safety:**
  * Default power-loss state must be defined (normally closed or open)
  * Valve state feedback is recommended but not mandatory

==== Manual Valves ====

Manual valves are **fully AOFS-compliant**.

If automatic valves are not present:

  * AOFS must generate clear, step-by-step instructions:
    * Which valve to operate
    * Required action (open/close)
    * Timing and duration
  * Operator confirmations must be logged:
    * Operator identity
    * Action taken
    * Timestamp
    * Relevant sensor context

Manual operation is not a degraded mode; it is a supported baseline configuration.

===== 8. Drainage, Overflow & Emergency Paths =====

**Purpose:** Prevent uncontrolled flooding and structural damage.

**Requirements:**
  * Defined drainage paths for excess water
  * Emergency overflow paths for tanks and basins
  * Drainage must function without power

**AOFS Safety Rules:**
  * Drainage paths must never be obstructed by controllable valves
  * Emergency water release must not depend on software logic

===== 9. Integration with Sensors =====

Hydraulic components are tightly coupled with the **Sensors Layer**.

Required integrations include:

  * Tank level sensors → pump enable/disable
  * Pressure sensors → pump and valve safety cutoffs
  * Flow meters → leak detection and flow confirmation
  * Rainfall sensors → irrigation lockout

Sensor failure or invalid data must result in a **safe hydraulic state**.

===== 10. Manual Operation & Fallback =====

AOFS systems **must remain operable without automation**.

Manual fallback includes:

  * Manual pump start/stop
  * Manual valve operation
  * Human confirmation workflows

All manual hydraulic actions should be logged whenever possible to preserve auditability.

===== 11. Documentation & Records =====

AOFS deployments must document:

  * Hydraulic schematics
  * Component identifiers
  * Pipe diameters and lengths
  * Pump specifications
  * Tank capacities

Changes to the hydraulic system must be recorded and versioned.

===== 12. Compliance Requirements =====

An AOFS-compliant hydraulic system must implement at minimum:

  * Defined water source(s)
  * Storage tank with LOW and FULL protection
  * Pump interlocks preventing dry-run and over-pressure
  * Flow and pressure monitoring
  * Manual operability of critical components

Optional enhancements must never weaken baseline safety guarantees.

===== 13. References =====

  * [[architecture:field_controller:start|Field Controller Layer]]
  * [[sensors:start|Sensors Layer]]
  * [[actuation:start|Actuation & Control]]
  * [[safety:start|Safety & Fail-Safe Design]]