# 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.