open-fdd 2.0.13

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

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 Starts

Open-FDD Engine-only (rules engine, no Docker) PyPi

If you only want the Python rules engine (without the full platform stack), you can use it in standard Python environments.

pip install open-fdd

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 and intended for IoT edge applications using Docker exclusively.

Debian / Ubuntu setup

• Git: Install Git if needed, e.g. sudo apt update && sudo apt install git.
• Docker: Follow the official guide to install Docker Engine (and Compose): Install Docker Engine on Ubuntu.

Prerequisites (Ubuntu / Debian-style)

After Docker is installed, add your Linux user to the docker group so you can run docker without sudo (log out and back in, or use newgrp, for the group change to apply):

sudo usermod -aG docker "$USER"
newgrp docker
docker ps

Create a Python virtual environment and install argon2-cffi (used to hash passwords for bootstrap):

python3 -m venv .venv
source .venv/bin/activate
pip install argon2-cffi

Clone the repository:

git clone https://github.com/bbartling/open-fdd.git

Standard HTTP bootstrap (no TLS) and app login

The --bacnet-address value is the static bind address for BACnet, which is the usual setup for BACnet/IP on operations technology (OT) LANs. Bootstrap supports dual-NIC hosts: use this address on the OT interface; your other interface can use DHCP for outbound internet access.

cd open-fdd

printf '%s' 'YourSecurePassword' | ./scripts/bootstrap.sh \
  --bacnet-address 192.168.204.16/24:47808 \
  --bacnet-instance 12345 \
  --user ben \
  --password-stdin

NOTE: Both the DIY BACnet server and Open-FDD API in the Standard HTTP bootstrap (no TLS) configuration still require bearer tokens for authorization. These are defined in open-fdd/stack/.env and are set during the bootstrapping process.

Standard hardened stack — self-signed TLS (Caddy) and app login

Open-FDD runs over TLS with self-signed certificates, and there is no access to the Open-FDD API or the DIY BACnet server Docker container APIs.

cd open-fdd

printf '%s' 'YourSecurePassword' | ./scripts/bootstrap.sh \
  --bacnet-address 192.168.204.16/24:47808 \
  --bacnet-instance 12345 \
  --user ben \
  --password-stdin \
  --caddy-self-signed

Bootstrap Troubleshooting

./scripts/bootstrap.sh --doctor

Also available is the partial stack mode: ./scripts/bootstrap.sh --mode collector, --mode model, or --mode engine. See the Docs below for more information.

---

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, Kindle-friendly documentation
• ✨ LLM prompt (copy/paste template) — export the data model (knowledge graph) as JSON, run an external LLM-assisted tagging workflow outside Open‑FDD, then re-import the JSON; the backend parses it on import.
• 🤖 Open‑Claw / external agents — GET /model-context/docs, GET /mcp/manifest, data-model export/import for your own OpenAI-compatible stack.

---

Dependencies

Authoritative lists and version pins: pyproject.toml (dependencies and [project.optional-dependencies]).

Core (installed with pip install open-fdd): pandas · PyYAML · PyJWT · argon2-cffi (password hashing for auth).

Platform / API (extras e.g. pip install "open-fdd[platform]" or .[dev] in a clone): FastAPI · Uvicorn · pydantic-settings · httpx · python-multipart · psycopg2-binary · requests · openai (optional AI client).

Brick / SPARQL / TTL (extra [brick] or bundled in .[dev]): rdflib · pyparsing (pinned range for SPARQL compatibility).

BACnet (extra [bacnet]): bacpypes3 · ifaddr · httpx.

Viz (extra [viz]): matplotlib.

---

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