Python Home Assistant Automation — Core Concepts

What Home Assistant Is

Home Assistant is an open-source home automation platform written in Python. It runs locally on your network, connects to over 2,500 different brands and technologies, and provides a unified interface to monitor and control everything. Started by Paulus Schoutsen in 2013, it has grown into the largest open-source smart home project with millions of installations worldwide.

It runs on Raspberry Pi, mini PCs, NAS devices, or any machine with Docker. The recommended installation method is Home Assistant Operating System (HAOS), a purpose-built Linux distribution.

The Entity Model

Everything in Home Assistant is an entity — a thing with a state and optional attributes:

• light.living_room — state: “on”, attributes: brightness: 80, color: warm_white
• sensor.outdoor_temperature — state: “18.5”, attributes: unit: “°C”
• lock.front_door — state: “locked”
• binary_sensor.motion_hallway — state: “on” (motion detected)
• media_player.kitchen_speaker — state: “playing”, attributes: volume: 0.4

Entities follow a naming pattern: domain.object_id. The domain tells you what kind of thing it is (light, sensor, switch, climate), and the object_id identifies the specific instance.

Automations: Trigger, Condition, Action

Automations are the core of Home Assistant’s intelligence. Every automation has three parts:

Trigger — What starts the automation. Examples: a sensor changes state, the sun sets, a time is reached, a device is detected on the network.

Condition (optional) — Requirements that must be true for the automation to proceed. Examples: only if someone is home, only on weekdays, only if a light is already off.

Action — What happens. Examples: turn on a light, send a notification, adjust the thermostat, play music.

# automation.yaml
- alias: "Porch Light at Sunset"
  trigger:
    - platform: sun
      event: sunset
      offset: "-00:30:00"  # 30 minutes before sunset
  condition:
    - condition: state
      entity_id: person.david
      state: "home"
  action:
    - service: light.turn_on
      target:
        entity_id: light.porch
      data:
        brightness_pct: 80

Integrations

Integrations connect Home Assistant to devices and services. They are Python packages that translate device-specific protocols into Home Assistant’s entity model:

• Zigbee (ZHA) — Connects Zigbee devices (Philips Hue bulbs, Aqara sensors, IKEA smart plugs) through a USB coordinator
• Z-Wave — Connects Z-Wave devices (locks, thermostats, dimmers)
• MQTT — Connects any MQTT-capable device
• Google Cast — Controls Chromecast and Google Home speakers
• ESPHome — Manages custom ESP32/ESP8266 devices with YAML configuration
• REST/API — Connects to web services and APIs

Most integrations are configured through the UI, but many support YAML configuration for advanced setups.

Dashboards

Home Assistant provides a Lovelace dashboard system for visualization and control:

# Custom dashboard card
type: entities
title: Living Room
entities:
  - entity: light.living_room
  - entity: sensor.living_room_temperature
  - entity: sensor.living_room_humidity
  - entity: media_player.living_room_speaker

Dashboards are accessible from any browser, and Home Assistant provides companion apps for iOS and Android with push notifications, location tracking, and local network access.

Python Scripts in Home Assistant

Home Assistant can run Python scripts for custom logic:

# python_scripts/notify_if_hot.py
temp = float(hass.states.get('sensor.outdoor_temperature').state)
name = data.get('name', 'Friend')

if temp > 35:
    hass.services.call('notify', 'mobile_app', {
        'message': f'Hey {name}, it is {temp}°C outside. Stay hydrated!',
        'title': 'Heat Warning'
    })

Triggered from an automation:

action:
  - service: python_script.notify_if_hot
    data:
      name: "David"

Scenes and Scripts

Scenes capture a snapshot of desired entity states:

# scenes.yaml
- name: Movie Night
  entities:
    light.living_room:
      state: on
      brightness: 30
    light.kitchen:
      state: off
    media_player.tv:
      state: on

Scripts are reusable action sequences:

# scripts.yaml
goodnight:
  alias: "Goodnight Routine"
  sequence:
    - service: lock.lock
      target:
        entity_id: lock.front_door
    - service: light.turn_off
      target:
        entity_id: all
    - service: climate.set_temperature
      target:
        entity_id: climate.thermostat
      data:
        temperature: 19

Common Misconception

People often think Home Assistant requires cloud connectivity. In fact, it is designed to work entirely locally. Your automations run on your local machine without internet access. Cloud features (like Nabu Casa for remote access and voice control) are optional add-ons. This is a deliberate design choice for privacy and reliability — your lights should still work if your internet goes down.

One thing to remember: Home Assistant’s power lies in its universal entity model — every device from any manufacturer becomes a simple entity with a state, and automations combine triggers, conditions, and actions to make your home respond intelligently.