Tag: hass.io

How to set up Git to version control your Home Assistant configuration

Congratulations on making it this far!

You now have an installation of Hass.io running on your Raspberry Pi. This is the crucial point where you want to begin treating your installation with more care and professionalism.

There is a phrase in the DevOps world that applies here. “Treat your servers like cattle, not pets”. This means that you want your server (i.e. Raspberry Pi) to be homogeneous and easily replaceable (like cattle). You don’t want your server to be hand-built and hand-maintained (like pets).

This means that you should be able to throw away your server (i.e. flash it with a clean install) and use Infrastructure as Code (IaS) to configure it.

In the cloud development world, we would provision everything, including the server itself with code. In our installation, we have an actual piece of hardware (i.e. Raspberry Pi) and so we can’t do a complete IaS implementation.

However, we can version control our Hass.io configuration. Hass.io runs on a series of YAML files. These are simple JSON documents that declarative describe what they system should do. Hass.io determines how to do it based upon what is in the YAML files.

Hass.io does have a built-in way to “backup” your configuration; snapshots. On the Hass.io page, under the “SNAPSHOTS” tab, there is a button to take a snapshot. The downside of this is that it is still stored locally. You would have to then setup a system to copy this snapshot somewhere else. Therefore, I do not recommend this as the primary way you back up your configuration.

The best way, in my humble opinion, is to use Git & Github to back up your configuration files. Git is the de-facto standard for source control management and Github is a free, online repository for backing up, contributing and sharing out source code with the world.

Note that this is a rehash of the excellent instructions on the Home Assistant website.

Be warned, however, Git is not a simple system to learn and there are a huge number of options. However, since you will be doing very little multi-user editing of the configuration files, you are unlikely to run into the big issues with understanding git’s branching, merging, rebasing, etc. tools. A few simple commands should be sufficient to effectively use Git.

Setting up Github

First, we need to set up a Github account so we can store our configuration files. Navigate to the Github signup page and create an account.

Once you have an account, click on the New Repository button to create a new repo to store your configuration files.

Give it a meaningful name (example: homeassistant-config). The standard naming convention for Git repos is all lowercase letters separated by a dash. This is not required, but will make typing it easier.

Choose Public or Private. This is really up to you. If you want to make it easier to share your configuration with others, you can make it Public. If you don’t want to do this, you can make it Private.

Warning!!! Because you will be uploading your configuration to a “public” site, you must be careful not to expose secrets. We will go into this later, but setting the repo to “Private” is not enough to protect your secrets (passwords, IP addresses, etc.). Hass.io has built-in ways to deal with these.

Do not check the “Initialize this repository with a README” checkbox. Since we will already have a repo set up on our local machine, we want to upload it to a clean Github repo.

Do not add a .gitignore or license file yet. We want a clean, empty repo to start with and we will have a custom .gitignore file anyway.

Initialize the Git repo

Now that we can login to our Raspberry Pi and see our configuration files, we need to upload them to Git.

  • Launch PuTTY and connect to your Raspberry Pi (if you need a refresher, please see my previous blog post).
  • Now we are in the directory where the Hass.io configuration files are located inside the Docker image (if you are in the “home” directory for the Raspberry Pi, either see my previous blog post).
  • Make sure git is already installed (or install if needed)
which git
/usr/bin/git       <-- already installed
                   <-- not installed (will not return anything)

sudo apt-get update         <-- update your packages
sudo apt-get install git    <-- install git if needed

You will now need to create a .gitignore file. This is the most important file, both to prevent publishing important/sensitive data (IP addresses, passwords, etc) and to reduce what you upload to Github to a minimum.

whoami         <-- which user are you logged in as
root

pwd
/config         <-- make sure you are in this directory

vim .gitignore

Here is a copy of the excellent .gitignore file from the Home Assistant website. Feel free to customize as needed.

# Example .gitignore file for your config dir.
# A * ensures that everything will be ignored.
*

# You can whitelist files/folders with !, these will not be ignored.
!*.yaml
!.gitignore
!*.md

# Ignore folders.
.storage
.cloud
.google.token

