Home Assistant Zigbee Integration with Matrix Creator

WARNING: Due to issues with the “not officially supported” supervised guide to installing Home Assistant, you will likely encounter an issue accessing the Matrix audio device in and outside of Home Assistant. This is a known issue, but there is no solid idea when this will be fixed. Disabling hassio_audio through Portainer might fix it as well. https://github.com/home-assistant/plugin-audio/issues/12 One user lists this potential solution which I can’t confirm

NOTE: I did not come up with this guide on my own, it is a compilation of information, mainly sourced from this community guide: https://community.home-assistant.io/t/installing-home-assistant-supervised-on-raspberry-pi-os/201836)

Installing Home Assistant on a Raspberry Pi 4B with Zigbee integration

Section 0 – Getting ready

1) This guide assumes that you have a Raspberry Pi 4B and a Matrix Creator.
It may work with other hardware, but not guaranteed. You also need to have access to a router via Ethernet cord unless you follow additional steps not outlined in this guide to enable WiFi. Make sure the Matrix Creator is fully seated over the GPIO pins before continuing.
2) You will need a MicroSD (HC works too) card flashed with the Raspbian OS
and one that is rated as Class 10, A1 or A2. If you haven’t yet purchased an SD, or would like some excellent information on SD cards, this YouTube video is worth watching. Explaining Computers - SD Card Benchmarks … If you already have this, you can skip the rest of this section and section 1.
3) You will need a MicroSD to USB adapter.
I’m using a combination of the SanDisk adapter that came with my preflashed SD card and a USB3.0 adapter you can also get on Amazon.
4) A host OS to flash your disk from. I’m on Windows and I’m using a free flashing software called Rufus.
5) At least 1 ZigBee compatible device.
I’m using a RGBWW lightstrip that is prebuilt from Amazon

Section 1 – Install Raspberry Pi OS

1) Start by downloading Raspberry Pi OS (32-bit) Lite from Their official website Note (64-bit may sound appealing, but does not have good package support and is unlikely that it will work)

Insert the SD card into your computer via a USB to SD card adapter.

2) Once the Raspberry Pi OS download has finished, you will write the image to an SD card using software called Rufus. It is free and easy to use. It will take care of the formatting and writing of the downloaded OS image you downloaded.

Select your drive first. It should be listing the SD card you plugged into your computer. If you are on windows and aren’t finding the drive, you can follow this guide to set a drive letter manually.

Click Select and navigate to the location you saved the Raspberry Pi OS image (named something like 2020-05-27-raspios-buster-lite-armhf.zip ), Make sure the file system is set to FAT32 and click Start. Mine was pretty quick to flash, but it did hang at 100%, so don’t be alarmed if it takes a while.

3) When everything was finished, windows should remount the drive. But if it doesn’t, just make sure Rufus is reporting the process is complete, unplug the USB drive and reinsert it. You should see Windows recognize the drive, allowing you to inspect the contents.

4) Next you will now create an SSH file so that when you first boot the Pi, you can connect to it from your PC via SSH.
I’m not going to go over the various SSH clients, but if you are on Windows 10, you can follow a guide like this to install the optional Windows package. I’m personally using Visual Studio Code’s integrated terminal and SSH to edit files on my remote host (The Raspberry Pi). You can also use PuTTY, available HERE . Putty is a free and open-source terminal emulator, serial console and network file transfer application.

To create the SSH file, press the Windows Key on your keyboard plus the R key (Windows Key + R) . In the box that comes up type in cmd and press Enter.

You should now have command prompt open and pointed to your user directory C:\Users\YourName . In this window, type in the drive letter of the SD card It should look like this D: then press enter. This will set your terminal to the root of the SD card in order to put a file on the drive using the following command.

type nul > ssh

This creates a blank file on the SD card that indicates to the Pi to enable SSH, which is disabled by default. At this point, you can eject the SD card and move on to configuring it over SSH.

Section 2 – Setting up the Pi

1) Insert the SD card into your Pi. If you’ve never done this before, there is no hard locking mechanism, but a slot at the bottom of your Pi. Be careful not to eject the card while in use.

Plug in the Ethernet cable and power on the Pi. My Pi kit came with a USB-C power connector. It is required that you use a 5.1V 3.0A Power supply in order to fully power the Matrix

2) You will now connect via SSH to run commands on the Pi from your PC. Check your router for the IP address of your Pi.

You can connect to the Pi using a command following the pattern

ssh pi@192.168.1.4

Where the number following @ is the IP address of your pi. You will be prompted to enter a password, which is raspberry by default. We will change this later.

3) Next you will run the Raspberry Pi Configuration utility.
Enter the following command in your terminal:

sudo raspi-config

