How to add a GE Z-Wave Smart Switch (1 gang) to your Home Assistant system

In this post, I will show you how to install a single GE Z-Wave Smart Switch (1 gang) to your Home Assistant system.

I am not a licensed electrician, so take my advice only as an amateur DIYer. If you are uncomfortable re-wiring a switch in your home, call an electrician to install the switch for you!

There are 2 ways to automate & control the lights in your house. You can either control the lights via the switches or via the bulbs themselves. Controlling the bulbs means buying very expensive replacements like the Phillips Hue. These give you the ability to have hundreds or more colors and lots of different options. However, you must leave the switches for these bulbs on all the time.

However, I prefer to just replace the switches in my house and keep my existing dumb CFL or LED light bulbs. For me, it is very important that lights keep working as normal, even if Home Assistant (or some other automation system) is unavailable. If either Home Assistant or some cloud service is down, I still want my switches to work as they always did. If I have someone over, I don’t want them to have to figure out my smart home system; they should just be able to turn the lights on and off as they always have. In addition, I haven’t seen much use in having the ability to change the colors of my bulbs. This may change in the future, but for now, that’s what I have decided to do.

Here are the tools and devices you will need to do this installation (affiliate links below).

There are 2 primary steps in this installation.

  • Replace the old electric switch with the new smart switch
  • Register your new smart switch with Home Assistant

Replace the old electric switch with the new smart switch

I am not a licensed electrician, so take my advice only as an amateur DIYer. If you are uncomfortable re-wiring a switch in your home, call an electrician to install the switch for you!

I cannot stress this enough. You can absolutely electrocute yourself or start a fire if you don’t do the electrical job correctly.

For simple jobs, I feel confident in my electrical ability to replace outlets, switches, etc. I have absolutely called in a professional electrician for complex jobs (like when I had a short in my bathroom GFCI outlets and they kept tripping). There is no shame in admitting when you need a professional to do a job!

If you are willing to keep going, then you need to turn the power off to the circuit that powers the switch you want to replace. Obviously, you could turn the power off to the whole house, but that would be silly! 🙂

This usually involves turning on the switch you want to replace (so the light is on), then start toggling the breakers one by one until the light turns off. To make this easier, I have found a very useful tool to determine which breaker controls which circuit in my house. I recommend you purchase a Klein Tools Digital Circuit Breaker Finder. You plug this device into an outlet that is on the circuit you want to find, then you use the included tester on each breaker until you find the one that matches. How it works is that it sends out an electrical signal over your internal power wires and it is received by the tester in your breaker box.

This is not a foolproof way of testing electric switches because it is possible your outlets in a given room are not on the same circuit as the lights, but it is a good possibility. As always, your mileage may vary and you should still test the light switch yourself to ensure it does not work anymore after you disable the breaker.

Now that you have disabled the circuit that powers the switch you want to replace, you can remove the old switch. Remove the 2 screws that hold the decorative faceplate on and then the 2 screws that attach the switch to the electrical box. Pull the electric switch out and look at the wires.

At a minimum, you will see 2 wires (usually black, but this is not guaranteed). These are known as the “line” and “load”. The “line” is the wire from your electrical breaker box and supplies the power. The “load” is to the device you want to power (lights, fans, etc). This is important because the smart switches must be installed with the correct wire inserted into the correct receptacle on the smart switch or it will not work.

This next step is where your mileage will vary considerably depending on the age of your home and the quality of the wiring job the contractor did when they built and wired your home. To install the GE Z-Wave Smart Switch (and most other smart switches), you must have 2 other wires. You must have a “neutral” (usually white, but not guaranteed) and a “ground” (usually copper and uninsulated, no plastic insulation around the wire). The colors of the wires are absolutely not guaranteed. Color coding has not always been the standard and there is no guarantee the contractor used the correct colors even if it was code (you must test the wire to be sure which is which). The typical skinny toggle switches many homes have don’t usually require a ground or a neutral to function, so many homes won’t have it. However, in order for the Z-Wave antenna to function, it must be powered at all times. This is the function of the “neutral” wire. It completes the circuit from the “line” so that the Z-Wave antenna is always broadcasting and receiving.