# Ensure these YAML files are ignored, otherwise your secret data/credentials will leak.
ip_bans.yaml
secrets.yaml
known_devices.yaml

Now we need to “initialize” your git repository. This means we are going to tell git that this directory and all of its contents should be tracked as version controlled files (excluding the files/directories mentioned in the .gitignore file, of course)

git init       <-- initialize as a version controlled directory

git status     <-- see what files have been modified
On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   configuration.yaml
        modified:   groups.yaml
        modified:   scene.yaml
        modified:   sensor.yaml
        modified:   switch.yaml

You are now seeing a listing of all the files and directories that git sees that have not been committed yet (your list will be different depending on what was set up in the directory).

We need to set some configuration options so git knows how to annotate our changes

git config user.email "dwight.k.schrute@dunder-mifflin.com" 
git config user.name "dwight"   

We need to “add” all the files and directories to the changeset so git saves their current state.

git add *

Now commit your changes so git will save them.

git commit -m "Initial checkin"

Excellent, now you have an initial git repo with a known setup that you can always refer to (or revert to if you break something).

Generate SSH key to connect between Raspberry Pi and Github

Now we need to “push” our changes to a central server to back them up. Git is a distributed version control system. This means it tracks and saves changes locally, but does not “upload” them somewhere else unless you tell it to. This was originally designed to allow lots of people to work independently (even when disconnected) and make it easy to upload and share code when network connectivity was restored.

The most secure way to connect to Github is via SSH key. Here is the link to the help documents on the Github site. We need to generate an SSH key locally, store it in the SSH agent on the Raspberry Pi and then upload it to Github.

Note: we have to generate and store the SSH key in the /config directory inside the Docker container. If it is stored anywhere else (like the default location, ~/.ssh/id_rsa, it will get deleted the next time the container is restarted.

  • Make sure you are in the /config directory
pwd
/config
  • Make a new directory to store the key, generate the ssh key and save it to disk. Save the file to .ssh/id_rsa. Enter a passphrase if you want to (you will be required to enter it each time unless you also set up ssh-agent, I’m not doing this as I feel it is overkill at this time).
mkdir .ssh       <- create a new "hidden" directory to store the key in

ssh-keygen -t rsa -b 4096 -C "dwight.k.schrute@dunder-mifflin.com"
Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa): .ssh/id_rsa
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in .ssh/id_rsa.
Your public key has been saved in .ssh/id_rsa.pub.

Now we need to upload the SSH key to Github so we can use it to authenticate our git repo pushes.You need to copy the public key from your local Raspberry Pi to Github (actual key redacted). If you are using Putty, you can just highlight the text starting with ssh-rsa and ending with your email address and it will be copied to the clipboard.

cat .ssh/id_rsa.pub
ssh-rsa .......................................................................................................................................................................................................................................== dwight.k.schrute@dunder-mifflin.com
  • In your Github.com account you created earlier, click on your profile picture in the upper-right hand corner and select Settings.
  • Select SSH and GPG keys
  • Click on New SSH key
  • Enter a Title: Home Assistant (or whatever will remind you what this key is used for)
  • Enter the Key: ssh-rsa…
  • Click Add SSH key
  • Enter your Github.com password to confirm

Push from Raspberry Pi to Github

Now you can “push” your configuration files from your Docker container to Github so they are backed up.

  • Navigate to your Github repo (click on the left-hand icon and select the repo you created earlier)
  • Click on the Clone or download button
  • Click on the Use SSH hyperlink in the right-hand corner if it is not already selected (the title of the dialog should say ‘Clone with SSH’)
  • Copy the url (git@github.com:username/repoName.git)
  • Set the remote repo where git will push your changes
git remote set-url origin git@github.com:dw/homeassistant-config.git
  • If you try to push now, you will get a permission denied error (-u says to use a new upstream repo for this branch, origin is the name of this upstream repo in git, master is the branch we are on). This is because you have stored your SSH key in a non-standard location. We need to tell git where to find the SSH key.
git push -u origin master
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
  • Git allows you to store configuration files locally, inside the repo itself. This is especially useful for our Docker container since we don’t want these changes to be lost when the container restarts. We need to tell Git where to find our SSH file
