‎App Store: Home Assistant

In this article we’re going to look at a Home Assistant companion — AppDaemon (https://goo.gl/mxvm6W). This is a framework that allows you to build your own Python applications and have them react to events and interact directly with Home Assistant. It gives you the flexibility to write complex automations directly in Python, and if you have a programming background, this will be easier than writing long automations in YAML. An added bonus is that it comes with a framework to build pretty-looking dashboards.

AppDaemon can be installed either on the same system as Home Assistant, also known as HA, or on a different system since it communicates with HA over a network socket. Installation is straightforward, and you can find instructions at https://goo.gl/Hci4zm.

$ sudo pip3 install appdaemon

In the future, you can easily upgrade appdaemon with:

$ sudo pip3 install --upgrade appdaemon

You should also create this systemd service to handle automatic startup:

$ cat /etc/systemd/system/appdaemon.service
[Unit]
Description=AppDaemon
After=homeassistant.service
[Service]
Type=simple
User=homeassistant
ExecStart=/usr/local/bin/appdaemon -c /home/homeassistant/.homeassistant
[Install]
WantedBy=multi-user.target

$ sudo systemctl enable appdaemon
$ sudo systemctl start appdaemon

You will need to create a default configuration preferably inside your HA configuration directory and add a default application to test your setup. The appdaemon.yaml configuration file also stores the credentials to access your Home Assistant instance, or can read them from the file ‘secrets.yaml’.

$ sudo su - homeassistant
$ cat /home/homeassistant/.homeassistant/appdaemon.yaml
 AppDaemon:
 logfile: STDOUT
 errorfile: STDERR
 logsize: 100000
 log_generations: 3
 threads: 10
 HASS:
 ha_url: http://127.0.0.1:8123
 ha_key: !secret api_password
$ mkdir /home/homeassistant/.homeassistant/apps
$ cat /home/homeassistant/.homeassistant/apps/hello.py
import appdaemon.appapi as appapi

#
# Hello World App
#
# Args:
#

class HelloWorld(appapi.AppDaemon):

def initialize(self):
 self.log("Hello from AppDaemon")
 self.log("You are now ready to run Apps!")

The hello.py code above was taken from the installation instructions, but you can find some useful apps in this repository as well at https://goo.gl/6nkzhm. In order to activate and configure an app you will need to add the following inside ‘apps.yaml’:

$ cat /home/homeassistant/.homeassistant/apps.yaml
 hello_world:
 module: hello
 class: HelloWorld

Once you restart AppDaemon, the apps will automatically load. In this case, you should see a «Hello from AppDaemon» message in your logs indicating that the initial setup is done, you can check for this with:

$ sudo journalctl -f -u appdaemon

The best way to get started is to read the documentation. There is a comprehensive tutorial that walks you through all the steps here: https://goo.gl/ha5iC8. Additionally, there is an API reference for quick lookup: https://goo.gl/QeJSYu. The framework is event-driven, so you need to set up listeners for various events that happen in Home Assistant, so your code will be called automatically. You can also access all the states and attributes of Home Assistant entities. When you are familiar with the framework, you can look at the example apps to get an idea how things are done.

Do you remember the heater project in Home Assistant, published in the last issue of ODROID magazine? Well, maybe because I’m getting older, I feel the need to turn the heat on during certain hours of the day and night, so I wanted to create an app to do it for me. There’s a catch though: I want to have some sort of user-friendly switchboard inside Home Assistant to allow me to select at what times I want the heater to be on, as some sort of cron job replacement. I estimated that having 15 minute intervals per switch should be fine, so, if I want to turn the heater on during 4:00 to 4:30, I would need to turn on two switches in the user interface (4:00 and 4:15).

A quick calculation shows us that a day consists of 96 15-minute intervals, and since I’m a lazy person and don’t want to write all that configuration code, I made a script to generate the configuration for me (https://goo.gl/DYY5Mj). If you run the script above, it will create 96 input_boolean switches (https://goo.gl/BtJZ41), and distribute them into 4-hour groups. You can then copy/paste this into your configuration file under the relevant sections and restart Home Assistant. Don’t forget to add the ‘heater_timer_group’ in the ‘heater’ view:

$ wget https://raw.githubusercontent.com/mad-ady/home-assistant-customizations/master/configuration_helper/make_heater_switches.py
$ python make_heater_switches.py

Configuration.yaml will look something like this:

input_boolean:
 …
 heater_timer_00_00:
 name: Heater timer 00:00
 initial: off
 icon: mdi:fire
 heater_timer_00_15:
 name: Heater timer 00:15
 initial: off
 icon: mdi:fire
 …

group:
 heater_timer_group_0:
 name: Timer group 00:00 - 04:00
 control: hidden
 entities:
 - input_boolean.heater_timer_00_00
 - input_boolean.heater_timer_00_15
 - input_boolean.heater_timer_00_30
 …
 heater_timer_group:
 name: Heater timer
 control: hidden
 entities:
 - group.heater_timer_group_0
 - group.heater_timer_group_1
 - group.heater_timer_group_2
 - group.heater_timer_group_3
 - group.heater_timer_group_4
 - group.heater_timer_group_5

…
 heater:
 name: Gas heater
 view: yes
 icon: mdi:fire
 entities:
 - switch.heater
 - climate.heater_thermostat
 - group.heater_timer_group

You should get the view shown in Figure 1 when done.

In order to give these switches functionality, there has to be some application to listen to their state changes in order to do the desired actions. I’ve written an code for AppDaemon which does the following:

• On startup, it begins listening for events from input_boolean entities called heater_timer_*, which iterates through all entities and registers a listener for each one.
• When it detects that a boolean has been toggled, it checks if the name of the boolean is the same as the current time, and if yes, controls the heater
• Every minute that the corresponding input_boolean for the current time interval is checked. If it is on, then the heater is turned on.

The full source code is available at https://goo.gl/WGvoAL, and can be installed with the following commands:

$ cd ~homeassistant/.homeassistant/apps/
$ wget 
 https://raw.githubusercontent.com/mad-ady/home-assistant-customizations/master/appdaemon_apps/manual_heater.py

You will also need to edit the apps.yaml file and add the following:

manual_heater:
 module: manual_heater
 class: ManualHeater
 climate: "climate.heater_thermostat"
 heater: "switch.heater"
 interval_length: 15

Now, when you restart AppDaemon the new app will load and will react to the state of your input_booleans. You can follow its progress by reading the AppDaemon’s log.

All might seem fine, however, there’s a new problem. If you restart HomeAssistant, or if there’s a power outage in the middle of the night, all 96 switches will default to the off position. There has to be a way to save their state and have them load the previous state on reboot. Luckily there already is an app for that: switch_reset.py, available at https://goo.gl/LVYdD2. Here’s how you can configure it:

$ cd ~homeassistant/.homeassistant/apps/
$ wget -O switch_reset.py 
 https://raw.githubusercontent.com/home-assistant/appdaemon/dev/conf/example_apps/switch_reset.py
$ wget -O globals.py 
 https://raw.githubusercontent.com/home-assistant/appdaemon/dev/conf/example_apps/globals.py

Add the following configuration to apps.yaml:

switch_reset:
 module: switch_reset
 class: SwitchReset
 log: ""
 file: "/home/homeassistant/.homeassistant/switch_states"
 delay: 10

After restarting AppDaemon, the changes to input_boolean, input_number, input_select and device_tracker entities will be stored inside /home/homeassistant/.homeassistant/switch_states, providing our switch state persistence.

Although we’re using automated applications, the major reason why people use AppDaemon is because it provides a dashboard interface so that you can expose and control Home Assistant entities on a touchscreen. Usually people use a TV or a tablet to show the dasboard, but, I’ve used the HardKernel 3.5″ LCD (http://www.hardkernel.com/main/products/prdt_info.php?g_code=G147435282441), with an ODROID-C2 as the computer backend.

In order to enable the dashboard (https://goo.gl/Z8iMW8), you will need to add the following section to appdaemon.yaml:

HADashboard:
 dash_url: http://0.0.0.0:5050
 dash_password: !secret api_password
 dash_dir: /home/homeassistant/.homeassistant/dashboards

The dash_password directive is optional. For ease of use, it’s best not to use a password, so that the dashboards can load on boot with no user intervention. You will need to create a sample dashboard under ~homeassistant/.homeassistant/dashboards. Create the directory first, then name it hello.dash:

$ mkdir ~homeassistant/.homeassistant/dashboards
$ mkdir -p 
 /home/homeassistant/.homeassistant/compiled/javascript/css
$ mkdir -p /home/homeassistant/.homeassistant/compiled/css
$ mkdir -p 
 /home/homeassistant/.homeassistant/compiled/html/default
$ cd ~homeassistant/.homeassistant/dashboards
$ vi hello.dash

hello.dash

#
# Main arguments, all optional
#
title: Hello Panel
widget_dimensions: [120, 120]
widget_margins: [5, 5]
columns: 8

label:
 widget_type: label
 text: Hello World

layout:
 - label(2x2)

After restarting AppDaemon, you will be able to access this at http://[odroid-ip]:5050/hello, where [odroid-ip] is the IP address of the ODROID-C2.

Dashboards are dynamically generate web pages which can render and control the states of Home Assistant entities. Most entities have corresponding snippets of dashboard configuration, which can control appearances. The reference documentation is available at https://goo.gl/G6iYib.

In order to get started, you need to specify the screen dimensions and think about how you want to divide the screen into widgets. Usually the screen is divided into x*y cells, and each cell has a fixed width and height. You have some flexibility because you can merge cells to create a bigger one, and you can also have empty cells or rows. The standard cell size is 120×120 pixels. Since the 3.5″ display has a small resolution (480×320), we’ll need to get creative and implement some sort of menu to jump between different dashboards. We will also use small cells, 38×38, with a 1 pixel margin and combine them together to create larger widgets when needed. Note that if you are using a large enough screen you can use, and should use, larger widget sizes to avoid layout issues.

Regarding navigation with a menu, HADashboard has a navigation widget which can be used to load a different dashboard. The plan is to create an 8-item vertical menu which will be imported in all dashboards for quick navigation, then populate the dashboards according to my needs with internal data from Home Assistant, sensors, switches, media players, cameras, and external data such as Netdata Dashboard graphs or online weather. One of the buttons can serve as a menu and load a different dashboard with more buttons, so you have a lot of options.

Here is an example dashboard head that I’ve duplicated on all dashboards:

#
# Main arguments, all optional
#
title: 3.5in LCD panel - 480x320 divided into 12x8 cells - Home
widget_dimensions: [38, 38]
widget_margins: [1, 1]
columns: 12
use_gass_icon: 1

In order to set up navigation, I’ve set up a list of «buttons» in a different file called ~homeassistant/.homeassistant/dashboards/navigation-definition.yaml, which is imported in all dashboards and looks like this, just a few items are shown to give you an idea:

home:
 widget_type: navigate
 dashboard: "lcd35-hq"
 icon_active: fa-home
 icon_inactive: fa-home
mpd:
 widget_type: navigate
 dashboard: "mpdkitchen"
 icon_active: fa-music
 icon_inactive: fa-music
tv:
 widget_type: navigate
 dashboard: "tv"
 icon_active: mdi-television-classic
 icon_inactive: mdi-television-classic
 icon_style: "font-size: 1.5em !important;"
 …

extendedmenu:
 widget_type: navigate
 dashboard: "extendedmenu"
 args:
 timeout: 10
 return: lcd35-hq
 icon_active: mdi-menu
 icon_inactive: mdi-menu

You can get a copy of the complete file at https://goo.gl/vwYD33. As you can see, most entries are navigation widgets which get a dashboard file name as a parameter and can have a custom icon or style. The «extendedmenu» item causes that dashboard to be loaded for 10 seconds, then the «lcd35-hq» dashboard is loaded, if there is no other action. This allows you to simulate a popup menu that goes away by itself.

The layout of the widgets on the page is done by creating a layout directive with the rows enumerated below it. For each cell in a row, you would write the widget name as defined in the dashboard, or imported files. Widget names may have their size appended to the name. In order to reuse the configuration as much as possible, you can also import external definitions from other dashboards, like the navigation snippet above. The following snippet is from the main dashboard:

layout:
 - include: navigation-definition
 - include: sensors
 - home, clock(4x4), weather(7x4)
 - mpd
 - webcams
 - tv
 - heating, sensorliving(2x4), sensorkids(2x4), heater(2x4), forecast(5x4)
 - cooling
 - blinds
 - extendedmenu

The leftmost items on the list are the navigation targets defined in the navigation-definition.yaml file. Unfortunately, since I wanted to have a vertical menu, I need to explicitly add them to each dashboard. If I had only a horizontal row, I could have done the layout inside the navigation-definition.yaml file.

The top row begins with a small «home» widget used to navigate back here, then a 4×4 clock widget and a 7×4 weather widget. The next row lists only «mpd», which is part of the menu. The rest of the row is occupied by the big clock and weather widgets, so no new items are appended. Using this logic you can get a mental image of how it’s supposed to look. The rest of the items are defined in the dashboard and in the included sensors.yaml, like this:

clock:
 widget_type: clock
 time_format: 24hr
 show_seconds: 0
 time_style: "color: yellow; font-size: 40pt; font-weight: bold;"
 date_style: "font-size: 16pt; font-weight: bold;"

weather:
 widget_type: weather
 units: "°C"
 sub_style: "font-size: 110%; font-weight: bold;"
 main_style: "font-size: 75%; font-weight: bold;"
 unit_style: "font-size: 250%;"

forecast:
 widget_type: sensor
 title: Prognoza
 title_style: "font-size: 14pt;"
 text_style: "font-size: 16pt; font-weight: bold;"
 precision: 0
 entity: sensor.dark_sky_forecast_ro

As you can see, most widgets require an entity which provides the glue to Home Assistant items, a type and the rest of configuration deals with fonts, colors and icons. The icons of various widgets can come from Home Assistant, but can be overridden with icons from Material Design, https://materialdesignicons.com, prefixed with mdi, or from Font Awesome,http://fontawesome.io, prefixed with fa.

If you were to load this dashboard right now in a browser by navigating to http://odroid-ip:5050/lcd35-hq, it would look like Figure 4.

However, there seems to be a problem with the layout of the navigation widgets. If you were to use Developer Tools in your browser and inspect the layout, you’d see that while the widgets are placed correctly, the icons inherit a CSS style which uses absolute positioning to offset the icon by 43 pixels downward. This is a problem because the dashboard was designed for larger displays with bigger widgets. In order to get around the issue, it’s best if we create a skin that loads a custom javascript file that resets the absolute layout of icons and also adjusts the size. In order to do this, you’ll need some Javascript, HTML and CSS know-how, but you can get the finished skin from at https://goo.gl/Fwcbti.

$ sudo su - homeassistant
$ cd .homeassistant/
$ mkdir -p custom_css/defaultsmall
$ cd custom_css/defaultsmall
$ wget -O dashboard.css 
 https://raw.githubusercontent.com/mad-ady/home-assistant-customizations/master/appdaemon_skins/defaultsmall/dashboard.css
$ wget -O dashboardsmall.js 
 https://raw.githubusercontent.com/mad-ady/home-assistant-customizations/master/appdaemon_skins/defaultsmall/dashboardsmall.js
$ wget -O variables.yaml 
 https://github.com/mad-ady/home-assistant-customizations/blob/master/appdaemon_skins/defaultsmall/variables.yaml

Now, if you reload the dashboard and specify an explicit skin you’ll get much better results (http://[odroid-ip]:5050/lcd35-hq?skin=defaultsmall)

Now you can take a look at my dashboards. All the configuration is at https://goo.gl/VuB9sr. The MPD dashboard consists of 3 similar dashboards that I can cycle through by using the top navigate widgets. They load 3 different MPD instances around the house. The difference between the dashboards are just the instance loaded (see mpdkitchen below). The dashboard’s layout is pretty simple:

layout:
 - include: navigation-definition
 - include: mpd
 - home, navigationmpdliving(4x1), navigationmpdkids(4x1), navigationmpdkitchen(3x1)
 - mpd, mpdkitchen(11x7)
 - webcams
 - tv
 - heating
 - cooling
 - blinds
 - extendedmenu

I also have a dashboard view to control my TV, which was imported in Home Assistant as described at https://ipad-mobile.ru/article/home-assistantscripts-customization/. We are getting the image from a camera component inside Home Assistant and using the Camera Widget. The buttons are used to control the virtual remote and connect to script components in Home Assistant as well as to the script entity in HADashboard. An example for layout and widgets can be found below:

layout:
 - include: navigation-definition
 - home, streamtv(10x8), tv_living_off
 - mpd, tv_living_on
 - webcams, tv_living_source
 - tv, tv_living_mute
 - heating, tv_living_volume_up
 - cooling, tv_living_volume_down
 - blinds, tv_living_ch_up
 - extendedmenu, tv_living_ch_down

streamtv:
 widget_type: camera
 entity_picture: http://192.168.1.4:8123/api/camera_proxy/camera.tv_living_image?token=62f78994c790a89459e2f60cc6ed80bdfce3e9b5ff5473633ba60e3d7089f0a6&api_password=odroid
 refresh: 2

tv_living_off:
 widget_type: script
 entity: script.tv_living_power_off
 icon_on: mdi-power-plug-off
 icon_off: mdi-power-plug-off

tv_living_on:
 widget_type: script
 entity: script.tv_living_power_on
 icon_on: mdi-power
 icon_off: mdi-power

What’s different about the camera widget is that it requires a URL via Home Assistant’s API. This URL has to include the API key and also a token which is visible in Home Assistant -> Entities view for the entity in question. If you also use a password to access Home Assistant, you’ll need to append the password to the URL. Figure 7 shows you the end result.

Another dashboard allows you to control the heater, manually, and the thermostat. The configuration for the thermostat widget looks like this, and the end result is in Figure 8.

layout:
 - include: navigation-definition
 - include: sensors
 - home, heater(4x4), thermostat(6x8)
 - mpd
 - webcams
 - tv
 - heating, sensorliving(2x4), sensorkids(2x4)
 - cooling
 - blinds
 - extendedmenu

thermostat:
 widget_type: climate
 title: Thermostat
 step: 0.5
 precision: 1
 entity: climate.heater_thermostat
 unit_style: "color: yellow;"
 level_style: "color: yellow; font-size: 48pt;"
 unit2_style: "color: yellow;"
 level2_style: "color: yellow; font-size: 40pt;"
 level_up_style: "font-size: 20pt;"
 level_down_style: "font-size: 20pt;"

During the summer, the Cooling dashboard will see some use. Here are placed the sensors, switches and timers that control the AC system, as described in https://ipad-mobile.ru/article/home-assistantscripts-customization/ . The dashboard looks like Figure 9.

The extended menu is nothing more than a dashboard with more navigate widgets. In it, I have links to a Netdata dashboard and an Hourly forecast and images from my webcams, with room for more in the future.
The Hourly Weather forecast dashboard makes use of the iframe widget to load a URL, while the Netdata Dashboard cycles through a list of URLs every 5 seconds:

mynetdata:
 widget_type: iframe
 refresh: 5
 url_list:
 - http://192.168.1.5:19999/server1.html
 - http://192.168.1.5:19999/server2.html
 - http://192.168.1.5:19999/server3.html
 - http://192.168.1.5:19999/server4.html
 - http://192.168.1.5:19999/server5.html

Now that the dashboard is working to your liking, you’ll have to invest a bit of time on the display side. You can start with @FourDee’s installation script for the display at https://forum.odroid.com/viewtopic.php?t=24248. You will also need to enable autologin inside lightdm (https://wiki.odroid.com/accessory/display/3.5inch_lcd_shield/autox#auto_login). Once this is done, it’s time for some cleanup. It’s best to remove programs that display popups on screen, like the Update Manager and screensaver:

$ sudo apt-get remove update-manager gnome-screensaver

We will also prepare a script that runs Chromium in Kiosk mode, with no password store, so that it won’t ask you every time to unlock your password store. Chromium will also be set up with a fix that makes it forget it crashed, so in case of an unclean shutdown, it won’t ask you if you want to restore the previous session. In addition to this, we’ll set the monitor to always on:

$ cat /usr/local/bin/kiosk-mode.sh
#!/bin/bash
/usr/bin/xset s off
/usr/bin/xset -dpms
/usr/bin/xset s noblank
/bin/sed -i 's/"exited_cleanly": false/"exited_cleanly": true/' ~/.config/chromium/Default/Preferences
dashboard=lcd35-hq
/usr/bin/chromium-browser --noerrdialogs --incognito --password-store=basic --kiosk http://odroid-ip:5050/$dashboard?skin=defaultsmall
$ sudo chmod a x /usr/local/bin/kiosk-mode.sh

You can also add the Scrollbar Anywhere Chrome extension (https://goo.gl/UD3hDA). Configure it to react to the left button and enable «Use Grab-and-drag style scrolling» so that you can scroll, if needed, with your finger on the dashboard.

Test that the script is working correctly when started from the graphical environment, and when ready, you can add it to the list of autostarted applications in Control Center -> Personal -> Startup Applications. Just click “add”, use «Kiosk mode» for the name, and /usr/local/bin/kiosk-mode.sh as the command. Once you restart lightdm, you should see a full screen dashboard.

Show in Figure 11 is the end result, running on the 3.5″ display. Hardkernel’s 3.5″ display is perfect for a small dashboard. The font sizes and colors used are optimized for easy reading from 2-3 meters away and the contrast helps with reading from wider angles. The display’s low refresh rate of 10 fps is not noticeable with the dashboard.

You can get the dashboard configuration files from the GitHub project at https://ipad-mobile.ru/mad-ady/home-assistant-customizations, and view a demonstration video at youtu.be/fEoHs3-_3B0. Please note that they were tested with appdaemon 2.1.12, but version 3 is currently under development ,and by the time you implement this, some things may have changed slightly. Keep an eye on the GitHub repository and on the support thread at https://forum.odroid.com/viewtopic.php?t=27321.