# Home Assistant

Welcome to my Home Assistant setup repository.  
This repository documents and maintains the Home Assistant instance running in my home, hosted on homesrv01/casa server.  
All essential Docker containers, such as MQTT and speech recognition, are hosted on the same server for seamless integration.  

<!-- omit in toc -->
## Table of Contents

- [Devices](#devices)
  - [Broadlink - RM4 Pro](#broadlink---rm4-pro)
  - [ZigBee - Smart Plugs](#zigbee---smart-plugs)
  - [Shelly - Smart Plugs](#shelly---smart-plugs)
- [Integrations](#integrations)
  - [MQTT](#mqtt)
  - [zigbee2mqtt](#zigbee2mqtt)
  - [Broadlink](#broadlink)
  - [Wyoming Protocol](#wyoming-protocol)
  - [HACS](#hacs)
  - [Google Cast](#google-cast)
  - [LG webOS Smart TV](#lg-webos-smart-tv)
  - [Mobile App](#mobile-app)
  - [Meteorologisk institutt (Met.no)](#meteorologisk-institutt-metno)
  - [Pi-hole](#pi-hole)
  - [Proxmox VE](#proxmox-ve)
  - [Shelly](#shelly)
  - [Speedtest.net](#speedtestnet)
  - [Squeezebox (Lyrion Music Server)](#squeezebox-lyrion-music-server)
  - [Sun](#sun)
  - [Time \& Date](#time--date)
  - [Xbox](#xbox)
- [Setup](#setup)
  - [Docker](#docker)
    - [Deploy and update](#deploy-and-update)
    - [Volumes](#volumes)
      - [`has_config`](#has_config)
  - [Development Environment](#development-environment)

## Devices

### Broadlink - RM4 Pro

Using as Ir blaster for living room devices and temperature meter.

![ZigBee Smart Plugs](doc/images/broadlink-universal-remote-irwifi-rm4-mini.jpg)

**Integrations:**

- [broadlink](#broadlink)

### ZigBee - Smart Plugs

Currently controlling:

- bed room lights
- dining table lights

![ZigBee Smart Plugs](doc/images/51ojy7qoMmL._SL1500_.jpg)

**Integrations:**

- [zigbee2mqtt](#zigbee2mqtt)
- [mqtt](#mqtt)

### Shelly - Smart Plugs

Currently controlling and monitoring:

- brutus.dev.lan (proxmox server)
- office light

![Shelly - Smart Plug](doc/images/shellysmartplug.png)

Devices connected to IOT lan.

**Integrations:**

- [shelly](#shelly)

## Integrations

### MQTT

MQTT (Message Queuing Telemetry Transport) is a lightweight, publish/subscribe messaging protocol designed for machine-to-machine (M2M) communication and the Internet of Things (IoT). It operates on top of TCP/IP, making it ideal for resource-constrained devices.

**Setup:**  
The Mosquitto MQTT broker is configured as the central messaging hub. For setup details, refer to the [Mosquitto setup repository](https://git.limbosolutions.com/marcio.fernandes/mosquitto).

**Requirements:**  
Ensure port `1883` is accessible from Home Assistant to the Mosquitto server (`mqtt.lan`).

**Links:**  

- [Home Assistant MQTT Integration Documentation](https://www.home-assistant.io/integrations/mqtt)

### zigbee2mqtt

Configured as a docker container on [homesrv01](/marcio.fernandes/homesrv01.dev.lan#zigbee2mqtt).

Using SONOFF Universal Zigbee 3.0 USB Dongle Plus.

### Broadlink

The [broadlink integration](https://www.home-assistant.io/integrations/broadlink) allows you to control and monitor Broadlink universal remotes, smart plugs, power strips, switches and sensors.

![broadlink integration](./doc/images/integrations-broadlink.png).

Devices:

- RM4 mini (IR Blaster)

Requires port 80 access from home assistant to Broadlink devices.

### Wyoming Protocol

A peer-to-peer protocol for voice assistants (basically JSONL + PCM audio)

```json
{ "type": "...", "data": { ... }, "data_length": ..., "payload_length": ... }
<data_length bytes (optional)>
<payload_length bytes (optional)>
```

Used in Rhasspy and Home Assistant for communication with voice services.

This is an open standard of the Open Home Foundation.

Docker containers currently hosted at [homesrv01.dev.lan](https://git.limbosolutions.com/marcio.fernandes/homesrv01.dev.lan#wyoming).

**Links:**

- <https://github.com/home-assistant/addons/blob/master/whisper/DOCS.md>
- <https://github.com/rhasspy/wyoming-faster-whisper>

### HACS

**Links:**

- [Official git repo](https://github.com/hacs/integration)

### Google Cast

**Links:**

- [Home Assistant - Official integration documentation](https://www.home-assistant.io/integrations/cast)
- [Official git repo](https://github.com/home-assistant/core/tree/dev/homeassistant/components/cast)

### LG webOS Smart TV

The webostv platform allows you to control a LG webOS Smart TV.

There is currently support for the following device types within Home Assistant:

- Media player
- Notifications

To begin with enable LG Connect Apps feature in Network settings of the TV.

### Mobile App

The Mobile App integration allows Home Assistant mobile apps to easily integrate with Home Assistant.

**Links:**

- [Home Assistant - Official integration documentation](https://www.home-assistant.io/integrations/mobile_app)

### Meteorologisk institutt (Met.no)

The met platform uses the Met.no web service as a source for meteorological data for your location. The weather forecast is delivered by the Norwegian Meteorological Institute and the NRK.

**Links:**

- [Home Assistant - Official integration documentation](https://www.home-assistant.io/integrations/met)

### Pi-hole

The Pi-hole integration allows you to retrieve statistics and interact with a Pi-hole system.

**Links:**

- [Home Assistant - Official integration documentation](https://www.home-assistant.io/integrations/pi_hole)

### Proxmox VE

Proxmox VE Custom Integration Home Assistant

**Links:**

- [Official integration repo](https://github.com/dougiteixeira/proxmoxve)

### Shelly

Integrate Shelly devices into Home Assistant.

[Devices](#shelly---smart-plugs) connected to IOT lan.

**Firewall rules:**

- allow TCP:80(HTTP) from server homesrv to vlan IOT
- allow TCP:5683(CoIoT) from vlan IOT to server homesrv
- allow TCP:80(HTTP) from vlan IOT to server homesrv

**Links:**

- [Home Assistant - Official integration documentation](https://www.home-assistant.io/integrations/shelly)

### Speedtest.net

The Speedtest.net integration uses the Speedtest.net web service to measure network bandwidth performance.

**Links:**

- [Home Assistant - Official integration documentation](https://www.home-assistant.io/integrations/speedtestdotnet)

### Squeezebox (Lyrion Music Server)

The Squeezebox integration allows you to control music players from the Lyrion Music Server (LMS) ecosystem. Lyrion Music Server was previously known as Logitech Media Server.

The Squeezebox music player ecosystem, which can be controlled through this integration, includes hardware audio players from Logitech, including Squeezebox 3rd Generation, Squeezebox Boom, Squeezebox Receiver, Transporter, Squeezebox2, Squeezebox and SLIMP3, and many software emulators like Squeezelite, SqueezeSlave, SoftSqueeze and SqueezePlay.

[Check git repo](/marcio.fernandes/lms) for more information how to setup Lyrion Music Server docker container.

**Links:**

- [Home Assistant - Official integration documentation](https://www.home-assistant.io/integrations/squeezebox)

### Sun

The sun integration will use the location as configured in your Home Assistant configuration to track if the sun is above or below the horizon. The sun can be used within automation's as a trigger with an optional offset to simulate dawn/dusk or as a condition with an optional offset to test if the sun has already set or risen.

**Links:**

- [Home Assistant - Official integration documentation](https://www.home-assistant.io/integrations/sun)

### Time & Date

The time and date (time_date) integration allows one to create sensors for the current date or time in different formats. All values are based on the timezone which is set in “General Configuration”.

**Links:**

- [Home Assistant - Official integration documentation](https://www.home-assistant.io/integrations/time_date)

### Xbox

The Xbox integration allows you to control Xbox One (or newer) consoles from Home Assistant.

Home Assistant authenticates with Xbox Live through OAuth2 using the Home Assistant Cloud account linking service.

**Links:**

- [Home Assistant - Official integration documentation](https://www.home-assistant.io/integrations/xbox)

## Setup

### Docker

The deployment and maintenance of this Home Assistant setup are managed using Docker. A [Docker Compose file](./docker-compose.yaml) is used to define and run the multi-container environment.

#### Deploy and update

A [Git Action workflow](./.gitea/workflows/deploy.yml) is configured to:

- Automatically pull the latest Docker images daily.
- Execute `docker-compose up` to ensure the environment remains up-to-date and operational.

#### Volumes

##### `has_config`

The `has_config` volume stores the Home Assistant configuration files. For more details, refer to the [Home Assistant configuration repository](/marcio.fernandes/homeassistant.config).

### Development Environment

Development and maintenance tasks are performed using Visual Studio Code on the Lazarus development device. The Docker context is set to the host [homesrv01.dev.lan](/marcio.fernandes/homesrv01.dev.lan) for seamless integration and management.