REFERENCE
AgriEnergy — Reference
Section titled “AgriEnergy — Reference”Single reference for algorithms, simulation, and integrations. The repo is public; this doc is the main technical entry point.
1. Algorithms
Section titled “1. Algorithms”Selection: GET /api/agrienergy/algorithms returns presets; the UI dropdown sends PATCH /api/agrienergy/trackers/{id}/algorithm with { "activeAlgorithm": { "id": "<preset_id>" } }. Stored in the tracker’s activeAlgorithm (NGSI-LD).
Built-in presets (all use fail-safe {"var": ["path", default]} and return { "tilt", "azimuth" }):
| Id | Name | Logic (summary) |
|---|---|---|
| default:maximize | Maximize production | GHI > 10 → 0°; else -60°. |
| default:hierarchical_failsafe | Hierarchical fail-safe (recommended) | Wind > 15 → 0°; stress_index > 0.8 → 70°; GHI > 10 → 0°; else -60°. |
| thermal_stress | Thermal stress (T > 35°C) | Shade 70°; else 0°. |
| wind_barrier | Wind barrier (> 15 m/s) | Tilt 75°; else 0°. |
| hydric_stress | Hydric stress (LSTM) | stress_index > 0.8 → 70°; else -60°. |
| frost_prevention | Frost (leaf_temperature ≤ 2°C) | Tilt 0°; else keep current. |
| par_optimization | PAR under panel < 800 | Standby -60°; else keep current. |
Adding a new algorithm: (1) Ensure data is in context (signalMapping for sensors; Intelligence for biology.*). (2) Write JSON Logic with var + default and return { "tilt", "azimuth" }. (3) Add an entry to AlgorithmEngine.builtin_algorithms() in backend/app/engines/algorithm_engine.py.
Tracker attribute rotationAxis (optional): north_south | east_west | two_axis. When set, single-axis trackers keep current azimuth; only tilt is applied from the rule.
2. Simulation
Section titled “2. Simulation”- One-shot: POST
/api/agrienergy/simulate— tracker, parcel, telemetry, target_tilt → expected_power_w, shadow_area_m2, shadow_polygon_2d. - Period: POST
/api/agrienergy/simulate-period— start, end, resolution, series (payload); returns time series of tilt, azimuth, expected_power_w, shadow_area_m2, optional stress_index. Full contract: SIMULATE_PERIOD_SPEC.md (limits wheninclude_biology, O(1) series lookup, state carry-over).
3. Intelligence (scalar bundle)
Section titled “3. Intelligence (scalar bundle)”AgriEnergy calls POST /api/intelligence/evaluate_status in the /notify flow (after building context and shadow). Request: tracker_id, parcel_id, timestamp, shadow_polygon_2d, telemetry. Response: scalar bundle (e.g. stress_index) → injected as context["biology"].
- Timeout: 200 ms. Intelligence must respond via fast read (e.g. Redis cache), not on-demand LSTM in the request.
- Fail-safe: On timeout/5xx, AgriEnergy sets
context["biology"] = {}. Rules use{"var": ["biology.stress_index", 0]}for defaults.
The Intelligence module (evaluate_status, worker, Redis) is implemented and maintained by a separate team; this contract is the interface.
4. Odoo / N8N (energy communities)
Section titled “4. Odoo / N8N (energy communities)”FinBridgeEmitter can POST to an N8N webhook with tenant_id, tracker_id, date, generation_wh, consumption_wh, surplus_wh, module. URL configurable via AGRIENERGY_N8N_WEBHOOK_URL.
Phase 8.2 (daily aggregation job) is blocked until the method for computing generation_wh is documented: either (1) hardware read (inverter/smart meter total energy) or (2) software integration (e.g. trapezoidal rule over measured_w time series in DataHub). Until then, no automatic daily job; FinBridgeEmitter is available for manual or external triggers.