====== Field Controller Layer ======

See overview: [[architecture:start|System Architecture Overview]]

The **Field Controller Layer** is the on-site, **safety-authoritative AOFS controller**.  
It is responsible for executing irrigation schedules, monitoring sensors, enforcing fail-safes, and ensuring reliable operation even **without network connectivity**.  

All AOFS deployments **must** include a Field Controller for each irrigation site or zone.

===== 1. Purpose =====

The Field Controller:

  * Executes irrigation schedules in real time.
  * Reads all field sensors and enforces safety logic.
  * Operates autonomously offline; cannot be bypassed by Farm or HQ Controllers.
  * Provides local operator monitoring for **non-critical functions only**.
  * Logs all events, including safety triggers, irrigation actions, and manual operator inputs.

---

===== 2. Core Responsibilities =====

1. **Irrigation Execution**  
   * Opens and closes valves according to schedules.  
   * Controls pumps based on tank levels, flow, and pressure.  
   * Stops irrigation when safety thresholds are exceeded.

2. **Sensor Monitoring**  
   * Soil moisture per zone  
   * Water tank levels (FULL / LOW floats)  
   * Flow meters and pressure sensors  
   * Battery voltage / current  
   * Rain detection (e.g., tipping bucket)  
   * Optional: Optical / camera data for local analytics  

3. **Fail-Safe Enforcement**  
   * Prevent over-irrigation, flooding, and pump damage.  
   * Stop pumps when tank is LOW or battery voltage below minimum.  
   * Stop irrigation during rain lockout or safety-triggered conditions.  
   * Operates independently of software updates or network availability.  

4. **Local Operator Interaction**  
   * Embedded interface (small touchscreen, local web UI, or buttons + display).  
   * Operators may view data, acknowledge alerts, or trigger **non-critical overrides** only.  
   * Critical irrigation decisions **cannot be overridden** by the operator.  

5. **Event Logging & Auditability**  
   * All irrigation events, sensor readings, alerts, and operator interactions must be logged with timestamps.  
   * Logs are persisted locally and later transmitted to Farm/HQ Controllers during sync.  

---

===== 3. Offline Operation Requirements =====

  * The Field Controller **must operate independently** of LAN, WiFi, or cellular connections.  
  * Irrigation, safety enforcement, and data collection must **continue uninterrupted**.  
  * Any local operator interface functions must **not compromise safety-critical rules**.  

---

===== 4. Optional Weather-Aware Control =====

  * Field Controllers operate fully offline by default using local sensors, operational logic, and historical data
  * When internet connectivity is available, controllers may fetch local or global weather forecasts
    * High wind, storm, or extreme precipitation warnings trigger automated alerts to operators
    * Controllers can temporarily maintain minimum water levels in tanks, suspend irrigation, or adjust equipment operation to prevent structural damage
    * Forecasts may also inform reservoir management, overflow routing, irrigation sequencing, and protective actions for farm structures
  * Local wind measurement devices are recommended at every farm to provide **real-time, farm-wide risk assessment**
    * Controllers evaluate wind conditions continuously for all critical infrastructure
    * Immediate actions are triggered if an asset is at risk (e.g., tanks, greenhouses, solar panels, or lightweight structures)
    * Actions may include maintaining minimum ballast, suspending irrigation, adjusting movable structures, or sending operator alerts
  * All forecast- and wind-informed actions are **non-normative** and optional; offline/manual operation remains fully functional
  * Actions based on wind measurements or forecasts **must never override core safety-critical rules**
  * All such preventive actions and alerts are logged for auditability

---

===== 5. Authority Rules =====

  * Field Controller is **fully authoritative** for all safety-critical operations.  
  * No remote controller or operator input can bypass Field Controller fail-safes.  
  * Farm or HQ Controllers may **suggest configuration or irrigation adjustments**, but Field Controller rules take precedence.  

---

===== 6. Human Interface =====

  * Minimal embedded UI for operators:  
    * View irrigation status per zone  
    * See safety alerts (tank LOW/FULL, battery low, rain lockout)  
    * Acknowledge alerts  
  * Operators **cannot override critical safety logic**.  
  * Operator actions are logged for audit purposes.  

---

===== 7. Hardware & Integration =====

  * Embedded microcontrollers (ESP32, Arduino, or industrial equivalent).  
  * Interfaces:  
    * PIO/relay control for pumps and valves  
    * Analog/digital inputs for sensors  
    * Optional serial / I2C / SPI for additional modules  
  * Power: must tolerate brownouts, low-voltage conditions, and recover automatically.  
  * Optional backup: small local battery or UPS to maintain control during power interruptions.  

---

===== 8. Compliance Notes =====

  * AOFS compliance **requires each field site to have a Field Controller**.  
  * All safety and irrigation decisions must be logged locally.  
  * Any attempt to bypass Field Controller logic by higher-layer controllers **invalidates AOFS compliance**.  
  * Field Controller must remain fully functional **even if disconnected from Farm or HQ controllers**.

---

===== 9. References =====

  * [[architecture:start|System Architecture Overview]]  
  * [[architecture:farm_controller:start|Farm Controller Layer (Local / Federated)]]  
  * [[hydraulics|Hydraulic & Water Systems]]  
  * [[electrical|Electrical & Control Interfaces]]  
  * [[sensors|Measuring, Monitoring & Documentation Systems]]