git config core.sshCommand "ssh -i /usr/share/hassio/homeassistant/.ssh/id_rsa -F /dev/null"

git push -u origin master           <-- push your changes to Github.com
Enumerating objects: 19, done.
Counting objects: 100% (18/18), done.
Delta compression using up to 4 threads
Compressing objects: 100% (11/11), done.
Writing objects: 100% (12/12), 1.26 KiB | 143.00 KiB/s, done.
Total 12 (delta 8), reused 0 (delta 0)
remote: Resolving deltas: 100% (8/8), completed with 5 local objects.

To github.com:dw/homeassistant-config.git
 * [new branch]      master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'.

Hurray! You have successfully uploaded your initial configuration to Github!

How to set up Home Assistant (Hass.io) as a home automation hub

Now that you have set up the hardware and flashed the software for running your hub, you need to configure both Home Assistant software and the Raspberry Pi OS.

Overview

  • Login to Hass.io the first time
  • Login to your Raspberry Pi via SSH
  • Change the default password right now!!!!
  • Enable VNC for GUI-based access to your Raspberry Pi
  • Change basic security settings on your Raspberry Pi

Login to Hass.io the first time

You will now log into Hass.io from your browser window. The trick now is to figure out what IP address has been assigned to your Raspberry Pi. Unfortunately, there is not a single, consistent to do this. The process will be different depending on your network hardware and how you connected your Raspberry Pi to the network (wired vs. wireless). You will need to login to your router to figure out what IP address. The reason for this is that your router will assign an IP address to the Raspberry Pi that you plugged into it, but you cannot predict what that IP address will be. After getting logged in, though, we can assign a static IP address going forward, to ensure it is always the same, but the first time, we will have to ask the router what IP address was assigned.

If you are using Ubiquiti hardware and Unifi software to run your home network (in my opinion, a fantastic option and one I will cover in more detail in a future post), you can login to your Unifi controller, then navigate to the “Clients” page to see all of the devices on your home network.

