Home Assistant App Example

This repository serves as a reference implementation for creating Home Assistant add-ons. It demonstrates the standard structure and features required to build a functional, production-ready add-on.

Key architectural patterns demonstrated include:

• Configuration Management: Use of config.yaml and build.yaml files.
• Process Management: Implementation of the S6 overlay system to manage services.
• Containerization: Standard Dockerfile structure and deployment to the GitHub Container Registry.
• Utility Integration: Basic usage of Bashio and the Bash function library provided in the base images.
• Metadata: Proper use of the Docker label schema for Home Assistant compatibility.
• CI/CD: Automated workflows using GitHub Actions.

The installation process follows the standard Home Assistant add-on installation flow:

1. Open the app in your Home Assistant instance using the 'My Home Assistant' button.
2. Click the Install button.
3. Start the 'Example' app.
4. Check the app logs to verify it is running correctly.

The Example app can be configured via the Home Assistant add-on configuration interface. Note: You must restart the app for any configuration changes to take effect.

log_level: info
seconds_between_quotes: 5

The log_level option controls the verbosity of the application logs. This is useful for troubleshooting. Each level includes all messages from more severe levels (e.g., debug includes info).

Available values:

• trace: Show every detail, including all called internal functions.
• debug: Shows detailed debug information.
• info: Normal (usually) interesting events. (Default setting)
• warning: Exceptional occurrences that are not errors.
• error: Runtime errors that do not require immediate action.
• fatal: Critical errors that make the app unusable.

The seconds_between_quotes option sets the interval (in seconds) between the output of each random quote.

• Value range: 1 to 120 seconds.
• Default: 5 seconds.

The primary executable for this application is example1.sh. When running, the application enters an infinite loop where it fetches and displays a random quote, then waits for a specified interval before repeating the process.

It uses the bashio library to interact with the Home Assistant environment, specifically for logging, accessing configuration, and checking variables.

#!/command/with-contenv bashio

# The script runs as a background process in the Home Assistant environment,
# reading the 'seconds_between_quotes' configuration key to determine the loop interval.

The example2.sh script is a secondary executable provided within the application's root filesystem. When executed, it runs an infinite loop that outputs Second Script Output to the standard output every 10 seconds. It is designed to run within a Home Assistant environment using the bashio library for logging.

./usr/bin/example2.sh