Home Assistant Packages

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.

Realistic Setups

In real life, many people, like myself, have their configuration spread across different files. Converting those separate files to packages often…

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.yaml

# /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 want to discover other information about Home Assistant Packages then please visit the official feature page.

If you need help with this feature then you can either:

Credits

Featured image by RoseBox رز باکس on Unsplash

“I will now” photo by Rhett Wesley on Unsplash

Further Reading

Here are links to a few good coding practices:

Grandadevans

I am a disabled veteran of 3 tours of Iraq and a tour of Afghanistan as part of the British Army. No longer able to work as I have to lay down on a sofa-bed in my living room 20-ish hours a day. I'm hoping to be able to make a living blogging about my Home Automation /Smart Home journey and maybe regain some dignity in life.

Leave a Reply