Home Assistant Core

Warnings

• breaking Home Assistant undergoes monthly releases, often including breaking changes. Users must diligently review release notes and the 'Backward-incompatible changes' section before updating to avoid unexpected issues.
  Fix: Always read the official release notes and breaking changes log before updating. Pay attention to warnings in logs and repair issues in the UI.
• gotcha YAML configuration is crucial for Home Assistant, and incorrect indentation is a leading cause of errors. This can lead to configurations or automations failing silently or behaving unexpectedly.
  Fix: Use a linter (e.g., `yamllint`) or a text editor with strong YAML support. Pay close attention to spacing and indentation in configuration files.
• gotcha Running Home Assistant on an SD card (e.g., on a Raspberry Pi) for extended periods can lead to SD card wear and failure due to frequent write operations (logs, state changes). This can result in data loss or system instability.
  Fix: Use more robust storage like an SSD (via USB adapter for Raspberry Pi) or a network-attached storage solution. Ensure regular, automated backups are in place.
• gotcha Custom components are community-maintained and, unlike official integrations, may not receive immediate updates for breaking changes in Home Assistant Core. They can cause instability or break functionality after a core update.
  Fix: Exercise caution when using custom components. Follow their respective repositories for updates and compatibility information. Report issues to the custom component's maintainer, not Home Assistant Core developers. Minimize their use if stability is paramount.
• gotcha The `python_script` integration is a sandboxed environment and does not allow arbitrary Python imports. Developers accustomed to full Python scripting often find this limitation restrictive.
  Fix: For advanced scripting with full Python library access, consider using AppDaemon or pyscript integrations instead of `python_script`.

Install

• pip install homeassistant Install Home Assistant Core

Imports

• HomeAssistant

  from homeassistant.core import HomeAssistant

  The central coordinator object for Home Assistant operations.
• ConfigEntry

  from homeassistant.config_entries import ConfigEntry

  Used for managing UI-based integration configurations.
• DOMAIN

  from homeassistant.const import DOMAIN

  Common constant used to define an integration's unique identifier.
• Platform

  from homeassistant.const import Platform

  Used for defining entity platforms (e.g., light, sensor).
• async_setup_entry

  from homeassistant.config_entries import ConfigEntry
  async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:

  The primary asynchronous entry point for setting up UI-configured integrations.

Quickstart

This quickstart demonstrates how to programmatically start and interact with a basic Home Assistant Core instance, primarily for testing or embedding purposes. For integration development, you would typically use the `python3 -m script.scaffold integration` command within a development environment to generate a boilerplate custom component structure, then implement your logic in `__init__.py`, `config_flow.py`, and entity platform files.

import asyncio
from homeassistant.core import HomeAssistant, CoreState

async def run_hass_instance():
    hass = HomeAssistant(".homeassistant") # Use a temporary config directory
    await hass.async_start()
    print(f"Home Assistant started. State: {hass.state}")

    # Example: Set a state (e.g., for a custom sensor)
    hass.states.async_set("test.hello_world", "Hello from Python!")
    print(f"State of test.hello_world: {hass.states.get('test.hello_world').state}")

    # Keep running for a short period or until manually stopped
    await asyncio.sleep(5)

    await hass.async_stop()
    print("Home Assistant stopped.")

if __name__ == "__main__":
    # Note: Running Home Assistant Core programmatically like this is mostly for testing or specific advanced scenarios.
    # For typical development, you would create a custom component and run HA via its standard entrypoint.
    try:
        asyncio.run(run_hass_instance())
    except KeyboardInterrupt:
        print("Operation interrupted by user.")