This is my experience of setting up Home Assistant on a Raspberry Pi3 using a Macbook Pro laptop. I’m really documenting this for my own reference but I hope it MAY help other people who have the same setup as me and are as clueless as I once was about how to get started. I am the FURTHEST thing from an expert on any of this, so I’ll probably annoy some HA geniuses with my lack of knowledge. But I am a pretty technical guy in normal life and I can only guess at how many hundreds of people have probably given up in frustration at how technical and finicky setting up HA can be.
Getting Started
First thing I learned, you don’t need an install of Linux on the Raspberry Pi to run Home Assistant. I’ve done this, installing and setting it up, only to discover that you just need to use BalenaEtcher to burn the image of the latest Home Assistant disc image onto a microSD card to get started. The image includes the operating system. Good to know.
I didn’t have a microSD card reader so I bought a $6 USB stick reader on Amazon that works great.
There is apparently a process of setting up the Pi to connect on wifi by installing a file in a user-created folder called CONFIG. One way uses a blank USB stick and another involves creating a folder on the microSD card. I have done both and have no idea if either worked. I just run my Pi connected to the network via Ethernet and don’t know what the benefits of being on wifi would be. Maybe some day.
Once you’ve “etched” the HA image on your card with BalenaEtcher (it’s very easy), you insert the microSD card in the Pi and turn it on. Wait about 20 minutes for it to get online and update to the latest software and then go to the address of your Pi in a web browser:
192.168.1.160:8123
(This IP address is not defined and will be whatever your router assigns when HA and the Pi boot up and go online. There are probably other ways to find this but I just log into my router’s IP address and search for hass (for hassio) and find the IP address that was assigned. Then I make that a permanent assignment in the router, changing it to something easy and memorable.)
OR go to
hassio.local:8123
OR if it is a new enough install (which it should be if you’re reading this, but mine strangely isn’t)
homeassistant.local:8123
The 8123 is the port Home Assistant assigns, so unless you know a way to change it, get used to remembering it.
Account Creation
Okay, so after the 20 or so minutes go by, you’ll go to that address and there’s an account creation page. As far as I can tell, this is all local on the Pi, meaning you could set this up without going online. To keep things simple, I just use my first name for the Name and Username. In the past I’ve used my full name and a different “account” name that I use on websites but that got confusing when I had to enter login info in HA and I wasn’t sure what it was asking for. I also stopped using first and last names because in the HA interface, there are moments when it displays a user, and who cares to see my last name - I know it’s me. It also saves you the time it takes to alter your name when you get tired of seeing your last name in HA. For the password, I also try to use the same one across all HA related apps and services so I don’t have to think in those moments when it asks for a password.
Location
Allow it to detect your location then adjust the map and click on where you’re at. Then I search online for “what is my elevation” and a website will tell you. Type that into the field.
Add Devices and Services
Anything that HA detects will show up here. It can be exciting to see that it’s already working but a lot of your stuff won’t show up here because you haven’t set it up to be seen yet. It can also be interesting to see stuff you didn’t know you had. For example, my Sony TV offers up a Google Cast. I usually just skip this part and add these things later as I set up. You can find them later under Configuration > Integrations.
Setting Up Alternate Access Points
You can do everything you need in this web interface but there will be times when something gets messed up and HA will not load something right - either a menu you need, a service, or the entire webpage. If that happens, you’re screwed. I’ve gone down the path a few times of doing something that broke HA and ended up starting from scratch just because it was easier than finding what broke. HA is not for the faint of heart. It’s really designed by and for people who are comfortable with programming languages.
The FIRST thing you want to do is build an escape route for when things get messed up. You want to be able to access the text files that run HA so you can edit them whether the web interface is working or not. Two ways to do this are Samba and SSH.
Samba
Samba is a way to mount your Pi on your computer so it shows up like any other drive or folder. You can see icons, make folders, move things around, drag and drop files into the folders, etc. It makes all the command line interfacing seem more bearable.
Install the ‘Samba share’ add-on by going to the Supervisor menu then find ‘Samba share’ under the ‘Add-On Store’ menu at the top. It’s in the ‘Official add-ons’ section.
Click on it and hit install. Once it’s active, you can scroll down and find the Config section.
Under username: homeassistant change homeassistant to whatever username you created when you set up HA the first time - this is one of the reasons why I suggested keeping that username simple when you set up HA. I just use my first name.
And update password: YOUR_PASSWORD to the password you created when you set up HA.
Under allowed hosts, I don’t know if you need to change that. Just to be safe, I changed the third one (192.168.0.0/16) to match my laptop’s permanent address on my router. I don’t know what the /16 means at the end so I left it and I don’t know if changing anything here made a difference.
Samba is the easy one. To test it, go to the finder on the Mac and type command-K. This brings up a window where you can type an address. Type in smb://192.168.1.160 for the IP address of your Pi. You don’t need to add the :8123 on the end. If it works, a window will appear asking which folder you want to access. I go for the ‘config’ folder, since that’s where most of the files live, but once you’re in there, you can navigate to any of the folders. And then if it REALLY works, a finder window will appear with config mounted as a drive you can access. This is a great feeling, especially if it works the first time.
I’m not going to go through troubleshooting for when it DOESN’T work. That’s not the point of this document. I just want to walk through the steps of what SHOULD and has worked for me.
Terminal and SSH
This one lets you access your HA files through the Terminal interface, which is a Unix shell (SSH stands for Secure SHell - I know because I just looked it up). If you’ve never done this before, it feels like you’re doing some War Games-level hacking, but it’s really not that scary. Unfortunately, in some instances you don’t have any other options, so get used to it. Find the ‘Terminal and SSH’ add-on and click the Install button.
Here’s where it gets tricky.
You will need an authorized key. WTF is that? It is a long string of numbers and letters that is specific to you and your computer. It is stored locally on your computer (in my case on my Macbook) and HA checks its key against the one on your computer and when they match, you can access HA through a secure shell.
Where do I get an authorized key? You make it with your computer (again, in my case on my Macbook). By the way, I’ll explain because I didn’t know: the authorized key is made independently from HA. You’re just going to tell HA what the key is and if it matches what it has on file, it will work.
Now is when you will feel like a computer programmer LOL…
Open a Terminal shell - it’s an app on your Mac. I just type command-Spacebar to bring up the spotlight search function and type term until it finds Terminal, and then I hit return. That will open a fresh terminal shell. You can also go into the Applications > Utilities folder and find Terminal and open it there.
If you don’t know if you have any authorization keys already, you can type this at the shell prompt:
ls -al ~/.ssh
It’s saying list all (ls -al) the files in the .ssh (.ssh) folder in my home folder (~/).
Most likely, you’ve never done this before so there’s not much to see and nothing to worry about breaking.
To generate your key, type this (replace USERNAME with your username keeping the quotes - again that one you used when setting up HA) and hit enter:
ssh-keygen -t rsa -b 4096 -C "USERNAME"
It will ask where to save the key, so just hit return. It will ask for a password, but don’t enter anything, just hit return when it asks. If the files don’t already exist, it should make/populate two files called id_rsa and id_rsa.pub
Go ahead and check out what’s in those files now. The easy way to do it is to navigate to the folder where they live. Type this:
cd ~/.ssh
Then open the file with a shell text editor:
nano id_rsa.pub
You’ll see the string of text that makes the key. Nano is a horrendous way to access files, but if you use the arrow keys, you can navigate to the end of the long string and you should see your username. Not important, but nice to see that things are working. To get out of Nano, type control-x. If it prompts you to save any changes, type no.
I don’t remember the order between this step and the next one, but let’s say this one is first. If a file called config does not exist in this .ssh folder, you need to create one. One way to do it, is to type:
nano
That will open up the nano text editor and it should be blank.
Type (or paste) this into the file:
Host *
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_rsa
To save it, hold control-x. It will ask if you want to Save modified buffer? Enter:
y
Then type config (the name of the file you want to make) and hit enter.
Add the authorization key to your keychain access (on your Mac) by doing this:
eval "$(ssh-agent -s)"
That loads it up, I guess.
Then do this:
ssh-add -K ~/.ssh/id_rsa
It’s basically saying to add the file to your Mac’s keychain. Why, I don’t know, but mine is working. This and the previous step with the config file seem to be similar and I don’t know if you have to do both, but it didn’t hurt to do so.
Finally - and this is a trick that took me a while to discover but is SO critical to saving your sanity - you will COPY the key so you can plug it in to HA. Type this:
pbcopy < ~/.ssh/id_rsa.pub
This copies the generated key to the clipboard so you can go back to the ‘Terminal and SSH’ add-on in HA and find the Config section. After authorized_keys: click between the [] brackets and paste your key. Then click the SAVE. It will save and reload the page, and reformat the text. Don’t bother adjusting the text to look like when you pasted it because it will just reformat it again on save if you try. Just trust it. It should look something like this (don’t copy this because it won’t work):
authorized_keys:
- >-
ssh-rsa
AAAAB3Nza…..(this goes on forever)
USERNAME (this will be your username from the end of the string)
password: ''
And under the Network section on the same ‘Terminal and SSH’ add-on page, I type 22 in the host section. Again, I don’t know if this is right or wrong, but mine is working, so I just go with it.
If you haven’t done it already, scroll to the top of this page and click START.
By the way, I turn on all the options for plugins - Start on boot, Auto update, and Show in sidebar. Why not, right?
Just to be sure, I reboot the Pi. Go to Configuration > Server Controls > Server Management - RESTART.
When it’s all up, you should see a menu called Terminal on the left side of the HA window. If you click in there it will open up a ‘terminal’ in the browser, which is very retro and convenient. To see what’s there, type to list the files:
ls
If it’s working, you should see around five folders listed. You can go into the config folder by typing
cd config
Again, once you’re in there, you can list the files by typing:
ls
This is all fine, but it’s through the HA web interface and if that goes down, you want to be sure that you can access the files from the Terminal app. So, in the terminal app on the Mac (not in the HA Terminal window), type:
ssh [email protected]
If it works, you have done something that took me forever to figure out. You will see a real terminal that has Home Assistant spelled out in ACSCII art, just like you saw in the HA web interface. You can do all the same things to see the files that I just mentioned above.
Troubleshooting
I said I wouldn’t troubleshoot, but getting this to work almost made me give up. So these are the things I did when it wouldn’t work (over and over and over). I spent so much time trying to find what was not working with SSH and the authorization key, I finally found that the most effective approach was to start from scratch. In the Terminal shell I deleted these files d_rsa, id_rsa.pub, id_rsa.sav by typing the delete command, once for each one (careful this rm can be a powerful and destructive command):
rm id_rsa
rm id_rsa.pub
rm id_rsa.sav
And then I made sure that the file known_hosts was empty. To open it:
nano known_hosts
Once it opens, just delete all the info inside and save it.
Finally, I opened up the keychain access app and searched for and deleted any Home Assistant keychain items. You would think this might not be necessary, but as soon as I got rid of them, it worked for me. They get repopulated anyways once you log in and get going.
My next frontier is DuckDNS. I’ve tried and failed plenty with that, but if and when I get that sorted, I’ll add what I know here.
This is really the setup of it all and has nothing to do with the actual running of Home Assistant. I have plenty to learn there before I could feel comfortable sharing what I’ve learned.
