358 lines
9.2 KiB
Markdown
358 lines
9.2 KiB
Markdown
# Hyprland Monitor Control Integration for Home Assistant
|
|
|
|
This custom integration allows you to control your Hyprland desktop monitors directly from Home Assistant. It connects to your Hyprmonitors Rust server to provide full monitor control capabilities.
|
|
|
|
## Features
|
|
|
|
- **Monitor Status Sensors**: Real-time status of all monitors (on/off/mixed)
|
|
- **Individual Monitor Switches**: Control each monitor separately
|
|
- **Master Switch**: Turn all monitors on/off at once
|
|
- **Custom Services**: Advanced automation capabilities
|
|
- **Auto-discovery**: Automatically detects available monitors
|
|
- **Real-time Updates**: Monitor status updates every 30 seconds
|
|
|
|
## Prerequisites
|
|
|
|
1. **Hyprmonitors Server**: The Rust server must be running and accessible
|
|
2. **Home Assistant**: Version 2023.1.0 or newer
|
|
3. **Network Access**: Home Assistant must be able to reach your Hyprmonitors server
|
|
|
|
## Installation
|
|
|
|
### Method 1: Manual Installation
|
|
|
|
1. Create the custom components directory in your Home Assistant configuration:
|
|
```bash
|
|
mkdir -p config/custom_components/hyprmonitors
|
|
```
|
|
|
|
2. Copy all files from this directory to your Home Assistant custom components:
|
|
```bash
|
|
cp -r custom_components/hyprmonitors/* config/custom_components/hyprmonitors/
|
|
```
|
|
|
|
3. Restart Home Assistant
|
|
|
|
### Method 2: HACS (Recommended when available)
|
|
|
|
1. Add this repository to HACS as a custom repository
|
|
2. Search for "Hyprland Monitor Control" in HACS
|
|
3. Install the integration
|
|
4. Restart Home Assistant
|
|
|
|
## Configuration
|
|
|
|
### Via UI (Recommended)
|
|
|
|
1. Go to **Settings** → **Devices & Services**
|
|
2. Click **Add Integration**
|
|
3. Search for "Hyprland Monitor Control"
|
|
4. Enter your Hyprmonitors server details:
|
|
- **Host**: IP address or hostname (default: localhost)
|
|
- **Port**: Port number (default: 3000)
|
|
5. Click **Submit**
|
|
|
|
The integration will automatically discover your monitors and create entities.
|
|
|
|
### Via configuration.yaml (Legacy)
|
|
|
|
```yaml
|
|
hyprmonitors:
|
|
host: localhost
|
|
port: 3000
|
|
```
|
|
|
|
## Entities Created
|
|
|
|
### Sensors
|
|
|
|
- **`sensor.hyprmonitors_monitor_status`**: Overall status of all monitors
|
|
- States: `all_on`, `all_off`, `mixed`, `unavailable`
|
|
- Attributes: total monitors, monitors on/off count, monitor details
|
|
|
|
- **`sensor.hyprmonitors_[monitor_name]_status`**: Individual monitor status
|
|
- States: `on`, `off`, `unknown`, `unavailable`
|
|
- Attributes: monitor name, friendly name
|
|
|
|
### Switches
|
|
|
|
- **`switch.hyprmonitors_all_monitors`**: Master switch for all monitors
|
|
- Turn all monitors on/off simultaneously
|
|
- Shows mixed state when some monitors are on/off
|
|
|
|
- **`switch.hyprmonitors_[monitor_name]`**: Individual monitor switches
|
|
- Control specific monitors by name
|
|
- Examples: `switch.hyprmonitors_dp_1`, `switch.hyprmonitors_hdmi_a_1`
|
|
|
|
## Services
|
|
|
|
The integration provides several services for advanced automation:
|
|
|
|
### `hyprmonitors.turn_on_monitor`
|
|
Turn on a specific monitor by name.
|
|
|
|
```yaml
|
|
service: hyprmonitors.turn_on_monitor
|
|
data:
|
|
monitor: "DP-1"
|
|
```
|
|
|
|
### `hyprmonitors.turn_off_monitor`
|
|
Turn off a specific monitor by name.
|
|
|
|
```yaml
|
|
service: hyprmonitors.turn_off_monitor
|
|
data:
|
|
monitor: "HDMI-A-1"
|
|
```
|
|
|
|
### `hyprmonitors.turn_on_all_monitors`
|
|
Turn on all monitors.
|
|
|
|
```yaml
|
|
service: hyprmonitors.turn_on_all_monitors
|
|
```
|
|
|
|
### `hyprmonitors.turn_off_all_monitors`
|
|
Turn off all monitors.
|
|
|
|
```yaml
|
|
service: hyprmonitors.turn_off_all_monitors
|
|
```
|
|
|
|
## Automation Examples
|
|
|
|
### Turn off monitors when away
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "Turn off monitors when away"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: person.your_name
|
|
to: "not_home"
|
|
action:
|
|
- service: hyprmonitors.turn_off_all_monitors
|
|
|
|
- alias: "Turn on monitors when home"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: person.your_name
|
|
to: "home"
|
|
action:
|
|
- service: hyprmonitors.turn_on_all_monitors
|
|
```
|
|
|
|
### Scheduled monitor control
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "Turn off monitors at night"
|
|
trigger:
|
|
- platform: time
|
|
at: "23:00:00"
|
|
action:
|
|
- service: switch.turn_off
|
|
entity_id: switch.hyprmonitors_all_monitors
|
|
|
|
- alias: "Turn on monitors in the morning"
|
|
trigger:
|
|
- platform: time
|
|
at: "07:00:00"
|
|
condition:
|
|
- condition: state
|
|
entity_id: person.your_name
|
|
state: "home"
|
|
action:
|
|
- service: switch.turn_on
|
|
entity_id: switch.hyprmonitors_all_monitors
|
|
```
|
|
|
|
### Smart meeting room control
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "Turn off secondary monitor during meetings"
|
|
trigger:
|
|
- platform: calendar
|
|
event: start
|
|
entity_id: calendar.work
|
|
condition:
|
|
- condition: template
|
|
value_template: "{{ 'meeting' in trigger.calendar_event.summary.lower() }}"
|
|
action:
|
|
- service: hyprmonitors.turn_off_monitor
|
|
data:
|
|
monitor: "DP-2" # Secondary monitor
|
|
|
|
- alias: "Turn on secondary monitor after meetings"
|
|
trigger:
|
|
- platform: calendar
|
|
event: end
|
|
entity_id: calendar.work
|
|
condition:
|
|
- condition: template
|
|
value_template: "{{ 'meeting' in trigger.calendar_event.summary.lower() }}"
|
|
action:
|
|
- service: hyprmonitors.turn_on_monitor
|
|
data:
|
|
monitor: "DP-2"
|
|
```
|
|
|
|
## Dashboard Cards
|
|
|
|
### Monitor Status Card
|
|
|
|
```yaml
|
|
type: entities
|
|
entities:
|
|
- entity: sensor.hyprmonitors_monitor_status
|
|
name: Monitor Status
|
|
- entity: switch.hyprmonitors_all_monitors
|
|
name: All Monitors
|
|
title: Monitor Control
|
|
```
|
|
|
|
### Individual Monitor Controls
|
|
|
|
```yaml
|
|
type: glance
|
|
entities:
|
|
- entity: switch.hyprmonitors_dp_1
|
|
name: Main Monitor
|
|
icon: mdi:monitor
|
|
- entity: switch.hyprmonitors_hdmi_a_1
|
|
name: Secondary
|
|
icon: mdi:monitor-speaker
|
|
- entity: switch.hyprmonitors_all_monitors
|
|
name: All Monitors
|
|
icon: mdi:monitor-multiple
|
|
title: Monitor Control
|
|
```
|
|
|
|
### Monitor Status with Attributes
|
|
|
|
```yaml
|
|
type: custom:auto-entities
|
|
card:
|
|
type: entities
|
|
title: Monitor Details
|
|
filter:
|
|
include:
|
|
- entity_id: "sensor.*monitor*status"
|
|
options:
|
|
type: custom:multiple-entity-row
|
|
name: "{{ state_attr(config.entity, 'friendly_name') }}"
|
|
show_state: true
|
|
entities:
|
|
- attribute: monitors_on
|
|
name: "On"
|
|
- attribute: monitors_off
|
|
name: "Off"
|
|
- attribute: total_monitors
|
|
name: "Total"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Docker Networking Issues
|
|
|
|
**Most Common Issue**: If you're running Home Assistant in Docker and getting connection timeouts:
|
|
|
|
1. **Use Docker host networking**:
|
|
- Replace `localhost` with `host.docker.internal` (Docker Desktop)
|
|
- Or use your host machine's IP address (e.g., `192.168.1.100`)
|
|
- Or add `--network host` to your Docker run command
|
|
|
|
2. **Docker Compose example**:
|
|
```yaml
|
|
version: '3'
|
|
services:
|
|
homeassistant:
|
|
container_name: homeassistant
|
|
image: ghcr.io/home-assistant/home-assistant:stable
|
|
volumes:
|
|
- ./config:/config
|
|
environment:
|
|
- TZ=America/New_York
|
|
ports:
|
|
- "8123:8123"
|
|
extra_hosts:
|
|
- "host.docker.internal:host-gateway" # For Docker on Linux
|
|
```
|
|
|
|
3. **Testing connectivity from Docker**:
|
|
```bash
|
|
# From inside the Home Assistant container:
|
|
docker exec -it homeassistant curl http://host.docker.internal:3000/health
|
|
|
|
# Or test with your host IP:
|
|
docker exec -it homeassistant curl http://192.168.1.100:3000/health
|
|
```
|
|
|
|
### Connection Issues
|
|
|
|
1. **Cannot connect to server**:
|
|
- **Docker users**: Use `host.docker.internal` instead of `localhost`
|
|
- Verify the Hyprmonitors server is running: `curl http://localhost:3000/health`
|
|
- Check host and port configuration
|
|
- Ensure firewall allows connections on port 3000
|
|
|
|
2. **Timeout errors in logs**:
|
|
- Check if Home Assistant is in Docker (see Docker section above)
|
|
- Verify network connectivity between Home Assistant and hyprmonitors server
|
|
- Check if firewall is blocking port 3000
|
|
- Try increasing timeout in integration settings
|
|
|
|
3. **Monitors not detected**:
|
|
- Check if Hyprland is running
|
|
- Verify monitors are detected: `hyprctl monitors`
|
|
- Restart the Hyprmonitors server
|
|
- Check server logs for errors
|
|
|
|
4. **Integration not loading**:
|
|
- Check Home Assistant logs for errors
|
|
- Verify all files are copied correctly
|
|
- Restart Home Assistant completely
|
|
|
|
### Debug Logging
|
|
|
|
Add to your `configuration.yaml` to enable debug logging:
|
|
|
|
```yaml
|
|
logger:
|
|
default: info
|
|
logs:
|
|
custom_components.hyprmonitors: debug
|
|
```
|
|
|
|
### Monitor Names
|
|
|
|
To find your exact monitor names, check:
|
|
- Hyprmonitors server logs on startup
|
|
- Run `hyprctl monitors` in terminal
|
|
- Check the sensor attributes in Home Assistant
|
|
|
|
Common patterns:
|
|
- **DisplayPort**: `DP-1`, `DP-2`, etc.
|
|
- **HDMI**: `HDMI-A-1`, `HDMI-A-2`, etc.
|
|
- **Laptop screen**: `eDP-1`
|
|
|
|
## Configuration Options
|
|
|
|
### Advanced Configuration
|
|
|
|
The integration supports these advanced options (configure via UI):
|
|
|
|
- **Scan Interval**: How often to check monitor status (default: 30 seconds)
|
|
- **Timeout**: API request timeout (default: 10 seconds)
|
|
|
|
## Support
|
|
|
|
- **Issues**: Report bugs and feature requests on GitHub
|
|
- **Documentation**: Check the main Hyprmonitors README
|
|
- **Community**: Join the Home Assistant Community forums
|
|
|
|
## License
|
|
|
|
This integration is part of the Hyprmonitors project and follows the same license terms. |