CHAPTER 04Configuration Files
All paths are on the Pi 5 (192.168.191.121). Access via SSH (key-based, see Chapter 6) or the HA file editor. HAOS is minimal — rsync is not installed; use scp/SFTP for file transfer.
4.1 AppDaemon — apps.yaml
Path: /addon_configs/a0d7b954_appdaemon/apps/apps.yaml
Critical — ElevenLabs Keys Lost on Rewrite Every time apps.yaml is rewritten during cleanup, the ElevenLabs credentials disappear. Before any edit, verify
elevenlabs_api_key and elevenlabs_voice_id are present under both prox_card and prox_ui.---
hello_world:
module: hello
class: HelloWorld
prox_card:
module: prox_card
class: ProxCard
twilio_sid: <SID> # MUST be preserved
twilio_token: <TOKEN> # MUST be preserved
twilio_from: +18166933464
elevenlabs_api_key: <KEY> # MUST be preserved
elevenlabs_voice_id: bAq8AI9QURijOtmeFFqT # Sigma Centauri
prox_ui:
module: prox_ui
class: ProxUI
twilio_sid: <SID> # MUST be preserved
twilio_token: <TOKEN> # MUST be preserved
twilio_from: +18166933464
elevenlabs_api_key: <KEY> # MUST be preserved
elevenlabs_voice_id: bAq8AI9QURijOtmeFFqT # Sigma Centauri
motion_monitor:
module: motion_monitor
class: MotionMonitor
twilio_sid: <SID> # MUST be preserved
twilio_token: <TOKEN> # MUST be preserved
twilio_from: +18166933464
4.2 AppDaemon App Files
| File | Path | Purpose |
|---|---|---|
| prox_card.py | /addon_configs/a0d7b954_appdaemon/apps/prox_card.py | Core access logic — MQTT card lookup and group-permission check; strike relay firing not yet live, see Chapter 1 |
| prox_ui.py | /addon_configs/a0d7b954_appdaemon/apps/prox_ui.py | Web UI; serve_snapshot and serve_manual routes; arm/disarm |
| prox_ui.html | /addon_configs/a0d7b954_appdaemon/apps/prox_ui.html | Main access control UI page template |
| motion_monitor.py | /addon_configs/a0d7b954_appdaemon/apps/motion_monitor.py | Camera motion handler |
| appdaemon.yaml | /addon_configs/a0d7b954_appdaemon/appdaemon.yaml | AD global config — log level, HA URL, lat/long |
4.3 SQLite Database
Path: /config/prox_cards.db
One card per tenant — the card number lives directly on tenants.card_number (format FFF:CCCCC, e.g. 011:31623; unassigned tenants get a UNASSIGNED-{id} placeholder since the column is NOT NULL UNIQUE). Door access is controlled by group membership, not a per-tenant permission list.
| Table | Key Columns | Purpose |
|---|---|---|
| tenants | id, name, card_number, unit, phone, email, status, user_group_id, company_id, viking_number | Registered building tenants — one row per person |
| doors | id, door_id, label, reader_id, gpio_info, is_exterior, ha_entity | Door definitions — 11 rows, see Chapter 1 |
| companies | id, name, viking_number | Tenant companies |
| tenant_types | id, name | Occupant / Lease Holder / Boss / Billing Contact |
| tenant_type_assignments | tenant_id, tenant_type_id | Many-to-many tenant ↔ type |
| door_keys | id, tenant_id, key_number, door_room, notes | Physical key tracking (unrelated to card access) |
| user_groups | id, name | Tenant access groups — e.g. Full-Time Tenants |
| door_groups | id, name | Door groupings — e.g. Outside Doors |
| door_group_members | door_group_id, door_id | Which doors belong to which door group |
| group_permissions | user_group_id, door_group_id | The live access-control matrix — which user groups can access which door groups. Managed on the Groups page. |
| access_log | id, card_number, tenant_id, tenant_name, door_id, door_label, result, deny_reason, display_result, created_at | Every swipe/arm/disarm event |
| access_log_images | id, log_id, image_path | Photos captured at access events |
| admin_accounts / trusted_devices / login_challenges / admin_audit_log | — | Passwordless SMS admin login — see 3.4 |
| building_state / arm_stations / arm_events / arm_event_images / post_arm_checks / post_arm_images | — | Arm/disarm state and post-arm camera checks |
door_permissions is legacy: An older per-tenant
door_permissions table still exists but is not used by current access-check logic — it's effectively empty. Don't add to it; use group_permissions via the Groups page instead.4.4 Web Content Paths
| Path | Purpose |
|---|---|
| /homeassistant/www/snapshots/ | TTS audio and camera images — served at /app/snapshot?f=filename |
| /homeassistant/www/snapshots/hal9000.jpg | HAL 9000 branding image |
| /homeassistant/www/snapshots/hal_speech.mp3 | ElevenLabs TTS audio — regenerated per announcement |
| /homeassistant/www/manual/ | HTML documentation — served at /app/manual?f=filename |
Wrong Path — Silent Failure: The correct snapshot path is
/homeassistant/www/snapshots/ — not /config/www/snapshots/. Files written to the wrong path are not served and no error is raised.4.5 ESPHome Device Configs
| File | Purpose |
|---|---|
| /config/esphome/wiegand-readers.yaml | Freenove #1 (192.168.191.64) — 7 Wiegand reader GPIO mappings |
| /config/esphome/wiegand-readers-2.yaml | Freenove #2 (192.168.191.73) — 4 Wiegand reader GPIO mappings + 1 spare header |
| /config/esphome/access_control.yaml | Waveshare relay board #1 (192.168.191.100) — 7 strike switch entities |
| /config/esphome/access_control_2.yaml | Waveshare relay board #2 (192.168.191.101) — 3 strike switch entities |
# All Wiegand reader entries must specify pulldown:
wiegand:
- id: reader_123b
d0: GPIO4
d1: GPIO5
on_tag:
- mqtt.publish:
topic: woodhaven/prox/scan
payload: !lambda 'return "{\"door\":\"123b\",\"card\":\"" + x + "\"}";'
4.6 Kiosk Configuration (Pi 4 — 192.168.191.109)
| File / Setting | Value / Purpose |
|---|---|
| /home/oracle/kiosk-watchdog.sh | Watchdog — restarts Chromium if it exits |
| sudo crontab | 0 3 * * * — daily 3 AM reboot |
| NetworkManager connection | netplan-wlan0-EIS — WiFi profile for EIS.local |
| ~/.config/openbox/rc.xml | Keyboard lockdown — blocks F1–F12 and escape shortcuts |
| Chromium flags | --start-fullscreen (blocks external windows — no on-screen keyboard possible) |
4.7 QNAP1 Shared Folders (192.168.191.10)
| Share | Purpose | Access |
|---|---|---|
| ha_backups_pi5 | Daily HA backups from Pi 5 | SMB from Pi 5 (user: homeassistant) |
| blueiris_recordings | Blue Iris recordings — redirection pending | Blue Iris PC (requires desktop access) |
| access_control | Access log images and exports | Pi 5 via SMB |
| system_backups/pi5_image | Full Pi 5 disk images | Manual |