XP-Pen ACK05 Home Automation Controller

Controls KEF LSX II speakers and a Samsung TV via Home Assistant using the XP-Pen ACK05 Wireless Shortcut Remote (10 buttons + scroll dial).

[14:23:01.412]  DEVICE SELECTED: LSX II
[14:23:04.100]  DIAL   clockwise             Δ+1   (LSX II: volume_up)
[14:23:06.200]  KEY 8  released (HDMI)             (LSX II: select_source → tv)
[14:23:09.000]  DEVICE SELECTED: TV
[14:23:09.500]  KEY 7  pressed  (TV: remote_command → KEY_NETFLIX)

---

Architecture

The system consists of two components:

1. Relay (src/host_relay.py) - Runs on a machine with direct USB access to the ACK05 receiver
2. Monitor (src/monitor.py) - Connects to the relay via TCP and dispatches events to Home Assistant

USB Device → Relay (TCP:6789) → Monitor → Home Assistant

File Roles

File	Runs on	Purpose
src/host_relay.py	USB host	Reads HID, decodes reports, broadcasts JSON over TCP:6789
src/hid_reader.py	Monitor host	TCP client; parses JSON into typed events
src/monitor.py	Monitor host	Dispatches events to HA actions
src/ha_client.py	Monitor host	Home Assistant REST API wrapper
src/ha_config.json	Monitor host	Key/dial mappings and entity IDs

---

Deployment

Choose your platform:

Platform	Use Case	Complexity	Init System
macOS	Development	Low	Manual
Proxmox Host	Production relay	Medium	systemd
Debian LXC	Production monitor	Medium	systemd
Alpine LXC	Production monitor	Medium	OpenRC
Docker	Containerized	Low	Docker

See deploy/README.md for detailed platform comparison and recommendations.

Recommended Production Setup

• Proxmox Host for the relay (direct USB access)
• Debian LXC or Alpine LXC for the monitor (isolated, lightweight)

---

Key Layout

See docs/key-layout.md for complete button mappings.

Quick reference:

• Keys 1–3: Select active device
• Keys 4–10: Device-specific actions (play/pause, source selection, etc.)
• Dial: Volume control (CW/CCW) and mute (press)

---

Environment Variables

Variable	Required	Description
HA_HOST	Yes	Home Assistant IP or hostname
HA_PORT	No	Home Assistant port (default: 8123)
HA_TOKEN	Yes	Long-lived access token
ACK05_RELAY_HOST	Monitor only	Relay host IP (default: localhost)
ACK05_RELAY_PORT	No	Relay port (default: 6789)
LOG_LEVEL	No	Logging level (default: INFO)

See .env.example for a template.

---

Home Assistant Entities

Entity	Integration	Purpose
media_player.lsxii	hass-kef-connector	KEF LSX II (sources, volume)
media_player.tv	Samsung Smart TV (built-in)	TV media player
remote.tv	Samsung Smart TV (built-in)	TV remote commands

---

Development

For local development on macOS:

# Install dependencies
pip3 install -r requirements.txt
pip3 install -r deploy/proxmox-host/requirements-host.txt

# Configure environment
cp .env.example .env
nano .env

# Start relay (in one terminal)
python3 src/host_relay.py

# Start monitor (in another terminal)
python3 src/monitor.py

See deploy/macos/README.md for full development guide.

---

Documentation

• Key Layout - Button mappings and customization
• Architecture - System design and event flow
• Deployment Guide - Platform comparison and setup guides
• Platform Template - Guidelines for adding new platforms

---

Troubleshooting

• Relay issues: Check Proxmox Host or macOS troubleshooting sections
• Monitor issues: Check your platform's README troubleshooting section
• Home Assistant issues: Run scripts/diagnose_ha_sources.py to test connectivity
• General issues: See deploy/README.md for common problems

---

License

This project is provided as-is for personal use.