1      Home Assistant Configuration

Given the vast number of add-on's and features of Home Assistant, configuration instructions are limited to achieving control of basic Sonoff, Zigbee and Z-Wave devices plus installing the integrations (packages) required for doing so. To proceed further requires knowing unique per-user requirements. Once basic configuration is complete, search the internet for HowTo's for any features / devices desired.

Home Assistant should be available (browser) at <Home Assistant LAN Address>:8123, where <LAN Address> depends on where HA was installed. For HA on real and virtual machines, it is the machine IP address. For docker-hassio (SecureOffice) installations it will be the SecureOffice LAN address. You should see the initial "create user account" page as shown below. Note that you may not see the left column, since HA is not yet been integrated with the SecureOffice menu system unless using the docker-hassio premium package. If not, verify installation steps and try again.

Figure 1: HA Initial Registration Page

To create the initial HA owner account, enter your name, create a user name, password and select "Create Account".

The next page will allow you to name and detect your location and select units of measurement. Configure according to your preferences. Press "Next", then "Finish".

The Home Assistant main page will be display, like below.

Figure 2:HA Main Page

1.1                Accessing Home Assistant Configuration Directory / Files

Subsequent configuration requires access to the HA internal filesystem. There are various methods for doing so, depending on how / where HA was installed. Subsequent instructions will refer to "<HA Config Dir>" which can be accessed by the following methods.

If using SecureOffice package "docker-hassio":

• The <HA Config Dir> is available as a network share for file browsing at "\\<SecureOffice LAN address>/Dockers/hassio/". No user name or password is required.

For all other HA installations if HA Add-on "Samba Share" is installed:

• The <HA Config Dir> is available as a network share for file browsing at "\\<Home Assistant LAN address>". The configured user name and password is required.

All HA installations, including docker-hassio if HA Add-on "SSH and Web Terminal" is installed:

• Can SSH to <Home Assistant LAN address>:<port configured for SSH> where <Home Assistant LAN address> is the LAN address of the device hosting HA and the port configured for SSH. You will need the user name and password that the SSH add-on was configured for.
• Can use the Web Terminal: "<Home Assistant LAN address>:8123->Supervisor->SSH & Web Terminal->Open Web UI". to get a command prompt within Home Assistant.

2      HA Configuration

HA can be configured by restoring from backup (snapshot) which automatically installs basic integrations and configuration or, manually installing and configuring integrations. Both methods are documented.

2.1                Configure Using Provided Snapshot

Given that HA configuration is a daunting task for new users with a steep learning curve, a snapshot (backup) of a pre-configured system is available to be up and running quickly. Experienced HA users may choose to skip this and start from the beginning and / or restore snapshots from their previous HA installations (eg: upgrading from unreliable Raspberry Pi installations).

As a convenience, a pre-configured Hassio snapshot (created from instructions in next section) is available for download by registered SecureOffice users from the SecureOffice custom repository. The snapshot is already included in the docker-hassio package. This snapshot will work with any Hassio installation on real or virtual machines.

The snapshot has the following configuration: HA user: "admin", password: "admin_54321".

The snapshot must be downloaded for all HA installations except the SecureOffice docker-hassio package.

Download the snapshot using a PC connected to the SecureOffice LAN only (otherwise, access will be denied due to unlicensed domain) from the SecureOffice custom repository. When prompted, enter your SecureOffice user ID and password (as previously entered in "/etc/opkg.conf") to download the snapshot (ha_default.tar). By "LAN only" means disable all network interfaces except the connection to the SecureOffice LAN (wired or WiFi).

Another (easier, no disabling network interfaces) download method is using a SecureOffice command prompt: "cd /tmp; sget ../Files/ha_default.tar" which will place the file in /tmp.

SSH access the <HA Config Dir>, enter "mkdir /backup" to create (if does not exist) the HA backup directory. Copy the downloaded snapshot (ha_default.tar) to the above directory (using shared folders, WinSCP or another method). Reboot the HA PC or VM (Web GUI "Configuration-> Server Controls-> Restart") for HA to detect the snapshot.

If there is more than one snapshot, it may be necessary to SSH into HA to identify the correct snapshot by date. "ls -la backup".

After HA reboots, the snapshot can be accessed by (web GUI) "Supervisor -> Snapshots -> Available Snapshots". Click on the snapshot, a "Restore Snapshot" window will display, as shown below:

Figure 3: HA Restore Snapshot

Unselect (check mark) "Home Assistant" to not use the snapshot Home Assistant version (keep existing HA version). Click "Wipe & Restore", click OK when prompted. Connection with HA will be lost until restore completes. After restore completes, several configuration values are required to personalize settings.

Open the Home Assistant GUI (not from within OpenWrt GUI - authorization bug related to HA in iframe) using https://<Home Assistant LAN address>:8123

• Go to HA web GUI->Supervisor->SSH & Web Terminal->Open Web UI
• A command prompt will appear
• Enter "nano /config/configuration.yaml".
• If using standard Sonoff devices, alter the sonoff entry for your EWeLink user ID and password using the Install SonoffLAN instructions.
• If using email notifications (for Hassio Custom Alarm or other purposes), alter the notify entry for your email server parameters using the Alarm Notifications instructions.
• Save the file and exit nano.
• A HA reboot (Configuration->Server Controls -> Restart) is required for the altered configuration to take effect.

The snapshot is pre-configured and tested with the following configuration / integrations:

• SSH and Web Terminal - Allows you to log in to your Home Assistant instance using SSH or by using the Web Terminal, including remote access over VPN. Pre-configured: username: "admin", password: "admin_54321", SSH server port: "2223".
• SonoffLAN - Control Sonoff Devices with eWeLink (original) firmware over LAN and / or Cloud from Home Assistant. To configure, follow instructions in Discover and Configure Sonoff Devices.
• ZHA Network Card - Custom Lovelace card that displays ZHA (Zigbee) network and device information. No configuration required.
• Alarmo Alarm - Fully functional burglar alarm. Requires motion detect and / or window / door sensor devices. More features than standard HA alarm. Disarm code: "4321"
• Nortek HUSBZB-1 combo Z-Wave / Zigbee interface. Can easily reconfigure to use any HA compatible interface device.

2.2                Configure HA Manually

Default HA configuration will be completely replaced. For reference, the default configuration is shown below:

Figure 4:HA Default configuration.yaml

Access <HA Config Dir> to edit file configuration.yaml. Delete all contents. Replace with contents from below:

Figure 5:HA Replacement configuration.yaml

Uncomment and alter the GPS and timezone values according to your location. Save the file.

Create directory "<HA_Config_Dir>/automations" for separate file.yaml per automation support.

Further configuration depends on which integrations you choose to enable / install (next section).

3      Install HA Basic Integrations

The following integrations may be installed manually or by restoring from the preconfigured snapshot with the following configuration settings. Any settings that are not mentioned are left at default values:

SSH & Web Terminal: username: "admin", password: "admin_54321", SSH server port: "2223"

Alarmo Alarm: Disarm code: "4321"

3.1                Samba Share

This addon is unnecessary if using package docker-hassio which automatically shares docker image persistent data from SecureOffice directory "/home/data/docker_data/hassio" This data is available to devices connected to the SecureOffice LAN (explorer) at "\\<your SecureOffice LAN address>/Dockers/hassio" (no password required).

This addon enables Home Assistant file sharing across different operating systems over a network. It lets you access your Home Assistant configuration files from Windows, Linux and macOS devices.

Using the Home Assistant web GUI, navigate to "Supervisor - > Add-on Store". Select "Samba Share", press "Install"

Enter add-on configuration values. It is mandatory to at least set the "start on boot, workgroup, username and password" values. After done, press "Start".

Using Windows explorer, navigate to \\<LAN address of Home Assistant>. You should see the following directories: "addons, backup, config, share, ssl". If not, restart Home Assistant and try again. Fix any errors before proceeding.

3.2                SSH and Web Terminal

This add-on allows you to log in to Home Assistant using SSH or the integrated Web Terminal in a browser. It also provides access to the HA command line utility and configuration files for managing home-assistant.

Using the Home Assistant web GUI, navigate to "Supervisor - > Add-on Store". Select "SSH & Web Terminal", press "Install". If the application does not show, enable advanced mode on your user profile page to make it visible.

Enter configuration values. It is mandatory to at least set the "username, password, SSH server port" values. The "SSH server port" must not be "22" or "2222", since it will conflict with the SecureOffice SSH server (2223 is a good choice). Press "Save" after any changes. Press "Start". Under "Log", press "REFRESH" periodically until you see "Starting session". Fix any errors such as insecure password before proceeding.