If your electrical box doesn’t contain a neutral wire, you cannot install this smart switch. There are certain kinds of switches that don’t require a neutral, but I have never tested them, so I can’t make recommendations at this time (however, my attic switch doesn’t have a neutral, even though the rest of my house’s switches do, so I will eventually find out).

Take a picture with your phone right now so you know how it was originally installed (both to make it easier to identify the various wires and so that you can restore it the original condition if you need to give up for whatever reason).

Remove each wire from the old light switch and separate them carefully so none of them are touching each other or anything else.

You need to identify which wire is the “line” and the “load”. This can be done using a Klein Tools Electric Voltage Tester. This will let you know which of the wires is “hot”. The “hot” wire is the “line” because it comes directly from the breaker box and always has electricity flowing through it.

Go back to the breaker box and turn the power back on. Now go back to the exposed wires and begin “testing” each one with the leads from the voltage tester. Put one of the leads on the “ground” (exposed copper) wire and begin testing each of the other wires (probably black) to determine which one is “hot”. The tool will flash 120 and buzz when it detects electricity in the line. This will be the “line”.

Turn the breaker for this circuit back off so you don’t electrocute yourself before continuing!

Take the “line” wire (probably black) and plug it into the “line” receptacle on the smart switch (probably in the bottom left-hand side when looking at the back of the switch). Tighten the screw on the side tightly to ensure the wire can’t fall out (tug on it lightly to ensure it is firmly held in place).

Take the other wire that was originally plugged into the switch, the “load” (probably black), and plug it into the “load” receptacle on the smart switch (probably in the upper left-hand side when looking at the back of the switch). Tighten the screw.

Now insert the “neutral” wire (probably white) into the “neutral” receptacle and tighten the wire. In my case, there was a pigtail with the neutral wires, so I removed it and plugged both of the neutral wires into the switch to complete the circuit.

Now you need to plug the “ground” into the switch. The ground wire protects you from electrical shorts by providing a path of least resistance to the “ground”. In my case, my ground wire was twisted together, so I needed to add a “jumper” wire (14 gauge) to make it easier to ground the switch (otherwise, the wire would have been very short and it would be too easy to pull out).

Now you can test the switch to see if you did the wiring correctly. Go turn the breaker back on. Begin toggling the switch. If you have wired everything correctly, toggling the switch up will turn on your lights. Toggling the switch down will turn the lights off. You will also see a small blue LED light when the switch is off. If you don’t see the blue light and the switch doesn’t turn on the lights, go back and carefully check which wires are plugged into which ports on the switch. If you hear crackling or popping, turn the breaker off and tighten all of your wire connections.

Now carefully push the switch back into the electrical box and replace the screws that hold it to the box. Then, put the new decorative faceplate on and tighten down the screws.

Congratulations, you have now installed the switch and can use it as a normal light switch.

Add the Z-Wave switch to Home Assistant

Link to Home Assistant documentation.

  • Navigate to your Home Assistant GUI in the browser
  • Click on Configuration
  • Click on Z-Wave
  • Click on Add node
  • On the Z-Wave smart switch, press up or down to put it in “pairing” mode
  • Click the Heal Network button. This will cause all of the Z-Wave switches to “report in” with the controller and it will optimize the routing of Z-Wave signals through your Z-Wave network.
  • Your Z-Wave switch is now added to Home Assistant

The next step is highly dependent on your individual configuration. If you are just starting out, you should see the switch added to the home page. If you have started enabling groups, you may not see new entities that have never been added before.

  • Click on the Unused entities button in the upper-right hand corner of the home screen (in the hamburger menu)
  • Toggle the switch to see if everything is set up correctly
  • Click on the name of the switch to rename it
  • Click on the gear
  • Click on the name override and give it a descriptive name
  • Click on the entity ID and give the name you will use to refer to it in the YAML files
  • Click Save, then click on the back arrow, then X

Now you need to add it to a group so it will show up in Home Assistant (this step may not be required for your setup)

  • Connect to your Raspberry Pi using Putty
  • Open the configuration.yaml file
  • Check to see if you have groups enabled

When you start using groups, you need to add every device to a group for it to show up on the home screen.

  • Open the groups.yaml file
  • Create a new group kitchen_hidden and list your outlet using the name you defined above. This is needed because the Home Assistant GUI will not show nested groups together in the same page if they are both shown. Note the control flag is set to hidden to hide the group from the GUI
  • Create a new group kitchen that you will use to create a new page in the Home Assistant GUI. Note the view flag is set to yes to show the group in the GUI
  • Optional, add your master_bedroom_hidden group to a “downstairs” group
    (mine will have more entries than yours, customize as needed)
