# ¶ Configuration

Most configuration for homeassistant is done by the `services/homeassistant/config/configuration.yaml` file, which is in the `/config` directory in the container. It points to some other files, which are often inside `/config/.storage`. This is a docker named volume, so is specific to the box in question and persistent across updates.

## ¶ Automations

Some automations are installed on every box, so we store them in `/services/homeassistant/config/automations`.

Other are box-dependent, so should be made persistent. However, for them to be editable in the homeassistant ui, they must be at `/config/automations.yaml` in the container. In order to maintain persistent automations, we have two automations in the location above, and a docker named volume: `cofybox-homeassistant-config-storage`. These automations are stored at `/services/homeassistant/config/automations/automations_persistence.yaml`. One copies the `config/automations.yaml` file to the storage container (at `/config/.storage/user/automations.yaml`) whenever they are edited, from the front end or directly. The other loads the automations from the storage container back to `/config/automations.yaml` when homeassistant loads.

## ¶ Blueprints

Some blueprints are installed on every box. We store these at `/services/homeassistant/blueprints-automation-powershaper`, and copy them into `/config/blueprints/automation/powershaper` in the `start.sh` script. This is done so that we can also enable box-dependent blueprints to be persistent (see below).

Some blueprints are box-dependent. For these, we have mounted another docker named volume `cofybox-homeassistant-blueprints` directly to `/config/blueprints`, meaning that all blueprints are stored in this persistent way. To have certain blueprints installed on all devices, we copy these files into the volume (see above).

# ¶ Upgrading homeassistant

We should follow the homeassistant release cycle fairly closely. They release on the first Wednesday of every month at time of writing. There is usually a lot of good stuff, so it would be good to also update once a month.

We can only update when docker images have been uploaded to both the raspberrypi3 repository(for the boxes) and the amd64 repository(for testing locally).

We should check the release notes to see if anything is being deprecated or removed entirely, and act accordingly.

To do the upgrade, you just change the `ha_version` in the docker-compose file. It is also necessary to update the `ha_compatible_pip_version` to the latest pip version which that version of homeassistant is compatible with.

We should also check our custom integrations and scripts. These don't automatically update, so we have to do it manually.

To update custom integrations, you have to:

- clone the latest version of the repository from GitHub or similar (or the most recent stable version, if they have such a thing)
- remove the folder `services/homeassistant/custom_components/COMPONENT_NAME`
- copy the folder (and files within) `custom_components/COMPONENT_NAME` from the cloned repo, e.g. `cp -r ha-myenergi/custom_components/myenergi cofybox-balena/services/homeassistant/custom_components`
- make sure to test these with the new version of homeassistant.

The other things to check are the files under `services/homeassistant/config/automations` and `services/homeassistant/config/python_scripts`.

Once we've updated all of the above, we should test

- locally
- on a local mode box
- on staging
- on prod

Take note of any deprecation warnings when homeassistant starts up!