The Great Migration

Home Assistant is based around components. One type of components is the one that provide an entity abstraction for a type of device, like lights, switches or media players. Historically, to integrate with these abstractions, you would create a platform for this component. If the light component would be light/, the integration would create its platform as light/ This way, all logic for the lights was kept together.

As Home Assistant grown, so has the capabilities/size of the devices/services that we've integrated with. It's no longer that an integration is just a platform for an entity component, it is five platforms + a component to manage the connection. With integrations that big, having the files be spread out as light/, switch/, cover/ etc becomes a maintenance hell. It also makes distribution of custom components harder, as now users need to create files across different folders.

So with Home Assistant 0.87 we started a migration. Instead of looking up platforms for entity components as light/, we will now look it up as hue/ The content of the file will stay exactly the same. By moving the files out of the entity component folder, we will also be able to break up big entity components into multiple files, to support maintainability.

This change has been implemented mostly backwards compatible with a minor breaking change for custom components: if you override a built-in platform, you will now need to use the new hue/ filename format.

With the consolidation of integration files into a single folder, we're also going to enforce a new rule: all platforms will be loaded from the same source as the component. This means that if you want to override a built-in component/platform with a custom version, you will need to copy over all component and platform files, not just the one you want to load. By doing so, we can prevent custom platforms or components from breaking if a Home Assistant upgrade moves internal files/values around.

Notes for custom component developers

  • Components are created in <config>/custom_components/<integration name>/. Always make sure you create at least an empty file in that folder.
  • If you make a platform for an entity component, put it in the folder with the name of the integration: <integration name>/
  • If you want to share an adjusted version of a Home Assistant integration, copy over ALL the files. Do your users a favor and stick to relative imports to avoid having your component break during an upgrade. Example of a relative import is from . import DATA_BRIDGE.


Related architecture issues:

Deprecating homeassistant.remote

With the release of Home Assistant 0.76, the functions in the homeassistant.remote package will be deprecated and will be removed in 0.77. This package contains functions to call the Home Assistant REST API in a non-async way.

The reason for removing is two-fold: first the code is not being used inside Home Assistant and thus should not be part of Home Assistant. Second, it is not compatible with the new auth system nor do we want to spend the time to make it compatible.

If you want to keep using the methods in homeassistant.remote, feel free to copy the code to your own project.

Trying the new auth system

In Home Assistant 0.69 we introduced the foundation for a new authentication API. We're switching from a single hardcoded API password to a refresh/access token based authentication system (powered by OAuth2).

For Home Assistant 0.73, I've sprinted together with [@awarecan] to ensure that we have reached a minimum viable product of the auth system:

  • Users can be managed via a built-in command line script.
  • The frontend will ask for username and password to login
  • If you opt-in for the new system, the API password will no longer work.
  • To not force a hard break with the ecosystem around Home Assistant, a temporary legacy mode has been added to turn API password support back on. This will be removed in the future.

The system is not yet ready for mainstream consumption, we still need to add support and a user interface to help guiding the user to create their first user account and to manage users. You can follow (and join!) the work to be done here.

If you're interested in trying it out, keep on reading.

0.71: Improved custom panels and minor changes for custom UI

Efforts to modernize and localize the frontend are moving full speed. This blog post will touch upon the upcoming features for Home Assistant 0.71 which should hit the beta channel today and is planned for a release a week from now.

Improved Custom Panel support

Custom panels allow developers to build panels that will plug into the Home Assistant user interface, with the same possibilities like our other panels like history, map etc. The Home Assistant frontend will manage authentication and the subscription for states of the backend, the panel only has to take care of displaying the data and can offer users option to control things (calling services etc).

This support has been around for a while, but last week we've spend some time polishing our support and have three new additions:

First new feature is that we now allow importing a panel from a JavaScript URL. This is going to be the preferred way to distribute panels moving forward. This also means that you can refer to a panel hosted externally. The user will have to approve before external panels get loaded. It's still possible for users to host it locally (and no approval is needed) by copying the panel to <config dir>/www/your-panel.js and use /local/your-panel.js as the url.

Second new feature is that we can now embed your panel in an iFrame. This allows panel developers to not have to worry about including duplicate web components and it makes it possible to develop React-based panels. In the past, React-based panels didn't work because React doesn't work well inside Shadow DOM (more info).

Third new feature is that we now make a starter kit available to start developing React based panels! The kit contains everything that is needed to start developing React-based panels and share them with the community. Let us know what you're building!

Custom UI: <state-info> and <ha-relative-time>

If you're building custom UI, odds are that you're using either <state-info> and <ha-relative-time>. Although not officially supported as external facing API, we still want to give a heads up that it's going to be needed to pass the hass object in.

This is necessary because <ha-relative-time> can now be localized thanks to c727 in #1241

Updates for Custom UI and Custom Panels

With the release of Home Assistant 0.70, we've migrated the build pipeline for our frontend from being based on HTML imports to ES module imports (more on this later). One of the effects of this is that we're no longer using the window object to share classes, data and utilities with other pieces of code.

This might impact you if you dependend on some of this. Examples are Polymer (window.Polymer) or one of our utilitity functions that used to be available as window.hassUtil, window.HAWS or window.hassMixins.

To give developers time to migrate, we're adding a temporary legacy support layer that will expose some of our internals again on the window object. We've already added window.Polymer, window.Polymer.Element and window.Polymer.html. If you're using other specific things from the window object, please let us know.

Th legacy support layer will no longer be included in releases happening after July 2018.