3A) Firstly, select Option 1 and press to Enter to change the default password. Type a new password when prompted and press Enter. This new password will be what you use to log into the Pi in the future, so make a note of it.

3B) Next using your arrow keys, select Option 4 and press Enter and then select Change Timezone and press enter. Using the arrow keys, select your Geographical area, press Enter, and then select your City/Region from the provided list and press Enter.

3C) Next you will select Option 7 Advanced Options, and then select Option A1 – expand file system , and press Enter. Once this has been completed, you can use the arrow keys to navigate to Finish. When you are asked if you would like to reboot, select Yes. The Pi will now reboot. After a few minutes, your Raspberry pi will reboot. At this point, reconnect to it using SSH and the new password you set up.

4) Run any necessary updates:

sudo apt update && sudo apt dist-upgrade -y && sudo apt autoremove -y

Depending on your network connection, this could take anywhere from 1 to 20 minutes, so be patient. When it has completed, you can reboot the Pi using this command:

sudo reboot

Section 2 – Setting up ZigBee with Bellows (And the Matrix)

Note: Much of this section of the guide is based on this thread.
Also, I believe that if you have MALOS installed you will need to disable it first.

# Installation the Matrix Init Package
# Add repo and key
curl https://apt.matrix.one/doc/apt-key.gpg | sudo apt-key add -
echo "deb https://apt.matrix.one/raspbian $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/matrixlabs.list

# Update packages and install
sudo apt-get update
sudo apt-get upgrade
sudo apt install git matrixio-creator-init matrixio-kernel-modules libmatrixio-creator-hal libmatrixio-creator-hal-dev -y
sudo reboot

Disable em358-program.bash

comment out em358-program.bash to prevent a device factory reset on reboot or power cycle
(possible an unwanted behavior in matrix init)
sudo nano /usr/share/matrixlabs/matrixio-devices/matrix-init.bash
change

./em358-program.bash
to
# ./em358-program.bash

Section 3 – Install Home Assistant Supervised

Now that you have Raspberry Pi OS and Matrix configured installed, you can move on to installing Home Assistant Supervised. Connect to you Pi using Putty as you have previously using the IP of the Pi, the user name pi and the password you set.

1) Copy each line of the below commands one at a time and paste them into the SSH window, and press Enter. One of the following commands will execute a shell script as root, and some people may be concerned with the security risk. If you would like to read the script for piece of mind, click HERE

sudo -i

apt-get install -y software-properties-common apparmor-utils apt-transport-https avahi-daemon ca-certificates curl dbus jq network-manager socat

systemctl disable ModemManager

systemctl stop ModemManager

curl -fsSL get.docker.com | sh

curl -sL "https://raw.githubusercontent.com/Kanga-Who/home-assistant/master/supervised-installer.sh" | bash -s -- -m raspberrypi4
exit

Add yourself as a user able to access docker commands.

sudo usermod -aG docker $USER

2) This could take a few minutes to install. Now is a good time to make a cup of coffee or tea. You can check the progress of Home Assistant setup by connecting to the IP address of your machine in an internet browser on port 8123. (e.g. http://192.168.1.4:8123 )

Once you can see the login screen, the setup has been completed and you can set up an account name and password.

Add a new integration by clicking More.
Search for Zigbee Home Automation (At the bottom)
Select Manual
Radio Type: ESZP
Device Path: /dev/ttyS0
You should see a screen like this:

On the homepage, go to Configuration


Click add Devices

Plug in your ZigBee devices (You should see [0x0000:zdo] ZDO request ZDOCmd.Mgmt_Permit_Joining_req: [60, <Bool.false: 0>] at the bottom before.

Here is the screen I got once my device was connected:

You’re now set up to manage your newly connected ZigBee devices from Home Assistant.

Optional

Install Portainer

I find this tool to be extremely useful now that we have a handful of docker containers to manage. My instructions for this process came from here.

sudo docker run -d -p 8000:8000 -p 9000:9000 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer

Once it is done installing, you can connect to portainer at the port 9000 (eg: http://192.168.1.4:9000/)

Experimental Section

Disabling hassio_audio and forwarding pulseaudio

sudo apt-get install pulseaudio pulseaudio-module-zeroconf alsa-utils avahi-daemon pulseaudio-module-zeroconf pulseaudio-utils
#To enable ALSA:

sudo modprobe snd-bcm2835                      # load module for single boot
echo "snd-bcm2835" | sudo tee -a /etc/modules  # load module for persistance
#To set up networking:

sudo nano /etc/pulse/default.pa
and uncomment the lines:

load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1;192.168.0.0/16
load-module module-zeroconf-publish

# Give permissions to write to your directory
sudo chown -R $USER:$USER $HOME/

# To start the pulseaudio server, use:

pulseaudio -D
1 Like