Basic system
OS Installation
Download the official Raspbian image from here and write it to a SD card of at least 8GB, following the official instruction.
Enable ssh access putting a blank file named “ssh” without extension onto boot partition. See point 3 of this guide for more details.
Put the SD card into your Raspberry Pi 3 Model B, connect it to your network using the ethernet port and power it on.
Find the IP address of your Pi and connect to it via ssh. If you are on a linux machine and your system supports avahi / zeroconf, simply open a terminal (CTRL+ALT+t) and type:
user@host:~$ ssh pi@raspberrypi.local
The default password is “raspberry”, change it to “d-diot.com”:
pi@raspberrypi:~ $ passwd
Update the OS running this three commands. This may take a while
pi@raspberrypi:~ $ sudo apt update pi@raspberrypi:~ $ sudo apt dist-upgrade -y pi@raspberrypi:~ $ sudo apt autoremove
Add the user “pi” to the “dialout” group and verify the result.
pi@raspberrypi:~ $ sudo usermod -a -G dialout pi pi@raspberrypi:~ $ sudo groupmems -g dialout -l
Create the user “homeassitant” and add them to “dialout” group (no add it to “gpio” group)
pi@raspberrypi:~ $ sudo useradd -rm homeassistant -G dialout
In the d-diot image v.1.4 and above add the “homeassistant” user to the “gpio” group
pi@raspberrypi:~ $ sudo usermod -a -G gpio homeassistant pi@raspberrypi:~ $ sudo groupmems -g gpio -l
Create a directory for the installation of Home Assistant and change the owner to the homeassistant account
pi@raspberrypi:~ $ cd /srv pi@raspberrypi:~ $ sudo mkdir homeassistant pi@raspberrypi:~ $ sudo chown homeassistant:homeassistant homeassistant
Reboot your Pi
pi@raspberrypi:~ $ sudo reboot
d-diot images 1.0 and 1.1
Reconnect via ssh and install some required packages. This may take a while.
pi@raspberrypi:~ $ sudo apt install -y minicom arduino-core arduino-mk lirc liblircclient-dev python3 python3-venv python3-pip libffi-dev mosquitto mosquitto-clients samba git net-tools nmap python-pip python-dev ipython bluetooth libbluetooth-dev python-imaging python-smbus i2c-tools mariadb-server libmariadb-dev libmariadbclient-dev shellinabox nodejs npm libudev-dev python3-lxml python-lxml libxml2-dev libxslt-dev libopenzwave1.5-dev libopenzwave1.5
Please note that with the previous command you have installed also shellinabox, that is a small program that allows you to have a terminal in the web browser, so an ssh client is not more needed to access your Raspberry Pi.
Simply put the following url in a web browser https://YOUR_RASPI_IP:4200, or if your network supports avahi / zeroconf, https://d-diot.local:4200
As you can see it use an encrypted connection (https), but with a self-signed certificate, so your browser may report a security issue; simply accept the certificate and proceed. In the next steps we will integrate shellinabox in the Home Assistant home page with a Panel iFrame.
d-diot image 1.2 and above
With the kernel 4.19.X and Raspbian Buster the installation process of LIRC is a bit different, but thanks to the patch provided by the user neuralassembly (see this post) it is possible to use LIRC in the usual way.
In order to have the new dtoverlays gpio-ir and gpio-ir-tx working simoultaneously, two instances of LIRC will be created, as described here.
Reconnect via ssh and compile the patched version of LIRC from source.
pi@raspberrypi:~ $ sudo su -c "grep '^deb ' /etc/apt/sources.list | sed 's/^deb/deb-src/g' > /etc/apt/sources.list.d/deb-src.list" pi@raspberrypi:~ $ sudo apt update pi@raspberrypi:~ $ sudo apt install devscripts
Make sure that the version of LIRC present in the official repo is not installed and install some required packages
pi@raspberrypi:~ $ sudo apt remove lirc liblirc0 liblirc-client0 pi@raspberrypi:~ $ sudo apt install dh-exec doxygen expect libasound2-dev libftdi1-dev libsystemd-dev libudev-dev libusb-1.0-0-dev libusb-dev man2html-base portaudio19-dev socat xsltproc python3-yaml dh-python libx11-dev python3-dev python3-setuptools
Build and compile the patched version of LIRC
pi@raspberrypi:~ $ mkdir build pi@raspberrypi:~ $ cd build pi@raspberrypi:~/build $ apt source lirc pi@raspberrypi:~/build $ wget https://raw.githubusercontent.com/neuralassembly/raspi/master/lirc-gpio-ir-0.10.patch pi@raspberrypi:~/build $ patch -p0 -i lirc-gpio-ir-0.10.patch pi@raspberrypi:~/build $ cd lirc-0.10.1 pi@raspberrypi:~/build/lirc-0.10.1 $ debuild -uc -us -b
If the building process fail, install the missing dependencies indicated by the debuild command
pi@raspberrypi:~/build/lirc-0.10.1 $ sudo apt install dh-exec dh-python doxygen expect libasound2-dev libftdi1-dev libsystemd-dev libudev-dev libusb-1.0-0-dev libusb-dev libx11-dev man2html-base portaudio19-dev python3-dev python3-setuptools socat xsltproc
Install the patched version of LIRC
pi@raspberrypi:~/build/lirc-0.10.1 $ cd .. pi@raspberrypi:~/build $ sudo apt install ./liblirc0_0.10.1-5.2_armhf.deb ./liblircclient0_0.10.1-5.2_armhf.deb ./lirc_0.10.1-5.2_armhf.deb
The final install command will fail. The installation process will be repeated after the change of some configuration files and then it will success.
Edit the /boot/config.txt file:
pi@raspberrypi:~/build $ sudo nano /boot/config.txt
For the d-diot image 1.3 add the following lines at the end of the file:
- /boot/config.txt
dtoverlay=gpio-ir,gpio_pin=22 dtoverlay=gpio-ir-tx,gpio_pin=12
For the d-diot image 1.4 and above add the following lines at the end of the file:
- /boot/config.txt
dtoverlay=gpio-ir,gpio_pin=22 dtoverlay=gpio-ir-tx,gpio_pin=26
Exit (CTRL+x) and save the changes (y).
Rename the following configuration files to have a successful installation of LIRC:
pi@raspberrypi:~/build $ sudo cp /etc/lirc/lirc_options.conf.dist /etc/lirc/lirc_options.conf pi@raspberrypi:~/build $ sudo cp /etc/lirc/lircd.conf.dist /etc/lirc/lircd.conf
Remove devinput (not used)
pi@raspberrypi:~/build $ sudo mv /etc/lirc/lircd.conf.d/devinput.lircd.conf /etc/lirc/lircd.conf.d/devinput.lircd.conf.dist
Repeat the installation command:
pi@raspberrypi:~/build $ sudo apt install ./liblirc0_0.10.1-5.2_armhf.deb ./liblircclient0_0.10.1-5.2_armhf.deb ./lirc_0.10.1-5.2_armhf.deb
Now LIRC is installed, the configuration of the two instances of the daemon is described here.
Install some required packages. This may take a while.
pi@raspberrypi:~ $ sudo apt install -y minicom arduino-core arduino-mk python3 python3-venv python3-pip libffi-dev libssl-dev mosquitto mosquitto-clients samba git net-tools nmap python-pip python-dev ipython bluetooth libbluetooth-dev python-pil python-smbus i2c-tools mariadb-server libmariadb-dev libmariadbclient-dev shellinabox nodejs npm libudev-dev python3-lxml python-lxml libxml2-dev libxslt1-dev libopenzwave1.5-dev libopenzwave1.5
Please note that with the previous command you have installed also shellinabox, that is a small program that allows you to have a terminal in the web browser, so an ssh client is not more needed to access your Raspberry Pi.
Simply put the following url in a web browser https://YOUR_RASPI_IP:4200, or if your network supports avahi / zeroconf, https://d-diot.local:4200
As you can see it use an encrypted connection (https), but with a self-signed certificate, so your browser may report a security issue; simply accept the certificate and proceed. In the next steps we will integrate shellinabox in the Home Assistant home page with a Panel iFrame.
Install additional packages for stream component
To fix this potential issue with the stream component, which provides a way to proxy live camera streams through Home Assistant, install the following additional packages
pi@raspberrypi:~ $ sudo apt install -y python-dev pkg-config libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libavresample-dev libavfilter-dev
Localization and GPIO pin
Run the raspi-config tool
pi@raspberrypi:~ $ sudo raspi-config
select the options 4 “Localisation Options” and change the following parameters according to your needs:
- I1 Change Locale
- I2 Change Timezone
- I3 Change Keyboard Layout
In the d-diot images before v.1.4 the wifi country is not set, while in v.1.4 it is set to Italy. This apect will be covered more in depth later and this setting has to be changed by the final user during the first installation.
Select option 2 “Network Options” and change the hostname to “d-diot”:
- N1 Hostname
Select option 5 “Interfacing options” and then enable:
- P4 SPI
- P5 I2C
GPIO: d-diot images v.1.0 and v.1.1
Edit the config.txt file to set GPIO pin for MySensors radio modules (SPI), ATmega2560 serial communication (RFlink), Lirc (ir receiver and blaster), SHUTDOWN and POWEROFF functionalities.
pi@raspberrypi:~ $ sudo nano /boot/config.txt
Add the following lines at the end of the file:
- /boot/config.txt
### d.diot settings # Enable serial enable_uart=1 # Enable spi0 for MySensors RFM69 radio module and set the cs pins (GPIO pin 8 and 7 = PIN 24 and PIN 26) dtoverlay=spi0-cs,cs0_pin=8,cs1_pin=7 # Enable spi1 for MySensors NRF24 radio module and set the cs pin (GPIO pin 16 = PIN 36) dtoverlay=spi1-1cs,cs0_pin=16 # Enable shutdown pin (GPIO pin 5 = PIN 29) dtoverlay=gpio-shutdown,gpio_pin=5,active_low=1,gpio_pull="up" # Enable poweroff pin (GPIO pin 6 = PIN 31) dtoverlay=gpio-poweroff,gpiopin=6 # Enable lirc-rpi and set IN and OUT pins (GPIO pin 22 and 12 = PIN 15 and PIN 32) dtoverlay=lirc-rpi,gpio_in_pin=22,gpio_out_pin=12
Exit (CTRL+x) and save the changes (y).
GPIO: d-diot image v.1.2 and v.1.3
Edit the config.txt file to set GPIO pin for MySensors radio modules (SPI), ATmega2560 serial communication (RFlink), Lirc (ir receiver and blaster), SHUTDOWN and POWEROFF functionalities.
pi@raspberrypi:~ $ sudo nano /boot/config.txt
Add the following lines at the end of the file. Remember to delete the lines
dtoverlay=gpio-ir,gpio_pin=22 dtoverlay=gpio-ir-tx,gpio_pin=12
before re-addingh them in block
- /boot/config.txt
### d.diot settings # Enable serial enable_uart=1 # Enable spi0 for MySensors RFM69 radio module and set the cs pins (GPIO pin 8 and 7 = PIN 24 and PIN 26) dtoverlay=spi0-cs,cs0_pin=8,cs1_pin=7 # Enable spi1 for MySensors NRF24 radio module and set the cs pin (GPIO pin 16 = PIN 36) dtoverlay=spi1-1cs,cs0_pin=16 # Enable shutdown pin (GPIO pin 5 = PIN 29) dtoverlay=gpio-shutdown,gpio_pin=5,active_low=1,gpio_pull="up" # Enable poweroff pin (GPIO pin 6 = PIN 31) dtoverlay=gpio-poweroff,gpiopin=6 # Enable lirc-rpi and set IN and OUT pins (GPIO pin 22 and 12 = PIN 15 and PIN 32) dtoverlay=gpio-ir,gpio_pin=22 dtoverlay=gpio-ir-tx,gpio_pin=12
Exit (CTRL+x) and save the changes (y).
GPIO: d-diot image v.1.4 and above
Edit the config.txt file to set GPIO pin for MySensors RFM69 radio modules (SPI), MySensors NRF24 serial gateway, ATMega328P (mainmcu) serial communication. ATmega2560 serial communication (RFlink), Lirc (ir receiver and blaster), SHUTDOWN and POWEROFF functionalities.
pi@raspberrypi:~ $ sudo nano /boot/config.txt
Add the following lines at the end of the file. Remember to delete the lines
dtoverlay=gpio-ir,gpio_pin=22 dtoverlay=gpio-ir-tx,gpio_pin=26
before re-addingh them in block
- /boot/config.txt
### d.diot settings # Enable serial (uart1 = mainmcu, uart3 = RFLink, uart 5 = MySensors NRF24) enable_uart=1 dtoverlay=uart3 dtoverlay=uart5 # Enable spi0 for MySensors RFM69 radio module and set the cs pins (GPIO pin 8 and 7 = PIN 24 and PIN 26) dtoverlay=spi0-cs,cs0_pin=8,cs1_pin=7 # Enable shutdown pin (GPIO pin 16 = PIN 36) dtoverlay=gpio-shutdown,gpio_pin=16,active_low=1,gpio_pull="up" # Enable poweroff pin (GPIO pin 6 = PIN 31) dtoverlay=gpio-poweroff,gpiopin=6 # Enable lirc-rpi and set IN and OUT pins (GPIO pin 22 and 26 = PIN 15 and PIN 37) dtoverlay=gpio-ir,gpio_pin=22 dtoverlay=gpio-ir-tx,gpio_pin=26
Exit (CTRL+x) and save the changes (y).
Mount the doard
Shutdown your Pi
pi@raspberrypi:~ $ sudo poweroff
and mount the d-diot board. Power it on again and reconnect via ssh.
Please note that after the change of the hostname, if your system supports avahi / zeroconf, to connect to your raspberry you need to use the new name. For example if you are on a linux machine, open a terminal and then type:
user@host:~$ ssh pi@d-diot.local
Serial port configuration
To enable the serial communication with the ATmega2560 microcontroller through the pins 8 and 10 of the raspberry GPIO you need to disable the serial console. For a Raspberry Pi 3 Model B:
pi@d-diot:~ $ sudo systemctl stop serial-getty@ttyS0.service pi@d-diot:~ $ sudo systemctl disable serial-getty@ttyS0.service
You also need to remove the console from the cmdline.txt file, removing the following string: console=serial0,115200
pi@d-diot:~ $ sudo nano /boot/cmdline.txt
You should see something like that:
dwc_otg.lpm_enable=0 console=serial0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline fsck.repair=yes root wait
that you need to modify to:
- /boot/cmdline.txt
dwc_otg.lpm_enable=0 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline fsck.repair=yes root wait
Exit (CTRL+x) and save the changes (y).
A very good explanation on how to deal with serial ports in the Raspberry Pi is here
Wifi Access Point
To use the built-in Wifi module of your Raspberry Pi as a wireless access point for your IOT devices you need to install some additional packages. A detailed guide is here.
Install dnsmasq and hostapd and then stop it
pi@d-diot:~ $ sudo apt install -y dnsmasq hostapd pi@d-diot:~ $ sudo systemctl stop dnsmasq pi@d-diot:~ $ sudo systemctl stop hostapd
Set a static IP address for the wlan0 interface
pi@d-diot:~ $ sudo nano /etc/dhcpcd.conf
Add the following lines at the end of the file:
- /etc/dhcpcd.conf
interface wlan0 static ip_address=192.168.10.1/24 nohook wpa_supplicant
then exit (CTRL+x) and save the changes (y). Restart the dhcp client service to load the new configuration
pi@d-diot:~ $ sudo systemctl daemon-reload pi@d-diot:~ $ sudo systemctl restart dhcpcd
Configure dhcp server (dnsmasq), but first backup the original config file
pi@d-diot:~ $ sudo mv /etc/dnsmasq.conf /etc/dnsmasq.conf.orig pi@d-diot:~ $ sudo nano /etc/dnsmasq.conf
Add the following lines to enable the dhcp server for interface wlan0 (lease time = 24h)
- /etc/dnsmasq.conf
interface=wlan0 dhcp-range=192.168.10.2,192.168.10.100,255.255.255.0,24h
Configure the hotspot (hostapd)
pi@d-diot:~ $ sudo nano /etc/hostapd/hostapd.conf
- /etc/hostapd/hostapd.conf
ssid=d-diot wpa_passphrase=d-diot.com country_code=IT #ieee80211d=1 ieee80211n=1 interface=wlan0 driver=nl80211 hw_mode=g channel=7 wmm_enabled=1 macaddr_acl=0 auth_algs=1 ignore_broadcast_ssid=0 wpa=2 wpa_key_mgmt=WPA-PSK wpa_pairwise=TKIP rsn_pairwise=CCMP
You have to set your country code “country_code=XX”, then uncomment the ieee80211d=1 line. If you wont change also the name of your wifi network “ssid=d-diot” and the passphrase “wpa_passphrase=d-diot.com”.
Set the configuration file for hostapd. Search for the line #DAEMON_CONF, and replace it with this string DAEMON_CONF=“/etc/hostapd/hostapd.conf”.
pi@d-diot:~ $ sudo nano /etc/default/hostapd
Exit (CTRL+x) and save the changes (y).
Enable dnsmasq and hostapd services
pi@d-diot:~ $ sudo systemctl enable dnsmasq pi@d-diot:~ $ sudo systemctl enable hostapd
If you get an error saying that hostapd is masked, run the following command:
pi@d-diot:~ $ sudo systemctl unmask hostapd.service
To test hostapd
pi@d-diot:~ $ sudo hostapd -d /etc/hostapd/hostapd.conf
Start dnsmasq and hostapd
pi@d-diot:~ $ sudo systemctl start dnsmasq pi@d-diot:~ $ sudo systemctl start hostapd
Add routing
pi@d-diot:~ $ sudo nano /etc/sysctl.conf
and uncomment the line 28 net.ipv4.ip_forward=1
Add a masquerade (NAT) for outbound traffic on eth0
pi@d-diot:~ $ sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
Save the iptables rule.
pi@d-diot:~ $ sudo sh -c "iptables-save > /etc/iptables.ipv4.nat"
To make the NAT persistent edit the file /etc/rc.local
pi@d-diot:~ $ sudo nano /etc/rc.local
and add the following line before the exit 0 string
- /etc/rc.local
# Wifi AP NAT iptables-restore < /etc/iptables.ipv4.nat
Reboot the system
pi@d-diot:~ $ sudo reboot
If you wont to use the built in Wifi as a client for your network, follow this how to.
MariaDB server
The default database engine of Home Assistant is SQLite which doesn’t require any configuration and stores all the data in a plain file located in /home/homeassistant/.homeassistant.
Home Assistant supports also different database engines and MariaDB is one of them. The adoption of a full SQL server, like MariaDB has some pros and cons and, after some thinking, it has been chosen for the d-diot project.
More information on MariaDB and Home Assistant can be found here and here.
Before using the MariaDB server is a good practice to secure the installation
pi@d-diot:~ $ sudo mysql_secure_installation
Set root password and say Y to all questions, except for change password. The root password for the database in the d-diot image is “d-diot.com”.
Test the database connection
pi@d-diot:~ $ mysql -u root -p
If you tried to login with correct credentials but it keeps saying something like this: ERROR 1698 (28000): Access denied for user 'root'@'localhost'. You can disable MySQL from trying to authenticate root user using plugin:
pi@d-diot:~ $ sudo mysql -u root
MariaDB [(none)]> use mysql; MariaDB [mysql]> update user set plugin='' where User='root'; MariaDB [mysql]> flush privileges; MariaDB [mysql]> \q
Create the database and the user for Home Assistant. As you can see the password is “d-diot.com”.
pi@d-diot:~ $ mysql -u root -p
MariaDB [(none)]> CREATE DATABASE homeassistant; MariaDB [(none)]> CREATE USER 'homeassistant' IDENTIFIED BY 'd-diot.com'; MariaDB [(none)]> GRANT ALL PRIVILEGES ON homeassistant.* TO 'homeassistant'; MariaDB [(none)]> FLUSH PRIVILEGES; MariaDB [(none)]> exit
Now your database server is ready to work with Home Assistant; how to configure Home Assistant to use MariaDB is covered in the next steps.
Samba server
The samba server allows you to remotely access some predefined directories on the Raspberry filesystem. To configure it follow the steps below.
Create a system user “admin” and add it to samba
pi@d-diot:~ $ sudo adduser --no-create-home --disabled-password --disabled-login admin pi@d-diot:~ $ sudo smbpasswd -a admin
In the d-diot image the default samba password for the user admin is “d-diot.com” Add pi and homeassistant user to samba to allow write permission to admin
pi@d-diot:~ $ sudo smbpasswd -a pi pi@d-diot:~ $ sudo smbpasswd -a homeassistant
In the d-diot image the default samba password for the both users, pi and homeassistant, is “d-diot.com” Add the /home/pi and /home/homeassistant directories to share list
pi@d-diot:~ $ sudo nano /etc/samba/smb.conf
Disable the default home shares commenting out (#) the lines 187, 188, 189, 193, 197, 201, 208 ([Home] and subsequent), then add the following lines at the end of the file. For the d-diot image v.1.2 the lines to comment out are: 169, 170, 171, 175, 179, 183, 190
[Pi] create mode = 755 writeable = yes path = /home/pi force user = pi force group = pi comment = pi write list = admin directory mode = 755 valid users = admin [HA] create mode = 755 writeable = yes path = /home/homeassistant force user = homeassistant force group = homeassistant comment = Home Assistant write list = admin directory mode = 755 valid users = admin
Save, exit and restart samba server.
pi@d-diot:~ $ sudo systemctl restart smbd