A HA console session can be started by either "OPEN WEB UI" from within the add-on or using a SSH client (putty) to connect to <IP Address of host>:< SSH server port>.

Docker-hassio ONLY: Be aware there is an authorization bug related to HA in iframe which is used to integrate docker-hassio with the OpenWrt menu system. This means the "OPEN WEB UI" function will have an access error. To avoid this, access HA using https://<SecureOffice LAN address>:8123

If this add-on was installed using restore snapshot from backup, the default configuration values can be seen and changed from "Supervisor->SSH & Web Terminal->Configuration". It is recommended to change the default password.

3.3                Alarmo-Alarm

This add-on replaces the standard Home Assistant alarm panel with a fully functional burglar alarm with the following features:

• Fully compatible with Home Assistant and the Alarm Panel Card.
• Has an integrated panel for complete management via UI (no YAML required).
• No restarts required when making changes.
• Can set up to 4 arm modes (armed_away, armed_home, armed_night, armed_custom_bypass), each with configurable delays and security perimeter.
• Supports configuring your existing HA entities as security sensors. These sensors will be watched automatically.
• Allows setting up multiple users with individual pincode and permission levels.
• Will restore its previous state after restart of HA.
• Built-in actions: receive push notifications when anything changes in the alarm, activate a siren when the alarm is triggered, etc.
• Supports splitting up your house security system into multiple areas which can be armed independently.

Alarmo links:

• Home Page: https://github.com/nielsfaber/alarmo
• Documentation: https://github.com/nielsfaber/alarmo/#readme
• Help / Forum: https://community.home-assistant.io/t/custom-component-alarmo-browser-managed-alarm-system/

This addon requires motion detectors and / or door / window sensors to function. Tested with Xiaomi Aqara motion sensors, but any HA compatible motion sensor should work.

This addon / HA has also been tested with HEIMAN HS1SA-E (zigbee) smoke detectors, which can also be used as alarm triggers, as can any binary sensor.

3.3.1      Alarmo Installation

Go to HA web GUI->Supervisor->SSH & Web Terminal->Open Web UI

Enter the following commands:

• "sudo apt -y install unzip"
• "sudo cd /tmp; wget https://github.com/nielsfaber/alarmo/releases/latest/download/alarmo.zip"
• "sudo mkdir -p /config/custom_components/alarmo"
• "sudo cd /config/custom_components/alarmo"
• "sudo unzip /tmp/alarmo.zip, rm -f /tmp/alarmo.zip"
• Restart Home Assistant to detect the component.
• Go to Configuration -> Integrations and click the big orange '+' button. Look for Alarmo and click to add it.
• The Alarmo integration is ready for use. You can find the configuration panel in the menu on the left.

3.3.2      Alarmo Configuration

Prior to configuration, ensure that all motion detect and security sensor devices have been discovered by Home Assistant (Configuration -> Devices). If not, install and configure your devices prior to proceeding.

After HA restarts, Click on "Alarmo" in the Home Assistant sidebar. The Alarmo main page will display, as shown below:

Figure 6: Alarmo Main Page

Follow the instructions in the Alarmo documentation to configure Alarmo for your requirements, including modes of operation, sensors, notifications and actions.

3.3.3      Add Alarm Panel Card

Alarmo arm / disarm can be controlled using the standard HA "Alarm Panel" card, or the Alamo custom Alarm Panel which has more features such as a countdown timer for mode entry and displaying which sensors triggered the alarm.

To install the standard HA card, from the HA main page, click the 3 vertical dots in upper right to enter "Edit Dashboard" mode. Click "Add Card" and select the "Alarm Panel" card. Alarm Panel configuration will appear as shown below:

Figure 7: HA Alarm Card Configuration

If interested in additional states such as arm_night or arm_custom_bypass (see documentation), add them and press "Save". The HA Alarm Card will appear in the HA dashboard as shown below:

Figure 8: HA Alarmo Card

To install the custom Alarmo card, from the HA main page, click the 3 vertical dots in upper right to enter "Edit Dashboard" mode. Click "Add Card" and select "Custom: Alarmo Card". Select "alarm_control_panel.alarmo" for entity. Alarmo Panel, configuration will appear as shown below:

Figure 9: Alarmo Card Configuration

Press "Save". The Alarmo Card will appear in the HA dashboard as shown below:

