Open-FDD is open-source fault detection and diagnostics (FDD) and retro-commissioning (RCx) for HVAC, packaged as a Normal Framework app. It runs on the building's NF edge box, reads the Haystack model and point history directly, and works on the local network or through the Normal Online portal.
- 77 SQL fault rules for air handlers, VAVs, plant, boilers, heat pumps, meters and sensors, run hourly inside NF. Results are written back as tagged NF points and can be served on NF's BACnet server.
- 60 retro-commissioning charts, CSV export, and an RDF model with a SPARQL query panel.
- All calculations in SI units; the display can be imperial or SI.
- No site-specific code: equipment and points are bound by Haystack tags and NF classes.
Open-FDD (nf-app/) |
Open-FDD Lite (lite/) |
|
|---|---|---|
| Hardware | 2 GB+ (4 GB+ for PGlite, TimescaleDB on larger hosts) | 1 GB, e.g. Raspberry Pi 3 |
| Includes | FDD engine, RCx charts, CSV export, SPARQL | Dashboard, charts, weather, BACnet mirror |
| Deploy | python3 scripts/nf/hooks/nf_app_sync.py --env <env> push nf-app/app.json |
... push lite/app.json |
Try it without an NF box, using a synthetic two-site building:
node nf-app/dev/mock-nf.mjs
# open http://127.0.0.1:8765/api/v1/apps/static/open-fdd/Install on an NF box (NF 3.10+): see the install guide (editions, one-command install, upgrade, troubleshooting). How API users read the results: FDD data access.
Run the tests:
node --test nf-app/tests/*.test.mjs lite/tests/*.test.mjs
(cd nf-app && npm ci && npm run typecheck)
python3 -m pytest tests -q| Path | Contents |
|---|---|
nf-app/ |
Full edition: UI, hooks, rule packs, tests, mock NF |
lite/ |
Lite edition |
sql/fdd/ |
Fault rules (SQL), registry, role scales, tuning catalog |
open_fdd/ |
PyPI package: pandas reference rules and NF agent tools |
scripts/nf/ |
Build and deploy tooling |
deploy/nf-caddy/ |
Optional Caddy front door |
docs/ |
Documentation site |
openfdd_agent_spec/ |
Guidance for AI coding agents |
The rules also run without NF: SQL on PostgreSQL / TimescaleDB, or pandas in Python. Imperial data (°F, inH₂O, cfm) is converted to SI first.
| SQL (PostgreSQL / TimescaleDB) | pandas (Python, used for testing) | |
|---|---|---|
| Rules | sql/fdd/postgres/rules/, one file per rule |
open_fdd/rules/, or pip install open-fdd |
| Cookbook | SQL cookbook: each rule's inputs, SI parameters and full SQL | pandas cookbook: source plus a runnable example per rule |
| Thresholds | sql/fdd/tuning_catalog.json: defaults for every rule |
SI defaults in each rule; any difference from SQL is listed in the parity report |
CI checks the two against each other; the parity report explains each known difference.
pip install open-fdd # ECM / ROI calculators and workbooks
pip install "open-fdd[nf,anomaly,ml]" # NF + SPARQL client, anomaly screening, ML detectorsExtras: oracle (pandas rules), nf, analytics, anomaly, ml, ml-copod, ontology, ontology-shacl, reporting, rdf, duckdb, postgres, ecm-web.
Commands: open-fdd-nf, open-fdd-anomaly, open-fdd-ml, open-fdd-report, open-fdd-ecm, open-fdd-ontology-audit, open-fdd-version.
Every tool with an example: PyPI agent tools.
The ML detectors are benchmarked on public LBNL AHU data: results.
The package (4.x) is versioned separately from the NF app (5.x).
Questions and discussion: Discord.
MIT. See LICENSE and CHANGELOG.md.
