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

Hyprmonitors Server: The Rust server must be running and accessible
Home Assistant: Version 2023.1.0 or newer
Network Access: Home Assistant must be able to reach your Hyprmonitors server

Installation

Method 1: Manual Installation

Create the custom components directory in your Home Assistant configuration:
```
mkdir -p config/custom_components/hyprmonitors
```

Copy all files from this directory to your Home Assistant custom components:

cp -r custom_components/hyprmonitors/* config/custom_components/hyprmonitors/

Restart Home Assistant

Method 2: HACS (Recommended when available)

Add this repository to HACS as a custom repository
Search for "Hyprland Monitor Control" in HACS
Install the integration
Restart Home Assistant

Configuration

Via UI (Recommended)

Go to Settings → Devices & Services
Click Add Integration
Search for "Hyprland Monitor Control"
Enter your Hyprmonitors server details:
- Host: IP address or hostname (default: localhost)
- Port: Port number (default: 3000)
Click Submit

The integration will automatically discover your monitors and create entities.

Via configuration.yaml (Legacy)

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.

service: hyprmonitors.turn_on_monitor
data:
  monitor: "DP-1"

`hyprmonitors.turn_off_monitor`

Turn off a specific monitor by name.

service: hyprmonitors.turn_off_monitor
data:
  monitor: "HDMI-A-1"

`hyprmonitors.turn_on_all_monitors`

Turn on all monitors.

service: hyprmonitors.turn_on_all_monitors

`hyprmonitors.turn_off_all_monitors`

Turn off all monitors.

service: hyprmonitors.turn_off_all_monitors

Automation Examples

Turn off monitors when away

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

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

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

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

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

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:

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

Docker Compose example:

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

Testing connectivity from Docker:

# 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

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
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
Monitors not detected:
- Check if Hyprland is running
- Verify monitors are detected: hyprctl monitors
- Restart the Hyprmonitors server
- Check server logs for errors
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:

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.