Skip to content

Commit 544fbab

Browse files
fabafffabaff
authored
Add missing example (fixes home-assistant#4269) (home-assistant#4275)
1 parent 7340308 commit 544fbab

File tree

2 files changed

+160
-1
lines changed

2 files changed

+160
-1
lines changed

‎source/_cookbook/python_component_automation.markdown

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
layout: page
3+
title: "Automation in Code"
4+
description: "A sample to do automations in Python Code."
5+
date: 2016-02-14 0:40 -0800
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
ha_category: Automation in Python Examples
11+
---
12+
13+
Example component to target an `entity_id` to:
14+
15+
- turn it on at 7AM in the morning
16+
- turn it on if anyone comes home and it is off
17+
- turn it off if all lights are turned off
18+
- turn it off if all people leave the house
19+
- offer a service to turn it on for 10 seconds
20+
21+
To set it up, add the following lines to your `configuration.yaml` file:
22+
23+
```yaml
24+
# Example configuration.yaml entry
25+
example:
26+
target: TARGET_ENTITY
27+
```
28+
29+
Configuration variables:
30+
31+
- **target** (*Required*): TARGET_ENTITY should be one of your devices that can be turned on and off, e.g., a light or a switch. Example value could be light.Ceiling or switch.AC (if you have these devices with those names).
32+
33+
Create the file `<config dir>/custom_components/example.py` and copy paste the content below:
34+
35+
36+
```python
37+
"""
38+
Example of a custom component.
39+
"""
40+
import time
41+
import logging
42+
43+
from homeassistant.const import STATE_HOME, STATE_NOT_HOME, STATE_ON, STATE_OFF
44+
from homeassistant.helpers import validate_config
45+
from homeassistant.helpers.event_decorators import \
46+
track_state_change, track_time_change
47+
from homeassistant.helpers.service import service
48+
import homeassistant.components as core
49+
from homeassistant.components import device_tracker
50+
from homeassistant.components import light
51+
52+
# The domain of your component. Should be equal to the name of your component.
53+
DOMAIN = "example"
54+
55+
# List of component names (string) your component depends upon.
56+
# We depend on group because group will be loaded after all the components that
57+
# initialize devices have been setup.
58+
DEPENDENCIES = ['group', 'device_tracker', 'light']
59+
60+
# Configuration key for the entity id we are targeting.
61+
CONF_TARGET = 'target'
62+
63+
# Variable for storing configuration parameters.
64+
TARGET_ID = None
65+
66+
# Name of the service that we expose.
67+
SERVICE_FLASH = 'flash'
68+
69+
# Shortcut for the logger
70+
_LOGGER = logging.getLogger(__name__)
71+
72+
73+
def setup(hass, config):
74+
"""Setup example component."""
75+
global TARGET_ID
76+
77+
# Validate that all required config options are given.
78+
if not validate_config(config, {DOMAIN: [CONF_TARGET]}, _LOGGER):
79+
return False
80+
81+
TARGET_ID = config[DOMAIN][CONF_TARGET]
82+
83+
# Validate that the target entity id exists.
84+
if hass.states.get(TARGET_ID) is None:
85+
_LOGGER.error("Target entity id %s does not exist",
86+
TARGET_ID)
87+
88+
# Tell the bootstrapper that we failed to initialize and clear the
89+
# stored target id so our functions don't run.
90+
TARGET_ID = None
91+
return False
92+
93+
# Tell the bootstrapper that we initialized successfully.
94+
return True
95+
96+
97+
@track_state_change(device_tracker.ENTITY_ID_ALL_DEVICES)
98+
def track_devices(hass, entity_id, old_state, new_state):
99+
"""Called when the group.all devices change state."""
100+
# If the target id is not set, return
101+
if not TARGET_ID:
102+
return
103+
104+
# If anyone comes home and the entity is not on, turn it on.
105+
if new_state.state == STATE_HOME and not core.is_on(hass, TARGET_ID):
106+
107+
core.turn_on(hass, TARGET_ID)
108+
109+
# If all people leave the house and the entity is on, turn it off.
110+
elif new_state.state == STATE_NOT_HOME and core.is_on(hass, TARGET_ID):
111+
112+
core.turn_off(hass, TARGET_ID)
113+
114+
115+
@track_time_change(hour=7, minute=0, second=0)
116+
def wake_up(hass, now):
117+
"""Turn light on in the morning.
118+
119+
Turn the light on at 7 AM if there are people home and it is not already
120+
on.
121+
"""
122+
if not TARGET_ID:
123+
return
124+
125+
if device_tracker.is_on(hass) and not core.is_on(hass, TARGET_ID):
126+
_LOGGER.info('People home at 7AM, turning it on')
127+
core.turn_on(hass, TARGET_ID)
128+
129+
130+
@track_state_change(light.ENTITY_ID_ALL_LIGHTS, STATE_ON, STATE_OFF)
131+
def all_lights_off(hass, entity_id, old_state, new_state):
132+
"""If all lights turn off, turn off."""
133+
if not TARGET_ID:
134+
return
135+
136+
if core.is_on(hass, TARGET_ID):
137+
_LOGGER.info('All lights have been turned off, turning it off')
138+
core.turn_off(hass, TARGET_ID)
139+
140+
141+
@service(DOMAIN, SERVICE_FLASH)
142+
def flash_service(hass, call):
143+
"""Service that will toggle the target.
144+
145+
Set the light to off for 10 seconds if on and vice versa.
146+
"""
147+
if not TARGET_ID:
148+
return
149+
150+
if core.is_on(hass, TARGET_ID):
151+
core.turn_off(hass, TARGET_ID)
152+
time.sleep(10)
153+
core.turn_on(hass, TARGET_ID)
154+
155+
else:
156+
core.turn_on(hass, TARGET_ID)
157+
time.sleep(10)
158+
core.turn_off(hass, TARGET_ID)
159+
```

‎source/developers/architecture_components.markdown

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ In the event of the sun setting:
5151
Turn on the lights
5252
```
5353

54-
Look [here](https://github.com/home-assistant/home-assistant/blob/master/config/custom_components/example.py) for a comprehensive example of a home automation component.
54+
Look [here](/python_component_automation/) for a comprehensive example of a home automation component.
5555

5656
### {% linkable_title The full picture %}
5757

0 commit comments

Comments
 (0)