feat: Added homeassistant plugin
This commit is contained in:
uttarayan21
315
homeassistant/README.md
Normal file
315
homeassistant/README.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# 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
|
||||
|
||||
### Connection Issues
|
||||
|
||||
1. **Cannot connect to server**:
|
||||
- Verify the Hyprmonitors server is running: `curl http://localhost:3000/health`
|
||||
- Check host and port configuration
|
||||
- Ensure firewall allows connections
|
||||
|
||||
2. **Monitors not detected**:
|
||||
- Check if Hyprland is running
|
||||
- Verify monitors are detected: `hyprctl monitors`
|
||||
- Restart the Hyprmonitors server
|
||||
|
||||
3. **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.
|
||||
Reference in New Issue
Block a user