Note: Please, be aware that this post may contain affiliate links.
Home Assistant Packages have been around for a while now, but you rarely hear anything about them. I must admit, I’ve only recently started using them myself.
What are Home Assistant Packages?
In the basic terms: they are single files that allow you to group together all of the code for a certain integration or other groups of code.
For example, I use the Home Assistant Alexa integration quite a bit (separate post on its way), which utilises Home Assistant Packages. That means that if for some reason the Alexa integration becomes obsolete and I have to completely remove it, all I have to do is delete that specific file, and remove the integration.
In real life, many people, like myself, have their configuration spread across different files. Converting those separate files to packages often…
- means you can often find things quicker
- saves you having to edit a central & essential file
- helps with the separation of concerns
(other good coding practices in the Further Reading)
Let’s take a look at another example, this one I will refactor while I am writing this post to show you how neater it makes my codebase. I have chosen to concentrate on my Tado integration as it doesn’t involve too many items, but it helps me get the point across.
Tado Heating Example
I’m actually going to list the files as they currently are, and then I’m going to condense them all into a package:
# Integration details /config/tado.yaml # Extract the actual temperature /config/sensors/attributes__tado__actual_temperature.yaml # Extract the actual humidity /config/sensors/attributes__tado__actual_humidity.yaml # Extract the desired temperature /config/sensors/attributes__tado__desired_temperature.yaml # Make sure heating is off when windows/doors open /config/automations.yaml # device tracker /config/device_trackers/tado.yaml
I will now condense all these into a single file!
# /config/packages/tado.taml #Integration details tado: username: !secret tado_username password: !secret tado_password # device tracker device_tracker: platform: tado username: !secret tado_username password: !secret tado_password home_id: !secret tado_home_id new_device_defaults: track_new_devices: false #Sensors sensor: - platform: attributes friendly_name: "Living Room Actual Temperature" attribute: current_temperature unit_of_measurement: "°C" entities: - climate.living_room - platform: attributes friendly_name: "Living Room Actual Humidity" attribute: current_humidity unit_of_measurement: "%" entities: - climate.living_room - platform: attributes friendly_name: "Living Room Desired Temperature" attribute: temperature unit_of_measurement: "°C" entities: - climate.living_room - platform: attributes friendly_name: "Heating Mode" attribute: hvac_modes entities: - climate.living_room automation: # Turned heating off when somebody opens door/window - id: '1580529178046' alias: Turn heating off if windows or doors open description: '' trigger: - entity_id: group.windows_and_doors from: 'off' platform: state to: 'on' condition:  action: - data: hvac_mode: 'off' entity_id: climate.living_room service: climate.set_hvac_mode # Turned heating off when somebody opens door/window # TODO: I need to change this so before the heating is turned off the current state is assigned to a variable and then that state is then re-applied when door/window is closed again - id: '1580530514789' alias: Turn heating on when all windows and doors closed description: '' trigger: - entity_id: group.windows_and_doors from: 'on' platform: state to: 'off' condition:  action: - data: hvac_mode: auto entity_id: climate.living_room service: climate.set_hvac_mode
Tell Home Assistant we are using Packages
We now need to tell Home Assistant that we are using packages. So under the “homeassistant” section of your configuration.yaml place the following
homeassistant: packages: !include_dir_named packages
Hopefully, you can see how grouping all the code for similar things together in a single file can make sense.
For me, it means that if I have problems with the Tado unit and I have to put my old thermostat back up, I just need to move the /config/packages/tado.yaml file to /config/packages_unused/ dir (a common tactic I use) and I can get rid of all the entities in a single shot.
An even more complex example
An even more complex example is one that relates to the whole Alexa echo-system <– get it? echo-system? Do you see what I did there? You see I replaced “eco” with “echo” – it’s a play on wor…
Never mind: if I have to explain it, it’s not funny 🙁
Anyway – that example is from another post that I’m writing at the same time as this and is dedicated to the Alexa TTS integration in Home Assistant.
Adding Home Assistant Packages
As well as including a single file for every Home Assistant Package, you could include them in a number of other ways including inline and recursive subdirectories.
My preferred choice is still the one I’ve outlined though.
If you need help with this feature then you can either:
- See if the answer is on the official feature page
- Follow the guidance on the official help page
- Leave a comment on here
- Contact me
- Ask for help on the community forum
- Go back to your old way of thinking :-/
Here are links to a few good coding practices: