ha
This commit is contained in:
mjallen18
188
docs/home-assistant/README.md
Normal file
188
docs/home-assistant/README.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Home Assistant Configuration
|
||||
|
||||
This document provides comprehensive information about the Home Assistant setup in this NixOS configuration.
|
||||
|
||||
## Overview
|
||||
|
||||
Home Assistant is configured as a NixOS service with custom components, integrations, and automations. The configuration uses a modular approach with separate files for different aspects of the setup.
|
||||
|
||||
## Module Structure
|
||||
|
||||
The Home Assistant configuration is organized in the following structure:
|
||||
|
||||
```
|
||||
modules/nixos/homeassistant/
|
||||
├── automations/ # Automation configurations
|
||||
│ ├── lightswitch/ # Light switch automations
|
||||
│ └── motion-light/ # Motion-activated light automations
|
||||
├── default.nix # Main module configuration
|
||||
├── options.nix # Module options definition
|
||||
└── services/ # Related service configurations
|
||||
├── govee2mqtt/ # Govee integration via MQTT
|
||||
├── homeassistant/ # Core Home Assistant service
|
||||
├── music-assistant/ # Music Assistant integration
|
||||
├── thread/ # Thread border router
|
||||
└── zigbee2mqtt/ # Zigbee to MQTT bridge
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
The Home Assistant module is enabled in the system configuration by setting:
|
||||
|
||||
```nix
|
||||
mjallen.services.home-assistant.enable = true;
|
||||
```
|
||||
|
||||
This activates Home Assistant and related services such as MQTT, Zigbee2MQTT, and the Matter server.
|
||||
|
||||
## Configuration Options
|
||||
|
||||
The module provides several configuration options:
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `enable` | boolean | `false` | Enable Home Assistant and related services |
|
||||
| `mosquittoPort` | integer | `1883` | Port for the MQTT broker |
|
||||
| `zigbee2mqttPort` | integer | `8080` | Port for the Zigbee2MQTT web interface |
|
||||
| `zigbeeDevicePath` | string | `/dev/ttyUSB0` | Path to the Zigbee USB device |
|
||||
|
||||
## Core Services
|
||||
|
||||
### Home Assistant
|
||||
|
||||
The main Home Assistant service is configured in `services/homeassistant/default.nix` with:
|
||||
|
||||
- PostgreSQL database backend
|
||||
- Custom components
|
||||
- Custom Lovelace modules
|
||||
- HTTPS access with authentication
|
||||
- Integration with other services
|
||||
|
||||
### MQTT
|
||||
|
||||
MQTT is used as a messaging protocol for various smart home devices. The Mosquitto MQTT broker is automatically configured when Home Assistant is enabled.
|
||||
|
||||
### Zigbee2MQTT
|
||||
|
||||
Zigbee2MQTT allows integration with Zigbee devices. It's configured with:
|
||||
|
||||
- Automatic discovery for Home Assistant
|
||||
- OTA updates for Zigbee devices
|
||||
- Web interface for management
|
||||
|
||||
### Thread Border Router
|
||||
|
||||
The Thread Border Router provides integration with Thread-based devices like Matter devices.
|
||||
|
||||
## Custom Components
|
||||
|
||||
The following custom components are included:
|
||||
|
||||
- `ha-anycubic` - Anycubic 3D printer integration
|
||||
- `ha-bambulab` - Bambu Lab 3D printer integration
|
||||
- `ha-bedjet` - BedJet climate control integration
|
||||
- `ha-gehome` - GE Home appliance integration
|
||||
- `ha-icloud3` - Enhanced iCloud device tracking
|
||||
- `ha-local-llm` - Local LLM integration
|
||||
- `ha-mail-and-packages` - Mail and package delivery tracking
|
||||
- `ha-nanokvm` - NanoKVM integration
|
||||
- `ha-openhasp` - openHASP integration for DIY displays
|
||||
- `ha-overseerr` - Overseerr media request integration
|
||||
- `ha-petlibro` - PetLibro pet feeder integration
|
||||
- `ha-wyzeapi` - Wyze device integration
|
||||
|
||||
## Automations
|
||||
|
||||
### Light Switch Automations
|
||||
|
||||
The light switch automations handle physical switch inputs for controlling smart lights.
|
||||
|
||||
### Motion Light Automations
|
||||
|
||||
Motion light automations turn lights on when motion is detected and off after a period of inactivity.
|
||||
|
||||
### Custom Automations
|
||||
|
||||
Additional automations are placed in the `/etc/hass` directory and are included in the Home Assistant configuration. These include:
|
||||
|
||||
- `fountain_automation.yaml` - Toggles the water dispensing mode on the Dockstream Smart RFID Fountain every 15 minutes between constant and intermittent flow.
|
||||
|
||||
## Smart Home Devices
|
||||
|
||||
The configuration includes support for various smart home devices:
|
||||
|
||||
### Lighting
|
||||
|
||||
- Various smart lights throughout the home
|
||||
|
||||
### Climate
|
||||
|
||||
- Smart thermostat
|
||||
- Humidifier control
|
||||
|
||||
### Pet Care
|
||||
|
||||
- Dockstream Smart RFID Fountain with scheduling
|
||||
- Smart pet feeders for pets named Joey and Luci
|
||||
- Litter-Robot 4 smart litter box
|
||||
|
||||
### Media
|
||||
|
||||
- Google Cast devices
|
||||
- Smart TVs
|
||||
- Media players
|
||||
|
||||
### Sensors
|
||||
|
||||
- Temperature, humidity, and motion sensors
|
||||
- Door and window sensors
|
||||
- Presence detection
|
||||
|
||||
## Integration with Other Services
|
||||
|
||||
Home Assistant is integrated with:
|
||||
|
||||
- **Music Assistant** - For enhanced music streaming capabilities
|
||||
- **Govee Integration** - For Govee smart devices
|
||||
- **Matter** - For Matter-compatible devices
|
||||
|
||||
## Adding New Automations
|
||||
|
||||
To add a new automation:
|
||||
|
||||
1. Create a YAML file with the automation definition
|
||||
2. Place it in `/etc/hass`
|
||||
3. The automation will be automatically included in Home Assistant
|
||||
|
||||
Example automation format:
|
||||
|
||||
```yaml
|
||||
alias: "Automation Name"
|
||||
description: "Description of what the automation does"
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: binary_sensor.motion_sensor
|
||||
to: "on"
|
||||
condition: []
|
||||
action:
|
||||
- service: light.turn_on
|
||||
target:
|
||||
entity_id: light.living_room
|
||||
mode: single
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Zigbee Device Pairing Issues**
|
||||
- Make sure the Zigbee coordinator is properly connected
|
||||
- Check the Zigbee2MQTT logs for errors
|
||||
|
||||
2. **Service Unavailable**
|
||||
- Check if all related services are running
|
||||
- Verify firewall rules allow access to the services
|
||||
|
||||
3. **Database Issues**
|
||||
- Check PostgreSQL service status
|
||||
- Verify database connection settings
|
||||
148
docs/home-assistant/automations.md
Normal file
148
docs/home-assistant/automations.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# Home Assistant Automations
|
||||
|
||||
This document details the automations configured in the Home Assistant setup.
|
||||
|
||||
## Automation Types
|
||||
|
||||
Automations in this configuration are managed in several ways:
|
||||
|
||||
1. **Module-Based Automations**: Defined in Nix modules within the `modules/nixos/homeassistant/automations/` directory
|
||||
2. **YAML Automations**: Defined in YAML files and included via the `automation manual` directive
|
||||
3. **UI-Created Automations**: Created through the Home Assistant UI and stored in `automations.yaml`
|
||||
|
||||
## Module-Based Automations
|
||||
|
||||
### Light Switch Automations
|
||||
|
||||
**Location**: `modules/nixos/homeassistant/automations/lightswitch/`
|
||||
|
||||
These automations link physical light switches to smart lights:
|
||||
|
||||
- **Bedroom Light Switch**: Controls the bedroom lights
|
||||
- **Living Room Light Switch**: Controls the living room lights
|
||||
- **Bedroom Closet Lights**: Controls the closet lights
|
||||
|
||||
### Motion-Activated Light Automations
|
||||
|
||||
**Location**: `modules/nixos/homeassistant/automations/motion-light/`
|
||||
|
||||
These automations turn lights on when motion is detected and off after a period of inactivity.
|
||||
|
||||
## YAML Automations
|
||||
|
||||
### Fountain Cycling Automation
|
||||
|
||||
**Location**: `/etc/nixos/fountain_automation.yaml`
|
||||
|
||||
This automation toggles the water dispensing mode on the Dockstream Smart RFID Fountain every 15 minutes:
|
||||
|
||||
```yaml
|
||||
alias: "Fountain Cycle Mode"
|
||||
description: "Toggles fountain water mode every 15 minutes between constant and intermittent flow"
|
||||
trigger:
|
||||
- platform: time_pattern
|
||||
minutes: "/15" # Every 15 minutes
|
||||
condition: []
|
||||
action:
|
||||
- service: select.select_next
|
||||
target:
|
||||
entity_id: select.dockstream_smart_rfid_fountain_water_dispensing_mode
|
||||
mode: single
|
||||
id: fountain_cycle_mode
|
||||
```
|
||||
|
||||
This automation:
|
||||
1. Triggers every 15 minutes
|
||||
2. Uses the `select.select_next` service to toggle between the two available options:
|
||||
- "Flowing Water (Constant)"
|
||||
- "Intermittent Water (Scheduled)"
|
||||
|
||||
The fountain is also configured with:
|
||||
- Water Interval: 10 minutes
|
||||
- Water Dispensing Duration: 15 minutes
|
||||
|
||||
## Creating New Automations
|
||||
|
||||
### Method 1: Module-Based Automation
|
||||
|
||||
For reusable, complex automations that should be managed in code:
|
||||
|
||||
1. Create a new directory in `modules/nixos/homeassistant/automations/`
|
||||
2. Create a `default.nix` file with the automation logic
|
||||
|
||||
Example:
|
||||
```nix
|
||||
{ config, lib, ... }:
|
||||
{
|
||||
config = {
|
||||
services.home-assistant.config."automation manual" = [
|
||||
{
|
||||
alias = "Example Automation";
|
||||
description = "Example automation created via Nix module";
|
||||
trigger = [
|
||||
{
|
||||
platform = "state";
|
||||
entity_id = "binary_sensor.example_sensor";
|
||||
to = "on";
|
||||
}
|
||||
];
|
||||
action = [
|
||||
{
|
||||
service = "light.turn_on";
|
||||
target.entity_id = "light.example_light";
|
||||
}
|
||||
];
|
||||
mode = "single";
|
||||
}
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Method 2: YAML Automation
|
||||
|
||||
For simpler automations:
|
||||
|
||||
1. Create a YAML file with the automation definition
|
||||
2. Place it in `/etc/hass/`
|
||||
|
||||
Example:
|
||||
```yaml
|
||||
alias: "Example Automation"
|
||||
description: "Example automation in YAML"
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: binary_sensor.example_sensor
|
||||
to: "on"
|
||||
action:
|
||||
- service: light.turn_on
|
||||
target:
|
||||
entity_id: light.example_light
|
||||
mode: single
|
||||
```
|
||||
|
||||
### Method 3: UI Creation
|
||||
|
||||
For quick prototyping or simple automations:
|
||||
|
||||
1. Go to Home Assistant UI > Settings > Automations & Scenes
|
||||
2. Click "+ Add Automation"
|
||||
3. Configure using the UI editor
|
||||
|
||||
## Testing Automations
|
||||
|
||||
To test an automation:
|
||||
|
||||
1. In the Home Assistant UI, go to Developer Tools > Services
|
||||
2. Select `automation.trigger` as the service
|
||||
3. Enter the entity_id of your automation in the service data field
|
||||
4. Click "Call Service" to trigger the automation manually
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If an automation isn't working as expected:
|
||||
|
||||
1. Check the Home Assistant logs for errors
|
||||
2. Verify entity names and service calls are correct
|
||||
3. Test individual triggers and actions separately
|
||||
4. Use the "Debug" section in the automation editor to trace execution
|
||||
96
docs/home-assistant/fountain-automation.md
Normal file
96
docs/home-assistant/fountain-automation.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Pet Fountain Automation
|
||||
|
||||
This document details the automation for the Dockstream Smart RFID Fountain device.
|
||||
|
||||
## Overview
|
||||
|
||||
The Dockstream Smart RFID Fountain is a smart pet fountain controlled through Home Assistant. A custom automation has been created to toggle the water dispensing mode between constant flow and intermittent flow every 15 minutes. This cycling helps keep the water fresh while reducing energy consumption.
|
||||
|
||||
## Fountain Configuration
|
||||
|
||||
The Dockstream Smart RFID Fountain has the following settings in Home Assistant:
|
||||
|
||||
| Setting | Entity ID | Value | Description |
|
||||
|---------|-----------|-------|-------------|
|
||||
| Water Dispensing Mode | `select.dockstream_smart_rfid_fountain_water_dispensing_mode` | Toggles between modes | Controls how water flows |
|
||||
| Water Interval | `number.dockstream_smart_rfid_fountain_water_interval` | 10 minutes | Time between water dispensing in intermittent mode |
|
||||
| Water Dispensing Duration | `number.dockstream_smart_rfid_fountain_water_dispensing_duration` | 15 minutes | How long water flows in intermittent mode |
|
||||
| Cleaning Cycle | `number.dockstream_smart_rfid_fountain_cleaning_cycle` | 14 days | Reminder interval for cleaning |
|
||||
|
||||
## Available Modes
|
||||
|
||||
The fountain supports two water dispensing modes:
|
||||
|
||||
1. **Flowing Water (Constant)** - Water flows continuously
|
||||
2. **Intermittent Water (Scheduled)** - Water flows according to the interval and duration settings
|
||||
|
||||
## Automation Details
|
||||
|
||||
The fountain cycling automation is defined in `/etc/nixos/fountain_automation.yaml`:
|
||||
|
||||
```yaml
|
||||
alias: "Fountain Cycle Mode"
|
||||
description: "Toggles fountain water mode every 15 minutes between constant and intermittent flow"
|
||||
trigger:
|
||||
- platform: time_pattern
|
||||
minutes: "/15" # Every 15 minutes
|
||||
condition: []
|
||||
action:
|
||||
- service: select.select_next
|
||||
target:
|
||||
entity_id: select.dockstream_smart_rfid_fountain_water_dispensing_mode
|
||||
mode: single
|
||||
id: fountain_cycle_mode
|
||||
```
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Trigger**: The automation runs every 15 minutes based on the time pattern trigger
|
||||
2. **Action**: It uses the `select.select_next` service to toggle to the next available option
|
||||
3. **Mode**: Set to "single" to prevent multiple executions if triggers overlap
|
||||
|
||||
## Installation
|
||||
|
||||
The automation is included in Home Assistant via the `automation manual` directive in the Home Assistant configuration:
|
||||
|
||||
```yaml
|
||||
"automation manual" = "!include_dir_merge_list /etc/hass";
|
||||
```
|
||||
|
||||
The YAML file needs to be placed in the `/etc/hass` directory to be loaded.
|
||||
|
||||
## Testing
|
||||
|
||||
To manually test the automation:
|
||||
|
||||
1. In Home Assistant UI, go to Developer Tools > Services
|
||||
2. Select `automation.trigger` as the service
|
||||
3. Enter the following service data:
|
||||
```yaml
|
||||
entity_id: automation.fountain_cycle_mode
|
||||
```
|
||||
4. Click "Call Service" to trigger the automation
|
||||
|
||||
## Customizing
|
||||
|
||||
To adjust the cycling interval:
|
||||
|
||||
1. Edit the YAML file at `/etc/nixos/fountain_automation.yaml`
|
||||
2. Change the `minutes` value in the trigger section (e.g., from `"/15"` to `"/30"` for every 30 minutes)
|
||||
3. Save the file
|
||||
4. Restart Home Assistant or reload automations
|
||||
|
||||
To adjust fountain settings:
|
||||
|
||||
1. In Home Assistant UI, go to Settings > Devices & Services
|
||||
2. Find the Dockstream Smart RFID Fountain device
|
||||
3. Adjust the water interval or dispensing duration settings
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the automation is not working as expected:
|
||||
|
||||
1. Check that the entity ID is correct and the fountain is online
|
||||
2. Verify that Home Assistant is including the automation file correctly
|
||||
3. Look for errors in the Home Assistant logs related to the automation or the fountain
|
||||
4. Try manually controlling the fountain to ensure it responds to commands
|
||||
Reference in New Issue
Block a user