Rev 2026-07-30 TCEC Access Control System Documentation

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

FilePathPurpose
prox_card.py/addon_configs/a0d7b954_appdaemon/apps/prox_card.pyCore 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.pyWeb UI; serve_snapshot and serve_manual routes; arm/disarm
prox_ui.html/addon_configs/a0d7b954_appdaemon/apps/prox_ui.htmlMain access control UI page template
motion_monitor.py/addon_configs/a0d7b954_appdaemon/apps/motion_monitor.pyCamera motion handler
appdaemon.yaml/addon_configs/a0d7b954_appdaemon/appdaemon.yamlAD 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.

TableKey ColumnsPurpose
tenantsid, name, card_number, unit, phone, email, status, user_group_id, company_id, viking_numberRegistered building tenants — one row per person
doorsid, door_id, label, reader_id, gpio_info, is_exterior, ha_entityDoor definitions — 11 rows, see Chapter 1
companiesid, name, viking_numberTenant companies
tenant_typesid, nameOccupant / Lease Holder / Boss / Billing Contact
tenant_type_assignmentstenant_id, tenant_type_idMany-to-many tenant ↔ type
door_keysid, tenant_id, key_number, door_room, notesPhysical key tracking (unrelated to card access)
user_groupsid, nameTenant access groups — e.g. Full-Time Tenants
door_groupsid, nameDoor groupings — e.g. Outside Doors
door_group_membersdoor_group_id, door_idWhich doors belong to which door group
group_permissionsuser_group_id, door_group_idThe live access-control matrix — which user groups can access which door groups. Managed on the Groups page.
access_logid, card_number, tenant_id, tenant_name, door_id, door_label, result, deny_reason, display_result, created_atEvery swipe/arm/disarm event
access_log_imagesid, log_id, image_pathPhotos captured at access events
admin_accounts / trusted_devices / login_challenges / admin_audit_logPasswordless SMS admin login — see 3.4
building_state / arm_stations / arm_events / arm_event_images / post_arm_checks / post_arm_imagesArm/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

PathPurpose
/homeassistant/www/snapshots/TTS audio and camera images — served at /app/snapshot?f=filename
/homeassistant/www/snapshots/hal9000.jpgHAL 9000 branding image
/homeassistant/www/snapshots/hal_speech.mp3ElevenLabs 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

FilePurpose
/config/esphome/wiegand-readers.yamlFreenove #1 (192.168.191.64) — 7 Wiegand reader GPIO mappings
/config/esphome/wiegand-readers-2.yamlFreenove #2 (192.168.191.73) — 4 Wiegand reader GPIO mappings + 1 spare header
/config/esphome/access_control.yamlWaveshare relay board #1 (192.168.191.100) — 7 strike switch entities
/config/esphome/access_control_2.yamlWaveshare 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 / SettingValue / Purpose
/home/oracle/kiosk-watchdog.shWatchdog — restarts Chromium if it exits
sudo crontab0 3 * * * — daily 3 AM reboot
NetworkManager connectionnetplan-wlan0-EIS — WiFi profile for EIS.local
~/.config/openbox/rc.xmlKeyboard 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)

SharePurposeAccess
ha_backups_pi5Daily HA backups from Pi 5SMB from Pi 5 (user: homeassistant)
blueiris_recordingsBlue Iris recordings — redirection pendingBlue Iris PC (requires desktop access)
access_controlAccess log images and exportsPi 5 via SMB
system_backups/pi5_imageFull Pi 5 disk imagesManual
← Previous3 · SoftwareNext →5 · User Manual