Skip to content
bbartlingPublic

About

Fault Detection Diagnostics (FDD) for HVAC datasets

Topics

Resources

Security policy

Stars

181 stars

Watchers

9 watching

Forks

Latest commit

 

History

2,638 Commits

Folders and files

Repository files navigation

Open-FDD

open-fdd: fault detection & analytics plugin for the Normal Framework

NF app CI Open-FDD Grok bot skills Security (ZAP, audit, gitleaks)

Online docs FDD Rule Cookbook — 77 SQL + 71 pandas, SI units Open-FDD on PyPI Quick start: install the NF app Normal Framework plugin ADR-014: Open-FDD as an NF plugin Open-FDD skills on Grok bot

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.

Editions

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

Quick start

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

Repository

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

FDD rules in SQL and pandas

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.

AI agent tools (Python)

pip install open-fdd                          # ECM / ROI calculators and workbooks
pip install "open-fdd[nf,anomaly,ml]"         # NF + SPARQL client, anomaly screening, ML detectors

Extras: 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).

Support

Support this work

Donations fund ongoing development and independent security testing.

Donate $25 via PayPal Donate $50 via PayPal Donate $250 via PayPal Choose a custom PayPal donation amount

Questions and discussion: Discord.

License

MIT. See LICENSE and CHANGELOG.md.

About

Fault Detection Diagnostics (FDD) for HVAC datasets

Topics

Resources

Security policy

Stars

181 stars

Watchers

9 watching

Forks

Releases

Packages

Used by

Contributors

Languages