Continuing on from last weeks post, I was also recently persuaded to try out AppDaemon for Home Assistant (again). I have previously tried out AppDaemon, so that I could use the excellent OccuSim app. I never got as far as writing any apps of my own and I hadn’t reinstalled it in my latest HASS migration. This post is going to detail my first steps in getting started with AppDaemon more seriously.
I should probably start with a run down of what AppDaemon is for anyone that doesn’t know. The AppDaemon website provides a high level description:
AppDaemon is a loosely coupled, multithreaded, sandboxed python execution environment for writing automation apps for home automation projects, and any environment that requires a robust event driven architecture.
In plain English, that basically means it provides an environment for writing home automation rules in Python. The supported home automation platforms are Home Assistant and plain MQTT. For HASS, this forms an alternative to both the built in YAML automation functionality and 3rd party systems such as Node-RED. Since AppDaemon is Python based, it also opens up the entirety of the Python ecosystem for use in your automations.
AppDaemon also provides dashboarding functionality (known as HADashboard). I’ve decided not to use this for now because I currently have no use for it. I also think the dashboards look a little dated next to the shiny new HASS Lovelace UI.
Installation
I installed AppDaemon via Docker by following the tutorial. The install went pretty much as expected. However, I had to clean up the config files from my old install before proceeding. The documentation doesn’t provide an example docker-compose configuration, so here’s mine:
appdaemon:
image: acockburn/appdaemon:latest
volumes:
- /mnt/docker-data/home-assistant:/conf
- /etc/localtime:/etc/localtime:ro
depends_on:
- homeassistant
restart: always
networks:
- internalI’ve linked the AppDaemon container to an internal network, on which I’ve also placed my HomeAssistant instance. That way AppDaemon can talk to HASS pretty easily.
You’ll note that I’m not passing any environment variables as per the documentation. This is because my configuration is passed only via the appdaemon.yaml file, since it allows me to use secrets:
---
log:
logfile: STDOUT
errorfile: STDERR
appdaemon:
threads: 10
timezone: 'Pacific/Auckland'
plugins:
HASS:
type: hass
ha_url: "http://172.17.0.1:8123"
token: !secret appdaemon_tokenYou’ll see here that I use the docker0 interface IP to connect to HASS. I tried using the internal hostname (which should be homeassistant on my setup), but it didn’t seem to work. I think this is due to the HASS container being configured with host networking.
Writing My First App
I wanted to test of the capabilities and ease of use of AppDaemon. So, I decided to convert one of my existing automations into app form. I chose my bathroom motion light automation, because it’s reasonably complex but simple enough to complete quickly.
I started out by copying the motion light example from the tutorial. Then I updated it to take configuration parameters for the motion sensor, light and off timeout:
class MotionLight(hass.Hass):
def initialize(self):
self.motion_sensor = self.args['motion_sensor']
self.light = self.args['light']
self.timeout = self.args['timeout']
self.timer = None
self.listen_state(self.motion_callback, self.motion_sensor, new = "on")
def set_timer(self):
if self.timer is not None:
self.cancel_timer(self.timer)
self.timer = self.run_in(self.timeout_callback, self.timeout)
def is_light_times(self):
return self.now_is_between("sunset - 00:10:00", "sunrise + 00:10:00")
def motion_callback(self, entity, attribute, old, new, kwargs):
if self.is_light_times():
self.turn_on(self.light)
self.set_timer()
def timeout_callback(self, kwargs):
self.timer = None
self.turn_off(self.light)I’ve also added a couple of utility methods to manage the timer better and also to specify more complex logic to restrict when the light will come on. Encapsulating both of these in their own methods will allow re-use of them later on.
The timer logic of the example app is particularly problematic in the case of multiple motion events. In the original logic one timer will be set for each motion event. This leads to the light being turned off even if there is still motion in the room. It also caused some general flickering of the light between motion events and triggered callbacks. I mitigate this in the set_timer method here by first cancelling the timer if it is active before starting a new timer with the full timeout.
At this point, we have a fully functional and re-usable motion activated light. We can instantiate as many of these as we would like in our apps/apps.yaml file, like so:
motion_light_1:
module: motion_lights
class: MotionLight
motion_sensor: binary_sensor.motion_sensor_1
light: light.light_1
timeout: 120
motion_light_2:
module: motion_lights
class: MotionLight
motion_sensor: binary_sensor.motion_sensor_2
light: light.light_2
timeout: 60
...Note that we haven’t yet recreated the functionality of my original automation. In that automation, the brightness was controlled by the door state. We’ll tackle this next.
Extending the App
Since our previous MotionLight app is just a Python object, we can take advantage of the object orientated capabilities of the Python language to extend it with further functionality. Doing so allows us to maintain the original behaviour for some instances, whilst also customising for more complex functionality.
Our subclassed light looks like this:
class BrightnessControlledMotionLight(MotionLight):
def initialize(self):
self.last_door = "Other"
for door in self.args['bedroom_doors']:
self.listen_state(self.bedroom_door_callback, door, old = "off", new = "on")
for door in self.args['other_doors']:
self.listen_state(self.other_door_callback, door, old = "off", new = "on")
super().initialize()
def bedroom_door_callback(self, entity, attribute, old, new, kwargs):
self.last_door = "Bedroom"
self.log("Last door is: {}".format(self.last_door))
def other_door_callback(self, entity, attribute, old, new, kwargs):
self.last_door = "Other"
self.log("Last door is: {}".format(self.last_door))
def motion_callback(self, entity, attribute, old, new, kwargs):
if self.is_light_times():
if self.get_state(entity=self.light) == "off":
if self.now_is_between("07:00:00", "20:00:00") or self.last_door != "Bedroom":
self.turn_on(self.light, brightness_pct = 100)
else:
self.turn_on(self.light, brightness_pct = 1)
self.set_timer()Here we can see that the initialize method loads only the new configuration parameters. The existing parameters from the parent class are loaded from the parent’s initialize method via the super call. The new configuration options are passed as lists, allowing us to specify several bedroom or other doors. In order to set the relevant callbacks I loop over each list and set the callback. The callback is the same for each entry in the list since it only matters what type they are. The specifics of each door are irrelevant.
Next we have the actual callback methods for when the doors open. These just set the internal variable last_door to the relevant value and log it for debugging purposes.
Most of the new logic comes in the motion_callback method. Here I have reused the is_light_times and set_timer methods from the parent class. The remainder of the logic first checks that the light is off and then recreates the operation of the template I used in my original automation. This sets the light to dim if the last door opened was to one of the bedrooms and bright otherwise. There are also some time based restrictions on this for times when I always want the light bright.
The configuration is pretty similar to the previous example, with the addition of the lists for the doors:
brightness_controlled_motion_light:
module: motion_lights
class: BrightnessControlledMotionLight
motion_sensor: binary_sensor.motion_sensor
light: light.motion_light
timeout: 120
bedroom_doors:
- binary_sensor.bedroom1_door_contact
- binary_sensor.bedroom2_door_contact
other_doors:
- binary_sensor.kitchen_hall_door_contactConclusion and Next Steps
The previous automation (or more rightly set of automations) totaled to 78 lines. The Python code for the app is only 56 lines long. However, there is another 11 lines of configuration required. By this measurement, it seems like the two are similar in complexity. However, we now have an easily re-usable implementation for two types of motion controlled lights with the AppDaemon implementation. Further instances can be called into being with only a few lines of simple configuration. Whereas the YAML automation would need to be duplicated wholesale and tweaked to fit.
This power makes me keen to continue with AppDaemon. I’m also keen to integrate it with my CI Pipeline. Although I’m actually thinking of separating it out from my HASS configuration. With this I’d like to try out some more modern Python development tooling, since it’s been quite some time since I’ve had the opportunity to do any serious Python development.
I hope you’ve enjoyed reading this post. For anyone already using AppDaemon, this isn’t anything groundbreaking. However, for those who haven’t tried it or are on the fence, I’d highly recommend you give it a go. Please feel free to show off anything you’ve made in the feedback channels for this post!
Leave a Reply