Open-FDD

Open-source semantic building analytics and HVAC supervisory fault detection. Local-first. On-premises. Vendor-neutral. Free to run at the edge or offline.

Open-FDD is an open-source analytics platform for building automation that combines semantic knowledge graph modeling, live operational technology (OT) data, and high-performance columnar analytics.

The platform includes:

• Semantic building modeling using Project Haystack knowledge graphs
• JWT authentication and a modern React web interface
• Apache Arrow & Feather columnar data storage
• Apache DataFusion SQL analytics and fault detection (59+ cookbook rules)
• BACnet, Modbus, Haystack, and JSON API drivers (fieldbus container)
• Interactive plotting, dashboards, and CSV job workflows
• Optional external agent integration via MCP stdio and JWT REST (no embedded chatbot)
• Docker compose build recipes published to GitHub Container Registry

Open-FDD supports flexible deployment recipes:

Standalone (all-on-edge)

mqtt + central + ui + fieldbus on one host — internal MQTTS, full OT + analytics.

Central hub

mqtt + central + ui — cloud or LAN hub; remote fieldbus edges attach over MQTTS.

Fieldbus edge only

fieldbus alone — attach to a remote central via MQTTS.

CSV-only

central + ui — bulk CSV jobs and FDD without pulling mqtt or fieldbus images.

FDD Rule Cookbook (the heart of the project)

The HVAC FDD Rule Cookbook is the validated catalog of 59 fault-detection rules, published in two parity-matched flavors:

• DataFusion SQL cookbook — copy-paste SQL that runs on the edge/central Arrow historian
• Pandas cookbook — the same rules for notebooks, CSV exports, and RCx studies

Rules use generic Haystack semantic roles, so they are portable across any modeled site. CI enforces a minimum of 59 rule headings in both cookbooks (scripts/cookbook_parity_check.py) — the catalog can never shrink.

Install / run

GHCR images

Open-FDD does not ship an embedded AI chatbot. External agents connect via MCP or REST — see docs/examples/external-agents.md.

Quick start (standalone)

git clone https://github.com/bbartling/open-fdd.git && cd open-fdd
export OPENFDD_IMAGE_TAG=nightly
export OPENFDD_JWT_SECRET='change-me'
export OPENFDD_ADMIN_PASSWORD='change-me'
./scripts/openfdd_stack_up.sh standalone
# UI http://127.0.0.1:3000  API http://127.0.0.1:8080

Other recipes

./scripts/openfdd_stack_up.sh csv          # central + ui only
./scripts/openfdd_stack_up.sh central      # hub without fieldbus
./scripts/openfdd_stack_up.sh edge         # fieldbus only (set OPENFDD_MQTT_HOST)

See Build recipes and docker/VERSION_MANIFEST.md.

MCP (external agents)

docker run -i --rm --network host \
  -e OPENFDD_API_BASE=http://127.0.0.1:8080 \
  -e OPENFDD_MCP_TOKEN="$TOKEN" \
  ghcr.io/bbartling/openfdd-mcp:nightly

Full tool list: mcp/README.md.

Develop

git clone https://github.com/bbartling/open-fdd.git && cd open-fdd
./scripts/openfdd_stack_up.sh csv --build   # or: cargo run -p openfdd-central
./scripts/openfdd_ui_dev.sh                 # Vite :5173 → API :8080

Native Rust: cargo test --workspace

Releases

Maintainers: Actions → Rust Release → set VERSION match + channel beta or stable.

Full policy: Release channels · GHCR images

Open-FDD is for LAN / VPN / OT networks, not public internet hosting.

License

MIT — see LICENSE.

Version: 3.3.0-beta.1 (next release candidate — see release channels)