Upgrading from 2.x

This documentation is for AppDaemon is 3.0.0 or later. If you are upgrading from a 2.x version, there have been some changes to the way AppDaemon is configured, and you will need to edit your config files and make some other changes. The changes are listed below:

Note that not all changes will apply to everyone, some of them are in fairly obscure parts of AppDaemon that few if any people use, however, everyone will have to make some changes, so read carefully.

  • AppDaemon no longer supports python 3.4

This is a fairly significant step, and the decision to do this was influenced by HASS’ pending end of support for Python 3.4. There are many technical reasons why this is a good thing, but the bottom line is that you will need to upgrade your python version to run HASS anyway, so I took this opportunity to follow suit. AppDaemon 3.0 will remain in beta until HASS drops python 3.4 support entirely.

  • Apps need to change the import and super class

The naming and placement of the imports needed to change to support the plugin architecture, and to make more sense of the naming in a multiple plugin environment. You will need to edit each of your apps and change the top couple of lines from:

import appdaemon.appapi as appapi

class MyClass(appapi.AppDaemon):
...

to:

import hassapi as hass

class MyClass(hass.Hass):
...

Note, we are changing both the import name, and the superclass.

  • info_listen_state() now returns the namespace in addition to the previous parameters

I introduced namespaces as a way of handling multiple plugins at the same time - the docs have more details, but if you are just using a single HASS instance, as everyone has been doing until now, you can safely ignore namespaces.

  • The “ha_started” event has been renamed to “plugin_started”

If you use this event, the name has been changed. The plugin started event has a parameter called name which gives the name of the plugin that was restarted.

  • RSS Feed parameters have been moved to the hadashboard section

When HADashboard is integrated with HASS, the config for HADashboard needs to be all in one place.

e.g.:

hadashboard:
  dash_url: http://192.168.1.20:5050
  rss_feeds:
    - feed: http://rss.cnn.com/rss/cnn_topstories.rss
      target: news
  rss_update: 300
  • Log directives now have their own section

Logging is a function of the underlying execution code, not specifically AppDaemon (for instance, when integrated with HASS, AppDaemon will use HASS logging. For that Reason, the log directives were pulled out into their own section. The section is optional, and if not specified all the previous defaults will apply.

For example:

log:
  accessfile: /export/hass/appdaemon_test/logs/access.log
  errorfile: /export/hass/appdaemon_test/logs/error.log
  logfile: /export/hass/appdaemon_test/logs/appdaemon.log
  log_generations: 5
  log_size: 1024
appdaemon:
...
  • AppDaemon section renamed to appdaemon, HADashboard section renamed to hadashboard

This was done mainly for consistency, and because the capitals bugged me ;)

  • Plugins (such as the HASS plugin now have their own parameters under the plugin section of the config file

This comes down to a reorganization of the appdaemon.yaml file to reflect the fact that there are now plugins and there may be more than one of them. Rather than having its own section, the HASS plugin is now listed under the appdaemon section, although the arguments remain the same. Here is an example:

appdaemon:
  api_port: 5001
  api_key: !secret appdaemon_key
  threads: 10
  time_zone: GMT+0BST-1,M3.5.0
  plugins:
    HASS:
      type: hass
      ha_key: !secret home_assistant_key
      ha_url: http://192.168.1.20:8123
      #commtype: SSE
  • –commtype command line argument has been moved to the appdaemon.cfg file

This parameter applies specifically to HASS, so it made no sense to have it as a commandline argument. See above for an example.

  • Accessing other Apps arguments is now via the app_config attribute, config retains just the AppDaemon configuration parameters

Required due to the restructuring of the config files.

  • the self.ha_config attribute has been replaced by the self.get_hass_config() api call and now supports namespaces.

This reflects the fact that the yaml files have been reconfigured, and that the config info is now owned by the individual plugins.

  • The !secret directive has been moved to the top level of appdaemon.yaml

The same argument as the logs - not strictly relevant to AppDaemon, more a concern of the execution environment.

  • apps.yaml in the config directory has now been deprecated

One of the new features in 3.0 is that it is now possible to split the apps.yaml into multiple files. You are free to do this in any way you want and place the yaml files with any name, anywhere in the directory hierarchy under the appdir. Apart from flexibility, another reason for this was to prepare the way for later features around configuration tools and automatic app installs. For now, the only necessary step is to move your apps.yaml file from the config directory into the apps directory. If you do not, you will get a warning but everything should still work for now. If you do stick with apps.yaml at in the config directory for now, any other yaml files in the apps directory will be ignored.

  • select_value() has been renamed to set_value() to harmonize with HASS

A minor change just to reflect the recent changes to HASS in this area, e.g input_slider being renamed to input_number and the service name changing.

  • It is no longer possible to automatically migrate from the legacy cfg style of config, and support for cfg files has been dropped.

This has been on the cards for a while - if you are still using cfg files, use the latest 2.0 version of appdaemon to migrate to yaml style configuration before you upgrade to 3.0.

  • App modules not listed in an apps.yaml file will no longer be loaded. Python modules may still be imported directly if they are in a directory in which other apps reside.

  • cert_path is deprecated. With the replacement of requests with aiohttp, it is now sufficient to set cert_verify to False to use a self signed certificate.

  • In apps.yaml, dependencies should now be a proper yaml list rather than a comma separated string

This rewrite introduces some breaking changes as dependencies are now tracked at the app level rather than the module level. This gives a lot more flexibility, and solves a couple of problems. For instance, @ReneTode, the undisputed AppDaemon power user has one App that he is running 60 different instances of. Under the old system, a change to one of those instances parameters in apps.yaml forced all 60 apps to reload - not good :) With the new app level dependencies, just the affected app will reload, along with any other apps that depend on it.

While I was in the code I made another change that I had been wanting to for a while - dependencies used to be a comma separated list, now they are a true yaml list.

So what does that mean for anyone upgrading? Well, if you weren’t using dependencies before, then absolutely nothing, all should work the same.

If you were using dependencies, you will need to make some minor changes, to reference apps rather than modules, and to change the format for multiple entries. Here’s an example of an old style dependency tree:

app1:
  module: module1
  class: class1
app2:
  module: module2
  class: class2
app3:
  module: module3
  class: class3
  dependencies: module1
app4:
  module: module4
  class: class4
  dependencies: module1,module2

Under the new system we change the dependencies to apps and change the way the dependencies are listed:

app1:
  module: module1
  class: class1
app2:
  module: module2
  class: class2
app3:
  module: module3
  class: class3
  dependencies: app1
app4:
  module: module4
  class: class4
  dependencies:
    - app1
    - app2

As you can see, single dependencies can be listed inline, but if you have more than one you must us the YAML list format.

For those of you that are relying on the module based reloading to force reloads of modules that aren’t apps, this can be achieved using global module dependencies.