Home Assistant — Setting Up for Advanced Projects

Read This First

The projects on this site involve editing Home Assistant configuration files, installing apps, and working with ESPHome devices. None of it is particularly difficult — but there are a handful of things you need to understand and set up before you start, or you will eventually break something and not know how to fix it.

This page covers everything. Do it once, do it properly, and the rest becomes straightforward.

1. Backups — Set These Up Before Anything Else

This is the single most important thing on this page. If you break your HA configuration and have no backup, you are starting from scratch. If you have a backup from last night, you are five minutes from a working system.

Enable Automatic Nightly Backups

1. Go to Settings → System → Backups
2. Click the three-dot menu in the top right
3. Select Automatic backups
4. Enable automatic backups, set the schedule to daily, and set how many to keep — 7 is reasonable

HA will now create a full backup of your entire installation every night including all configuration files, apps, and integrations.

Local vs External Backups

Backups stored on the same device running HA are useful but not sufficient on their own. If the SD card or SSD fails completely, your backups go with it.

An external backup is more valuable than a local one. Here is why: if something goes badly wrong and you do not know how to fix it, you can wipe the device completely, do a fresh HA install, and restore from your external backup. The whole process takes around 20 minutes and you end up with a perfectly working system as it was the previous night. This has saved at least one of us from a very bad day.

Options for external backup:

• Copy manually to a USB drive or NAS periodically via the Samba Share app
• Google Drive Backup — a community app that automatically copies backups to Google Drive on a schedule

If you do nothing else from this page, set up an automatic external backup.

How to Restore a Backup

If something goes wrong:

1. Go to Settings → System → Backups
2. Select the backup you want to restore
3. Click Restore
4. Choose full restore or restore specific parts
5. HA will restore and restart

A full restore takes a few minutes. When it comes back up it will be exactly as it was when the backup was taken. For a complete reinstall and restore from scratch, the HA documentation covers the recovery interface that is accessible even when the main UI is unavailable.

2. Essential Apps

Apps are additional software that runs alongside Home Assistant. Go to Settings → Apps to find and install them.

File Editor

You need a way to edit configuration files. File Editor is a simple browser-based text editor — it opens configuration files, shows a green tick at the top when the syntax is valid, and a red exclamation mark when there is an error. It is the right tool for the projects on this site.

To install: Go to Settings → Apps, search for File editor, click it and click Install. Enable Show in sidebar so it appears in the left menu. Click Start.

Advanced users may prefer Studio Code Server which provides a full VS Code editor experience with more features, but File Editor is sufficient for everything here and considerably less intimidating.

ESPHome Device Builder

Required for all ESP32 projects. This app compiles and flashes ESPHome firmware to your devices, and manages the connection between ESPHome devices and HA.

To install: Go to Settings → Apps, search for ESPHome, click ESPHome Device Builder and install it. Enable Show in sidebar.

Mosquitto Broker

Required if you want to use MQTT — the messaging protocol used to pass data between devices.

To install: Go to Settings → Apps, search for Mosquitto broker and install it. Once installed go to Settings → Devices & Services where it should appear as a discovered integration — configure it there.

For MQTT connections from ESPHome devices and tools like MQTT Explorer, use your HA username and password as the MQTT credentials.

Samba Share

Allows you to access HA files from your computer as a network drive. Useful for copying backups to an external location and for accessing configuration files from a desktop editor.

To install: Go to Settings → Apps, search for Samba share and install it. On the Configuration tab set a username and password, save, and start the app. The HA file system will appear as a network share at \\homeassistant.local\ on Windows or smb://homeassistant.local/ on Mac.

3. Understanding the File Structure

Home Assistant configuration lives in /config/. The files you will edit most often are:

You should never need to edit anything outside /config/ for the projects on this site.

4. secrets.yaml — Keep Passwords Out of Config Files

Any password, API key, or sensitive value should go in secrets.yaml, not directly in configuration.yaml. This means if you share your config files or paste them somewhere for help, your passwords are not exposed.

secrets.yaml lives in /config/ alongside configuration.yaml. It is simple key-value pairs:

wifi_ssid: "YourNetworkName"
wifi_password: "YourWifiPassword"
mqtt_username: "yourusername"
mqtt_password: "yourpassword"

In any other config file reference them with !secret:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

Create secrets.yaml once and add to it as needed. Never paste its contents anywhere public.

5. Editing configuration.yaml Safely

This is where most people get into trouble. configuration.yaml uses YAML format — a structured text format where indentation is critical. One wrong space and HA will refuse to start.

The good news is there are safety nets built in. Use them every single time.

Open the File

Click File editor in the left sidebar. Click the folder icon in the top left, navigate to configuration.yaml and open it.

YAML Rules You Must Know

Indentation uses spaces, never tabs. Two spaces per level is standard.

Indentation defines structure. This is valid:

sensor:
  - platform: template
    name: "My Sensor"

This is broken — name is indented one level too far:

sensor:
  - platform: template
      name: "My Sensor"

Colons need a space after them. name: "value" is correct. name:"value" will fail.

Lists use a dash and a space. - item not -item.

The Green Tick

File Editor shows a green tick at the top of the screen when the file syntax is valid, and a red exclamation mark when there is an error. Always wait for the green tick before saving. If you see a red mark there is a syntax error somewhere — find and fix it before saving.

Validate Before Restarting

