ha
This commit is contained in:
mjallen18
116
docs/modules/README.md
Normal file
116
docs/modules/README.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# Custom Modules
|
||||
|
||||
This directory contains documentation for the custom modules used in this NixOS configuration.
|
||||
|
||||
## Module Types
|
||||
|
||||
The repository uses two main types of modules:
|
||||
|
||||
1. **NixOS Modules** - System-level configurations in `modules/nixos/`
|
||||
2. **Home Manager Modules** - User-level configurations in `modules/home/`
|
||||
|
||||
## NixOS Modules
|
||||
|
||||
These modules configure the system-level aspects of NixOS:
|
||||
|
||||
- [Boot Modules](./boot.md) - Boot loader and kernel configurations
|
||||
- [Desktop Modules](./desktop.md) - Desktop environment configurations
|
||||
- [Development Modules](./development.md) - Development tools and environments
|
||||
- [Hardware Modules](./hardware.md) - Hardware-specific configurations
|
||||
- [Home Assistant Modules](./homeassistant.md) - Home automation configuration
|
||||
- [Networking Modules](./network.md) - Network configuration and services
|
||||
- [Security Modules](./security.md) - Security-related configurations
|
||||
- [Services Modules](./services.md) - Various service configurations
|
||||
- [System Modules](./system.md) - General system configurations
|
||||
- [Virtualization Modules](./virtualization.md) - Virtualization and containerization
|
||||
|
||||
## Home Manager Modules
|
||||
|
||||
These modules configure user environments:
|
||||
|
||||
- [Applications](./home/applications.md) - User applications
|
||||
- [Desktop](./home/desktop.md) - User desktop environments
|
||||
- [Development](./home/development.md) - User development environments
|
||||
- [Media](./home/media.md) - Media applications
|
||||
- [Shell](./home/shell.md) - Shell configurations
|
||||
|
||||
## Module Structure
|
||||
|
||||
Each module follows a standard structure:
|
||||
|
||||
```
|
||||
modules/nixos/example-module/
|
||||
├── default.nix # Main implementation
|
||||
├── options.nix # Option declarations
|
||||
└── submodule/ # Optional submodules
|
||||
└── default.nix # Submodule implementation
|
||||
```
|
||||
|
||||
### default.nix
|
||||
|
||||
The `default.nix` file contains the main implementation of the module:
|
||||
|
||||
```nix
|
||||
{
|
||||
config,
|
||||
lib,
|
||||
pkgs,
|
||||
namespace,
|
||||
...
|
||||
}:
|
||||
let
|
||||
cfg = config.${namespace}.example-module;
|
||||
in
|
||||
{
|
||||
imports = [ ./options.nix ];
|
||||
|
||||
config = lib.mkIf cfg.enable {
|
||||
# Module implementation when enabled
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### options.nix
|
||||
|
||||
The `options.nix` file declares the module's configuration options:
|
||||
|
||||
```nix
|
||||
{ lib, namespace, ... }:
|
||||
with lib;
|
||||
let
|
||||
inherit (lib.${namespace}) mkOpt;
|
||||
in
|
||||
{
|
||||
options.${namespace}.example-module = {
|
||||
enable = mkEnableOption "enable example module";
|
||||
# Other option declarations
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Using Modules
|
||||
|
||||
To use a module in your system configuration:
|
||||
|
||||
1. Enable the module in your system configuration:
|
||||
|
||||
```nix
|
||||
{ config, ... }:
|
||||
{
|
||||
mjallen.example-module = {
|
||||
enable = true;
|
||||
# Other options
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Creating New Modules
|
||||
|
||||
To create a new module:
|
||||
|
||||
1. Create a new directory in `modules/nixos/` or `modules/home/`
|
||||
2. Create `default.nix` and `options.nix` files
|
||||
3. Implement your module functionality
|
||||
4. Import the module in your system configuration
|
||||
|
||||
See the [Getting Started](../getting-started.md) guide for more details on creating modules.
|
||||
190
docs/modules/homeassistant.md
Normal file
190
docs/modules/homeassistant.md
Normal file
@@ -0,0 +1,190 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user