CHAPTER 06Maintenance Guide
Routine tasks, troubleshooting procedures, and development roadmap.
6.1 Routine Check Schedule
| Frequency | Task | How |
|---|---|---|
| Daily | Access log is updating | Open prox.tcec.ca — new entries should appear |
| Daily | Nest Mini available | HA → Devices → media_player.therese_office_122a |
| Weekly | HA backup written to QNAP1 | QNAP1 web UI → ha_backups_pi5 — check timestamps |
| Weekly | AppDaemon log review | HA → Add-ons → AppDaemon → Log — look for ERROR/WARNING |
| Monthly | QNAP1 storage and drive health | SMART warnings on drives 1 and 4 · volume 93% full — plan migration |
| Monthly | Test swipe on each active reader | Swipe known card — verify Granted logged and strike fires |
| Monthly | Verify ElevenLabs API key active | grep elevenlabs apps.yaml; test announcement from HA Developer Tools |
6.2 SSH and Log Tailing
ssh oracle@192.168.191.121
# Tail AppDaemon log
tail -f /addon_configs/a0d7b954_appdaemon/logs/appdaemon.log
# Last 20 access log entries
sqlite3 /config/prox_cards.db \
'SELECT timestamp, door_id, display_result FROM access_log ORDER BY id DESC LIMIT 20;'6.3 apps.yaml — Preservation Rule
WARNING — Keys Lost on Rewrite: Before any apps.yaml edit, read the current file and confirm both ElevenLabs keys exist under both prox_card and prox_ui. Verify again after writing.
# 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_ui6.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.yamlIf hot reload does not take effect: HA → Settings → Add-ons → AppDaemon → Restart.
Duplicate Entry Bug: A duplicate entry at the top of apps.yaml without a
class: line causes silent parse failures — the app shows no startup message. Always lint apps.yaml after edits.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.py6.6 Updating the Documentation
Each chapter is an independent HTML file in /homeassistant/www/manual/. To update a chapter:
- In a Claude session, describe what changed and which chapter to update.
- Claude regenerates that chapter file with a new revision date.
- Upload the replacement file via FileZilla (SFTP to 192.168.191.121) to
/homeassistant/www/manual/. - Reload the page — no server restart required.
- The index page shows the revision date for each chapter independently.
The build source files (_shared.js and build.js) are the source of truth — request updated files from Claude rather than editing HTML directly.
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 neededKnown Limitation: On-screen keyboards cannot appear over Chromium
--start-fullscreen. This is an OS constraint, not a bug.6.8 Backup and Recovery
- HA backs up
/config/daily to QNAP1 shareha_backups_pi5via SMB. - SQLite DB at
/config/prox_cards.dbis included in every HA backup. - Restore: HA → Settings → Backups → select → Restore. Verify ElevenLabs keys in apps.yaml immediately after.
# Manual DB text backup
sqlite3 /config/prox_cards.db .dump > /config/prox_cards_backup_$(date +%Y%m%d).sql6.9 Development Roadmap
| Priority | Task | Detail |
|---|---|---|
| 1 — Now | Implement fire_strike() | Add ha_entity column to doors table; call correct Waveshare relay switch entity on access granted. |
| 2 | Viking C-4000 LOG BUS | USB-to-serial adapter; 1200 baud ASCII; deploy VikingEntryLogger; map slot numbers via TENANT_MAP. |
| 3 | Blue Iris HA integration | Create Blue Iris user (requires desktop at 192.168.191.80); complete motion/snapshot triggers. |
| 4 | Blue Iris → QNAP1 storage | Redirect recordings to blueiris_recordings share — requires physical or RDP access to Blue Iris PC. |
| 5 | QNAP1 drive replacement | Drives 1 and 4 have SMART warnings; 93% full. Migrate to spare drives before failure. |
| 6 | Full alarm system | Multi-step arming, presence-based siren, post-siren audio loop, report-not-completed flag. |