After saving configuration.yaml, always validate it before restarting HA:

1. Go to Developer Tools — the </> icon in the left sidebar, installed by default
2. Click the YAML tab
3. Click Check Configuration

If valid you will see:

Configuration valid!

If there is an error it will tell you exactly which file and line the problem is on. Fix it, save, and check again before restarting.

Never restart HA without checking the configuration first. It takes ten seconds and saves enormous amounts of grief.

Restart Safely

Once the configuration check passes, click Restart in Developer Tools → YAML.

For minor changes such as template sensors or automations you can use the specific reload buttons rather than a full restart — faster and less disruptive.

What to Do When It Breaks

If HA fails to start after a configuration change:

1. The web UI may still be partially accessible even if HA core failed to load — try accessing it
2. Go to Settings → System → Logs to find the exact error
3. Open configuration.yaml in File Editor and fix the problem on the line indicated
4. Check the configuration again in Developer Tools
5. Restart

Nine times out of ten the problem is a missing space, an extra space, or a tab where there should be a space. The error message points directly at the line.

If you cannot access the web UI at all, restore last night’s backup.

6. Developer Tools

Developer Tools is installed by default in every HA installation — look for the </> icon at the bottom of the left sidebar.

States tab — if a sensor is not working, search for its entity ID here first. If it does not appear, the device is not connected to HA. If it shows unknown or unavailable, the device is connected but not reporting data yet.

Template tab — test any template expression here and see the result immediately before putting it into configuration.yaml. This saves many unnecessary restart cycles.

7. ESPHome — First Time Setup

ESPHome is the firmware framework used for all the ESP32 projects on this site. Getting the first device set up can trip people up — here is the process.

First Flash — Use the Web Installer

The very first time you flash a new ESP32 you need a USB cable and a Chrome or Edge browser (other browsers do not support the Web Serial API required for USB flashing).

Go to https://web.esphome.io and follow the prompts to install a basic ESPHome firmware via USB. This gets the device onto your WiFi network for the first time.

Common problems at this stage:

• Wrong USB cable — many USB cables are charge-only with no data lines. If the browser does not detect the device, try a different cable.
• Wrong COM port selected — if you have multiple devices connected, select the one that appears when you plug in the ESP32.
• Boot mode — some ESP32 boards need to be manually placed in boot mode before flashing. Try holding the BOOT button while clicking flash and releasing after upload starts. If that does not work, use this sequence: hold BOOT, keep it held, press and release RESET, then release BOOT. The board is now in boot mode and ready to flash.

After First Flash — Use the ESPHome App

Once the device is on your WiFi network, all subsequent flashes happen wirelessly (OTA — Over The Air) from the ESPHome app in HA. No USB cable needed.

In the ESPHome app, the device will appear as Discovered. Click Adopt to bring it under ESPHome management and create a yaml configuration file for it.

The yaml Configuration File

Every ESPHome device has a yaml file that defines everything about it — sensors, display, buttons, MQTT settings. The projects on this site provide complete yaml files you can use as a starting point.

Edit the yaml in the ESPHome app, click Install → Wireless to flash it over WiFi. The device will reboot with the new firmware.

Keeping Device Names Permanent

Once HA has discovered an ESPHome device and started recording its sensor data, do not change the device name in the yaml. Sensor history is stored against entity IDs derived from the device name. Renaming it creates new entities with no history.

8. MQTT Explorer

MQTT Explorer is a free desktop application for Mac, Windows, and Linux that connects to your MQTT broker and shows all topics and messages in real time.

Download from: https://mqtt-explorer.com

Connecting to Your HA Broker

Create a new connection with these settings:

What to Use It For

• Verifying that ESPHome devices are publishing data correctly
• Checking sensor values in real time
• Finding and deleting stale retained discovery messages when you rename or remove devices

Retained messages are shown with an R indicator. To delete one, click the topic, clear the value field, ensure the retain flag is set, and publish an empty message. This removes it from the broker permanently.

9. The HA Log

When something is wrong, the log tells you what. Check it after any significant change.

Settings → System → Logs

Errors appear in red, warnings in orange. Most warnings are harmless — focus on errors. The log shows the exact component and line causing the problem.

Download the full log file using the download icon in the top right — useful when asking for help.

10. Keeping Things Tidy

A few habits that prevent problems accumulating:

Check the log after every new device. A fresh device should add no new errors to the log. Fix them immediately — errors accumulate and become hard to untangle months later.

Give everything a unique name. Never give two ESPHome devices a sensor, button, or light with the same name. Generic names like "Restart" or "Display Backlight" cause duplicate entity ID errors when MQTT is involved.

Use secrets.yaml from the start. Retrofitting it later is tedious.

Never pull the power to restart HA. Always use the software restart. Pulling power mid-write can corrupt the database.

Keep purge_keep_days at a sensible value. The default is 10 days which is too short. 90 days is a good balance between database size and useful history. Long-term statistics are stored separately and never purged regardless of this setting.

You Are Ready

With backups running, the essential apps installed, and an understanding of how to edit configuration files safely, you are ready to tackle the projects on this site.

When something goes wrong — and it will occasionally — you have the tools to diagnose and fix it, and a backup to fall back on.

Questions or Problems

If anything on this site is unclear, incorrect, or missing a step that left you stuck, please get in touch. These guides are written from real experience and improved based on feedback.

Contact: fletcher@gingineers.com