View source for Architecture:Field Controller Layer

= Principles:Field Controller Layer =

See overview: [[Architecture:System_Architecture_Overview|System Architecture Overview]]

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

All AOWIS 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 ==

# '''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.

# '''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  

# '''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.  

# '''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.  

# '''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 ==

* AOWIS 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 AOWIS compliance'''.  
* Field Controller must remain fully functional '''even if disconnected from Farm or HQ controllers'''.

== 9. References ==

* [[Architecture:System_Architecture_Overview|System Architecture Overview]]  
* [[Architecture:Farm_Controller_Layer|Farm Controller Layer (Local / Federated)]]  
* [[Infrastructure:Hydraulic_&_Water_Systems|Hydraulic & Water Systems]]  
* [[Infrastructure:Electrical_&_Power_Control_Interfaces|Electrical & Control Interfaces]]  
* [[Measurement:Sensors_&_Environmental_Monitoring|Measuring, Monitoring & Documentation Systems]]