Executable, engine-verified HVAC fault detection rules. Every rule is a CDL block graph, shipped as CXF JSON-LD that the open-control engine loads directly — no code generation, no black box.
📖 Browse the library — every rule, playbook, and point dictionary, published as a book.
Status: early access. Shared for review ahead of a broader release; content and contracts may still change.
Most FDD libraries are papers, spreadsheets, or vendor black boxes. This one runs — and you can audit every step, from the plain-language fault card down to the exact logic the engine verified.
Each rule is one folder of four files that travel together:
| File | What it is |
|---|---|
card.md |
the fault card — what the rule detects, the points and parameters it needs, likely diagnoses, energy impact, and every judgment call written down |
rule.cxf.jsonld |
the detection logic itself, as elementary CDL blocks |
vectors.json |
executable test scenarios that pin the rule's behavior from both sides of every threshold |
diagram.svg |
the block graph, drawn |
A rule is marked verified only when the engine at a pinned revision
replays every vector green. The engine's content_id is stamped on the card,
so the verified logic stays identifiable forever.
Here's a real one — AHU-0016, simultaneous heating and cooling:
- 137 verified fault rules across fourteen equipment families — air handlers, VAV boxes, fan-powered terminals, rooftop units, heat pumps, chillers, cooling towers, hot-water plants, hydronic heat exchangers, fan coils, energy recovery ventilators, pumps, VFDs, and cross-equipment sensor-health rules. The Fault Code Map lists them all.
- Point dictionaries (
points/) — every canonical point name grounded in Brick 1.4.4 and ASHRAE 223P, so binding a rule to a real building is mechanical. - Remediation playbooks (
playbooks/) — verify → remote fix → on-site service → confirm, with typical costs and times. - Fault clusters (
clusters/) — faults that share a root cause, with a trigger rule and a fix order. - CI verification (
tools/verify) — every push replays every rule against the pinned engine.
Every card cites its sources — standards, research reports, and this library's own simulation studies — and records each place the rule departs from them. The detail lives on the cards; start with any rule in the book.
The graph computes fault-given-valid-data, and only that. Data quality, operating-state gating, and suppression are host concerns, declared on the card for the host to enforce — never buried in the logic. Rules stay portable, and every judgment call is written down where a reviewer can disagree with it.
# read the contracts
$EDITOR SCHEMA.md
# run one rule's vectors against the engine (sibling checkout of open-control required)
cargo run --manifest-path tools/verify/Cargo.toml -- faults/ahu/AHU-0016
# run everything
cargo run --manifest-path tools/verify/Cargo.toml -- --all
# build the book locally
python3 tools/book/generate.py && mdbook serve book --openSCHEMA.md— the normative contracts. Read this first.faults/<equip>/<FAULT-ID>/— one folder per rule;faults/registry.jsonmaps them all.points/— canonical point dictionaries.playbooks/,clusters/— remediation workflows and fault syndromes.tools/— the verifier, lints, and book generator.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.