Desk2HA Agent

Multi-vendor desktop telemetry agent for Home Assistant.

Collects hardware metrics, peripheral status, and display settings from Windows, Linux, and macOS — and exposes them via HTTP and MQTT for the Desk2HA HA integration.

Features

• Cross-platform: Windows, Linux, macOS
• 3-tier collector model: Platform (OS) → Generic (DDC/CI, HID, BLE, Bluetooth, UVC) → Vendor (Dell, HP, Lenovo, Logitech, Corsair, SteelSeries, Razer)
• Display control: Brightness, contrast, volume, input source, color preset, sharpness, RGB gain (R/G/B), black level (R/G/B), audio mute, KVM switch, PBP mode, auto brightness, auto color temp, smart HDR, power nap, factory reset via DDC/CI
• Webcam control: Brightness, contrast, saturation, sharpness, gain, gamma, white balance, focus, exposure, zoom, pan, tilt, backlight compensation, autofocus, auto WB, auto exposure via UVC
• Litra control: Power, brightness, color temperature for Logitech Litra Glow/Beam
• Wireless receivers: Dell Universal, Logitech Bolt/Unifying/Lightspeed, Jabra Link, Corsair Slipstream, Razer HyperSpeed
• Dual transport: HTTP API (OpenAPI v2.0.0) + MQTT with HA Discovery
• Auto-discovery: Zeroconf/mDNS (_desk2ha._tcp.local.)
• Self-update: Version check via GitHub Releases + pip upgrade
• Elevated helper: Separate process for admin-only metrics (Dell DCM WMI)
• Vendor images: Tier 1 generic + Tier 2 vendor-specific SVG device silhouettes
• System tray: Windows tray icon with status menu

Collectors

Installation

pip install desk2ha-agent

# Windows extras (WMI, tray icon):
pip install desk2ha-agent[windows]

Quick Start

1. Create a config file (desk2ha-agent.toml):

[http]
enabled = true
bind = "0.0.0.0"
port = 9693
auth_token = "YOUR_RANDOM_TOKEN"

2. Run the agent:

desk2ha-agent --config desk2ha-agent.toml

3. In Home Assistant, add the Desk2HA integration and point it to http://<agent-ip>:9693.

Elevated Helper

Some metrics (Dell Command Monitor WMI, DDC/CI) require admin privileges. The elevated helper runs as a separate process with admin rights and serves metrics via localhost HTTP:

# Start manually (reads [helper].secret from config.toml):
desk2ha-helper --config config.toml --log-dir logs

# Or install as a Windows Scheduled Task (run as Administrator):
powershell -File scripts/install-helper-service.ps1

The task runs in the user's interactive session at logon with Highest run level — DDC/CI needs Session 1+, so a Windows Service under LocalSystem will not work.

The agent automatically queries the helper at http://127.0.0.1:9694 if it's running, authenticating with the shared bearer token from [helper].secret. If the helper is unreachable, elevated metrics are simply skipped.

Configuration

See examples/full-config.toml for all options.

API Endpoints

Recommended Vendor Software

The agent works out of the box with basic metrics via standard OS APIs. For full telemetry (detailed thermals, fan speeds, battery health, thermal profile control), install the vendor-specific software for your hardware:

Dell

HP

Lenovo

Logitech

Linux (ThinkPad)

Cross-Platform

Note: All vendor software is optional. The agent gracefully skips collectors when the required software is not installed. You can check which collectors are active via GET /v1/info.

Windows Autostart

The agent needs an interactive desktop session for DDC/CI monitor control. Use the Startup folder (not a Windows Service):

%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\Desk2HA Agent.vbs

The elevated helper runs as a Scheduled Task in the user's interactive session (required for DDC/CI — Session 0 services cannot access DDC/CI):

# Run as Administrator:
powershell -File scripts/install-helper-service.ps1

Known Issues

Upcoming Features

• Prometheus endpoint: /metrics in Prometheus scrape format
• SteelSeries/Razer battery: Battery levels via HID for wireless peripherals
• macOS Bluetooth: CoreBluetooth support for paired device enumeration
• Logitech HID++: Wireless peripheral metrics via HID++ protocol
• USB PD Dock Monitoring: Thunderbolt/USB4 dock-specific metrics

License

Apache-2.0