====== HQ / Federated Controller Layer ======

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

The **HQ / Federated Controller Layer** provides **multi-farm oversight, analytics, and management**.  
It sits above Farm Controllers in the AOFS hierarchy, enabling federation, global reporting, and configuration distribution while **never bypassing Field Controller safety rules**.

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

The HQ Controller:

  * Aggregates telemetry and logs from multiple Farm Controllers.  
  * Provides management dashboards, reporting, and analytics.  
  * Supports configuration distribution to Farm Controllers.  
  * Ensures Field Controller safety authority is always respected.  
  * Maintains an audit trail of all multi-farm operations and synchronization events.  

---

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

1. **Telemetry Aggregation**  
   * Collect irrigation events, sensor data, flow measurements, and operator logs from all Farm Controllers.  
   * Normalize and store data for reporting and analytics.  

2. **Analytics & Reporting**  
   * Multi-farm dashboards for water usage, energy consumption, irrigation efficiency, and crop outcomes.  
   * Alerts for anomalies across farms (e.g., persistent irrigation failures, abnormal flows, power shortages).  

3. **Configuration Distribution**  
   * Push authorized configuration changes or irrigation schedules to Farm Controllers.  
   * Ensure updates **do not violate local Field Controller safety rules**.  

4. **Audit Logging**  
   * Record all pushes, pulls, operator actions, and synchronization events.  
   * Preserve audit logs for regulatory compliance and traceability.  

---

===== 3. Federation / Push-Pull Model =====

The HQ Controller operates as part of AOFS’ **decentralized federation network**:

  * **Pull from Farm Controllers:**  
    - Retrieve logs, sensor data, irrigation events, and audit trails.  
    - Updates occur automatically or on-demand, queued if connectivity is unavailable.  

  * **Push to Farm Controllers:**  
    - Deliver configuration updates, irrigation schedules, or software/firmware updates.  
    - Changes are applied **only after Field Controller validation**.  

  * **Multi-HQ federation (optional):**  
    - HQ Controllers can sync with each other to share aggregated data, analytics, or best-practice configurations.  
    - Conflicts resolved via deterministic rules and logged.

---

===== 4. Authority Rules =====

  * **Safety authority:**  
    * Field Controllers retain full authority for all safety-critical operations.  
    * HQ Controller cannot directly actuate pumps, valves, or override irrigation cutoffs.  

  * **Supervisory authority:**  
    * HQ Controller may propose schedules, thresholds, and configurations.  
    * Farm Controllers apply changes according to local rules and validation.  

  * **Conflict resolution:**  
    * Timestamp precedence and operator approval at the farm level.  
    * Any conflicts that violate Field Controller rules are **blocked and logged**.  

---

===== 5. Human Interface =====

  * Web-based dashboards for multi-farm monitoring.  
  * Reporting modules for energy, water efficiency, and crop outcomes.  
  * Interfaces for authorized managers to submit configuration updates.  
  * Visualization of alerts, events, and historical performance.  
  * No interface may bypass Field Controller safety rules.  

---

===== 6. Offline Operation =====

  * HQ Controller may be offline; farm autonomy is **never compromised**.  
  * Logs and updates queue until connectivity is restored.  
  * HQ can continue analytics and dashboards locally with last synced data, but **cannot control irrigation in real-time** without live connection.

---

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

  * Hardware: industrial servers, cloud instances, or on-prem appliances.  
  * Communication protocols: secure LAN, WiFi, cellular, or VPN tunnels.  
  * Data storage: structured, versioned, and secure for multi-farm ingestion.  
  * Security: encryption for all communications; multi-factor authentication for operators.  
  * Scalability: supports hundreds of farms, multiple Farm Controllers per farm.  

---

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

  * HQ Controller **must never override Field Controller safety rules**.  
  * All multi-farm pushes, pulls, and operator actions must be logged.  
  * Deterministic conflict resolution must be implemented for configuration and schedule synchronization.  
  * Failure to respect authority hierarchy **invalidates AOFS compliance**.

---

===== 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]]