downstairs:
  name: Downstairs
  entities:
    - group.lamps_hidden
    - group.kitchen_hidden
    - group.master_bedroom_hidden
    - switch.front_door_outdoor_lights
    - switch.front_door_entryway_lights
  view: yes

kitchen_hidden:
  name: Kitchen
  entities:
    - switch.kitchen_table_light
  control: hidden

kitchen:
  name: Kitchen
  entities:
    - group.kitchen_hidden
  view: yes
  • Save and close the file
  • Go to the Configurations tab in Home Assistant and click General
  • Click Check Config to ensure you didn’t make a mistake in the yaml files
  • Click Restart to update the running Home Assistant with your new groups
  • Refresh and go to the home screen
  • You will see your new tab at the top with the switch inside it
  • You will also see the new group added to the Downstairs tab as well.

That’s it! You have now successfully added a Z-Wave switch to Home Assistant.

How to set up a Z-Wave network for your home automation

If you have been following along, you now have a Hass.io installation setup up and ready to begin creating automations.

As I said in my article about deciding on your home automation setup, you now need to set up the Z-Wave antenna so your various home automation equipment can talk to your Raspberry Pi and the Home Assistant software.

I recommend the Aeotec Z-Stick Gen5, Z-Wave Plus USB (affiliate link), but you theoretically can get any Z-Wave antenna and it will work.

  • Plug this USB device into your Raspberry Pi (and restart just to be safe).
  • Login to the Hass.io configuration using Putty
  • You need to figure out what the USB drive is called on your installation. Run the following command.
ls /dev/ttyACM*
/dev/ttyACM0     <-- this is the most common name, but yours may differ
  • You need to tell Home Assistant that it should expect to see Z-Wave communication on this device.
  • Open the configuration.yaml file using vim
vim configuration.yaml
  • Scroll down to the bottom of the file and enter the following command. Save and close vim (:wq)
zwave: !include zwave.yaml

This command will tell Home Assistant to look enable the Z-Wave component and to look for its configuration in a separate file in the same directory as configuration.yaml called zwave.yaml.

  • Create a new file using vim and enter the name of the Z-Wave USB stick you found before. Save and close vim.
vim zwave.yaml

usb_path: /dev/ttyACM0

Now, you will begin to “test” your configuration before actually running it. It is very easy to mess up the format of the .yaml files and cause Home Assistant to not start.

Luckily, Home Assistant has an easy way to check to see if configuration files are valid.

hass --script check_config -c /config

This tells Home Assistant to scan all of the .yaml files and see if there are any configuration issues that would cause it to not be able to restart and load. In typical Linux philosophy, if it reports no status, everything is good. This is because Linux “pipes” the output from one command to another and “chatty” output messages make it harder to pipe commands together.

You can also do this in the Home Assistant web portal.

  • Navigate to the web portal
  • Click on Configuration
  • Click on General
  • Click on Check Config
  • You will get

If everything is good, you will see a green “Configuration valid” message.

You can either reboot the Docker container or use the GUI. Note, as you add more and more automations, this will slow down (several minutes to reboot). This is why the GUI has options for just reloading pieces of the system.

exit            

whoami <-- make sure you are the "pi" user outside the Docker container
pi

sudo docker restart homeassistant
homeassistant

After Docker reports success (by printing out homeassistant), you will have to wait a few minutes for Home Assistant to finish loading.

  • You need to push you new changes to Github so they are saved. Log back into the Docker container and check the status of the files
sudo docker exec -it homeassistant /bin/bash
  • Check the status of your modified configuration files.
git status
On branch master
Your branch is up to date with 'origin/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:   zwave.yaml

no changes added to commit (use "git add" and/or "git commit -a")
  • Add these files (stage them) to your git changset so you can commit them.
git add *

git status
On branch master
Your branch is up to date with 'origin/master'.

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   configuration.yaml
        modified:   zwave.yaml
  • Commit the changes
git commit -m "Added zwave"
  • Push your changes to Github
git push

You are now finally ready to begin adding devices to your home automation!

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!