# pfv-bms — Home Assistant configuration (Turnsys PFV)

Production Home Assistant configuration for a private residence +
server room: physical-plant environmental monitoring (temperatures,
power, UPS), server-room badge access control, and alerting.

Licensed under the [GNU AGPLv3](LICENSE) — see [AGPL compliance
notes](#license) below.

## What lives here

- `configuration.yaml` + `packages/` — the full running config,
  deployed to the HAOS box via a git-webhook pipeline
- `packages/doorman.yaml` — badge-scan ingest + whitelist decisions
  (server-room door access)
- `packages/plant_snmp.yaml` — fleet temperature/power sensors over
  SNMP (lm-sensors extends, iDRAC, UPS, PDU relay)
- `automations.yaml` — tiered thermal alerts + sensor watchdogs
- `dashboards/` — Lovelace dashboards

## Security model (read this before forking)

- **No secrets in git, ever.** Everything sensitive is `!secret`
  indirection into an on-box `secrets.yaml` (gitignored). Verified by
  full-history scans.
- **Badge IDs are NOT in this repo.** The badge roster lives in a
  separate *private* repository (`access-roster`, two-human PR gate)
  and is fetched live at runtime via the gitea API with a secret auth
  header. This repo contains only the decision logic.
- Battery-powered room sensors and lock integrations are cloud-fed;
  their credentials also live in `secrets.yaml`.

## Related

- Work tracking: [Redmine project 55](https://projects.knownelement.com)
  ([#344](https://projects.knownelement.com/issues/344) HA integration,
  [#345](https://projects.knownelement.com/issues/345) badge access,
  [#762](https://projects.knownelement.com/issues/762) publication)
- Documentation:
  [VP TechOps on Discourse](https://community.turnsys.com/c/vp-techops)
- Badge listener/relay code: [KNEL/doorman](https://git.knownelement.com/KNEL/doorman)
- Wider fleet (Proxmox, DNS, monitoring): [KNEL/PFVCluster](https://git.knownelement.com/KNEL/PFVCluster)

## License

Copyright © 2026 Known Element Enterprises / Charles Wyble.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version. See [LICENSE](LICENSE)
for the full text.