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.
Engine-only (rules engine, no Docker)
If you only want the Python rules engine (no full platform stack):
pip install open-fdd
Then run the standalone examples from:
🚀 Platform Deployment (Docker)
git clone https://github.com/bbartling/open-fdd.git
cd open-fdd
./scripts/bootstrap.sh
For reverse-proxy deployments, frontend API calls default to VITE_API_BASE=/api and Caddy maps /api, /auth, and /ws to the API service. If you deploy without Caddy, override VITE_API_BASE in a compose override file (example: VITE_API_BASE=http://your-api-host:8000).
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)
All OpenClaw work starts from openclaw/README.md — that page is the single entry (mission, skills, bench tests, MCP/auth, and links to product integration docs).
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
Optional: rdflib (Brick TTL), matplotlib (viz)
Contributing
Open PRs against the current integration branch (e.g. develop or develop/vX.Y.Z), not master — master is release-only and protected.
Tests: ./scripts/bootstrap.sh --test (frontend + pytest + Caddy; frontend tries Docker then host npm), or from repo root:
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -v
.[dev] pulls in the full Python test deps; pyproject.toml sets default test paths. More detail: docs/contributing.md. Ask in #dev-chat on Discord if the active integration branch is unclear.
Fork sync (once add upstream, then as needed):
git remote add upstream https://github.com/bbartling/open-fdd.git
git fetch upstream && git checkout develop && git merge upstream/develop && git push origin develop
(Use your real integration branch name instead of develop if the project is on a versioned line.)
License
MIT