190 lines
4.8 KiB
Markdown
Executable File
190 lines
4.8 KiB
Markdown
Executable File
# Home Assistant Module
|
|
|
|
This document details the Home Assistant module configuration.
|
|
|
|
## Module Structure
|
|
|
|
The Home Assistant module 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
|
|
```
|
|
|
|
## Module Options
|
|
|
|
The module is configured through options defined in `options.nix`:
|
|
|
|
```nix
|
|
options.${namespace}.services.home-assistant = {
|
|
enable = mkEnableOption "enable home-assistant";
|
|
mosquittoPort = mkOpt types.int 1883 "Port for MQTT";
|
|
zigbee2mqttPort = mkOpt types.int 8080 "Port for zigbee2mqtt web interface";
|
|
zigbeeDevicePath = mkOpt types.str "/dev/ttyUSB0" "Path to zigbee usb device";
|
|
};
|
|
```
|
|
|
|
## Main Configuration
|
|
|
|
The main module configuration in `default.nix` includes:
|
|
|
|
1. **Activation Scripts** - For setting up custom components
|
|
2. **Service Configurations** - For Matter, PostgreSQL, etc.
|
|
3. **Firewall Rules** - For allowing required ports
|
|
|
|
```nix
|
|
config = lib.mkIf cfg.enable {
|
|
# Activation script for custom components
|
|
system.activationScripts.installCustomComponents = ''
|
|
chown -R hass:hass ${config.services.home-assistant.configDir}
|
|
chmod -R 750 ${config.services.home-assistant.configDir}
|
|
'';
|
|
|
|
# Service configurations
|
|
services = {
|
|
matter-server.enable = true;
|
|
postgresql = {
|
|
enable = false;
|
|
ensureDatabases = [ "hass" ];
|
|
ensureUsers = [
|
|
{
|
|
name = "hass";
|
|
ensureDBOwnership = true;
|
|
}
|
|
];
|
|
};
|
|
};
|
|
|
|
# Firewall rules
|
|
networking.firewall.allowedTCPPorts = [
|
|
cfg.mosquittoPort
|
|
cfg.zigbee2mqttPort
|
|
8095 # music-assistant
|
|
8097 # home-assistant
|
|
5580 # matter-server
|
|
];
|
|
};
|
|
```
|
|
|
|
## Home Assistant Service
|
|
|
|
The core Home Assistant service configuration in `services/homeassistant/default.nix` includes:
|
|
|
|
1. **Package Selection** - Using the standard Home Assistant package
|
|
2. **Component Configuration** - Enabling required components
|
|
3. **Custom Components** - Adding custom components from packages
|
|
4. **Lovelace Modules** - Adding custom UI components
|
|
5. **Integration Configuration** - Setting up integrations with other systems
|
|
|
|
```nix
|
|
services.home-assistant = {
|
|
enable = true;
|
|
package = pkgs.home-assistant;
|
|
openFirewall = true;
|
|
configDir = "/var/lib/homeassistant";
|
|
configWritable = true;
|
|
|
|
# Components
|
|
extraComponents = [
|
|
"mqtt"
|
|
"zha"
|
|
"homekit"
|
|
# ... many more components
|
|
];
|
|
|
|
# Custom components
|
|
customComponents = [
|
|
# ... custom components
|
|
];
|
|
|
|
# Lovelace modules
|
|
customLovelaceModules = [
|
|
# ... custom UI modules
|
|
];
|
|
|
|
# Configuration
|
|
config = {
|
|
# ... Home Assistant configuration
|
|
};
|
|
};
|
|
```
|
|
|
|
## Related Services
|
|
|
|
### Zigbee2MQTT
|
|
|
|
The Zigbee2MQTT service in `services/zigbee2mqtt/default.nix` connects Zigbee devices to MQTT:
|
|
|
|
```nix
|
|
services.zigbee2mqtt = {
|
|
enable = true;
|
|
settings = {
|
|
mqtt = {
|
|
server = "mqtt://localhost:${toString cfg.mosquittoPort}";
|
|
};
|
|
serial = {
|
|
port = cfg.zigbeeDevicePath;
|
|
};
|
|
# ... additional settings
|
|
};
|
|
};
|
|
```
|
|
|
|
### MQTT
|
|
|
|
MQTT is configured as a dependency for the Home Assistant module.
|
|
|
|
### Thread Border Router
|
|
|
|
The Thread Border Router in `services/thread/default.nix` provides Thread network connectivity for Matter devices.
|
|
|
|
## Automations
|
|
|
|
The module includes predefined automations in the `automations/` directory:
|
|
|
|
1. **Light Switch Automations** - For controlling lights via physical switches
|
|
2. **Motion Light Automations** - For motion-activated lighting
|
|
|
|
## Using the Module
|
|
|
|
To use this module in a system configuration:
|
|
|
|
```nix
|
|
{ config, ... }:
|
|
{
|
|
mjallen.services.home-assistant = {
|
|
enable = true;
|
|
# Optional: customize ports and device paths
|
|
mosquittoPort = 1883;
|
|
zigbee2mqttPort = 8080;
|
|
zigbeeDevicePath = "/dev/ttyUSB0";
|
|
};
|
|
}
|
|
```
|
|
|
|
## Extending the Module
|
|
|
|
### Adding Custom Components
|
|
|
|
To add a custom component:
|
|
|
|
1. Add the package to `packages/`
|
|
2. Add it to the `customComponents` list in `services/homeassistant/default.nix`
|
|
|
|
### Adding Custom Automations
|
|
|
|
To add a custom automation:
|
|
|
|
1. Create a new directory in `automations/`
|
|
2. Implement the automation in `default.nix`
|
|
3. Import it in the system configuration |