surface-dial-hass

A Linux daemon that turns a Microsoft Surface Dial into a volume knob for Home Assistant media players.

Features

• Rotation adjusts volume of a configurable media_player entity
• Button press toggles mute
• Auto-reconnects when the dial disconnects/reconnects over Bluetooth
• Debounces rapid rotation into single API calls for responsiveness
• Runs as a systemd service

Requirements

• Linux with Bluetooth LE support
• Microsoft Surface Dial paired via bluetoothctl
• A Home Assistant instance with a long-lived access token
• User must be in the input group: sudo gpasswd -a $(whoami) input

Building

cargo build --release

The binary will be at target/release/surface-dial-hass.

Configuration

Copy the example config and edit it:

cp config.toml.example config.toml

[homeassistant]
url = "http://homeassistant.local:8123"
token = "your_long_lived_access_token_here"

[media_player]
entity_id = "media_player.living_room"
volume_step = 0.02  # 2% per click

[dial]
device_name = "Surface Dial System Multi Axis"
debounce_ms = 50

Setting	Description	Default
homeassistant.url	Home Assistant base URL	—
homeassistant.token	Long-lived access token	—
media_player.entity_id	Entity to control	—
media_player.volume_step	Volume change per click (0.0–1.0)	0.02
dial.device_name	evdev device name to match	Surface Dial System Multi Axis
dial.debounce_ms	Debounce window for batching rotations	50

Usage

./target/release/surface-dial-hass --config config.toml

Set RUST_LOG=debug for verbose output.

Running as a systemd service

sudo cp target/release/surface-dial-hass /usr/local/bin/
sudo mkdir -p /etc/surface-dial-hass
sudo cp config.toml /etc/surface-dial-hass/config.toml
sudo cp surface-dial-hass.service /etc/systemd/system/
sudo systemctl enable --now surface-dial-hass

License

MIT