Initially, the “name” column may be something else (like the MAC address or a random name. You can look at the Device Vendor column to see that the manufacturer is “Raspberr” to determine that, indeed, this is your Raspberry Pi. Mine is set on 192.168.1.114 (this is my IP address inside my home network, yours is very likely to be different, make a note of the IP address, you will need it later).

Naturally, I recommend you rename this device right now so that it is easy to identity in the future. Note also that I have plugged my Raspberry Pi directly into my wired network (LAN) instead of using the wireless connection. This is to maximize the speed my Raspberry Pi can respond to other devices on the network (specifically Pihole), but there is nothing wrong with setting it up on the wireless network if you prefer.

Now that we know the IP address, we can open a browser and navigate to http://192.168.1.114:8123 (port 8123 is the default port that Hass.io is set up to listen to). If you have set up everything correctly, you will see the Hass.io home screen.

Yours will not be this complicated starting out. I have added lots of sensors, switches, controls, plugins, etc to my system. I will detail how I have set up all of these various systems in future blog posts.

The important thing is that you got this far!

Login to your Raspberry Pi via SSH

Now that you know you have a working Hass.io setup, you need to be able to login to the actual OS that is installed on your Raspberry Pi.

Earlier, you found the IP address for your Raspberry Pi in your router’s clients page. We will use that IP address to login to the OS.

In Windows, installPutty. Putty is a free SSH client for Windows. You will use it to login to the command prompt for your Raspberry Pi. Don’t worry if you are not comfortable always working on the command line, I will walk you through setting up VNC so you can have a GUI interface to the Raspberry Pi.

Many things in both the Raspberry Pi and Home Assistant can be configured via the GUI, but many things cannot. You will be most effective and will be able to configure the system exactly to your liking if you begin to learn and be comfortable with the command line (specifically, the Linux shell Bash).

Open Putty and enter the following configuration values:

  • Host Name (or IP address) – IP address of your Raspberry Pi, example: 192.168.1.114
  • Port – 22 (the default for SSH connections)
  • Connection Type – SSH

Click Open. The first time you do this, you will be asked for the username you wish to login with. By default, the Raspberry Pi has a user called “pi” with a password of “raspberry“. Don’t be shocked (this password is well-known), we are going to change this right away. If you are not familiar with Putty, you can “copy” a string to your Windows clipboard (highlight the raspberry string, right-click and select Copy, use the keyboard shortcut Ctrl+C, etc) and “paste” it by right-clicking in the Putty command window. You will not see any change since it is a password, but you can now press the Enter key and and it will log you in.

Congratulations! You are now a l33t h4ck32!.

Change the default password right now!!!!

I cannot stress this enough. The default password for the Raspberry Pi is raspberry. This is extremely well known and you must not leave it as the default or your system will get hacked by automated scanning tools that are constantly scanning all IP addresses and trying all well-known logins.

Don’t worry yet, though, your home network is an isolated bubble. You router is presenting a single IP address to the Internet (assigned by your Internet Service Provider, ISP). Your router is providing a local, internal network that all of your devices connect to. The IP address range for internal networks is typically 10.x.x.x, 172.16.x.x or 192.168.x.x. Your router is “protecting” your internal network and not broadcasting what the internal IP addresses of your devices are. Therefore, when automated tools try to login, they are blocked because they cannot ping the actual IP addresses of your devices, just the router (another good reason to change the default password on your router’s administration page as well).

However, you shouldn’t rely on just your router to protect you. You may decide to make your Raspberry Pi available on the Internet (though I will show you a different way to do this with a VPN) so you can access it remotely. You will definitely need to have set a different password to help ensure you do not get hacked.

Some sites will recommend changing the default username as well since pi is so well known. However, I have had several services on my Raspberry Pi break over the years because they expect the “pi” user to exist (not the best coding practice to expect a certain username to exist, but it happens). Therefore, I am not advocating changing the username at this time.

In addition, the best way to lock down your Raspberry Pi is via a SSH key, but I have not done this yet. I will update this post in the future when I have set this login type myself.

I highly recommend you store your username and password in a password management system (to help encourage you to generate strong passwords and not re-use passwords over and over again). I recommend you use LastPass (affiliate link), but there are numerous other ones that are good too.

As stated on the Raspberry Pi’s documentation page, here is how you change your password.

  • Login to your Raspberry Pi via SSH (Putty)
  • Type in passwd and press Enter
  • Enter your existing password (raspberry) and press Enter
  • Enter your new password and press Enter
  • Enter your new password again and press Enter
  • You will see “passwd: password updated successfully”

Enable VNC for GUI-based access to your Raspberry Pi

The vast majority of my examples going forward can be accomplished using just the SSH connection and the Bash shell on the Raspberry Pi. However, you may also want a GUI to more easily perform administration of your Raspberry Pi (some things are just easier with a GUI).

By default, your Raspberry Pi will not have a way to remote login to a GUI (you would have to plug an external monitor into the HDMI port to see the GUI. Therefore, you must install a remote desktop client.

In my opinion, the VNC Viewer is the easiest and best way to remote desktop from your Windows PC to your Raspberry Pi. VNC is free for home (non-commercial use) for up to 5 remote computers and 3 users.

You will need to do 2 installs, one of the VNC Viewer on your Windows PC and one on the Raspberry Pi of the VNC Server.

As stated on the Raspberry Pi documentation page, here are the instructions for how to install & set up.

Raspberry Pi

  • Login to your Raspberry Pi via SSH (Putty)
  • Type in sudo apt-get update and press Enter
    • sudo is the command in Linux to temporarily elevate your privileges so you can do privileged tasks like install new software
    • apt-get is the command in Linux (the Ubuntu/Debian distribution, specifically) to install a package via the built-in package system. APT makes is extremely simple to install, update & uninstall software from your Linux OS.
    • update is to ensure you have the latest of all installed packages before you continue (having outdated packages is often the cause of failed installations and running of software)
  • Type in sudo apt-get install realvnc-vnc-server realvnc-vnc-viewerand press Enter
    • This will install both the VNC server & viewer
  • Type in sudo raspi-config and press Enter
    • This will open the configuration options for your Raspberry Pi
  • Press the Down arrow key until you get to Interfacing Options and press Enter
  • Press the Down arrow key until you get to VNC and press Enter
  • Use the Left or Right arrow key and select Yes and press Enter
  • Press the Enter key to confirm that VNC Server is enabled

Windows

  • Download the VNC Viewer for Windows and install it
  • Run VNC Viewer from the Start Menu
  • Type in the IP address of your Raspberry Pi and press Enter
  • The first time you login, you will be asked for the username (pi) and the password you set when you changed it
  • If successful, you will see the Linux GUI that is installed on your Raspberry Pi

Change basic security settings on your Raspberry Pi

At this point, you have a basic Raspberry Pi server set up. You must now decide how much effort you want to put into securing your system. The Raspberry Pi documentation does a great job giving you several options for how to secure your Raspberry Pi. At this time, I won’t recommend you do any specific settings (since they will be a whole other article), but feel free to add them as you see fit at this time.

As long as you keep your Raspberry Pi inside your local network and do not expose it to the Internet directly, you are relatively protected by your router & its firewall. However, you must set up more protection if you expose your Raspberry Pi to the Internet.

Congratulations! You now have a working home automation hub setup and ready for some automations!

How to set up your Raspberry Pi as a home automation server

Now that you have agreed with my previous article, you have selected Home Assistant as your home automation hub! Congratulations!

A key idea you have to understand is that you will be running your hub software on a server. Don’t let the name scare you, it is just a computer that will be running all the time. It has to be running all the time to ensure it can communicate with your smart home devices and can run your home automations.

You now have to make a major choice. Do you want to run Home Assistant as a Docker container inside a specially created environment (Hass.io) or on a traditional Linux installation (Hassbian)? This is the crucial choice because the versions of Home Assistant installed in Hass.IO & Hassbian are different.

Even though there are instructions to do so, you do not want to try to run Home Assistant on Windows. There will be too many incompatibilities and the vast majority of the documentation will assume you are running in a Linux environment. Even if you are not very familiar with Linux, the basic commands are relatively simple to understand. In addition, if you are running Home Assistant as Hass.io (which you should be), you will not be on the Linux command line very often anyway.

I made the mistake when I first began with Home Assistant to run the Hassbian option. This is because I was under the mistaken assumption that I wanted to manage the underlying Linux infrastructure myself (I had already set up Pi-hole and I didn’t understand that I could run it as a plugin in Hass.io).

However, it became clear after a few weeks of running Home Assistant under Hassbian that it was sub-optimal. I had to manually update Home Assistant on the Linux command line. I had to enable the virtual environment to configure it. I could not take advantage of the many excellent plugins that have been developed for Hass.io that make configuration much easier.

Therefore, I only recommend you go the Hass.io route.

Hass.io

Hass.io is the preferred and easiest way to install and run Home Assistant. This takes advantage of Docker to run both Home Assitant and all the additional plugins you will want to run to have the most functional & flexible environment possible.

Docker is a technology called “containerization”. As the name implies, a Docker container contains all of the code & dependencies that a piece of software needs to run. The big advantage of Docker over just installing software on your computer is the “dependencies” part. In the past, ensuring you had the right versions of either .so files or .dll files was terrible (DLL Hell). Docker ensures that all of the code you need is available and isolated from all other processes running on your computer. This ensures reliable installation, updates & running of your application.

Hass.io has been specially designed to run Home Assistant and many plugins using Docker.

Hardware & Software needed to set up your Raspberry Pi

As I suspect many of you do, I run Windows 10 on my primary computer at home. Naturally, this is because it has the best games! However, my primary PC is not used to host my Home Assistant software. It is also not turned on except when I am playing a game, writing blog posts or my wife is using it edit maternity & newborn photos.

Therefore, you will need some crucial hardware & software to bridge the gap between your Windows PC & your Linux machine. Obviously, you may not need all the hardware or software I needed; mix & match as needed (affiliate links below).

Hardware

  • Raspberry Pi – Hosts your Home Assistant installation. I recommend you buy the latest model with the most CPU you can get. Home Assistant is a Python based system and needs plenty of CPU power to run the interpreter. The best version you can buy as of the time of this writing is the Raspberry Pi 3 Model B+. This technically has more feature than you need (built-in Bluetooth, HDMI port, camera port, 40-pin GPIO headers, etc). These features, while very cool and useful for other projects, will not help you with this home automation setup since you will be running the Raspberry Pi as a server and remoting into it from your PC.
  • Samsung Evo Plus 32GB MicroSD card – Stores the OS and configuration files for your Raspberry Pi. Your Raspberry Pi package is very likely to contain a MicroSD card already (so you can easily get started). However, I recommend you buy a higher-quality SD card. Flash memory is “volatile”, no pun intended, and these cards are being written to constantly. Eventually, I will migrate to a different storage medium, but for now, a better MicroSD card will do.
  • MicroSD card reader – Copies the Hass.io image from your Windows PC (where you will download it to initially) to your MicroSD card. Note that the reader I have linked to is a USB 3 model. This makes it more futureproof, but it will require more hardware to work on most Windows PCs.
  • USB Type C female to USB 3 male adapter – Converts from USB 3 on the MicroSD card reader to my traditional Windows PC with its USB Type C ports. This would not be needed if you select a MicroSD card reader that can already be plugged into your computer (either because you have a USB 3 port or because you pick a different reader). It was needed in my case (and surprisingly hard to Google for).
  • Short Ethernet patch cable – Connects your Raspberry Pi to your home network. I recommend you plug it in directly to the router instead of taking advantage of the WiFi network. This will make your network connection to the Raspberry Pi faster and more reliable (in addition, if you are running Pi-hole, you want a fast network connection to the DNS server running on the Raspberry Pi).

Software

  • balenaEtcher – Will “flash” the image of Hass.io you will copy down from the Internet from your Windows PC to your MicroSD card.
  • VNC Viewer – Log into the Raspberry Pi’s GUI from your Windows PC.
  • Putty – Log into the Raspberry Pi in a “headless” (no GUI mode). This is much faster than using the Raspberry Pi’s GUI, but you may be more comfortable using the Terminal window on the Raspberry Pi.

Flashing & plugging in your Raspberry Pi

Now that you have purchased the hardware & downloaded all of the needed software, you can get started.

  • Remove your Raspberry Pi from the box. If you purchased the Canakit version, it will also come with a great case to protect the delicate electrical components.
  • Remove the MicroSD card (or open the new MicroSD card you bought) and plug it into the MicroSD card reader that is plugged into your Windows PC. If prompted, select Open Files for what to do with media like this.
  • Open balenaEtcher to flash the MicroSD card with the image you have downloaded from the Hass.io website.
  • Click on “Select image” and navigate to where you downloaded the Hass.io image (most likely, the C:\Users\<your ID>\Downloads directory) and select the image (most likely, hassos_rpi3-2.10.img.gz). Click Open.
  • Most likely, Etcher will automatically figure out that it should select your USB 3.0 device to write to. If not, select “Change” and select your MicroSD writer.
  • Click “Flash!” to copy the image from your Windows PC to the MicroSD card. Note that this will overwrite anything already on the MicroSD card. If you recycled an existing MicroSD card you already had, you will lose anything that was on it. The image you downloaded is a complete OS and filesystem.
  • On the Windows taskbar, on the right-hand side of the screen, click on the Up arrow on the System Tray (where the clock is). You want to left-click on the USB device and select “Safely remove hardware and eject media” to ensure Windows finishes writing anything to the memory and cleanly removes it. Click “Eject”. I have had a few memory cards fail over the years due to Windows not being done with them before I yanked the card out, so I always eject.
  • Carefully install the MicroSD card back into your Raspberry Pi. You do not have to push hard to do this.
  • Install the Raspberry Pi carefully in its case. You must be careful with the exposed MicroSD to not damage it (slip the MicroSD card into the slot provided in the case. Now you can install the rest of the case.
  • Finally, plug your Raspberry Pi into power and your router via the Ethernet patch cable.

The next post will explain how to connect & configure Hass.io on your Raspberry Pi.