HVAC FDD Rule Cookbook

Open-source, standards-first fault detection for commercial HVAC. Rules use generic semantic variables (sat, oat, fan_cmd, …) — portable across Haystack-modeled sites and generic BAS telemetry.

Two cookbooks — exact parity target

Cookbook Runtime Use when
DataFusion SQL Open-FDD edge Live historian, /sql-fdd, API test-sql, confirmation engine
Pandas Outside Open-FDD CSV exports, notebooks, RCx, parity checks, public benchmarks

Every rule exists in both backends. See the parity matrix.

Framework

Doc Description
P0 rule catalog Full metadata for every shipped rule
Public taxonomy Equipment classes, rule families, severity
Rule schema Declarative metadata — compiles to SQL + Pandas
Gap matrix Coverage vs ASHRAE GL36, Berkeley, PNNL, NIST
Parity matrix SQL ↔ Pandas audit
Roadmap Priority-ranked expansion
Prerequisite macros Occupancy, fan proven, reset, override guards
Benchmark strategy Fixtures + regression (scripts/cookbook_parity_check.py)
Doc template Standard per-rule documentation

Rule inventory (summary)

Family Count Examples
Sensor validation 7 SV-1–SV-7
AHU GL36 (FC1–FC15) 15 Duct static, MAT envelope, PID hunting
VAV terminals 7 Comfort, reheat, damper, airflow bias, min flow
Economizer / ventilation 7 ECON-1–5, OA-1–2
Central plant 6 CHW ΔT, DP, reset, tower approach
Extended v2 12 Reset, schedule, override, cmd/status, leakage
Extended P2 6 VAV-6/7, TOWER-1, CTRL-2, SV-7, OA-2
Trim & respond 4 GL36 advisory
Heat pump / weather 3 HP-1, WX-1–2

Total: 60+ rules with catalog metadata. Default confirmation: 300 s (5 min).

Quick start

  1. Assignments — bind driver points → Haystack → FDD inputs (modeling guide)
  2. Plots — confirm historian columns
  3. SQL FDD Rules — paste SQL, test with confirmation_seconds: 300, activate (integrator)
  4. Pandas parity — export same window, run matching Pandas section

API quick test 

curl -s -X POST http://127.0.0.1:8080/api/fdd-rules/RULE_ID/test-sql \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"sql":"<SELECT ... fault_raw>","confirmation_seconds":300}' | jq '.ok, .engine'

Safety (edge)

  • SELECT only — DDL/DML rejected
  • Every rule exposes fault_raw (boolean)
  • Integrator JWT required to activate rules
  • Thresholds are defaults — always site-adjustable

Table of contents