open-fdd 2.0.9

Fault Detection and Diagnostics for HVAC systems — config-driven, pandas-based

Open-FDD

PyPI: open-fdd

Open-FDD is an open-source knowledge graph fault-detection platform for HVAC systems that helps facilities optimize their energy usage and cost-savings. Because it runs on-prem, facilities never have to worry about a vendor hiking prices, going dark, or walking away with their data. The platform is an AFDD stack designed to run inside the building, behind the firewall, under the owner’s control. It transforms operational data into actionable, cost-saving insights and provides a secure integration layer that any cloud platform can use without vendor lock-in. U.S. Department of Energy research reports median energy savings of roughly 8–9% from FDD programs—meaningful annual savings depending on facility size and energy spend.

The building is modeled in a unified graph: Brick (sites, equipment, points), BACnet discovery RDF, platform config, and—as the project evolves—other ontologies such as ASHRAE 223P, in one semantic model queried via SPARQL and serialized to config/data_model.ttl.

---

Quick Start — Open-FDD AFDD Platform Manually by the Human

Open-FDD uses Docker and Docker Compose to orchestrate and manage all platform services within a unified containerized environment. The bootstrap script (./scripts/bootstrap.sh) is Linux only (tested on Ubuntu Server and Linux Mint, x86; should work on ARM but is untested). Windows is not supported.

🚀 Platform Deployment (Docker)

git clone https://github.com/bbartling/open-fdd.git
cd open-fdd
./scripts/bootstrap.sh

This will start the full AFDD edge stack locally: TimescaleDB, API, React UI, BACnet gateway/scraper, weather and FDD loops, and more. Grafana and an MQTT broker are optional (./scripts/bootstrap.sh --with-grafana, --with-mqtt-bridge); see Getting Started. The default protocol is BACnet for commercial building automation data. Future releases may add other data sources such as REST/API and Modbus.

Also available is the partial stack mode: ./scripts/bootstrap.sh --mode collector, --mode model, or --mode engine. See Modular architecture for the service matrix and mode behavior.

Quick Start — OpenClaw (agent)

OpenClaw agents should use the in-repo skill/docs only—start at openclaw/SKILL.md, openclaw/README.md, and openclaw/HANDOFF_PROTOCOL.md—defaulting to web-app/testing workflows (plus ./scripts/bootstrap.sh --test) and using AI data-modeling or virtual-operator modes only when explicitly requested, with HTTP tool discovery at http://localhost:8000/mcp/manifest (and optional RAG http://localhost:8090/manifest) using Bearer OFDD_API_KEY from stack/.env (split-machine setup: OpenClaw integration).

Development: branches and tests

Work off the develop branch for day-to-day development; open feature branches from develop and merge back to develop. Releases are cut from master. No Docker needed for the test suite. From the repo root:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -v

• .[dev] installs pytest, black, aiohttp, and platform deps so the full suite (open_fdd + HA integration tests) runs.
• ./scripts/bootstrap.sh --test runs frontend checks + pytest + Caddy validate; frontend checks try container-first and fall back to host npm when needed. Pytest includes test_rdflib_sparql_stack.py, which runs the same SPARQL path as POST /data-model/sparql so a broken rdflib + pyparsing install fails CI before you deploy.
• Test paths are set in pyproject.toml (open_fdd/tests, stack/ha_integration/tests). Run pytest with no path to use them.
• Style and workflow: docs/contributing.md.

Note: If a develop branch does not exist, please request one in the #dev-chat channel on Discord.

---

The open-fdd Pyramid

If OpenFDD nails the ontology, the project will be a huge success: an open-source knowledge graph for buildings. Everything else is just a nice add-on.

---

Online Documentation

• 📖 Docs — GitHub Pages (Linux quick start, stack, reference).
• 📕 Documentation PDF — offline / print-friendly bundle.
• ✨ LLM prompt (copy/paste template) — canonical text on the docs site (same section as LLM workflow); GitHub Pages serves this path without a trailing slash.

---

Dependencies

pandas · PyYAML · FastAPI

Optional: rdflib (Brick TTL), matplotlib (viz)

---

Contributing

Contributions welcome — Please use the develop branch for integration. Open pull requests into develop, not master. Branch from develop for your work; master is reserved for releases and is protected. PR's to the master branch will be rejected.

Syncing your fork with upstream

To bring your fork up to date with the latest develop from this repo:

# Add the upstream repo once (replace with this repo’s URL if you forked from another fork)
git remote add upstream https://github.com/bbartling/open-fdd.git

# Fetch upstream and update your local develop
git fetch upstream
git checkout develop
git merge upstream/develop
git push origin develop

Then rebase or merge develop into your feature branch as needed. Use git pull --rebase upstream develop on your branch if you prefer a linear history.

Run unit tests before pushing to GitHub

~/open-fdd$ bash scripts/bootstrap.sh --test

---

License

MIT