Home Assistant Developer Documentation

Apps (formerly known as add-ons) allow users to extend Home Assistant functionality. They are used to run applications that integrate with Home Assistant (such as an MQTT broker) or to provide services like sharing configuration via Samba for easy editing.

Apps are implemented as container images published to registries such as GitHub Container Registry or Docker Hub. Users configure these apps via the Supervisor panel within Home Assistant.

Building a native Home Assistant app involves establishing a secure connection to a user's Home Assistant instance and providing a seamless interface for controlling their smart home. This guide covers the core capabilities required for a functional integration:

• Authentication: Allowing users to connect and authenticate with their specific Home Assistant instance.
• Telemetry: Sending device information and location data back to the Home Assistant server.
• Remote Control: Executing service actions, firing events, and rendering templates remotely.
• Webview Control: Providing a view to control the home via an authenticated webview.

Follow these core principles when developing for Android:

• SOLID: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion.
• KISS: Keep It Simple, Stupid.
• DRY: Don't Repeat Yourself.
• Keep it direct: Avoid premature abstractions. Only abstract when a second real use case appears or to hide implementation details from other modules.
• Root cause before fix: Address the actual cause of a bug rather than patching symptoms with speculative workarounds.

Contributions to the Home Assistant Android project are categorized into several areas:

• Code contributions: Fixing bugs, implementing new features, or optimizing performance.
• Code reviews: Providing constructive feedback on pull requests from other developers.
• Testing: Verifying app stability and functionality across various Android devices.
• Documentation: Writing and maintaining clear, concise guides.
• Beta testing: Joining the Google Play beta program to identify issues before production releases.
• Feedback: Providing ideas and suggestions for app improvements.

The Home Assistant design portal (also referred to as the "gallery" in the frontend repository) is a central resource for frontend design specifications. It provides information on:

• Reusable UI components: Documentation and visual references for components.
• Dashboard cards: Various configurations and states for cards.
• Theme comparison: Tools to compare components and cards between light and dark themes.
• Wording guidelines: Specific notes regarding terminology used within Home Assistant.

You can access the live portal at https://design.home-assistant.io.

Home Assistant uses an intent system to process commands. For detailed implementation and usage, refer to the Home Assistant Core documentation for the following areas:

• Built-in intents: A list of intents natively supported by the system.
• Conversation API: How to send text commands to Home Assistant and receive responses.
• Intent Handlers: How to register new intents to extend Home Assistant's capabilities.
• Firing Intents: How to trigger intents manually if you are using custom sentence matching logic.

The Home Assistant iOS repository is a multi-target workspace. A single change can affect multiple surfaces. When developing, you must identify which target your changes impact to ensure proper validation and testing across the following surfaces:

• Main App: The primary iPhone and iPad application.
• Widgets and App Intents: Home Screen widgets and system integrations.
• Apple Watch: Watch-specific actions, notifications, and complications.
• CarPlay: Templates, list items, and action execution for vehicles.
• Notification Extensions: Rich push handling and command execution.
• Extensions: Share and Matter extensions.
• macOS: macOS-specific bridge code.
• Supporting Packages: Standalone Swift packages for push services.

Dependency updates are automated using Renovate. Renovate scans for outdated dependencies, creates pull requests, and ensures that lockfiles are updated alongside the version changes.

Note on timing: Renovate is configured to wait 3 days after a new library release before opening a pull request to allow time for early adopters to report issues.

Home Assistant support for the Hardkernel ODROID-C4 is currently considered experimental. It relies heavily on configurations used for the Odroid-C2 and N2 due to SoC similarities and comparable Linux kernel support.

While support is experimental, the following features have been tested and confirmed to work:

• Booting from SD
• Booting from eMMC
• Obtaining the MAC address from eFuse

For additional configuration details, refer to the documentation for the ODROID-C2 and Odroid-N2, as much of that information is applicable to the C4.

The Home Assistant frontend is built using web components, which encapsulate templates, styling, and logic into composable HTML tags. The architecture is divided into four primary layers:

1. Bootstrap (src/entrypoints/core.ts): The initial script that handles authentication and establishes the WebSocket connection with the backend.
2. App shell (src/entrypoints/app.ts): Loads the <home-assistant> root element, initializes application state, and handles top-level navigation.
3. Panels (src/panels/): Represents individual pages (e.g., 'states', 'map', 'logbook'). Components can register additional panels.
4. Dialogs (src/dialogs): Used for information flows and data entry (e.g., the 'entity more info' dialog) that can be triggered from any page.