====== Measuring, Monitoring & Documentation Systems ======

The **Sensors Layer** defines all devices and documentation systems used by AOFS controllers to ensure **safe operation, authoritative control, and auditable farm management**.

All AOFS-compliant deployments **must implement the sensors and documentation systems specified here**.

===== 1. Sensor Layer Scope & Authority =====

AOFS sensors are classified by **operational authority**, not by technology type.

Sensor inputs fall into four functional roles:

  * **Safety enforcement** (prevent damage or loss)
  * **Authoritative control inputs** (drive irrigation decisions)
  * **Documentation & audit**
  * **Optimization & research**

AOFS controllers **must never depend on remote systems** to interpret or validate sensor data.

===== 2. Critical Safety & Protection Sensors =====

**Purpose:** Prevent equipment damage, flooding, dry-run pumps, and unsafe operating states.

**Mandatory Measurements:**
  * Tank levels: LOW and FULL float switches
  * Flow meters on main and zoned pipelines
  * Pressure sensors on pumps and main distribution lines
  * Rainfall measurement for irrigation lockout

**Safety Requirements:**
  * These sensors **must directly enforce Field Controller fail-safes**
  * Operation must be fully local and offline
  * Loss or invalid data from these sensors must trigger safe shutdown or degraded mode

===== 3. Primary Agronomic Control Sensors =====

==== Soil Monitoring Sensors ====

**Purpose:** Provide authoritative inputs for irrigation scheduling.

**Required Measurements:**
  * Soil moisture (volumetric water content) per irrigation zone

**Optional but Recommended:**
  * Soil temperature
  * Electrical conductivity (salinity)

**Placement Guidelines:**
  * At least one sensor per irrigation zone
  * Additional sensors for heterogeneous fields
  * Placement at crop-appropriate root depth

==== Weather Monitoring Sensors ====

**Purpose:** Modify irrigation behavior and enforce environmental lockouts.

**Required Measurements:**
  * Rainfall
  * Ambient temperature
  * Relative humidity

**Optional Measurements:**
  * Wind speed
  * Solar radiation / light intensity

**Integration with AOFS:**
  * Rainfall triggers irrigation suspension
  * Weather data refines thresholds and scheduling

===== 4. Power / Energy Monitoring =====

**Purpose:** Protect electrical systems and support energy-aware operation.

**Required Measurements:**
  * Pump power consumption
  * Valve power consumption

**Optional Measurements:**
  * Battery voltage and current
  * Solar panel output

**Integration:**
  * Low-voltage or overload conditions must trigger fail-safe behavior
  * Energy data may inform event prioritization and anomaly detection

==== Grid Power Monitoring & Predictive Use ====

**Purpose:** Enable AOFS to safely use intermittent grid power and optimize energy costs.

**Required Measurements (if grid is available):**
  * Grid voltage, current, and frequency
  * Short-term fluctuations and harmonics
  * Availability signal (on/off)

**Optional Measurements:**
  * Historical grid availability patterns
  * Probabilistic prediction of grid power for upcoming hours

**Integration & Control Logic:**
  * AOFS must only allow grid power usage if parameters are within safe thresholds
  * Automatic relays and actuators must cut off grid supply immediately on overvoltage, under-voltage, or unsafe frequency
  * Predictive patterns can inform decisions, e.g., delaying high-load pump operations until grid is likely available
  * All local safety thresholds remain authoritative and override probabilistic logic

===== 5. Water / Water Energy Monitoring =====

**Purpose:** Monitor and optimize water supply sources, including grid water, local wells, and storage tanks.

**Required Measurements:**
  * Tank LOW and FULL levels
  * Flow rate in main and zoned pipelines
  * Flow rate and pressure of grid water supply (if available)
  * Availability signal for grid water (on/off)

**Optional Measurements:**
  * Historical grid water supply patterns
  * Probability of grid water availability in next hours or days
  * Water quality indicators (salinity, turbidity)

**Integration & Control Logic:**
  * AOFS may delay pumping from wells if probability of grid water availability is high
  * Partial tank fill strategies: maintain mandatory minimum levels locally, avoid overfilling if grid water is likely
  * Safety thresholds for tank levels must always be enforced, independent of probabilistic logic
  * Logging of decisions, sensor readings, and probabilities is required for learning and optimization

===== 6. Human Input / External Event Logging =====

**Purpose:** Capture critical farm activities not measurable by sensors.

AOFS treats human input as **first-class data**, equal to automated sensor measurements.

**Examples of Loggable Events:**
  * Fertilizer application
  * Manual irrigation or drainage
  * Pest or disease treatment
  * Planting, pruning, or harvest activities

**Requirements:**
  * All events must be timestamped
  * Events must be linked to a field or irrigation zone
  * Operator identity must be recorded
  * Full audit trail for edits or deletions is required

===== 7. Optical / Camera Documentation Systems =====

**Purpose:** Provide visual documentation for review, auditing, and optional analysis.

**AOFS Scope:**
  * Still images only
  * No video streaming requirements

**Use Cases:**
  * Crop development tracking
  * Soil surface condition documentation
  * Pest or disease observation

**Requirements:**
  * Images must be timestamped
  * Camera ID and zone reference required
  * Images stored locally on the Field Controller
  * Optional synchronization with Farm and HQ Controllers

AI-based image analysis is **explicitly optional** and must not interfere with core logging or manual review.

===== 8. Data Logging & Synchronization Rules =====

  * All sensor readings and human-input events **must be logged locally**
  * Logs must include:
    * Timestamp
    * Source or sensor ID
    * Measured value or event data
    * Status or quality flags
  * Synchronization follows AOFS federation rules
  * Loss of connectivity must never result in data loss
  * Grid power and water predictive measurements and decisions must be logged, including:
    - Probability estimates for predictive logic
    - Decisions made (pump on/off, fill levels)
    - Outcome of the decisions for future optimization

===== 9. Calibration & Maintenance =====

  * All sensors must be calibrated according to manufacturer specifications
  * AOFS deployments must log:
    * Calibration events
    * Maintenance actions
    * Sensor replacements
  * Calibration and maintenance logs are auditable and synchronized

===== 10. Compliance Requirements =====

Minimum mandatory implementation:

  * Soil moisture sensors per irrigation zone
  * Tank LOW and FULL level sensors
  * Flow meters and pressure sensors on irrigation systems
  * Power monitoring for pumps and valves
  * Rainfall measurement for irrigation lockout

Optional sensors enhance optimization and research but **do not affect baseline compliance**.

===== 11. References =====

  * [[architecture:field_controller:start|Field Controller Layer]]
  * [[architecture:farm_controller:start|Farm Controller Layer (Local / Federated)]]
  * [[hydraulics:start|Hydraulic & Water Systems]]
  * [[electrical:start|Electrical & Control Interfaces]]