CHAPTER 06Maintenance Guide

Routine tasks, troubleshooting procedures, and development roadmap.

6.1 Routine Check Schedule

6.2 SSH and Log Tailing

ssh -i ~/Desktop/id_rsa root@192.168.191.121

# AppDaemon log (last 200 lines)
ha apps logs a0d7b954_appdaemon --lines 200

# Or via HA UI: Settings → Add-ons → AppDaemon → Log

For recent access events, use the Access Log page on prox.tcec.ca rather than querying the database directly — it has date/door/tenant/company filters built in.

6.3 apps.yaml — Preservation Rule

# Check before editing
grep elevenlabs /addon_configs/a0d7b954_appdaemon/apps/apps.yaml
# Should return 4 lines — api_key and voice_id under both prox_card and prox_ui

grep twilio /addon_configs/a0d7b954_appdaemon/apps/apps.yaml
# Should return 9 lines — sid, token, from under prox_card, prox_ui, and motion_monitor

6.4 Hot-Reloading AppDaemon Apps

# Reload after editing a Python file
touch /addon_configs/a0d7b954_appdaemon/apps/prox_card.py

# Reload after apps.yaml change
touch /addon_configs/a0d7b954_appdaemon/apps/apps.yaml

If hot reload does not take effect: HA → Settings → Add-ons → AppDaemon → Restart.

6.5 Patch App Pattern

# 1. Write patch app
vi /addon_configs/a0d7b954_appdaemon/apps/patch_xyz.py

# 2. Register in apps.yaml
# patch_xyz:
#   module: patch_xyz
#   class: PatchXyz

# 3. Trigger load
touch /addon_configs/a0d7b954_appdaemon/apps/apps.yaml

# 4. Verify ran, clean up — remove from apps.yaml, delete file
rm /addon_configs/a0d7b954_appdaemon/apps/patch_xyz.py

6.6 Updating the Documentation

Each chapter is a self-contained HTML file (inline CSS, no build step or shared JS) tracked in the local git repo at ~/tcec-access-control/manual/ and served from /homeassistant/www/manual/ on the Pi via prox_ui.py's serve_manual route. To update a chapter:

• In a Claude Code session, describe what changed and which chapter to update.
• Claude edits the HTML file directly and bumps its revision date.
• Deploy via scp to /homeassistant/www/manual/ (rsync is not available on the Pi).
• Reload the page — files are served fresh on each request, no AppDaemon restart required.
• Screenshots referenced by the docs live in manual/images/ alongside the chapter files.

6.7 Kiosk Troubleshooting (Pi 4)

ssh oracle@192.168.191.109

ps aux | grep chromium          # Is Chromium running?
bash /home/oracle/kiosk-watchdog.sh &  # Restart watchdog
nmcli connection show netplan-wlan0-EIS  # Check WiFi
sudo reboot                     # Reboot if needed

6.8 Backup and Recovery

• HA backs up /config/ daily to QNAP1 share ha_backups_pi5 via SMB.
• SQLite DB at /config/prox_cards.db is included in every HA backup.
• Restore: HA → Settings → Backups → select → Restore. Verify ElevenLabs keys in apps.yaml immediately after.

# Manual DB backup — always take one before running a migration
scp -i ~/Desktop/id_rsa root@192.168.191.121:/addon_configs/a0d7b954_appdaemon/prox_cards.db \
  ~/tcec-access-control/prox_cards_backup_$(date +%Y%m%d).db

A FileZilla copy of prox_cards.db works just as well and is the preferred method — always take one before running a schema migration. Migrations are done in-place via a temporary AppDaemon app (write it, register in apps.yaml, trigger via reload, confirm it ran, then remove it and the file) — never by export/reimport.

6.9 Development Roadmap