Home Assistant Guide

Beginner's Guide: Your First AppDaemon App in Home Assistant

AppDaemon is a powerful way to create advanced automations for Home Assistant using real Python code. If you find Home Assistant's built-in python_script integration limiting, or you want more flexibility and capability in your automations, AppDaemon is worth exploring - even for beginners. This guide walks you step-by-step through installing AppDaemon, understanding the key differences, and writing your very first app.

What is AppDaemon?

AppDaemon is a separate add-on for Home Assistant that lets you write automations in Python. Unlike python_script (the built-in integration for running simple, limited Python code), AppDaemon runs as a full Python environment, so you can use imports, external packages, and advanced logic. It's great for anyone who wants to go beyond the basics and build automations that aren't possible with YAML or python_script alone.

• AppDaemon vs python_script:
  • python_script is simple and safe, but very limited. You can't import libraries, perform network requests, or run long scripts.
  • AppDaemon allows real Python code, imports, networking, and persistent apps that can respond to any event - not just triggers you define up front.
  • AppDaemon has a slightly steeper learning curve, but if you're considering writing your own Python scripts, it's well worth the extra bit of learning. This guide aims to bridge that gap for you.

1. Installing the AppDaemon Add-on

AppDaemon runs as an add-on in Home Assistant OS and Supervised installations. Here's how to install it:

1. In Home Assistant, click Settings in the sidebar.
2. Click Add-ons.
3. Click the blue Add-on Store button (bottom right).
4. Search for AppDaemon (usually appears as "AppDaemon 4" by the Home Assistant Community).
5. Click it, then click Install.
6. After installation, click Start.
7. (Optional) Click Show in sidebar for quick access.
8. Wait a moment for AppDaemon to boot up and set up its folders.

2. Locating the AppDaemon Apps Folder

Unlike regular Home Assistant scripts, AppDaemon stores its apps in a special folder, not in your main /config directory.

• The folder is usually:
  (The a0d7b954_appdaemon part may differ - just look for the folder with "appdaemon" in the name under addon_configs.)
• How to find it: Use the File Editor, VS Code, or connect via Samba/SSH to browse files. In the root of your file browser, find addon_configs, then open the appdaemon folder, then apps. This is where you'll place your Python app files.

3. Writing and Registering Your First App

1. Create the Test Switch (Input Boolean)
   • In Home Assistant, go to Settings > Devices & Services > Helpers.
   • Click Create Helper > Toggle.
   • Name it: AppDaemon Test.
   • The entity will be something like input_boolean.appdaemon_test.
2. Write Your App
   • Create a file called testnotify.py in your AppDaemon apps folder.
   • Paste in the following code:

   import appdaemon.plugins.hass.hassapi as hass
   
   class TestNotify(hass.Hass):
   
       def initialize(self):
           # This runs when the app loads or reloads
           self.log("TestNotify app is loaded!")
           # Listen for the input_boolean changing (on or off)
           self.listen_state(self.toggle_changed, "input_boolean.appdaemon_test")
   
       def toggle_changed(self, entity, attribute, old, new, kwargs):
           # This runs every time the toggle changes
           message = f"Test switch changed from {old} to {new}"
           self.log(message)
           # Show a notification in Home Assistant
           self.call_service(
               "persistent_notification/create",
               title="AppDaemon Test",
               message=message
           )
   

   Code Explanation (click to expand)

   • import appdaemon.plugins.hass.hassapi as hass – Imports the special AppDaemon helper code that lets your app talk to Home Assistant.
   • class TestNotify(hass.Hass): – Defines your app as a Python class. All AppDaemon apps inherit from hass.Hass.
   • def initialize(self): – This special function runs automatically when the app starts. Good for setup code.
   • self.log(...) – Sends a message to the AppDaemon logs.
   • self.listen_state(self.toggle_changed, "input_boolean.appdaemon_test") – Tells AppDaemon: when this entity changes, run your function.
   • def toggle_changed(self, entity, attribute, old, new, kwargs): – This function runs every time the toggle is changed.
   • message = f"...{old} to {new}" – Builds a message about the change. The f before the quotes means this is an f-string: a way to insert variables into a string in Python.
   • self.call_service(...) – Creates a notification in Home Assistant (shows up under the bell icon).
3. Register Your App
   • Open (or create) apps.yaml in the same apps folder.
   • Add:

   test_notify:
     module: testnotify    # the filename, without .py
     class: TestNotify     # the class name you wrote
   

4. Restart the AppDaemon Add-on
   • Go to Settings > Add-ons > AppDaemon.
   • Click Restart.
   • Watch the add-on logs for errors or the "TestNotify app is loaded!" message.

4. Testing Your App

• In Home Assistant, go to your dashboard or Developer Tools > States.
• Find the entity input_boolean.appdaemon_test and toggle it ON or OFF.
• You should see:
  • A notification in Home Assistant ("bell" icon) saying the toggle changed.
  • Log messages in the AppDaemon logs confirming it ran.

Summary Table: Steps at a Glance

Troubleshooting Tips

• App not running?
  • Double-check that the file name (testnotify.py), class name (TestNotify), and apps.yaml entries match.
  • Make sure both the Python file and apps.yaml are in the correct apps folder.
  • Restart AppDaemon after changes.
• No notification?
  • Check the AppDaemon logs for errors.
  • Make sure the input_boolean entity name matches in your code and Home Assistant.

Next Steps

• Explore the AppDaemon API documentation for more advanced automations.
• Try listening for other entities, sending mobile notifications, or controlling lights from your app.
• Remember: AppDaemon gives you the full power of Python - ideal for anyone ready to move beyond Home Assistant's basic automation tools.