Figure 10: Alarmo Card

After adding sensors and enabling Alarmo "Arm Away" mode, if a sensor is triggered, the Alarmo panel will show "Triggered" and display the last sensor that triggered, as shown below:

Figure 11: Alarmo Triggered

3.3.4      Alarmo Notifications

A burglar alarm is useless without some way to announce that intruders have been detected. Notification options are:

• Email notification (modify example SMS notification to use email address rather than SMS gateway)
• SMS (text) notifications to cellphone - requires a SMS gateway, which most cellular operators provide free for their customers.
• Use one of the many notification integrations provided by HA.

Configuration instructions to send an email / SMS notification follow.

Enable HA built in email notifications by adding the following code to <HA Config Dir> file "/configuration.yaml":

Figure 12: Enable Email Notifications

To create an email / SMS text notification when the alarm is triggered, Navigate to HA GUI -> Alarmo -> Actions -> Notifications and enter the following:

Figure 13: Alarmo Notification

3.3.5      Alarmo Actions

A burglar alarm is useless without some way to indicate that intruders have been detected. Action options are:

• Siren controlled by Home Assistant (search for HowTo's) to alert neighbors.
• Flash all lights in house (search for HowTo's) to alert neighbors.
• Use a media device to play an alert sound or TTS announcement (search for HowTo's).

To create an action when the alarm is triggered, Navigate to HA GUI -> Alarmo -> Actions -> Actions.

The flash_light script was defined in Adding Scripts. This particular script was used to test Alarmo triggering, using the settings below:

Figure 14:Alarmo Trigger

3.4                Mosquitto Broker

Mosquitto Broker is a MQTT server. MQTT is a machine-to-machine (M2M) / "Internet of Things" connectivity protocol. It was designed as an extremely lightweight publish / subscribe messaging transport. It is useful for connections with remote locations where a small code footprint is required and / or network bandwidth is at a premium. For example, it has been used by sensors communicating to a broker via satellite link, over occasional dial-up connections with healthcare providers, and in a range of home automation and small device scenarios. It is ideal for mobile applications because of its small size, low power usage, minimised data packets, and efficient distribution of information to one or many receivers. The MQTT protocol provides a lightweight method of carrying out messaging using a publish (event sources publish events) / subscribe (event listeners subscribe to events of interest) model. This makes it suitable for Internet of Things messaging such as low power sensors or mobile devices, phones, embedded computers or microcontrollers.

Mosquitto broker can be used to control devices flashed with Tasmota (MQTT client), Z-Wave devices using the ZWave2MQTT (gateway) add-on and Zigbee devices by flashing Zigbee2mqtt firmware, (gateway to Zigbee devices - technical skills, hardware required) on an inexpensive CC2531 USB stick.

There are two options for Mosquitto Broker installation, the OpenWrt MQTT broker package (recommended) or the HA MQTT broker addon.

Any Home Assistant installation (virtual, docker or real servers anywhere on the SecureOffice LAN) can choose to use either the OpenWrt MQTT broker package or the HA MQTT broker addon.

Do not install Mosquitto broker until instructed to do so when (optionally) configuring MQTT for Tasmota, ZWave2MQTT or the CC2531 USB stick.

3.4.1      SecureOffice / OpenWrt Broker Package

The SecureOffice Mosquitto Broker is automatically installed if using the docker-hassio package.

To install the broker package for use by any other HA installation, enter (SecureOffice command prompt): "opkg update; opkg install mosquitto-ssl"

Create a new user for MQTT via HA GUI Configuration->Users (manage users). Note: This name cannot be "homeassistant" or "addon", those are HA reserved usernames. Suggest name: "MQTT", username: "mqtt", enter and remember the MQTT password. This user must have administrator privileges.

The SecureOffice Mosquitto broker password must match the MQTT password created above. If a user name other than "mqtt" was chosen, replace both "mqtt"'s in the following command by <MQTT username>. All devices connecting to the MQTT broker will require <MQTT username> and <MQTT password> to be set.

To change the SecureOffice MQTT password, enter (SecureOffice command prompt): "echo -e "mqtt\nmqtt\n" | mosquitto_passwd -c /etc/mosquitto/passwords.txt <MQTT password>"

Enable and start the MQTT broker: "/etc/init.d/mosquito enable; /etc/init.d/mosquito restart", using a SecureOffice command prompt.

Several files need to be created in the "/share" directory on the Home Assistant filesystem.

Create <HA Config Dir> file "/share/mosquitto/acl.conf" with contents "acl_file /share/mosquitto/accesscontrollist".

Create <HA Config Dir> file "/share/mosquitto/accesscontrollist" with the following contents (MQTT userid created above):

Navigate to HA GUI->Configuration->Integrations.

If the MQTT integration is enabled, delete it. Press "+" and search for MQTT. Click on MQTT.

Configure the Broker. IP Address: <SecureOffice LAN address>, Port (defaults), MQTT Username, Password (created previously) and Submit.

If not already done, flash your sonoff devices and ensure they show up and are controllable from Home Assistant->Overview.

Enable MQTT auto-discovery (add devices). Add the following to "<HA Config Dir>/configuration.yaml":

Figure 15:Enable MQTT Auto Discovery

Restart Home Assistant for the configuration to take effect.

3.4.2      Home Assistant Broker Addon

This addon is unnecessary if using the SecureOffice docker-hassio package. Mosquitto broker is provided by SecureOffice / OpenWrt.

Official Mosquitto Broker add-on documentation is here.

To install using the Home Assistant web GUI, navigate to "Supervisor- >Add-on Store". Select "Mosquitto broker", press "Install".

Navigate to Supervisor->Add-ons->Mosquitto broker->Configuration. Change Mosquitto Broker options as below:

Figure 16:Mosquitto Broker Add-on Configuration

Create a new user for MQTT via Configuration->Users (manage users). Note: This name cannot be "homeassistant" or "addon", those are reserved usernames. Suggest name: MQTT, username: "mqtt", enter and remember the password. This user must have administrator privileges.

Several files need to be created in the "/share" directory on the Home Assistant filesystem.

Create <HA Config Dir> file "/share/mosquitto/acl.conf" with contents "acl_file /share/mosquitto/accesscontrollist".

Create <HA Config Dir> file "/share/mosquitto/accesscontrollist" with the following contents (MQTT userid created above):

Start Mosquitto Broker add-on, check the log (Supervisor->System) and fix any reported issues.

Navigate to HA GUI->Configuration->Integrations.

If the MQTT integration is enabled, delete it. Press "+" and search for MQTT. Click on MQTT.

Configure the Broker. IP Address: 127.0.0.1, Port (defaults), MQTT Username, Password (created previously) and Submit.

If not already done, flash your sonoff devices and ensure they show up and are controllable from Home Assistant -> Overview.

Enable MQTT auto-discovery (add devices). Add the following to "<HA Config Dir>/configuration.yaml":

Restart Home Assistant for the configuration to take effect.

3.5                ZHA Network Card

This add-on displays discovered ZHA (Zigbee) network and device information as shown in Detected Zigbee Devices.

Documentation and installation instructions are available at the author's site.

4      Use Standard Sonoff Devices

Two options (integrations) are discussed for controlling standard Sonoff Devices:

• SonoffLAN - Recommended since, after initial device configuration, does not rely on or contact any internet servers.
• HASS-sonoff-ewelink - Relies on internet servers for operation. Internet research for HowTo's.

4.1                Install SonoffLAN

• Download latest SonoffLAN-master.zip file and extract it to a temporary location.
• Access <HA Config Dir> if "/custom_components" directory does not exist, create it.
• Navigate to where you extracted the downloaded "SonOffLAN-master.zip" file. Navigate to subdirectory "SonoffLAN-master/custom_compenents" You should see a "sonoff" directory. Select and copy the "sonoff" directory to the "<HA Config Dir>/custom_components/" directory.

4.2                Discover and Configure Sonoff Devices

Ensure that your Sonoff WiFi device(s) (including RF Bridge - if using) are connected and powered on.

The EWeLink application is required for device discovery. It can be installed on Android or IOS devices. An EWeLink user manual is available (read it).

After installing EWeLink, perform the following steps using EWeLink:

• Ensure that EWeLink (phone, tablet) is connected to the SecureOffice (2.4GHz only) WiFi network that your Sonoff device(s) will use.
• Register an account. Remember your username and password.
• Login to EWeLink server.

For each Sonoff device, enter pairing mode (press device button for 7 seconds). Press (EWeLink) "+" to enter discovery mode, Select "Quick Pairing". Fill in the WiFi credentials the device will use. If pairing takes too long, press the device button for 7 seconds again. Enter a "Device name" when prompted, press "Complete". The device will show up in EWeLink. Select the icon next to the device name for further configuration. If you see "Firmware update available", go to "Settings" to update.

Important: Every time you add or change devices using EWeLink, delete the hidden file "<HA Config Dir>/.sonoff.json" and restart Home Assistant (Configuration->Server Controls -> Restart). This file contains device settings downloaded from the EWeLink server, if the file does not exist locally. Downloading device settings from EWeLink is the only internet access that SonoffLAN requires and only if a local copy of "<HA Config Dir>/.sonoff.json" does not exist.

Append the following at the end of file "<HA Config Dir>/configuration.yaml" to allow Home Assistant to get device configuration from the EWeLink server.

Figure 17:Sonoff User Credentials

Restart Home Assistant and navigate to "Overview". You should see the Sonoff devices added. The figure below shows two Sonoff Basic switches controlled via the SonOffLAN addon.

Figure 18: HA Sonoff Switches

5      Use Tasmota Flashed Sonoff Devices

Choose which Mosquitto Broker implementation to use (SecureOffice MQTT broker package or HA MQTT broker add-on).

Install and configure the chosen Mosquitto broker implementation (previous link).

6      Use Z-Wave Devices

Enable the HA Z-Wave built-in integration for the Nortek HUSBZB-1 Zigbee / Z-Wave combo USB interface. Add the following to "<HA Config Dir>/configuration.yaml":

Figure 19:Z-Wave Interface Configuration

If running HA in a virtual machine it is necessary to (Vmware GUI) connect the Z-Wave interface to the virtual machine. Select "Player->Removable Devices-> <Interface Device Name>->Connect (Disconnect from Host)"

If using a different Z-Wave interface device, the USB path may be different. See Identify USB Interface Devices to determine the correct USB path.

New Z-Wave devices (became active after Home Assistant already running) can be discovered by going to Developer Tools->Services and entering "zha.permit". This avoids having to restart Home Assistant to discover new Z-Wave devices.

7      Use Zigbee Devices

Enable the HA Zigbee built-in integration for the Nortek HUSBZB-1 Zigbee / Z-Wave combo USB interface. Add the following to "<HA Config Dir>/configuration.yaml":

Figure 20:Zigbee Interface Configuration

The "usb path" entry is not used by newer versions of HA and remains commented. Older HA versions may require this variable to be set.

If running HA in a virtual machine it is necessary to (Vmware GUI) to connect the Zigbee interface to the virtual machine. Select "Player->Removable Devices-> <Interface Device Name> -> Connect (Disconnect from Host)"

If using a different Zigbee interface device, the USB path may be different. See Identify USB Interface Devices to determine the correct USB path.

8      Adding Automations

Refer to the HA automations documentation.

Home Assistant automations are programmed sequences of actions in response to events optionally qualified by states. The Alarmo Alarm is an automation. When the alarm is in armed state and an enabled motion detector triggers (event) occurs, a text message or email is sent. An automation is self-contained and includes triggers (event that invokes automation), conditions (state of some entity) and actions (what to do if trigger occurs and conditions are met).

Automations can be entered / defined using the HA GUI, in which case all automations are defined in a single file (<HA Config Dir>/automations.yaml). To support this mode of operation, "<HA Config Dir>/configuration.yaml" must contain "automation: !include automations.yaml" to include the automations file.

It is also possible to define automations directly in "<HA Config Dir>/configuration.yaml" using a text editor. Automations defined in configuration.yaml cannot be managed using the HA GUI.

As your HA installation grows in complexity, with many automations, it may become confusing to manage them all. To reduce complexity, it is possible to split automations into separate files, each file containing a specific automation, named according to function. Automations defined by this method cannot be managed using the HA GUI. To support this mode of operation, "<HA Config Dir>/configuration.yaml" must contain "automation: !include_dir_merge_list automations" to include all files in the automations directory (must be created).

An example automation is when motion occurs and it is dark: turn on / off a light or appliance, example (<HA Config Dir>/automations/upstairs_light.yaml) below:

Figure 21:Turn on Light By Motion

9      Adding Scripts

Refer to the HA script documentation.

Home Assistant scripts are programmed sequences of actions to execute when the script is called by an automation when a trigger occurs and conditions are met.

Scripts can be entered / defined using the HA GUI (script editor), in which case all scripts are defined in a single file (<HA Config Dir>/scripts.yaml). To support this mode of operation, "<HA Config Dir>/configuration.yaml" must contain "script: !include scripts.yaml" to include the scripts file.

It is also possible to define scripts directly in "<HA Config Dir>/configuration.yaml" using a text editor. Scripts defined in configuration.yaml cannot be managed using the HA GUI and must be managed using a text editor.

As your HA installation grows in complexity, with many scripts, it may become confusing to manage them all. To reduce complexity, it is possible to split scripts into separate files, each file containing a specific script, named according to function. Scripts defined by this method cannot be managed using the HA GUI. To support this mode of operation, "<HA Config Dir>/configuration.yaml" must contain "script: !include_dir_merge_named scripts" to include all files in the scripts directory (must be created).

An example script is turn on a light for one minute, then turn off the light, example (<HA Config Dir>/scripts/flash_light.yaml) below:

Figure 22:Turn on Light For One Minute

1  0Adding Sensor Status

Sensor status is important to display open sensors which may prevent arming the burglar alarm, seeing that all sensors are detected and monitoring smoke detectors.

From the HA main page, click the 3 vertical dots in upper right to enter "Edit Dashboard" mode. Click "Add Card" and select the "Glance" card. Glance configuration will appear as shown below:

Figure 23: Glance Status Configuration

Delete all entities and add all burglar alarm sensors. Add "Security Sensors" as title. Click save. Status of all configured entities will appear in the HA dashboard as shown below:

Figure 24: Security Sensors

If you have other sensors such as smoke detectors, add another Glance card containing the corresponding entities with title "Smoke Alarms". Status of all configured entities will appear in the HA dashboard as shown below:

Figure 25: Smoke Sensors

1  1Final Result

Thus far, configuration has dealt with setting up the HA infrastructure (interfaces, protocols, devices, integrations) required to provide event sources (sensors) and devices to control for Home Assistant automations.

What to do next is dependent on what YOU want Home Assistant to do. Consult the Home Assistant automations documentation for ideas, examples and HowTo's.

After following previous installation / configuration instructions (with devices which will change, dependent on user configured devices / UI), the Home Assistant completed main page is as shown below:

.

Figure 26: HA Final Main Page

The "ZHA STATUS" (discovered Zigbee devices) page is shown below:

Figure 27: Detected Zigbee Devices

HA must be re-configured to delete devices, entities and UI elements that you do not have / want and add what you do have / want. Consult the Home Assistant documentation.

1  2Backup Home Assistant

Once satisfied with Home Assistant configuration, it is prudent to backup your configuration, for disaster recovery.

All HA installations can be backed up using Supervisor->Snapshots->Create Snapshot. Copy the snapshot to a safe location on another (not HA) PC using any of the <HA Config Dir> access methods.

Alternatively, if using docker-hassio, Home Assistant can be backed up as part of a full system backup. Using SecureOffice / OpenWrt GUI, navigate to System->Backup / Flash Firmware->Generate Archive which will automatically save the full system backup (including Home Assistant) to your PC.

1  3Remote Access

Do you want to provide public (everyone) access to Home Assistant or keep it private (for those you choose such as family members), accessible locally and / or using VPN?

Four options exist for Home Assistant remote access:

• Private remote access: use the SecureOffice VPN server (recommended) which makes remote clients local to the remote client device such as PC, tablet, phone.
• Public and / or private remote access: use Nginx webserver (can proxy any Home Assistant server)
• Public remote access: open firewall port(s) (discouraged, since ports may be blocked by business, schools, internet cafe's).
• Private remote access: users of Home Assistant Cloud (subscription service) can use the Remote UI without requiring any further remote access configuration.

Public access means anyone on the internet can access your services. This is the least secure remote access method, since passwords can be cracked.

Private access means that only users on your local LAN and / or remote VPN (such as family members) can access your service. This is the most secure and recommended approach.

13.1            Remote Access Clients

Home Assistant can always be accessed from anywhere (local and / or remote if configured) using a web browser on any device. Various Android and IOS clients exist. To choose the remote access client that is best for you, search "Home Assistant remote client apps". A review of several popular Home Assistant client apps is available here.

Remote access client configuration is client specific and not covered by this document. Consult the client documentation and search for "Home assistant remote access".

13.2            Public Remote Access

This means anyone can take a crack at hacking your site, since anyone can access the login page.

This poses a serious security risk from hackers. Review Home Assistant authentication. Security can be increased by enabling secrets and using multi-factor authentication, but this increases login complexity and may require extra packages to be installed on remote devices.

It is far more secure to remotely access Home Assistant using the SecureOffice VPN Server which allows secure remote access clients to appear as local clients.

13.1            Docker-Hassio Public Internet Access

At docker-hassio installation, Home Assistant is automatically configured for private (clients on local LAN only) network access as a Nginx virtual host by Nginx configuration file "/etc/nginx/vhosts/hassio" installed as part of the package.

The general approach (and pre-requisites) for serving a site at a domain or subdomain is in the Nginx HowTo documentation.

Assuming prerequisites such as domain, DNS, SSL certificates were met prior to docker-hassio installation, the values "<your LAN address>" and "<your domain name>" were automatically set at docker-hassio installation.

To enable public Home Assistant access, comment (insert "#") or delete the "allow" and "deny" lines in the "/etc/nginx/vhosts/hassio" configuration file, shown below:

Home Assistant will be publicly accessible at "https://hassio.<your domain>".

Figure 28: Hassio Virtual Domain

Note: Home Assistant is http only and Nginx is converting http to https and the converse.

Restart nginx: "/etc/init.d/nginx restart; rm -rf /var/luci-*" at a command prompt for the changes to take effect.

Enter "https://hassio.<your domain name>" in a web browser on a PC not connected to the SecureOffice LAN. If all is well, you will see the Home Assistant registration page (Figure 1) without OpenWrt GUI.

If all is not well, enable Home Assistant logging "log_std* '1'" in file "/etc/config/docker/hassio", restart Home Assistant ("/etc/init.d/docker stop; /etc/init.d/docker start"), enter "logread -f | grep docker" (to watch error messages) and try to access Home Assistant again. Enter "CTRL+c" (together) to exit logread. Fix any errors.

13.2            Use Nginx Server

Home Assistant installations using any method other than docker-hassio are available at "http://<Home Assistant LAN address>:8123" and needs to be proxied by Nginx to be accessible by domain or subdomain name.

This configures Home Assistant to be accessible at a subdomain, for example, "http(s)//homeassistant/<your domain name>"

Home Assistant can be accessed locally or remotely (if enabled) by "http(s)//homeassistant/<your domain name>".

This approach has the following advantages:

• No port forwarding
• Uses standard ports (http:80, https:443) which no one can block without killing internet.
• http is automatically upgraded to https.
• https (secure) access shares SecureOffice SSL certificates.

This configuration is similar to the docker-hassio Nginx domain configuration (Hassio Virtual Domain) differing only by the "server_name" and "proxy_pass" directives. Also, since Home Assistant is external to SecureOffice (VM or real machine), it is not integrated with the SecureOffice / OpenWrt GUI.

Assuming the desired HA subdomain is "homeassistant", Nginx configuration ("/etc/nginx/vhosts/homeassistant.conf") will be like below (using method and all prerequisites from Create Nginx Virtual Host):

Figure 29: HA SubDomain Configuration

From a SecureOffice command prompt, enter "/etc/init.d/nginx restart" to have the new settings take effect. Try to access "http(s)//homeassistant/<your domain> ". You should see the Home Assistant add user or login page. Fix any issues before proceeding.

To allow public remote access, comment (add "#') or remove the "allow" and "deny" lines from the configuration file above.

If the URL "http(s)://homeassistant/<your domain name>" is not to your liking, it can be easily changed by changing the "server_name" directive and configuration file name.

13.3            Use Alternate Port

This configures Home Assistant to be locally accessible by "<your LAN address>:8123" and remotely by "http//<your domain name>:<port you choose>"

This approach has the following disadvantages:

• Firewall ports must be opened or forwarded,
• Non-standard ports may be blocked by business, schools, internet cafes.
• If https (secure) access required, Home Assistant must be further configured with SSL certificates. If not, http only (insecure) access. Consult online for HowTo's.

For port forwarding, follow port forwarding instructions, add the following port forward. When done, from a SecureOffice command prompt, enter "/etc/init.d/firewall restart"

Table 1:Home Assistant Port Forwards

Try to access "http//<your domain>:<port you chose>". You should see the Home Assistant add user or login page. Fix any issues before proceeding.