Repository instructions

Language

Use French when communicating with the user unless they ask otherwise. All new technical artifacts must be in English: code, identifiers, variable and function names, Home Assistant entity and sensor names, log messages, comments, test names, configuration keys, and technical documentation. Do not rename existing French identifiers or entities unless explicitly requested.

Context

This repository is an AppDaemon configuration for Home Assistant. Python apps in apps/ control real equipment, including heating, shutters, lighting, a projector, and a television. Application configuration is in apps/apps.yaml, supplemented by YAML files in apps/global/ and apps/rooms/. Runtime configuration is in appdaemon.yaml.

apps/ad_toolbox is a shared Git submodule. It provides the base classes, conditions, virtual sensors, and logging used by the apps. Only change it when the request explicitly concerns that component. Do not update its revision or discard its local changes without approval.

Security and operations

Never display, copy into responses, or commit tokens, passwords, secrets.yaml, apps/theframe_token.txt, or persisted data in apps/data/. Refer to their paths and redact sensitive values in diagnostics.
Do not start a second AppDaemon instance, rerun dockerStart.sh, or execute archiveLogs.sh manually while the service is running. The archive script moves active log files.
Do not restart the container, send device commands, or change heating setpoints unless the user explicitly requests it. To test heating logic, use mocks first or send_commands: false where available.
Local AppDaemon-core and startup-script patches may exist outside this persistent repository. Read docs/appdaemon-local-changes.md and docs/appdaemon-upgrade-rollback-instructions.md before upgrading or changing the runtime. Do not overwrite or "clean up" these patches.

Logs and diagnosis

When asked to investigate a warning, error, or runtime behavior, inspect /conf/logs first:

appdaemon.log, error.log, and virtualsensors.log for the current run;
archive/<timestamp>/ for previous runs;
memory_usage.csv when memory use is suspected.

Always inspect the lines following a warning: a successful reconnection or recovery can make an incident transient. Distinguish application problems from Home Assistant, MQTT, or hardware connectivity losses.

Changes

Follow the style and conventions of the app or module being changed. Apps often inherit from SmartObject and use SmartCondition; do not bypass these abstractions without a clear reason.
Keep an app, its apps/apps.yaml entry, its Home Assistant entities, and any related apps/global/ or apps/rooms/ configuration consistent.
Preserve AppDaemon lifecycle behavior: cancel timers, tasks, listeners, and sockets on reload or termination when a change introduces them.
Do not overwrite or reorganize the user's existing work. Keep diffs limited to the requested change.
Update documentation in docs/ when operational behavior, a hardware protocol, or a deployment procedure changes.

Validation

The project uses unittest; no formatter or linter is configured. After a Python change, run the focused test when one exists, for example:

python3 -m unittest discover -s tests -p 'test_vertex2.py' -v
python3 -m unittest discover -s tests -p 'test_boilerclimate.py' -v
python3 -m unittest discover -s tests -p 'test_samsungtheframe_async.py' -v

For shared changes or before a broader delivery:

python3 -m unittest discover -s tests -v
python3 -m unittest discover -s apps/ad_toolbox/unit_tests -p 'test_*.py' -v

The legacy YAML test runner for ad_toolbox is:

python3 apps/ad_toolbox/unittests.py

After a shell-script change, validate syntax at minimum with sh -n <script>. Changes to the VS Code extension in apps/ad_toolbox/vscode-appdaemon/ must also follow its own AGENTS.md, including compilation, packaging, and installation.

4.0 KiB Raw Blame History