jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-25 02:07:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Small tidy up of the current examples (#14647)

Browse Source 
Co-authored-by: Paulus Schoutsen <balloob@gmail.com>
This commit is contained in:
Franck Nijhof 2020-09-29 16:28:50 +02:00 committed by GitHub
parent d295893834
commit 6e0e706cd3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 9 additions and 675 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
source/_cookbook/custom_panel_using_react.markdown
View File

@ -1,34 +0,0 @@
---
title: "Custom Panel using React"
description: ""
ha_category: User Interface
---
This is a [React](https://facebook.github.io/react/) implementation of [TodoMVC](http://todomvc.com/) but instead of checking off to do items, you are turning lights and switches on/off.
- It uses React to render the data.
- It hooks into Home Assistant JS which means updates pushed from the server are instantly rendered.
- It accesses properties made available from Polymer.
- It uses the user configuration for the integration in the `configuration.yaml` file for rendering.
- It allows toggling the sidebar.
[Download the source for React Starter Kit here](https://github.com/home-assistant/custom-panel-starter-kit-react). Copy the file to `<config dir>/panels/` (you might have to create the directory if it doesn't exist).
Create an entry for the panel in your `configuration.yaml` file to enable it.
```yaml
panel_custom:
- name: react
sidebar_title: TodoMVC
sidebar_icon: mdi:work
url_path: todomvc
config:
title: hello
```
This video shows the example in action.
<div class='videoWrapper'>
<iframe width="560" height="315" src="https://www.youtube.com/embed/2200UutdXlo" frameborder="0" allowfullscreen></iframe>
</div>

6
source/_cookbook/custom_ui_by_andrey-git.markdown
View File

@ -1,6 +0,0 @@
---
title: "Custom UI state-card by andrey-git"
description: ""
ha_category: User Interface
ha_external_link: https://github.com/andrey-git/home-assistant-custom-ui
---

164
source/_cookbook/fail2ban.markdown
View File

@ -1,164 +0,0 @@
---
title: "fail2ban"
description: "Setting up fail2ban to read Home Assistant's log files to improve security."
ha_category: Infrastructure
---
This is a quick guide on how to set up `fail2ban` for Home Assistant. Contains extracts from [Is there a log file for invalid logins? \(Blocking hackers\)](https://community.home-assistant.io/t/is-there-a-log-file-for-invalid-logins-blocking-hackers/2892).
## Installing fail2ban
Debian/Ubuntu:
```bash
sudo apt-get install fail2ban
```
CentOS/RHEL:
```bash
sudo yum install epel-release
sudo yum install -y fail2ban
```
Fedora:
```bash
sudo dnf install -y fail2ban
```
For other package managers use the appropriate commands.
## Enable Home Assistant Logging
First, enable `http.ban` logging in `configuration.yaml` file for your Home Assistant instance:
```yaml
logger:
default: critical
logs:
homeassistant.components.http.ban: warning
```
Restart Home Assistant to activate the changes:
```bash
sudo systemctl restart home-assistant
```
Tail the Home Assistant log then log out of the Home Assistant web interface and attempt logging in with an incorrect password, look for a line like `Login attempt or request with invalid authentication from xxx.xxx.xxx.xxx`:
```bash
$ tail -f /home/homeassistant/.homeassistant/home-assistant.log | grep WARNING
2018-08-29 14:28:15 WARNING (MainThread) [homeassistant.components.http.ban] Login attempt or request with invalid authentication from xxx.xxx.xxx.xxx
```
## Configure fail2ban
Next we will create a filter and jail file for `fail2ban`:
- `/etc/fail2ban/filter.d/ha.conf`
- `/etc/fail2ban/jail.d/ha.conf`
Contents of `/etc/fail2ban/filter.d/ha.conf`:
```ini
[INCLUDES]
before = common.conf
[Definition]
failregex = ^%(__prefix_line)s.*Login attempt or request with invalid authentication from <HOST>.*$
ignoreregex =
```
Contents of `/etc/fail2ban/jail.d/ha.conf`. Note that you'll need to change the `logpath` to match your logfile which will be different from the path listed.:
```ini
[DEFAULT]
# Email config
sender = email@address.com
destemail = email@address.com
# Action "%(action_mwl)s" will ban the IP and send an email notification including whois data and log entries.
action = %(action_mwl)s
[ha]
enabled = true
filter = ha
logpath = /home/homeassistant/.homeassistant/home-assistant.log
# 3600 seconds = 1 hour
bantime = 30 # during testing it is useful to have a short ban interval, change this to 3600 later
# Maximum amount of login attempts before IP is blocked
maxretry = 3
```
Restart `fail2ban`:
```bash
sudo systemctl restart fail2ban
```
Confirm `fail2ban` is running:
```bash
sudo systemctl status fail2ban
```
Check that the ha jail is active:
```bash
sudo fail2ban-client status
Status
|- Number of jail: 1
`- Jail list: ha
```
## Testing fail2ban
Tail the fail2ban log file then log out of the Home Assistant web interface and attempt to log in again with an incorrect password.
```bash
sudo tail -f -n 20 /var/log/fail2ban.log
2018-08-29 13:25:37,907 fail2ban.server [10208]: INFO Starting Fail2ban v0.10.3.fix1
2018-08-29 13:25:37,916 fail2ban.database [10208]: INFO Connected to fail2ban persistent database '/var/lib/fail2ban/fail2ban.sqlite3'
2018-08-29 13:25:37,918 fail2ban.jail [10208]: INFO Creating new jail 'ha'
2018-08-29 13:25:37,922 fail2ban.jail [10208]: INFO Jail 'ha' uses poller {}
2018-08-29 13:25:37,922 fail2ban.jail [10208]: INFO Initiated 'polling' backend
2018-08-29 13:25:37,932 fail2ban.filter [10208]: INFO Added logfile: '/home/homeassistant/.homeassistant/home-assistant.log' (pos = 5873, hash = 02ec3aefc005465a6cd8db91eff2d5e57c45757e)
2018-08-29 13:25:37,932 fail2ban.filter [10208]: INFO encoding: UTF-8
2018-08-29 13:25:37,933 fail2ban.filter [10208]: INFO maxRetry: 3
2018-08-29 13:25:37,934 fail2ban.filter [10208]: INFO findtime: 600
2018-08-29 13:25:37,934 fail2ban.actions [10208]: INFO banTime: 30
2018-08-29 13:25:37,938 fail2ban.jail [10208]: INFO Jail 'ha' started
2018-08-29 13:27:49,125 fail2ban.filter [10208]: INFO [ha] Found xxx.xxx.xxx.xxx - 2018-08-29 13:27:48
2018-08-29 13:27:51,330 fail2ban.filter [10208]: INFO [ha] Found xxx.xxx.xxx.xxx - 2018-08-29 13:27:51
2018-08-29 13:27:52,533 fail2ban.filter [10208]: INFO [ha] Found xxx.xxx.xxx.xxx - 2018-08-29 13:27:52
2018-08-29 13:27:52,678 fail2ban.actions [10208]: NOTICE [ha] Ban xxx.xxx.xxx.xxx
2018-08-29 13:28:23,941 fail2ban.actions [10208]: NOTICE [ha] Unban xxx.xxx.xxx.xxx
```
Now that fail2ban is working it can be enabled for startup at boot time, also raise the bantime from 30 seconds to what ever you would like. 8 hours is 28800 seconds.
```bash
sudo sed -i 's/bantime = 30/bantime = 28800/g' /etc/fail2ban/jail.d/ha.conf
sudo systemctl enable fail2ban
sudo systemctl restart fail2ban
```
A final note, if you need to unban an IP it can be done with `fail2ban-client`:
```bash
sudo fail2ban-client set JAILNAME unbanip IPADDRESS
```
eg:
```bash
sudo fail2ban-client set ha unbanip xxx.xxx.xxx.xxx
```
Fail2ban should now be configured and running, if an IP address is banned you will receive an email with WHOIS details about the IP address that attempted to connect, if not you will need configure Postfix or another MTA (Mail Transport Agent).
If you want to read more about `fail2ban`, some links are below:
- [fail2ban Split configuration](http://www.fail2ban.org/wiki/index.php/FEATURE_Split_config)
- [How To Protect SSH with Fail2Ban on Ubuntu 14.04](https://www.digitalocean.com/community/tutorials/how-to-protect-ssh-with-fail2ban-on-ubuntu-14-04)

67
source/_cookbook/ifttt.manything.markdown
View File

@ -1,67 +0,0 @@
---
title: "ManyThing"
description: "Instructions on how to setup ManyThing support with IFTTT."
logo: manything.png
ha_category: Camera
redirect_from:
/integrations/ifttt.manything/
---
[Manything](https://manything.com) is a smart app that turns your Android device, iPhone, iPod, or iPad into a Wi-Fi camera for monitoring your home, your pets, anything! Comes with live streaming, motion activated alerts, cloud video recording, and more.
To get manything support, HA will use IFTTT's [Webhooks Service](https://ifttt.com/maker_webhooks) and the [ManyThing Service](https://ifttt.com/manything). Use the [IFTTT Setup instructions](/integrations/ifttt/) to activate the IFTTT Platform.
After setting up IFTTT, Maker Service and ManyThing Service, you can use the following examples to configure Home Assistant.
```yaml
# Example configuration.yaml entry
automation:
- alias: 'ManyThing Recording ON'
# This calls an IFTTT recipe to turn on recording of the ManyThing Camera
# if we leave the house during the day.
trigger:
- platform: state
entity_id: all
to: 'not_home'
condition:
- platform: state
entity_id: sun.sun
state: 'above_horizon'
action:
service: ifttt.trigger
data: {"event":"manything_on"}
- alias: 'ManyThing Recording OFF'
# This calls an IFTTT recipe to turn off recording of the ManyThing Camera
# when we get home unless it's nighttime.
trigger:
- platform: state
entity_id: all
to: 'home'
condition:
- condition: state
entity_id: sun.sun
state: 'above_horizon'
action:
service: ifttt.trigger
data: {"event":"manything_off"}
```
### Setting up a recipe
<p class='img'>
<img src='/images/integrations/ifttt/IFTTT_manything_trigger.png' />
You need to setup a unique trigger for each event you sent to IFTTT.
For ManyThing support, you need to set up an `on` and `off` event.
</p>
### Testing your trigger
You can use the developer tools to test your [Maker Service](https://ifttt.com/maker_webhooks) trigger. To do this, open the Home Assistant UI, open the sidebar, click on the first icon in the developer tools. This should get you to the 'Call Service' screen. Fill in the following values:
| Field | Value |
| ------------ | --------------------------- |
| domain | `ifttt` |
| service | `trigger` |
| Service Data | `{"event": "manything_on"}` |

184
source/_cookbook/python_component_automation.markdown
View File

@ -1,184 +0,0 @@
---
title: "Automation in Code"
description: "A sample to do automations in Python Code."
ha_category: Automation in Python Examples
---
Example integration to target an `entity_id` to:
- turn it on at 7AM in the morning
- turn it on if anyone comes home and it is off
- turn it off if all lights are turned off
- turn it off if all people leave the house
- offer a service to turn it on for 10 seconds
To set it up, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
example:
target: TARGET_ENTITY
```
{% configuration %}
target:
description: 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).
required: true
type: string
{% endconfiguration %}
Create the file `<config dir>/custom_components/example.py` and copy paste the content below:
```python
"""
Example of a custom component.
"""
import logging
import time
import voluptuous as vol
import homeassistant.components as core
import homeassistant.helpers.config_validation as cv
from homeassistant.components import device_tracker, light
from homeassistant.const import (
ATTR_ENTITY_ID,
SERVICE_TURN_OFF,
SERVICE_TURN_ON,
STATE_HOME,
STATE_NOT_HOME,
STATE_OFF,
STATE_ON,
)
from homeassistant.core import split_entity_id
from homeassistant.helpers.event import (
async_track_state_change,
async_track_time_change,
)
# The domain of your component. Should be equal to the name of your component.
DOMAIN = "example"
# List of integration names (string) your integration depends upon.
# We depend on group because group will be loaded after all the integrations that
# initialize devices have been setup.
DEPENDENCIES = ["group", "device_tracker", "light"]
# Configuration key for the entity id we are targeting.
CONF_TARGET = "target"
# Variable for storing configuration parameters.
TARGET_ID = None
# Name of the service that we expose.
SERVICE_FLASH = "flash"
# Shortcut for the logger
_LOGGER = logging.getLogger(__name__)
# Validate that all required config options are given.
CONFIG_SCHEMA = vol.Schema(
{DOMAIN: vol.Schema({vol.Optional(CONF_TARGET): cv.entity_id})},
extra=vol.ALLOW_EXTRA,
)
async def async_setup(hass, config):
"""Setup example component."""
TARGET_ID = config[DOMAIN][CONF_TARGET]
domain = split_entity_id(TARGET_ID)[0]
data = {ATTR_ENTITY_ID: TARGET_ID}
# Validate that the target entity id exists.
if hass.states.get(TARGET_ID) is None:
_LOGGER.error("Target entity id %s does not exist", TARGET_ID)
# Tell the bootstrapper that we failed to initialize and clear the
# stored target id so our functions don't run.
TARGET_ID = None
return False
async def async_switch_on(entity_id, old_state, new_state):
"""Callback to turn on our target entity"""
# If the target id is not set, return
if not TARGET_ID:
return
if not core.is_on(hass, TARGET_ID):
await hass.services.async_call(domain, SERVICE_TURN_ON, data)
async def async_switch_off(entity_id, old_state, new_state):
"""Callback to turn off our target entity"""
# If the target id is not set, return
if not TARGET_ID:
return
if core.is_on(hass, TARGET_ID):
await hass.services.async_call(domain, SERVICE_TURN_OFF, data)
async def async_wake_up(service):
"""Turn light on in the morning.
Turn the light on when called, but only if there are people home
and it is not already on.
"""
if not TARGET_ID:
return
if device_tracker.is_on(hass) and not core.is_on(hass, TARGET_ID):
_LOGGER.info("People home at 7AM, turning target on")
await hass.services.async_call(domain, SERVICE_TURN_ON, data)
async def async_flash_service(service):
"""Service callback that will toggle the target.
Set the light to off for 10 seconds if on and vice versa.
"""
if not TARGET_ID:
return
if core.is_on(hass, TARGET_ID):
# We need this call to run blocking, as we want to wait 10s after it finished
await hass.services.async_call(
domain, SERVICE_TURN_OFF, data, blocking=True
)
time.sleep(10)
await hass.services.async_call(domain, SERVICE_TURN_ON, data)
else:
await hass.services.async_call(domain, SERVICE_TURN_ON, data, blocking=True)
time.sleep(10)
await hass.services.async_call(domain, SERVICE_TURN_OFF, data)
# register the example.flash service
hass.services.async_register(DOMAIN, SERVICE_FLASH, async_flash_service)
# If all lights turn off, turn off.
async_track_state_change(
hass, light.ENTITY_ID_ALL_LIGHTS, async_switch_off, STATE_ON, STATE_OFF
)
# If all people leave the house and the entity is on, turn it off.
async_track_state_change(
hass,
device_tracker.ENTITY_ID_ALL_DEVICES,
async_switch_off,
STATE_HOME,
STATE_NOT_HOME,
)
# If anyone comes home and the entity is not on, turn it on.
async_track_state_change(
hass,
device_tracker.ENTITY_ID_ALL_DEVICES,
async_switch_on,
STATE_NOT_HOME,
STATE_HOME,
)
# Call wakeup callback at 7 AM
async_track_time_change(hass, async_wake_up, hour=7, minute=00, second=00)
# Tell the bootstrapper that we initialized successfully.
return True
```

76
source/_cookbook/python_component_mqtt_basic.markdown
View File

@ -1,76 +0,0 @@
---
title: "Basic MQTT Example"
description: ""
ha_category: Custom Python Component Examples
---
<div class='note'>
This example requires you to have the [MQTT integration](/integrations/mqtt/) up and running.
</div>
This is a simple hello world example to show the basics of using MQTT in a custom integration. To use this example, create the file `<config dir>/custom_components/hello_mqtt.py` and copy the below example code.
This example follows a topic on MQTT and updates the state of an entity to the last message received on that topic. It will also register a service 'set_state' that will publish a message to the MQTT topic that we're listening to.
```python
import homeassistant.loader as loader
# The domain of your component. Should be equal to the name of your component.
DOMAIN = "hello_mqtt"
# List of integration names (string) your integration depends upon.
DEPENDENCIES = ["mqtt"]
CONF_TOPIC = "topic"
DEFAULT_TOPIC = "home-assistant/hello_mqtt"
def setup(hass, config):
"""Set up the Hello MQTT component."""
mqtt = hass.components.mqtt
topic = config[DOMAIN].get(CONF_TOPIC, DEFAULT_TOPIC)
entity_id = "hello_mqtt.last_message"
# Listener to be called when we receive a message.
# The msg parameter is a Message object with the following members:
# - topic, payload, qos, retain
def message_received(msg):
"""Handle new MQTT messages."""
hass.states.set(entity_id, msg.payload)
# Subscribe our listener to a topic.
mqtt.subscribe(topic, message_received)
# Set the initial state.
hass.states.set(entity_id, "No messages")
# Service to publish a message on MQTT.
def set_state_service(call):
"""Service to send a message."""
mqtt.publish(topic, call.data.get("new_state"))
# Register our service with Home Assistant.
hass.services.register(DOMAIN, "set_state", set_state_service)
# Return boolean to indicate that initialization was successfully.
return True
```
Load the integration by adding the following to your `configuration.yaml`. When your integration is loaded, a new entity should popup and there should be a new service available to call.
```yaml
# configuration.yaml entry
hello_mqtt:
topic: some_mqtt/topic/here
```
You can call the service with example payload:
```json
{
"new_state": "some new state"
}
```

132
source/_cookbook/python_component_simple_alarm.markdown
View File

@ -1,132 +0,0 @@
---
title: "Flash lights when intruder detected"
description: "Detect intruders by checking if the light is turning on while no one is home."
ha_category: Automation in Python Examples
---
This example integration will detect intruders. It does so by checking if lights are being turned on while there is no one at home. When this happens it will turn the lights red, flash them for 30 seconds and send a message via [the notify integration](/integrations/notify/). It will also flash a specific light when a known person comes home.
This integration depends on the integrations [device_tracker](/integrations/device_tracker/) and [light](/integrations/light/) being setup.
To set it up, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
simple_alarm:
known_light: light.Bowl
unknown_light: group.living_room
```
{% configuration %}
known_light:
description: Which light/light group has to flash when a known device comes home.
required: false
type: string
unknown_light:
description: Which light/light group has to flash red when light turns on while no one home.
required: false
type: string
{% endconfiguration %}
Create the file `<config dir>/custom_components/simple_alarm.py` and copy paste the content below:
```python
"""Simple alarm component."""
import logging
import homeassistant.loader as loader
from homeassistant.components import device_tracker, light, notify
from homeassistant.helpers.event import track_state_change
from homeassistant.const import STATE_ON, STATE_OFF, STATE_HOME, STATE_NOT_HOME
_LOGGER = logging.getLogger(__name__)
DOMAIN = 'simple_alarm"'
DEPENDENCIES = ["group", "device_tracker", "light"]
# Attribute to tell which light has to flash when a known person comes home
# If omitted will flash all.
CONF_KNOWN_LIGHT = "known_light"
# Attribute to tell which light has to flash when an unknown person comes home
# If omitted will flash all.
CONF_UNKNOWN_LIGHT = "unknown_light"
# Services to test the alarms
SERVICE_TEST_KNOWN_ALARM = "test_known"
SERVICE_TEST_UNKNOWN_ALARM = "test_unknown"
def setup(hass, config):
"""Set up the simple alarms."""
light_ids = []
for conf_key in (CONF_KNOWN_LIGHT, CONF_UNKNOWN_LIGHT):
light_id = config[DOMAIN].get(conf_key, light.ENTITY_ID_ALL_LIGHTS)
if hass.states.get(light_id) is None:
_LOGGER.error("Light id %s could not be found in state machine", light_id)
return False
light_ids.append(light_id)
# pylint: disable=unbalanced-tuple-unpacking
known_light_id, unknown_light_id = light_ids
if hass.states.get(device_tracker.ENTITY_ID_ALL_DEVICES) is None:
_LOGGER.error("No devices are being tracked, cannot setup alarm")
return False
def known_alarm():
""" Fire an alarm if a known person arrives home. """
light.turn_on(hass, known_light_id, flash=light.FLASH_SHORT)
def unknown_alarm():
""" Fire an alarm if the light turns on while no one is home. """
light.turn_on(
hass, unknown_light_id, flash=light.FLASH_LONG, rgb_color=[255, 0, 0]
)
# Send a message to the user
notify.send_message(
hass, "The lights just got turned on while no one was home."
)
# Setup services to test the effect
hass.services.register(DOMAIN, SERVICE_TEST_KNOWN_ALARM, lambda call: known_alarm())
hass.services.register(
DOMAIN, SERVICE_TEST_UNKNOWN_ALARM, lambda call: unknown_alarm()
)
def unknown_alarm_if_lights_on(entity_id, old_state, new_state):
"""Called when a light has been turned on."""
if not device_tracker.is_on(hass):
unknown_alarm()
track_state_change(
hass,
light.ENTITY_ID_ALL_LIGHTS,
unknown_alarm_if_lights_on,
STATE_OFF,
STATE_ON,
)
def ring_known_alarm(entity_id, old_state, new_state):
"""Called when a known person comes home."""
if light.is_on(hass, known_light_id):
known_alarm()
# Track home coming of each device
track_state_change(
hass,
hass.states.entity_ids(device_tracker.DOMAIN),
ring_known_alarm,
STATE_NOT_HOME,
STATE_HOME,
)
return True
```

21
source/cookbook/index.markdown
View File

@ -6,27 +6,24 @@ regenerate: true
hide_github_edit: true
---
This is a community curated list of different ways to use Home Assistant. Most of these examples are using the [automation] integration and other built-in [automation related][sec-automation] and [organization] integrations available.
For [`python_script:` examples](/integrations/python_script/) visit the [Scripts section](https://community.home-assistant.io/c/projects/scripts) in our forum.
[automation]: /getting-started/automation/
[sec-automation]: /integrations/#automation
[organization]: /integrations/#organization
New recipes can be added via the [home-assistant.io repository](https://github.com/home-assistant/home-assistant.io/tree/current/source/_cookbook).
This is a community curated list of different ways to use Home Assistant. Most
of these examples are using [the automation integration][automations].
<div class='note'>
A great place to find popular configurations is on this [GitHub search](https://github.com/search?q=topic%3Ahome-assistant-config&type=Repositories) for repositories with the `home-assistant-config` topic.
A great place to find popular configurations is on this
[GitHub search][github-search] for repositories with the
`home-assistant-config` topic.
</div>
[automation]: /getting-started/automation/
[github-search]: https://github.com/search?q=topic%3Ahome-assistant-config&type=Repositories
{% assign cookbook = site.cookbook | sort: 'title' %}
{% assign categories = cookbook | map: 'ha_category' | uniq | sort %}
{% for category in categories %}
### {{ category }}
## {{ category }}
{% if category == 'Automation Examples' %}